Skip to content

feat(docs-hygiene): hand an every-time rule's mechanism in write-for-agents to /corrections:codify #17159

Description

@kyle-sexton

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

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

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:codify behind 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-proposal case, 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 own evals/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 Closes this 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-merge and 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 opus and sonnet aliases, 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 on sonnet at 3 runs a side; opus runs only to confirm a sonnet loss; a new case gets a 1 to 3 run smoke first. Select cases with --case, use --runs 3 and a --max-cost-usd ceiling, 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 opus confirm; 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" and do-not-merge out 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-merge once that record names the current head and no other hold stands. A push after the record needs a new record.

Out of scope

Related

Activity

  1. added
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    on Nov 18, 2026
  2. added
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Nov 18, 2026
  3. github-actions commented on Nov 18, 2026

    @github-actions
    Contributor

    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.

  4. removed
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Nov 18, 2026
  5. melodic-automation-lanes commented on Nov 18, 2026

    @melodic-automation-lanes
    Contributor

    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).

  6. melodic-automation-lanes commented on Nov 18, 2026

    @melodic-automation-lanes
    Contributor

    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

    • plugins/docs-hygiene/skills/write-for-agents/SKILL.md:166: 'A rule that must hold every time belongs in a hook, deny rule or CI check; a line that...' is the first site to change
    • plugins/docs-hygiene/skills/write-for-agents/reference/agent-doc-surfaces.md:52: 'in a hook or permission policy, not prose' is the second site to change
    • plugins/docs-hygiene/CHANGELOG.md:154: earlier release entry describing the current mechanism list (history, not edited)
    • plugins/session-flow/skills/*/evals/evals.json: session-flow eval files exist, the shape reference for the new case

    Automated refinement by the lanes App. Intake triages the issue again with it.

  7. melodic-automation-lanes commented on Nov 18, 2026

    @melodic-automation-lanes
    Contributor

    {"v":1,"actor_id":337595936,"title_sha256":"c4333f60532a8df8e41b4bd0bd240b154b9740465cde4aa3991b36a9b838701e","body_sha256":"7021a3cf468ba0d5c816588e31552336ebb320d34e4206222ad2ece1538e98e1"}

  8. melodic-automation-lanes commented on Nov 18, 2026

    @melodic-automation-lanes
    Contributor

    {"v":1,"actor_id":337595936,"title_sha256":"c4333f60532a8df8e41b4bd0bd240b154b9740465cde4aa3991b36a9b838701e","body_sha256":"7021a3cf468ba0d5c816588e31552336ebb320d34e4206222ad2ece1538e98e1"}

  9. 5 remaining items

  10. github-actions commented on Nov 19, 2026

    @github-actions
    Contributor
    No description provided.
  11. melodic-automation-lanes commented on Nov 19, 2026

    @melodic-automation-lanes
    Contributor

    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:

    The run did not start: the issue's title or body changed after agent-ready was added, each change by a listed account, so the runner wrote no issue file for the skill and no model ran.

    Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/44443843235

  12. github-actions commented on Nov 19, 2026

    @github-actions
    Contributor

    The triage sweep dispatched intake triage for this issue (dispatch 2; 2 runs that reach intake, or 6 dispatches, hand it to a maintainer).

  13. melodic-automation-lanes commented on Nov 19, 2026

    @melodic-automation-lanes
    Contributor

    {"v":1,"actor_id":337595936,"title_sha256":"c4333f60532a8df8e41b4bd0bd240b154b9740465cde4aa3991b36a9b838701e","body_sha256":"7021a3cf468ba0d5c816588e31552336ebb320d34e4206222ad2ece1538e98e1"}

  14. melodic-automation-lanes commented on Nov 19, 2026

    @melodic-automation-lanes
    Contributor

    {"v":1,"actor_id":337595936,"title_sha256":"c4333f60532a8df8e41b4bd0bd240b154b9740465cde4aa3991b36a9b838701e","body_sha256":"7021a3cf468ba0d5c816588e31552336ebb320d34e4206222ad2ece1538e98e1"}

  15. github-actions commented on Nov 19, 2026

    @github-actions
    Contributor
    No description provided.
  16. github-actions commented on Nov 19, 2026

    @github-actions
    Contributor
    No description provided.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.

    Type

    Fields

    Work status

    needs-triage

    Priority

    medium

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions