Skip to content

Reconciling docs-gate (FLT-64) with WorkWingman's docs job (WING-3)

Decision record, 2026-07-15. Two documentation gates were built in parallel by different sessions, and WorkWingman is in scope for both. This says who owns what, and why.

The two

WING-3 docs-gate (FLT-64)
Where WorkWingman/.github/workflows/ci.yml, bash standalone C# CLI + composite action
Scope WorkWingman only 22 fleet repos
Exemptions inline case lists in bash docs-gate.json

WING-3 rules: two-track pairing (technical ↔ plain siblings) · orphan reachability · relative links inside docs/ resolve · source changes ship docs changes · architecture changes carry diagram updates · making-of story beat (soft) · .d2 → SVG drift check.

docs-gate rules: required docs · link-integrity across all claim shapes, repo-bounded · making-of cites resolvable SHAs · content-binding via reviewed-at-commit · coverage floor over modules · diagram presence · board key format.

Verdict: docs-gate is the engine, WING-3 has the better rules

Not a merge of equals. They solve different halves and each is wrong where the other is right.

Port INTO docs-gate (WING-3 wins outright):

  1. Two-track pairing. docs-gate names five required files; WING-3 enforces that every technical doc has a plain sibling. Its exemption test is the best-shaped rule in either gate: "who reads it? — a doc earns exemption only when its audience is US, never a user." That is a criterion someone can be wrong about, which is what makes it a rule and not a vibe.
  2. Orphan reachability. docs-gate cannot see this at all. Orphan docs rot.
  3. Diagram drift (.d2 → SVG) and architecture→diagram coupling. docs-gate's diagram rule is presence-only and says so; WING-3 actually proves the diagram matches its source. Strictly better.

Retire on merge:

  • WING-3 Gate 2b (doc links resolve) — subsumed by docs-gate link-integrity, which parses reference links, HTML links, fenced blocks and globs. Gate 2b handles inline links only and documents that limit.
  • docs-gate diagram-presence — replaced by the drift check above.

The one real conflict, and how it is settled

WING-3 deliberately refuses to check links that escape into src/:

enforcing source paths here would red the docs job on every unrelated code move

docs-gate does exactly that, and it is the anti-hallucination core — it is what catches a repo citing src/cli/client.ts across four documents while having no src/ directory at all.

Both are right about different failures:

  • WING-3's objection is about drift — code moves, docs lag, the job reds for an unrelated reason. They solve it with co-change (Gate 3: touch src/, touch docs/).
  • docs-gate solves drift with content-binding (reviewed-at-commit + a staleness budget), which tolerates lag up to a threshold instead of demanding same-PR edits.

Settled: keep source-path link-integrity, keep content-binding, drop Gate 3. Reason: Gate 3's escape hatch is [skip docs] in a commit message — no reason required, no census, and nothing left in the tree to review. Content-binding's equivalent (reviewed-at-commit) is at least a line in a file that a reviewer can see and challenge. Both are gameable; only one is gameable in the open.

Finding against WING-3, raised 2026-07-15

[skip docs] and [skip diagrams] are commit-message mute buttons. This is the same defect a council review found in docs-gate's own allow-example-paths on 2026-07-15 and rated Critical: an exemption that applies wholesale, needs no justification, and is invisible after the fact. docs-gate's hatch was rewritten to name each exempted path, require reason="...", and print a census of every file claiming it. WING-3's hatches should get the same treatment before that gate starts enforcing — a commit-message hatch is worse, because it leaves no trace in the repository at all.

Raised as a finding, not a change. WING-3 is another session's branch (wt/WT-2ea1/WING-3).

Migration order (nothing goes gateless)

  1. Port two-track pairing, orphan reachability, diagram drift into docs-gate as rules.
  2. Reach parity, verified by running docs-gate against WorkWingman and diffing its findings against what the docs job reports. Parity means: no rule WorkWingman relies on today reports less.
  3. WorkWingman swaps its docs job for the pinned action; its bash gates are deleted in the same PR.
  4. Exemptions move from inline case lists into docs-gate.json, one mechanism, visible in review.

WorkWingman's ci.yml stays exactly as-is until step 3. Deleting a working gate to make room for an unfinished one is how repos end up with neither.

Status

Decision recorded. The port is not started — governor RED, and it is implementation work that should go to Codex/Gemini rather than run inline. docs-gate itself enforces nothing yet, so there is no collision today; this only becomes urgent when either gate flips to hard-fail.