@event4u/agent-config 14.9.0 → 14.11.0

package/dist/agent-src/rules/active-remediation.md

@@ -17,7 +17,7 @@ routes_to:
 workspaces: [engineering]
 packs: [engineering-base]
 enforced_by:
-  - "none"
+  - "instruction-only: the note, the ask and the user decision are all prose, so no gate can tell a discharged issue from a mentioned one"
 collision_ok:
   "refactor": "an explicit clean-up/refactor ask is the remediation ladder's own trigger"
 # obligation: line 31
@@ -97,11 +97,11 @@ While implementing/modifying code you pass an issue outside the literal task. Al
 - The issue is the task itself — then it's just the task (no ladder needed).
 - The user already decided this item (fixed later, or explicitly ignored).
 
-## Honest enforcement — `enforced_by: none`
+## Honest enforcement — `instruction-only`
 
 The note, the ask and the user's decision are all prose, and the issue set is
 whatever the agent happened to see, so no gate can tell a discharged issue from a
-mentioned one. This rule ships `enforced_by: none` — the honesty boundary
+mentioned one. This rule ships `instruction-only` — the honesty boundary
 [`security-sensitive-stop`](security-sensitive-stop.md) and
 [`ui-audit-gate`](ui-audit-gate.md) state for their own obligations. The ladder
 is the control; skipping it is caught by nothing.

package/dist/agent-src/rules/code-provenance.md

@@ -22,7 +22,7 @@ workspaces: [engineering]
 packs: [engineering-base]
 roles: [developer, reviewer, tester, po, incident, planner]
 enforced_by:
-  - "none"
+  - "instruction-only: close-the-source-and-re-derive is a pre-write reasoning step only the model observes; CI checks the ledger, never the derivation"
 # obligation: line 40
 obligation_frequency: "per-edit"
 ---
@@ -129,7 +129,7 @@ checks the ledger's own records, not similarity, and cannot catch an
 unrecorded borrow. The discipline above **is** the control; skipping it is
 not caught downstream by anything automatic. No script can enforce "close
 the source and re-derive" — a pre-write reasoning step only the model
-observes — so this rule ships `enforced_by: none`, same honesty stance as
+observes — so this rule ships `instruction-only`, same honesty stance as
 `security-sensitive-stop` and `untrusted-input-defense`.
 
 `lint_harvest_provenance.ts` stands in exactly the same relation to the

package/dist/agent-src/rules/context-hygiene.md

@@ -2,6 +2,10 @@
 type: "auto"
 tier: "1"
 alwaysApply: false
+norm:
+  tokens: 2000
+  remainder:
+    - "../docs/guidelines/agent-infra/context-hygiene-mechanics.md"
 description: "Debugging, fixing errors, or long conversations — 3-failure stop rule, tool-loop detection, fresh-chat triggers"
 triggers:
   - keyword: "3-failure"
@@ -81,37 +85,14 @@ A NUMBER THAT CHANGED IS NOT NEW INFORMATION UNLESS IT CHANGES WHAT YOU DO NEXT.
 ```
 
 Waiting on something external — CI, a deploy, a queue, a background job — is the
-one shape the loop test above systematically misses, in both of its clauses.
-
-- **"Same parameters" fails.** A `sleep 240` followed by `sleep 420` followed by
-  `sleep 595` are three different calls by any parameter comparison, so nothing
-  reads them as repetition.
-- **"Repetition without new information" fails too**, and this is the subtler
-  half: the poll genuinely returns a different value each round — 31 green, then
-  34, then 36 — which *feels* like progress. It is not information unless a
-  different digit would make you act differently. It would not: the only actions
-  available were wait, or stop and report, and 34 licensed neither more than 31
-  did. **The discriminator is the decision, not the digits.**
-
-For CI, do not hand-write the loop: `ci_settle <pr>` (mechanics below).
-
-So state it separately: pick **one** waiter for the condition and let it finish.
-Where the harness re-invokes on completion, waiting costs nothing and polling
-costs a turn per expiry — and every stacked waiter is a turn that arrives *after*
-the answer already did. Where it does not, one `until <condition>` loop is still
-one call rather than N.
-
-**Measured once, at n=1, and worth naming for its shape rather than its
-frequency** (2026-08-12): a CI wait started roughly 35 background commands —
-a fresh timer *and* a fresh condition-watcher per round, none cancelled when the
-next pair started. CI settled with about fifteen still live; each then expired
-and produced an empty turn. Nothing was corrupted, which is exactly why it ran
-so long: every individual step looked reasonable.
-
-**Enforcement: none, and the reason is structural.** The `context-hygiene` hook
-counts tool calls; a waiter is indistinguishable from any other call at that
-layer, and nothing in the envelope says two live waiters are watching one
-condition. This is model-carried on every host.
+one shape the loop test above systematically misses. Pick **one** waiter for the
+condition and let it finish; for CI use `ci_settle <pr>` rather than a
+hand-written loop. Enforcement is `none` and structurally so: the hook counts
+tool calls and a waiter is indistinguishable from any other call at that layer.
+
+Why the loop test misses it in both clauses, the n=1 measurement behind the
+clause, and the enforcement argument: [`context-hygiene-mechanics § Waiting is one
+waiter`](../docs/guidelines/agent-infra/context-hygiene-mechanics.md).
 
 ## Read-Loop Detection — the 15 / 25 rule
 
@@ -134,8 +115,7 @@ A mandated analysis/audit/review protocol is exactly the case that legitimately
 - **Undeclared reading keeps 3-warn / 5-abort.** Unchanged.
 - **A declared protocol raises the abort to 8 read-only turns** — and never suspends it. "Non-bypassable" narrows to **no *silent* bypass**: a declared protocol is not silent.
 
-> **The 8 is a guess, and specifically a LOWER BOUND.** One observed run — the coherence audit that motivated this clause — needed 8+ read turns and was legibly the protocol working, not a loop. So 8 is "the number that was enough once", not a measured optimum: n=1 says almost nothing about where the tail of the distribution sits, and nobody knows how many sessions silently hit the old 5 and should have continued. Calling this a derivation would be false advertising, which is the same failure class as the "17 rules carry absolutes" figure this rule's own roadmap refuted.
-> **Revisit-if — whichever comes first:** (a) **≥ 10 declared-protocol sessions** have been observed, at which point set the cap from their p95 and delete this note; or (b) **90 days** elapse with fewer than 10, which is itself the answer — declared protocols are rare, the cap is not load-bearing, and it drops back to the undeclared 5. A condition like "once a distribution exists" was rejected as unfalsifiable: it is gradual, never feels urgent, and absence of complaints is indistinguishable from absence of measurement.
+> **The 8 is a guess, a LOWER BOUND, and revisitable** — derivation, the n=1 run behind it, and the two-branch `revisit-if`: [`context-hygiene-mechanics § The declared-protocol cap`](../docs/guidelines/agent-infra/context-hygiene-mechanics.md).
 
 A declaration is only valid when it states, before the reading starts, all three of:
 

package/dist/agent-src/rules/council-availability.md

@@ -13,7 +13,7 @@ self_contained: true
 workspaces: [agent-config-maintainer, construction, engineering, finance, founder, gtm, legal-review-prep, ops, product, small-business]
 packs: [meta]
 enforced_by:
-  - "none"
+  - "instruction-only: no gate reads a chat claim about availability; check_council_config_location covers the tree side only"
 # obligation: line 27
 obligation_frequency: "per-task"
 ---
@@ -79,7 +79,7 @@ Availability is already settled this session, or the question is about council
 
 ## Enforcement
 
-`enforced_by: none` — no gate reads a chat claim. Deterministic instead:
+`instruction-only` — no gate reads a chat claim. Deterministic instead:
 `check_council_config_location` fails the build when a council surface ties the
 config to `.agent-settings.yml`, which never carried it, or to a project-tree
 path, and its §4 fails when no always-loaded rule carries this fact at all.

package/dist/agent-src/rules/decision-revisit-gate.md

@@ -23,6 +23,8 @@ packs: [meta]
 collision_ok:
   "honest null": "this rule asks whether a recorded null may be REVISITED; evaluator-independence asks how one was PRODUCED — different decision points on the same artefact"
 # obligation: line 31
+enforced_by:
+  - "instruction-only: no gate can observe an agent citing a decision it never opened; adr_cite_check is deterministic where it runs and nothing makes it run"
 obligation_frequency: "per-task"
 ---
 
@@ -176,7 +178,7 @@ precedent-creates-no-authority clause: [`adr-layout § Reopen authority`](../doc
 - [`ask-when-uncertain`](ask-when-uncertain.md) — the numbered-options shape
   used to present the revisit offer.
 
-## Honest enforcement — `enforced_by: none`
+## Honest enforcement — `instruction-only`
 
 `adr_cite_check` is deterministic where it runs, and nothing makes it run. No
 gate can observe an agent citing a decision it never opened, so step 2 above is

package/dist/agent-src/rules/design-fidelity.md

@@ -89,6 +89,24 @@ this": a prototype (HTML / JSX / Figma export), a mockup or screenshot, a
 design-system file (tokens, component library), or a URL / path. It encodes
 decisions already made — treat it like brand tokens, not like inspiration.
 
+## Two axes — artefact maturity is not instruction mandate
+
+```
+MATURITY IS A PROPERTY OF THE ARTEFACT. MANDATE IS A PROPERTY OF THE INSTRUCTION.
+A HANDOVER WHOSE OWN ARTEFACT DECLARES ITSELF LOW-FIDELITY CARRIES A **STRUCTURE**
+MANDATE, NEVER A **PIXEL** MANDATE — WHATEVER `design.fidelity_mode` SAYS.
+REPRODUCING A WIREFRAME'S GREYS 1:1 HONOURS THE WRONG HALF OF THE ARTEFACT.
+```
+
+`strict` means *do not redesign*; never *reproduce a wireframe's placeholder greys*, which
+are **non-decisions** ([`wireframe`](../skills/wireframe/SKILL.md) § Gotchas).
+**The discriminator reads the ARTEFACT, never the prose.** A finished comp whose prose
+mentions a wireframe it replaces routes **strictly** — a reference to a previous artefact,
+not a declaration about this one. **When the artefact does not declare its maturity,
+it is treated as finished**: the 1:1 floor is stricter, and guessing *low fidelity*
+would authorise the redesign this rule prevents. Maturity→spec table + the pinned near-miss:
+[`design-fidelity-mechanics § Artefact maturity`](../docs/guidelines/design-fidelity-mechanics.md).
+
 ## Strictness — set by `design.fidelity_mode`
 
 Read `design.fidelity_mode` from `.agent-settings.yml`. Missing → `strict`.

package/dist/agent-src/rules/design-review-after-ui-write.md

@@ -27,7 +27,7 @@ routes_to:
 workspaces: [agent-config-maintainer, engineering]
 packs: [frontend-design]
 enforced_by:
-  - "none"
+  - "instruction-only: no artefact proves a design review happened outside the work-engine dispatcher; the review verdict is self-report"
 collision_ok:
   # The "component" and "design token" entries were removed with their triggers
   # (2026-08-17): a collision note for a trigger that no longer exists is an
@@ -107,7 +107,7 @@ AS IF IT WERE VERIFIED.
 
 There is no artefact a chat session can point at to prove a design review
 happened — "I ran `design-review`" is self-report, and self-report is not
-enforcement. So this rule ships `enforced_by: none`, the same honesty boundary
+enforcement. So this rule ships `instruction-only`, the same honesty boundary
 `ui-audit-gate`, `security-sensitive-stop`, and `untrusted-input-defense` state
 for their own obligations, rather than pretending a satisfiable-by-assertion
 condition is a gate.

package/dist/agent-src/rules/evaluator-independence.md

@@ -2,6 +2,10 @@
 type: "auto"
 tier: "2a"
 alwaysApply: false
+norm:
+  tokens: 1500
+  remainder:
+    - "../docs/guidelines/agent-infra/evaluator-independence-mechanics.md"
 description: "Commissioning a review/judge/blind-pass on your own work — never author the verdict, never narrow the scope, record the prompt with the result"
 triggers:
   - keyword: "blind review"
@@ -13,6 +17,8 @@ triggers:
   - phrase: "review my own"
   - phrase: "commission a review"
   - phrase: "second opinion on my"
+routes_to:
+  - "guideline:agent-infra/evaluator-independence-mechanics"
 self_contained: true
 workspaces: [engineering]
 packs: [engineering-base]
@@ -73,6 +79,29 @@ was manufactured anyway.
 4. **One evaluation per turn per subject.** Re-running with a different prompt or
    scope after an unwelcome verdict selects the answer instead of measuring it.
 
+## The softer form — stating an expectation without stating the verdict
+
+The Iron Law forbids **authoring the verdict** into an evaluator's prompt. There is a
+weaker move that evades it while doing the same work, and it is the one an orchestrator
+reaches for without noticing: **stating an expectation.**
+
+```
+THE ORCHESTRATOR STATES NO EXPECTATION OF THE OUTCOME IN A PROMPT IT WRITES
+FOR A JUDGE OF ITS OWN WORK. NOT THE VERDICT, AND NOT THE DIRECTION.
+"THIS SHOULD BE CLEAN", "I BELIEVE THIS IS CORRECT", "JUST CONFIRM",
+"I EXPECT NO FINDINGS" — NONE OF THESE NAME A VERDICT, AND ALL OF THEM SUPPLY ONE.
+```
+
+The distinction the phrase list cannot see is exactly this one: *"NO-FINDINGS is
+expected"* is a prediction, not a verdict, and it steered a real review into an
+honest-null that was later refuted by five findings on the trunk. A prompt that says what
+the author thinks the answer is has authored the answer, whatever grammatical mood it
+used.
+
+**What to write instead:** the scope, the diff, and the question. Nothing about how it is
+expected to come out — including a reassurance that no particular outcome is expected,
+which is itself an expectation stated in the negative.
+
 ## When it does NOT fire
 
 - **Ordinary parallel fan-out.** Dispatching many subagents to read, map,
@@ -85,51 +114,34 @@ was manufactured anyway.
 
 ## Enforcement — honest scope
 
+```
+ITEM 1 IS ENFORCED. ITEMS 2, 3 AND 4 ARE NOT — 4 ONLY WARNS.
+NEVER CITE A GUARD THAT WARNS AS ONE THAT BLOCKS.
+```
+
 [`evidence_independence.ts`](../scripts/hooks/evidence_independence.ts) is a
-`pre_tool_use` concern. It **blocks** a dispatch whose prompt carries a
-pre-loaded verdict, and **blocks** a second *self-scoped* evaluation dispatch in
-the same turn; it **warns** on the first. It reads the prompt the agent is about
-to send, so items 1 and 4 above are mechanically enforced.
-
-Three limits, stated because they were measured. The pre-loaded-verdict list is
-a **phrase list**, so a paraphrase evades it — it catches recurrences of known
-steering wording, not steering as such. The turn boundary is the
-authorization ledger's `detected_at` stamp, because the envelope carries no turn
-id; with no ledger yet, the counter falls back to session scope. And the guard
-does not deny everywhere it exists: `pre_tool_use` is **bound** on three hosts —
-augment, claude, cowork — and only `claude` honours the deny. Everywhere else,
-augment and cowork included, items 1 and 4 join 2 and 3 as model-carried.
-`agent-config hooks:status` answers it for the host you are on right now.
-
-**Corrected 2026-08-17 — this paragraph was wrong on both sides of the line it
-drew.** It said `pre_tool_use` "exists on three hosts" and that the guard has
-"nowhere to bind" on the other five. Neither half survived a re-read of the
-tree. **Downward:** the manifest's own `native_event_aliases` table already maps
-`preToolUse` (cursor), `PreToolUse` (cline) and `BeforeTool` (gemini) onto
-`pre_tool_use`, so there the guard is **unbound, not unbindable**; only windsurf
-and copilot carry no pre-tool surface at all. **Upward, and worse:**
-`host_semantics.ts` certifies **claude alone**, and the augment and cowork
-trampolines discard dispatcher output and `exit 0` unconditionally — so on two
-of the three "enforcing" hosts this guard runs and is then ignored. Nor may the
-inverse be asserted downward: nothing records whether an unbound host's
-pre-tool event can *deny*, and `severity: blocking` is a property of the concern
-rather than of the host. The four states are tabulated once in
-[`hook-architecture-v1 § Which hosts carry pre_tool_use`](../docs/contracts/hook-architecture-v1.md).
-
-Stated at this length because this rule exists over a case where a process that
-*looked* followed produced fabricated evidence. An unbacked reason for a real
-gap and an unmeasured claim of enforcement are the same failure in a smaller
-font, and this paragraph had shipped one of each. Note also what the frequency
-join actually reports: `check_enforcement_coverage.ts` skips `fallback_only`
-platforms, so its gap set is **four** — cursor, cline, windsurf, gemini — never
-copilot, which is excluded by declaration rather than measured as a gap.
-
-Items 2 and 3 — an honestly chosen scope, and recording the prompt with the
-verdict — are **not** enforced by anything. A narrowed scope is not decidable
-from the prompt alone, and no validator reads the artefacts a verdict lands in.
-They are stated here as obligations and are model-carried. Saying so is the
-point: this rule exists because a process that *looked* followed produced
-fabricated evidence, and claiming coverage it does not have would repeat that.
+`pre_tool_use` concern reading the prompt the agent is about to send.
+
+- **Item 1 (pre-loaded verdict) BLOCKS** — `EXIT_BLOCK` at `:253`, on the one
+  host that honours a deny. Bound on augment, claude and cowork; only `claude`
+  denies. `agent-config hooks:status` answers it for the host you are on.
+- **Item 4 (second self-scoped evaluation) WARNS** — `EXIT_ALLOW` with
+  `decision: "warn"` (`:301-324`). The turn-budget clause is advisory, and the
+  manifest's `severity: blocking` is true of the item-1 path only.
+- **Item 2 (an honestly chosen scope) is enforced by nothing.** A narrowed scope
+  is not decidable from the prompt alone.
+- **Item 3 (recording the prompt with the verdict) IS enforced** by
+  [`check_review_prompt_binding.ts`](../../src/scripts/check_review_prompt_binding.ts),
+  with one limit that matters: **omission beats substitution** — not committing
+  the prompt package drops the round out of the checkable set with no finding.
+
+Where the guard does not deny, every item is model-carried. Never claim the
+review ran as if it were verified.
+
+Why each branch behaves that way, the phrase-list and turn-boundary limits, the
+four host states, the two corrections this section has taken, and the
+11-of-19 measurement behind item 3:
+[`evaluator-independence-mechanics`](../docs/guidelines/agent-infra/evaluator-independence-mechanics.md).
 
 ## See also
 

package/dist/agent-src/rules/fix-what-you-see.md

@@ -23,7 +23,7 @@ triggers:
 workspaces: [engineering]
 packs: [engineering-base]
 enforced_by:
-  - "none"
+  - "instruction-only: ownership-as-excuse is a disposition in prose; no gate can see a red check handed back with its cause named"
 ---
 
 # Fix What You See
@@ -106,3 +106,11 @@ maintainer decision, recorded), a kernel rule shortened to make room, or a
 option that would fire on tool output rather than on wording. Until then, `auto`
 plus this paragraph is the honest state: the obligation is real, its delivery is
 partial, and the partiality is named rather than implied away.
+
+## Honest enforcement — `instruction-only`
+
+Nothing observes a disposition. "I fixed it", "I landed a roadmap for it" and
+"I named the author and moved on" are the same prose to every gate in this tree,
+and the issue set is whatever the agent happened to see. So the two dispositions
+above are model-carried, and the activation gap named in the previous section
+sits on top of that rather than beside it.

package/dist/agent-src/rules/framework-neutrality-in-generic-skills.md

@@ -72,7 +72,7 @@ framework-specific): `laravel*`, `symfony*`, `nextjs*`, `react-*`,
 `^php-*`, `^pest-*`, `^eloquent`, `^blade*`, `^livewire`, `^flux`,
 `^artisan-*`, `^composer-*`, `^docker*`, `^aws-*`, `^grafana`,
 `^openapi$`, `^quality-tools`, `^sql-writing`, `^tailwind*`,
-`^terraform*`, `^terragrunt*`, `^traefik`, `^mobile-e2e`,
+`^terraform*`, `^terragrunt*`, `^traefik`, `^mobile-e2e`, `^monorepo-workspace$`, `^workspace-link$`,
 `-routing$`, `project-analysis-(laravel|symfony|nextjs|react|node-express|zend-laminas)`.
 
 ## The discipline in one breath

package/dist/agent-src/rules/minimal-safe-diff.md

@@ -43,29 +43,23 @@ change.
 - Never consolidate or split unrelated code paths as a side effect.
 - Never delete code that *looks* dead without proof it is unreachable.
 
-## Before writing the diff
+## Repair the shared path, don't patch the reported call site
 
-Ask yourself, in order:
-
-1. **What is the minimum set of files that must change for the stated task?**
-   If your answer includes files with no causal link to the task, stop and
-   remove them.
-2. **What is the minimum number of lines per file?** If you are editing a
-   method, edit the method — not the surrounding class.
-3. **Is any of this a refactor?** If yes, it belongs in its own commit or
-   PR, clearly labeled as a refactor, with no behavior change.
-
-## Red flags in your own diff — reject them
-
-Files the task never mentioned · import reordering, whitespace, or comments
-outside the edited region · "small improvements" to neighboring methods ·
-test-only mixed with behavior changes in one commit · renames outside the
-task scope · dependency bumps "because it was close to the cache".
+```
+BEFORE EDITING A SHARED PATH, ENUMERATE ITS CALLERS AND REPAIR THE PATH ONCE.
+PATCHING ONLY THE REPORTED CALL SITE IS NOT THE SMALLEST CHANGE — IT IS THE
+SMALLEST-LOOKING ONE, AND IT LEAVES EVERY OTHER CALLER BROKEN.
+```
 
-## When in doubt
+Fires when the defect sits in something several callers reach — a shared
+helper, a base class, a middleware, a query builder. The minimum set of files
+then INCLUDES the shared path and EXCLUDES the N call sites a per-caller patch
+would touch: repairing once is both smaller and complete.
 
-Ask. A minimal diff plus one follow-up is cheaper than a sprawling diff the
-reviewer has to untangle.
+**The PRE-fix half of a pair.** The post-fix half ships in
+[`downstream-changes`](downstream-changes.md) § Defect-pattern search — name
+the construct, grep the tree, report the count, AFTER the fix. Enumerate
+before, sweep after; the two run over different sets.
 
 ## Own-orphan cleanup
 

package/dist/agent-src/rules/missing-skill-recovery.md

@@ -16,6 +16,8 @@ self_contained: true
 workspaces: [engineering]
 packs: [meta]
 # obligation: line 41
+enforced_by:
+  - "instruction-only: nothing can observe an agent concluding that no skill exists; the skill-route concern covers only the prompts where the ranker is confident"
 obligation_frequency: "per-turn"
 ---
 
@@ -60,6 +62,16 @@ NEVER REBUILD A CAPABILITY BECAUSE ITS SKILL WAS NOT DELIVERED.
    inventing one. A ranked empty list and an unreachable catalogue are
    different answers; the tool distinguishes them (`status: no_catalogue`) and
    so should you.
+5. **If the tool is not registered, say THAT — and proceed.** This rule may
+   never instruct a call it cannot verify is possible. The tool arrives with
+   this package's MCP server, which `agent-config install` registers for the
+   `claude-code` tool in the project's `.mcp.json`. No entry there, or the
+   server not started, and there is no tool to call: name the gap in one clause,
+   proceed without a skill, and — only if the missing catalogue entry actually
+   mattered — point at `agent-config mcp:check`, which reports whether
+   `.mcp.json` carries the entry. Never retry a call that is not wired, and
+   never report "no skill covers this" when what you learned is "no tool
+   answered".
 
 ## When NOT to fire
 
@@ -70,7 +82,7 @@ NEVER REBUILD A CAPABILITY BECAUSE ITS SKILL WAS NOT DELIVERED.
 - A host that delivers its catalogue whole — the rule costs nothing there and
   simply never has a gap to close.
 
-## Honest enforcement — `enforced_by: none`
+## Honest enforcement — `instruction-only`
 
 Nothing can observe an agent concluding "no skill exists". The `skill-route`
 concern injects ranked pointers on `user_prompt_submit` when its floor is

package/dist/agent-src/rules/playbook-precedence.md

@@ -0,0 +1,105 @@
+---
+type: "auto"
+tier: "2a"
+description: "A repository's own playbook outranks a shipped skill for the same task — run its configured steps first, and treat an observed playbook as advisory"
+triggers:
+  - keyword: "playbook"
+  - keyword: "generator"
+  - keyword: "scaffold"
+  - phrase: "our own generator"
+  - phrase: "add a component"
+  - phrase: "new package"
+  - phrase: "unser generator"
+applies_to_user_types:
+  - "developer"
+  - "maintainer"
+# obligation: the precedence question comes due when a task arrives that both a
+# playbook and a shipped skill answer — once per task, not per turn or per edit.
+enforced_by:
+  - "instruction-only: no gate can tell a playbook-first run from a skill-first one — both produce a diff, and which answer was consulted leaves no artefact"
+obligation_frequency: "per-task"
+# frequency-override: the prose heuristic reads the Iron Law's "when both match a
+# task" as a turn-level phrase. It is not: the precedence question is settled once
+# per task, and re-deciding it on every turn of the same task would be the churn
+# this rule exists to prevent.
+routes_to:
+  - "skill:playbook-authoring"
+workspaces: [engineering]
+packs: [engineering-base]
+---
+
+# Playbook Precedence
+
+A shipped skill is a generic answer to a generic question. A **playbook** (ADR-244) is *this*
+repository's answer to the same question, carrying decisions the repository already made —
+file layout, barrel exports, test co-location, naming — that no generic skill can know.
+When both match a task, running the generic one produces output that looks right and is
+wrong for this repository.
+
+## The Iron Law
+
+```
+A MATCHING PLAYBOOK GOES FIRST. THE SHIPPED SKILL COVERS ONLY WHAT IT DOES NOT.
+`configured` STEPS ARE RUN. AN `observed` PLAYBOOK IS ADVISORY — READ IT, AND THE
+SHIPPED SKILL'S GATES STILL APPLY IN FULL.
+NEVER RUN A PLAYBOOK'S COMMAND SILENTLY — PROPOSE IT, THE HUMAN RUNS IT.
+NEVER SYNTHESISE A COMMAND A PLAYBOOK DID NOT NAME.
+```
+
+## Routing — matched on scope, dispatched on grade
+
+A playbook matches when its `scope` contains the current `scope_root`, or is the literal
+`repo`. **The `grade` axis then decides what the match buys:**
+
+| `grade` | What the agent does | Why |
+|---|---|---|
+| `configured` | run its steps first; the shipped skill covers only the remainder | every step's `invokes` id was resolved in the tree, so the procedure is verified, not inferred |
+| `observed` | read it, follow it as advice, keep every shipped-skill gate | at least one id did not resolve — the steps are a hypothesis, and a hypothesis does not get to suspend a gate |
+
+The grade is written by [`playbook-authoring`](../skills/playbook-authoring/SKILL.md), which
+refuses to write `configured` for a generator it did not see. That refusal is what makes
+this table safe to act on: without it, precedence would be granted on a claim rather than
+on evidence.
+
+## When NOT to fire
+
+- **No playbook matches** the task's scope — unchanged behaviour, and the absence is not a
+  reason to write one mid-task.
+- **The task is not what the playbook covers.** A playbook for adding a component says
+  nothing about deleting one; a partial scope match is not a match.
+- **The playbook's own § What this playbook does NOT cover** names the current task — it
+  ends where it says it ends, which is why that section is mandatory.
+
+## Failure modes
+
+- Running a `configured` command **silently** because the playbook looks authoritative. It
+  is still a command the human runs; propose-never-silent-run is unchanged.
+- Treating an `observed` playbook as `configured` because its steps read confidently.
+- **Synthesising a neighbouring command** — the playbook names `turbo gen component`, the
+  agent runs `turbo gen page` because the task mentioned a page. A command the playbook did
+  not name has no repository authority behind it.
+- Reaching for the shipped skill first *and then* reconciling with the playbook. The
+  reconciliation never happens; the generic output is already written.
+
+## Provenance
+
+The precedence shape — prefer a repository's local generator over a general one, and let the
+local answer bound the generic one — is taken from an external reference's generator skill.
+The source is deliberately not named here: per
+[`source-confidentiality`](source-confidentiality.md), a shipped artifact does not carry
+derivation attribution to a named external project. The attribution lives with the
+maintainer-side record.
+
+## See also
+
+- [`playbook-authoring`](../skills/playbook-authoring/SKILL.md) — writes the playbooks and owns the grade.
+- **ADR-244** — the artefact class, its home, and the two deferred generator kinds. Cited by number rather than linked: `docs/` is not projected into a consumer install, so a relative link here resolves in this repository and nowhere else.
+- [`agents-md-thin-root`](../skills/agents-md-thin-root/SKILL.md) § Workspace files — the per-workspace pointer list.
+- [`standards-from-config`](../skills/standards-from-config/SKILL.md) — the Class-A rule this applies to procedure.
+
+## Honest enforcement — `instruction-only`
+
+Nothing can see which answer was consulted. A playbook-first run and a
+skill-first run both produce a diff, and the precedence decision leaves no
+artefact a gate could read — so this rule is model-carried, and saying so is
+cheaper than a check that would have to guess.

package/dist/agent-src/rules/recurring-criticism.md

@@ -21,6 +21,8 @@ workspaces: [agent-config-maintainer, engineering]
 packs: [meta]
 collision_ok:
   "schon wieder": "active-remediation makes a user 'leave it' terminal against the AGENT re-raising a closed item; this rule fires only when the USER brings it back — a decision-maker reopening their own decision is not the nagging that rule prevents"
+enforced_by:
+  - "instruction-only: the earlier disposition, the three outcomes and the hardening are all prose; the self-repair occurrence counter covers only detector-matched defects"
 obligation_frequency: "per-task"
 ---
 
@@ -85,7 +87,7 @@ analysis prose by design, so "I found nothing" means *prose was grepped*, never
 - **The agent is the one repeating** — that is [`no-cheap-questions`](no-cheap-questions.md).
 - **Already resolved this task.** Once decided, it is decided.
 
-## Honest enforcement — `enforced_by: none`
+## Honest enforcement — `instruction-only`
 
 One narrow deterministic signal exists. `src/scripts/_lib/self_repair.ts` keeps one
 record per defect fingerprint with an `occurrences` counter and reopens a released

package/dist/agent-src/rules/roadmap-progress-sync.md

@@ -1,6 +1,11 @@
 ---
 type: "auto"
 tier: "1"
+norm:
+  tokens: 2400
+  remainder:
+    - "../docs/guidelines/agent-infra/roadmap-progress-mechanics.md"
+    - "../docs/guidelines/agent-infra/roadmap-deferred-resolution-provenance.md"
 description: "Any roadmap touch (file move, checkbox flip, phase change) regens dashboard same response; archive at 0 open"
 triggers:
   - path_prefix: "agents/roadmaps/"
@@ -9,6 +14,7 @@ triggers:
   - command: "/roadmap:process-full"
 routes_to:
   - "guideline:agent-infra/roadmap-progress-mechanics"
+  - "guideline:agent-infra/roadmap-deferred-resolution-provenance"
 workspaces: [agent-config-maintainer, engineering]
 packs: [meta]
 roles: [planner]
@@ -86,16 +92,12 @@ in the estate?**
   blocker id · every option · verdict + one-sentence rationale · dissent ·
   destination when carried · what closes it. A verdict with no record is a
   silent drop wearing a procedure.
-- **The residual hole, stated not papered over.** Both authoring seats named
-  it in their own strongest counter: a carried follow-up can still become an
-  indefinite deferral, so this test bounds *who decides*, not *whether the work
-  happens*. Only fix-now discharges it. A carried item untouched at the next
-  task boundary is raised again per [`active-remediation`](active-remediation.md).
-- **Why it changed.** Adopted 2026-08-19, unanimous 2/2 council (blind peer
-  review). The prior text — *"Wait for the user"* — handed back a fully
-  analysed choice with four costed options, the low-value interruption
-  [`no-cheap-questions`](no-cheap-questions.md) forbids. The gate protects the
-  item, not the maintainer's attention.
+- **The residual hole, and why the test changed** — a carried follow-up can
+  still become an indefinite deferral, so this test bounds *who decides*, not
+  *whether the work happens*; only fix-now discharges it, and a carried item
+  untouched at the next task boundary is raised again per
+  [`active-remediation`](active-remediation.md). Provenance and the argument:
+  [`roadmap-deferred-resolution-provenance`](../docs/guidelines/agent-infra/roadmap-deferred-resolution-provenance.md).
 
 ### `deferred_policy` — a declared contract removes the round, never the route
 
@@ -112,9 +114,8 @@ It changes **when the round happens**, never **who decides**:
 Recorded-or-it-did-not-happen applies unchanged to an automatic spawn, and
 fail-closed binds hardest here: a spawn naming a follow-up that does not exist
 yet reaches the user, because a contract cannot pre-authorize a promise.
-Reversible — `wait` is the default, so removing the field restores always-wait
-(`decision 2026-08-20`, AI council 2/2; record
-`agents/evidence/council/drain-blocker-dispositions-a.md`).
+Reversible — `wait` is the default, so removing the field restores always-wait;
+provenance in the mechanics guideline.
 
 ## Later disposition — blocked-for-later roadmaps are parked, never left active