docs-consolidate

Documentation consolidation

An audit, not a rewrite. It reports; you decide; only then does anything change.

Google's opendocs defines the audit archetype as inventory + analysis + recommendations, "explicitly excluding the writing or editing of docs based on those results". That separation is the point: LLM inconsistency detection is nowhere near reliable enough to edit unsupervised, and an autonomous rewrite would be confidently wrong at exactly the rate that matters.

This never blocks anything. If the user is mid-task, say what you found and let them come back to it.

--init

Adopt the trigger in this repo.

--init starts the clock; it does not audit. The audited= SHA it writes means "drift is measured from here", not "these docs were verified at this commit". Say that to the user when you run it, because the trigger will then stay silent for threshold − 1 commits over docs nobody has checked. If the repo's docs are of unknown quality, offer to run a full pass immediately after adopting.

1. Refuse if the record would be ignored. git check-ignore .docs-sync matching means the file would never reach a teammate's clone — stop and say so rather than creating a record that silently does nothing. (This is what ruled out putting it under .claude/: transcoder gitignores that directory.)

2. Write .docs-sync at the repo root:

   docs-sync: audited=<git rev-parse HEAD>
   Recorded: <ISO-8601 UTC>
   Run /docs-consolidate — do not hand-edit the audited= line.
   

   The second line says Recorded, not "Last consolidation", and both --init and a re-stamp use the same wording. At adoption no consolidation has happened, so a line claiming one would be false in the file whose entire job is to not make false claims.

3. Commit it. Then assert audited == git rev-parse HEAD~1 — the record names the commit whose tree was audited, which is the parent of the commit containing the record, because a file cannot carry the SHA of the commit that contains it.