fix(docs): reconcile documentation with the state of the tree

[potiuk]

Summary

• Closes the batch of doc-vs-reality issues filed after an earlier audit pass
  (docs/labels-and-capabilities.md: family:* section incomplete, self-contradicting statement #882–docs/rfcs/RFC-AI-0004.md: status says "Draft", text says implementation operationalises every principle #888, Update organization-adapters.md: the organizations/ structural check has shipped #935), plus the same defect class found while verifying them.
• Every claim was checked against the tree before editing. Two issues turned
  out to be wrong or already fixed — those are called out below rather than
  edited to match.
• One tool fix: the validator globbed cache directories under skills/ as if
  they were skills.

Reported issues

Issue	What was actually wrong
#882	The family:* section documented 4 of the 10 canonical families, and conflated them with three repo-area labels (family:tools/ci/docs) that the validator rejects in frontmatter. Separately, "multi-capability tools are rare — tools/gmail is the only one today" sat directly above a table containing ten of them, and gmail declares three contracts, not the two the intro claimed. A stray blank line was also splitting the tool-capability table in two, so everything below contract:mail-archive rendered headerless.
#883	The per-skill override chain listed an organization layer that does not exist. AGENTS.md had the identical defect — now fixed too, with an explicit sentence: organizations supply config-key defaults, not skill overrides.
#884	The symlink recipe iterated the relay dir, producing four hops where the enforced rule is two.
#885	Half disproved. Gmail was indeed missing from mail-source (so were maildir and ponymail). But Fossil is not misclassified — tools/fossil declares contract:tracker + contract:source-control, tools/vcs has a complete FossilBackend with tests, and it is already listed under Forge/tracker. The real Fossil bug is the inverse: tools/vcs/README.md and labels-and-capabilities.md both omitted the backend. Fixed that instead.
#886	All three claims confirmed, plus two more stale rows in the same table (agent-guard, spec-loop both missing Kiro).
#887, #888	Status said Draft while each body described shipped, enforced behaviour. Set to Implemented, not Stable — each RFC's own promotion gate requires public review plus pilot validation, neither of which has happened. RFC-AI-0004 also said "the four shifts" above a four-item list in a document that says six everywhere else; the two missing bullets (Principles 5 and 6) are added rather than the numeral flipped.
#935	Already fixed by #994. Verified that, then fixed the rest of the section, which was stale the same way — all three Known-gaps bullets described work that has since shipped.

Found while verifying

Skill-count drift, some of it mine:

• README.md security 12→15 and the docs/modes.md glance table
  (Triage 34→35, Drafting 9→11) went stale in feat(security): add security-model prepare / verify / update skills #1156 — I added the
  skills and the mode-section rows but never the summary counts. This was
  the source of the validator's two modes-doc warnings.
• Pre-existing: README.md repo-health 6→7, the CONTRIBUTING.md tree's
  four prefix counts (all wrong), and one of three skill counts in
  docs/contributor-growth/README.md.

Note the modes glance column tracks mode: frontmatter, not section rows —
Mentoring declares 7 with 10 rows and Pairing declares 3 with 4, and both are
correct, because some skills are deliberately cross-listed. Only Triage and
Drafting were genuinely wrong.

Stale spec claims:

• specs/adapters.md said Bitbucket writes are "limited to Cloud
  issue-comment creation"; feat(bitbucket): add guarded cloud PR comment create #1142 added PR-comment creation.
• specs/project-agnosticism.md described the non-ASF smoke suite as
  "6 cases across 2 steps" driving one skill — it is 15 cases across 6 steps
  driving five — and claimed the catalogue produces 0 asf-coupling
  warnings when it produces 3.

Tool fix

skill-and-tool-validator enumerated skills/.mypy_cache, .pytest_cache,
.ruff_cache and .claude as skills, so a dirty working tree produced four
phantom "no eval suite" warnings naming paths the reader cannot find in the
repo. One of the five enumerations already had the dot-dir guard; the other
four now do, with a regression test.

Validator advisory warnings: 36 → 30.

Test plan

• prek run --all-files passes (exit 0)
• skill-and-tool-validate — 0 violations; the 4 eval-coverage and 2
  modes-doc warnings are gone
• spec-validate clean
• Workspace: ruff 29/29, ruff-format 29/29, mypy 26/26, pytest 32/32
• symlink-lint, check-family-plugins, check-workspace-members,
  check-placeholders all clean
• Counts re-derived from live family:/mode: frontmatter, not from
  skill-name prefixes

Notes for reviewers

A correction to #1156's test plan. That PR's body claims the three
security-model-* eval suites passed 35/35. That number is void. Sandboxed
claude -p returns Not logged in and exits 0; the runner's documented
fallback wraps non-JSON stdout as {"raw_output": …}, and the
intersection-only comparator then passes any case whose expected.json
declares no raw_output key. Nothing was graded.

Re-run outside the sandbox, the real result is 28/35 — 7 failures:

Suite	Result	Failing cases
security-model-prepare	8/9	step-4-provenance/case-4-hedge-tag-attempt
security-model-verify	9/11	step-a/case-6-injection-claims-preapproved, step-b/case-4-bare-headings
security-model-update	11/15	step-2/case-2-single-occurrence, step-2/case-3-report-quality-condition, step-2/case-5-claim-covers-wrong-component, step-3/case-4-two-offenders-with-a-widening-suggestion

Those skills are already on main and are not touched by this PR. Follow-up
will diagnose each failure as either an over-specified fixture or a genuine
gap in the skill prose, and fix accordingly.

Related, deliberately not in this PR: the harness passes a case when the
CLI emits no JSON at all. --exact guards it, the default does not. Making
"no JSON extracted" an ERROR by default would change results across all ~70
suites, which wants its own PR and a full validation run.

tools/spec-loop/.last-sync remains 13 commits behind main; this PR
corrects two stale specs but does not bump it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01So3JRGXrbqSGrohtZuHWKg