Docs format invariants: what to review

Field	Value
Branch	feat/admin-and-merchant-portals, draft PR #976: feat(admin): portal navigation, financials and monitoring, plus the agent-process work behind them, not merged
Project	README.md
Issue	#954: feat(tooling): a gate that checks a document's stated rules against its own templates
Servers you need	None. There is nothing to click. This is a lint gate
Local origins	Not applicable

Is there anything to look at?

One command, and it is the whole review.

npm run lint:docs-format

• It should pass. It runs inside npm run validate under the lint scope, as Docs Format Invariants.
• To see it fire, add a bare issue number with no title (say #123) to a fenced template inside .agents/skills/agenda-documentation/skill.md and run it again.

What changed here?

A document that states a rule in prose and also ships a template has that rule written twice, and nothing kept the two in agreement.

• .agents/rules/project/writing-into-documents.md calls this the most expensive drift in the repo, and it was the one gate that did not exist.
• When the two disagree the TEMPLATE wins, because an agent told to follow a format copies the shape rather than reading the argument for it.
• agenda-documentation drifted six times on 2026-08-24 alone. It carried three renderings of the same log entry, and it said "every issue is a link carrying its real title" while none of its three templates held a single reference.

A generic prose-versus-template checker is not buildable, so the file DECLARES its invariants and the checker reads them in two directions.

• The skill owns a yaml invariants block. select finds candidate lines, unless excuses some, and exactly one of require or forbid decides.
• Direction one is the skill's own fenced templates. Direction two is a document the skill produced, which for agenda-documentation is the latest dated agenda in your context home.
• A rule that is not in the block is not enforced. That is deliberate: the block is the machine-readable half of the document, not a summary of it.

Templates are enforced at ZERO. The produced agenda is ratcheted.

• A template lives in the repo and is the copy that ships, so a violation there propagates into every later build. There is no baseline for them.
• The agenda is a living file several sessions write during the day, so its violations sit in docs-format-baseline.json as a burn-down list.

Four template violations in agenda-documentation were found and fixed in the same change.

• Including a bare issue number inside a Watch out line, in the one file whose prose says a reference always carries its title.

What is deliberately NOT done?

The 48 grandfathered agenda violations were not fixed, and burning them down is YOUR decision, not an agent's.

Invariant	Count	What it is
issue-ref-carries-title	33	Bare #N references, plus one bare linked number
main-quest-time-block	11	Main quests written as a bold time rather than a time range
bold-paragraph-is-a-heading	4	A claim standing as a bold paragraph instead of taking a heading
session-heading-checkbox	1	A status emoji where the checkbox belongs

• The ceiling moved three times in twenty minutes, and that is the finding rather than a flaw in the ratchet. The agenda breaks the first two SYSTEMATICALLY, so every appended quest or issue mention re-breaks them.
• The fork: burn the two down in one PM pass, or drop the produced-document direction to a warning until they are clean. Deliberately left undecided.

The produced-document direction does not run in CI.

• The agenda lives outside the repo, so CI has no file to read. The checker reports SKIPPED and names why.
• Zero findings against a file that was never read is not the same fact as zero findings, and reporting the stronger one is how a gate sits green while the thing it guards drifts.

No other skill declares invariants yet.

• The checker scans every .agents/skills/*/skill.md for a declaration, so a second skill opts in by adding a block. Nothing else was migrated.

What open findings touch this project?

Cross-referenced from ../merchant-and-venue-dashboards/branch-review-0828.md.

--update-baseline combined with --skill deletes every other skill's grandfathered counts. lint.docs-format.js:451

• It writes the baseline from only the skills processed in this run. The CI-skip path at line 410 already merges correctly; this path does not.
• Open, not fixed. Practical consequence: do not run npm run lint:docs-format:update-baseline scoped to one skill.

The reviewer named its own limit here.

• lint.docs-format.js (479 new lines) got a targeted pass, not a line-by-line read. Treat the rest of that file as unreviewed.

What issue does each piece close?

Piece	Issue	State
The gate	#954: feat(tooling): a gate that checks a document's stated rules against its own templates	Built, green, in validate
The sibling gate one layer up	#952: docs(agents): agent asset hierarchy, plus a drift gate for the workflows layer	Merged, in ../agent-workflow-hierarchy/README.md