feat: verify-forge-doc-consistency — check doc claims against repo state

[misnaej]

Background

Nothing in forge checks documentation for factual drift against repo
state. The ten foundation agents (FOUNDATION §3) don't: docs-types-checker
validates docstring content + type hints in code; design-checker
reviews code for SOLID/DRY/KISS; the rest cover commit, PR, security,
triage, perf, weekly, knowledge-search. No pre-commit step checks it either.

So when a doc asserts a fact about the repo ("ships 10 agents", "the repo is
public", "STEPS table matches install_bootstrap.py", "skill X exists"), the
only enforcement today is a human reading carefully, or an ad-hoc Explore
fan-out. Drift slips in silently across versions. A deterministic CLI gate
closes that hole for the structured, machine-checkable subset.

Symptoms

A manual Explore sweep on 2026-06-11 found a live inconsistency that no
shipped tooling catches:

README.md:100        "Forge is a public repo, so no auth setup is needed."
CONTRIBUTING.md:217  "Forge is public — no auth needed in CI."
ground truth         repo visibility is PRIVATE

The same sweep had to hand-verify ~12 cross-references (agent counts, skill
names, CLI table vs [project.scripts], hook list vs claude-hooks/, doc
links, FOUNDATION § anchors, the install_bootstrap.py STEPS table). All
passed — but the check was a one-off human-driven run, not a repeatable gate.

Categories of doc claim worth checking

• Counts — "ten foundation agents", "7 skills", "13 Claude Code hooks".
• Name lists — agent / skill / CLI / hook names vs actual files on disk
  and [project.scripts] / plugin.json.
• Cross-file tables — README STEPS table vs install_bootstrap.py STEPS
  tuple; CLI reference vs each CLI's --help.
• Internal links — docs/*.md referenced from README exist; no orphan
  docs; FOUNDATION §N anchors resolve.
• Repo-state facts — visibility (public/private), default branch,
  remote — claims that depend on gh repo view / git, not just files.
• Version claims — any hardcoded version vs plugin.json / latest tag.

Plan

Deterministic CLI (verify-forge-doc-consistency)

A verify-forge-* CLI that checks the machine-checkable subset of doc
claims: counts, name lists, table-vs-source, link resolution, § anchors.
Wired as a non-blocking pre-commit step first (per FOUNDATION §4 "new tools →
modified files only initially"), tightened later. Repo-state facts
(visibility) that need gh self-skip in non-interactive context
(FOUNDATION §15).

Scope is the structured subset deliberately — most doc drift IS structured (a
name added to a dir but not the README table), and a deterministic CLI can
gate it in pre-commit. Subtle prose-judgment claims that no static check can
reach are explicitly out of scope (see below); revisit only if structured
coverage proves insufficient.

Out of scope

• Auto-fixing docs (a reporter/verifier flags; a fixer is a separate concern).
• Rewriting the doc set's prose style.
• The one live public/PRIVATE inconsistency above — fix that directly in
  whatever PR addresses it; this issue is about the tooling to catch the
  class, not the single instance.

Acceptance criteria

• A check (CLI and/or agent) exists that, run against the repo on
  2026-06-11, flags the README.md:100 / CONTRIBUTING.md:217
  public-vs-private claim.
• Structured cross-references (agent/skill/CLI/hook counts + names, STEPS
  table, doc links, § anchors) are verified automatically.
• verify-forge-doc-consistency wired into forge-precommit (non-blocking
  initially) and reachable per the cli_wiring contract (CLAUDE.md).

Related

• FOUNDATION §3 — the ten foundation agents (none cover doc consistency).
• FOUNDATION §4 — "new tools → modified files only initially", non-blocking.
• FOUNDATION §12 — Single Source of Truth (doc drift is an SSOT violation).
• FOUNDATION §15 — runtime context (gh-dependent checks self-skip in CI).
• CLAUDE.md cli_wiring contract — new CLI must be reachable.
• The live public/PRIVATE doc inconsistency (README.md:100,
  CONTRIBUTING.md:217) that motivated this issue.

[misnaej]

[issue-triage] tier-3-standard applied: new verifier CLI — valuable for catching doc drift (FOUNDATION §12 SSOT principle) but not urgent. The live inconsistency it would have caught (README public/private claim) is a one-off fix, not an ongoing blocker. Per FOUNDATION §4 new tools start non-blocking and modified-files-only; this is normal feature delivery cadence. The feature label + ci-testing + docs labels confirm standard new-capability work.

[misnaej]

[issue-triage] FOUNDATION §14 (PR #37, merged 2026-06-12) now requires every issue to open with a Requires: line. This issue predates the rule. Dependency scan: standalone — no open issue or PR must land first. Please prepend Requires: nothing to the issue body.

[misnaej]

Delivered by #55 (v1.24.0): verify-forge-doc-consistency + the doc_consistency step. Shipped at v1 scope — CLI-name coverage vs docs/cli-reference.md (the agent-count check was dropped in review as brittle). Link-validation / repo-state-fact checks remain out of scope. [issue-triage] closing as shipped (v1).