evlog Content Pass

Content pass

One pass, one group, one pull request. The corpus is roughly 150 files: the docs tree and the landing, the four package READMEs, the internal and published skills, and the three AGENTS.md files. When the scanner's own count differs, the scanner wins. None of that gets fixed in a day, and trying is how a rewriter starts rewriting for its own sake.

Half the corpus is read by people and half by agents, and the pass treats them differently. A skill or an AGENTS.md governs the agent running this pass, so it may fix a house rule there (punctuation, a dead link, a retired entry point, a wrong term) and nothing else. Procedure, bounds, and a skill's description come back as findings for Hugo. That is M-09 in the doctrine, and content-targets enforces it by returning those files with mode report.

The doctrine lives in the repository, at .agents/skills/write-evlog-content/. This file is the procedure; that skill is the standard. Never restate its rules here. Read them there, and when they are wrong, fix them there.

The two halves

Rewrite is the default: the scanner ranks the corpus, the worst pages get reviewed, and what survives review gets applied.

Enrich is what runs when the rewrite half comes back empty, with no page above the bar or everything ranked inside its cooldown. That is a good day, not a wasted one. Switch to the second half rather than lowering the bar.

Never run both in one pass. A PR that rewrites two pages and adds a third is a PR nobody reviews properly.

Rewrite

1. Pick the targets

Call content-targets. It runs the scanner over the whole corpus, drops files changed inside the cooldown, and returns the top files from a single group with their candidates. A group is one docs section, one skill's directory, or a flat surface (readme, agents, landing).

Pass surface when Hugo asked for one, or when the weekly corpus check found a surface drifting. Otherwise take what ranks.

Read eligible before deciding anything. It is the count of files with findings that are outside the cooldown, and it is the only number that says whether there is work. eligible: 0 sends you to Enrich. Anything above zero means the rewrite half has targets, and the pass rewrites.

Write the three numbers into the PR body verbatim: scanned, candidates, eligible. A pass that says the rewrite half was empty without them is asserting, not reporting, and a corpus of 120 files with 47 eligible pages has been called empty before.

2. Branch

In /workspace/repo, from a fresh main:

git -C /workspace/repo checkout -B content/<group>-<slug> origin/main

Slugify the group: .agents/skills/create-adapter becomes skills-create-adapter.

3. Apply the derivable fixes first

node scripts/content-lint/index.mjs <each target> --fix

This rewrites only what follows from the rule rather than from taste: a retired entry point, a term with one replacement, a link with a redirect behind it. Dashes are not mechanical and stay findings for the reviewer. It re-scans each file afterwards and reverts anything that scored worse or introduced a new id, so a reverted file is a bug to report, not a file to retry.

Keep these page edits uncommitted until verification. The content agents share the parent's actual workspace, including new pages and local edits. Source code changes must be committed before capturing an identity; a local commit is sufficient. Never change Git state or write files while a reviewer is reading them.

Then re-run content-targets. A file whose findings were all mechanical now comes back clean and is dropped from the pass. Never send a reviewer a finding a codemod already fixed: it costs a dispatch and it teaches the reviewer that findings are cheap.

4. Review, in parallel

Call content_snapshot for each target. Dispatch content_review once per target with the returned identity, its surface, candidates and modelChecks. Include factual sources and executed-check results, but not your interpretation or preferred verdict. Content agents explicitly share the parent sandbox and call content_load to check the digest and source revision before reading. A load failure blocks that page; capture it again rather than substituting another version.

The candidates are what tripped a counter. The modelChecks are what no counter reached on that page, and the reviewer answers every one of them. Pass them through as they came; they are chosen per surface and per page, and editing them is how a pass quietly stops checking something.

The reviewer returns a verdict. pass means that page is done for this run; do not rewrite it, do not ask again.

5. Rewrite, in parallel

For every target whose snapshot loaded successfully, whose verdict is not pass and whose mode is rewrite, dispatch content_rewrite with the same snapshot and that page's findings. A blocked verdict from a failed snapshot load means the page was never reviewed: recapture it and send it back to review before rewriting. A verdict blocked on critical findings means the page was reviewed and refused: rewriting those findings is allowed.

The rewriter returns full replacement text and the original digest. Wait for all readers to finish. Before each edit, call content_snapshot again and compare both the revision and digest with the rewrite input. If either changed, capture and review the current page again. Otherwise, read the file and apply only the reviewed changes serially with the parent’s existing editing tools. Do not run other file writes or Git changes concurrently. This check is not an atomic write guard: if another writer is active, stop editing until access is coordinated. After saving, capture a fresh snapshot of the actual file for verification; the proposed text is not evidence of what was saved.

Targets with mode report skip this step: the landing page absent a critical finding, and any skill or AGENTS.md whose findings go past the house rules. Their findings go in the PR body for Hugo to decide on. Do not edit the landing page for voice or rhythm, and do not touch a procedure, a bound, or a description.

6. Verify

In the sandbox:

node scripts/content-lint/index.mjs <each changed file>
git -C /workspace/repo diff --stat

Then the checks the changed files actually need:

• A docs page or the landing: run the docs lint and content tests, parse changed frontmatter with the actual content parser, and inspect the rendered title, description and changed MDC. Run changed executable examples against the relevant package and runtime. A passing prose scan does not verify metadata, APIs or rendered output.
• A skill or an AGENTS.md: nothing builds these, so the check is the scanner plus reading the diff. Every relative link is resolved by U-16, so a dead cross-reference shows up in the scan.
• packages/evlog/README.md: this one ships to npm. It needs a changeset (patch), and the automd blocks are regenerated rather than hand-edited. The other three package READMEs follow the same rule.

What you are checking:

• Correctness is the blocking check. Send every freshly captured saved snapshot through content_review again, with the previous critical findings and execution evidence. Confirm the reported revision and digest match the saved snapshot, and that critical findings are resolved. Missing evidence remains explicitly unverified.
• Review new scanner candidates against their legitimate twins. Do not revert a factual correction solely because its style score fell. Explain a confirmed false positive in the PR and propose a narrow scanner correction; do not weaken thresholds or add filler to satisfy the score. A required CI failure blocks the PR: fix it or report the blocker.
• The diff touches only the target files. A stray change to a component, a config, or a package is a bug in the pass, not a bonus.
• Frontmatter and MDC structure survived. Read the diff, not just the score.

If verification finds a concrete new defect, send that finding back for a targeted correction and rerun affected checks. Do not retry for style variation alone. If the defect cannot be resolved, do not open the PR; report the blocker.

Before opening the PR, read the changed pages together: state the reader question each answers, remove duplicated explanations where a link suffices, and resolve contradictory promises. Record which checks ran on which revision. After further edits, rerun affected checks rather than carrying a stale pass forward.