Repository navigation
Description
Parent
Refs #15703
Source: #16029, part 2 of #15729. The list recorded in #16602 gives /docs-hygiene:write-for-agents the route "call /corrections:codify, presence-gated, with the strongest-first fallback".
Depends on
- none open. The docs-hygiene cut (Cut the model-read ecosystem specifics from docs-hygiene #16760, no pull request yet) edits
reference/agent-doc-surfaces.mdat its harness table (row F0180, about lines 114-130), not at the lines below. Whichever pull request lands second rebases over the first.
Outcome
When an agent-facing rule must hold every time, write-for-agents today sends it to a mechanism from its own list ("a hook, deny rule or CI check"; "a hook or permission policy"). After this change it hands that choice to /corrections:codify when it is available, with the shared strongest-first fallback when it is not. The writing rules themselves (plain words, no emphasis markers, a missed line means the file needs to be shorter) do not change.
Demo: with a corrections stand-in plugin loaded, ask /docs-hygiene:write-for-agents to add "NEVER commit generated files under dist/" to CLAUDE.md. The skill writes the rule in plain words and names /corrections:codify for a mechanism that holds it every time, instead of naming a hook or CI check itself.
Where the text changes
Line numbers as read on main at a483a2c1; they may move.
| File and lines | Present wording | Change |
|---|---|---|
plugins/docs-hygiene/skills/write-for-agents/SKILL.md:163-167 |
"A rule that must hold every time belongs in a hook, deny rule or CI check; a line that keeps getting missed means the file needs to be shorter." | First clause becomes the gated codify call plus the shared fallback; the second clause stays |
plugins/docs-hygiene/skills/write-for-agents/reference/agent-doc-surfaces.md:51-52 |
"These surfaces are context, not enforcement: a rule that must be mechanically guaranteed belongs in a hook or permission policy, not prose." | Keep "context, not enforcement"; the mechanism goes to /corrections:codify with the fallback |
Call form: /corrections:codify "<the rule>". The skill names it for the user; it does not build the mechanism.
Decisions
-
Design Q21 (Resolve ecosystem specifics from the consumer repository and align the enforcement ladder with the talk's pyramid #15703): a skill that carries no ladder copy reads the ladder by calling codify; only a skill that applies its own selection rule holds a synced copy and a Selection rules row.
-
docs(enforcement-ladder): add the architecture and retro Selection rules rows in ladder 3.2.0 #16602 recorded this skill under "call
/corrections:codify, presence-gated, with the strongest-first fallback (12; change, filed as follow-on items by part 2, List enforcement-placing skills and give each one route to the ladder - part 2 of 2 #16029)". -
The fallback wording is shared by all nine follow-ons of List enforcement-placing skills and give each one route to the ladder - part 2 of 2 #16029. After the gate sentence ("when
/corrections:codifyis among the available skills, hand it the choice of mechanism; it picks the strongest rung of the enforcement ladder that can decide the rule and proves the check"), the fallback is exactly:Otherwise, propose the strongest mechanism that can decide the rule: a change that makes the mistake impossible first, then a check that blocks it, then a test, and an instruction only when nothing a machine runs can decide it. Say that
/corrections:codifywas not available, so the proposal is unproven.
Key interfaces
- "A skill that carries no ladder copy calls
/corrections:codify, presence-gated, with a two-sentence strongest-first fallback. Only a skill that applies its own selection rule holds a synced copy and gets a row in the ladder's Selection rules table." (List enforcement-placing skills and give each one route to the ladder #15729) - The seam-phrasing convention: an availability gate, a stated fallback beside it, the plugin named and never the marketplace.
- ADR 0098 (plain words, no emphasis markers) stays as the rule this paragraph cites.
Done when
- Both sites hand the mechanism choice to
/corrections:codifybehind the availability gate, followed by the shared fallback, and list no mechanisms of their own. - The skill gains no ladder copy or Selection rules row, and no rung list is restated.
- The pull request body quotes the sentence that picked a mechanism from a private list before the change. If the recheck finds none, the skill is left unchanged and the finding is reported on List enforcement-placing skills and give each one route to the ladder - part 2 of 2 #16029.
- One new eval case loads a corrections stand-in plugin, in the shape of session-flow's
re-mechanical-finding-check-proposalcase, and grades that an every-time rule is written in plain words and handed to/corrections:codify, with no mechanism picked by the skill. - The pull request body names the existing case whose run reads the changed text (candidate:
wfa-path-scoped-migration-rule, and the skill's ownevals/evals.json), or says none does. The lane runs no eval. - A changelog fragment under
.changes/docs-hygiene/describes the change. - AC10: no new enforcement-placing skill is added here.
- Open the pull request with
Closesthis issue in its body, then stop: the lane adds no label.
After the pull request opens (host session, not the lane)
The pull request stays held with do-not-merge for the eval; a host session runs only the eval and posts its record; the merge lane releases the hold when the record matches the head.
- Hold line: the hub's sweep (or a host session) adds
do-not-mergeand posts, from a listed human's account, a comment with the line<!-- pr-hold reason=eval -->on a line of its own. - Run budget. List enforcement-placing skills and give each one route to the ladder #15729 asks for "that skill's cases on the
opusandsonnetaliases, three runs per side, and no more than 240 runs per plugin". The owner decision of 2026-11-16 in the owner-decisions record (hop 4 Q15, which names List enforcement-placing skills and give each one route to the ladder #15729, amended by hop 7 Q3) replaces the run counts: per changed skill, one targeted before-and-after case onsonnetat 3 runs a side;opusruns only to confirm a sonnet loss; a new case gets a 1 to 3 run smoke first. Select cases with--case, use--runs 3and a--max-cost-usdceiling, and start no batch after a usage-limit error. Ceiling for this plugin: 1 skill x (3 smoke + 6 sonnet + 6 opus confirm) = 15 runs, under the parent's 240. - Control: the removed mechanism list is a partial cut, so the pull request body carries a detection-control result. No paired no-loss compare (#15703 comment 6906800940).
- On a LOSS reading: a trace read of each dropped case and an
opusconfirm; only a loss traced to the changed text counts. - Record: the verdict and the control result go into the pull request body. When the run is VALID and shows no loss, the host session posts, from a listed human's account, a comment with the line
<!-- eval-pair verdict=no-loss validity=VALID head=<40-hex head SHA> -->naming the current head, keeping "do not merge" anddo-not-mergeout of that comment (docs/contracts/loop-lane/README.md, "Cross-lane PR hold"). A loss or a run that is not VALID leaves the hold in place; say so on the pull request. - Release: pr-merge's scheduled step "Release eval holds whose record matches the head" removes
do-not-mergeonce that record names the current head and no other hold stands. A push after the record needs a new record.
Out of scope
- The rest of write-for-agents' writing rules and every other docs-hygiene skill.
- The docs-hygiene ecosystem cut (Cut the model-read ecosystem specifics from docs-hygiene #16760).
Related
- Resolve ecosystem specifics from the consumer repository and align the enforcement ladder with the talk's pyramid #15703 (container)
- List enforcement-placing skills and give each one route to the ladder #15729
- List enforcement-placing skills and give each one route to the ladder - part 2 of 2 #16029
- docs(enforcement-ladder): add the architecture and retro Selection rules rows in ladder 3.2.0 #16602
Metadata
Metadata
Assignees
Labels
Type
Fields
Work status
Priority
Activity
github-actions commentedon Nov 18, 2026
Size: Small
Complexity: Low
Uncertainty: Known
Flags: none
Blocked by: none
Blast radius: two text sites in the docs-hygiene write-for-agents skill, one new eval case, and one changelog fragment; read by agents running that skill.
Reversible: yes; revert the pull request.
Open questions: none
Understood: replace the private mechanism lists at the two named sites with a gated hand-off to /corrections:codify plus the shared fallback, add one eval case and a changelog fragment. The scope and done-when are exact. The sibling follow-ons for other plugins are separate work, not duplicates. No merged pull request already covers this.
Automated triage. A maintainer reviews it.
melodic-automation-lanes commentedon Nov 18, 2026
Not admitted to the issue lane: its done-when asks for what an unattended lane run cannot perform: item 3 (tracker-output: "The pull request body quotes the sentence that picked a mechanism from a priv..."), item 4 (eval: "One new eval case loads a corrections stand-in plugin, in the shape of sessio..."); recommended split: keep the other items here as the admissible issue and move these to a child issue for the host queue (
host-run). Admission takes the issue once each of those is met, when intake triages it again (.github/actions/resolve-config/admission-rules.json).melodic-automation-lanes commentedon Nov 18, 2026
Refinement. A read-only run explored this repository, searched its issues and pull requests, and read the allowed docs to draft what follows. On an issue a listed human filed, it counts as the issue's spec once posted, while unedited; it is still model text, so check it.
Intended outcome: write-for-agents hands the every-time-rule mechanism choice at both sites to /corrections:codify behind an availability gate with the shared fallback, with a changelog fragment and no ladder copy.
Split. Done-when items 3, 4 of the issue body need a person: they are checks a person runs, listed below, and the lane does not do them. This issue keeps the rest of its done-when.
Not done by the lane: checks a person runs
External state: none
Related work
Sources read
Automated refinement by the lanes App. Intake triages the issue again with it.
melodic-automation-lanes commentedon Nov 18, 2026
{"v":1,"actor_id":337595936,"title_sha256":"c4333f60532a8df8e41b4bd0bd240b154b9740465cde4aa3991b36a9b838701e","body_sha256":"7021a3cf468ba0d5c816588e31552336ebb320d34e4206222ad2ece1538e98e1"}
melodic-automation-lanes commentedon Nov 18, 2026
{"v":1,"actor_id":337595936,"title_sha256":"c4333f60532a8df8e41b4bd0bd240b154b9740465cde4aa3991b36a9b838701e","body_sha256":"7021a3cf468ba0d5c816588e31552336ebb320d34e4206222ad2ece1538e98e1"}
5 remaining items
github-actions commentedon Nov 19, 2026
melodic-automation-lanes commentedon Nov 19, 2026
The work-resolve-issue lane stopped on this issue (
issue-edited-trusted): the issue's title or body changed after agent-ready was added, and every change came from a listed human or one of our listed Apps, so intake triage refines and admits the edited text again.It set Work status to needs-triage, so the hourly triage sweep sends it back through intake triage, and it waits on no decision from a person.
In the run's words:
Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/44443843235
github-actions commentedon Nov 19, 2026
The triage sweep dispatched intake triage for this issue (dispatch 2; 2 runs that reach intake, or 6 dispatches, hand it to a maintainer).
melodic-automation-lanes commentedon Nov 19, 2026
{"v":1,"actor_id":337595936,"title_sha256":"c4333f60532a8df8e41b4bd0bd240b154b9740465cde4aa3991b36a9b838701e","body_sha256":"7021a3cf468ba0d5c816588e31552336ebb320d34e4206222ad2ece1538e98e1"}
melodic-automation-lanes commentedon Nov 19, 2026
{"v":1,"actor_id":337595936,"title_sha256":"c4333f60532a8df8e41b4bd0bd240b154b9740465cde4aa3991b36a9b838701e","body_sha256":"7021a3cf468ba0d5c816588e31552336ebb320d34e4206222ad2ece1538e98e1"}
github-actions commentedon Nov 19, 2026
github-actions commentedon Nov 19, 2026