@event4u/agent-config 10.2.0 → 10.3.0

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

@@ -16,9 +16,11 @@ routes_to:
   - "guideline:agent-infra/active-remediation-mechanics"
 workspaces: [engineering]
 packs: [engineering-base]
+enforced_by:
+  - "none"
 collision_ok:
   "refactor": "an explicit clean-up/refactor ask is the remediation ladder's own trigger"
-# obligation: line 51
+# obligation: line 31
 obligation_frequency: "per-edit"
 ---
 
@@ -34,16 +36,53 @@ SMALL + TASK-ALIGNED → FIX IT NOW, IN THE SAME CHANGE, WITH ITS TEST.
 BIGGER OR DIVERGENT → NOTE IT, FINISH THE TASK, THEN ASK — NEVER MID-FLOW.
 TOO MANY → PROPOSE ONE OR MORE SEPARATE FOLLOW-UP PRs THE USER REVIEWS.
 A LIVE SECURITY / DATA-EXPOSURE GAP IS NEVER MERELY "NOTED FOR LATER".
+A NOTE IS NOT A DISCHARGE — THE DECISION IS. AN ISSUE REPORTED IN PROSE AND
+NEITHER FIXED NOR PUT TO THE USER IS STILL OPEN, AND STILL YOURS.
+THE ASK CARRIES CANDIDATE FIXES AND AN EXPLICIT "LEAVE IT" — NEVER A BARE FLAG.
 ```
 
 ## What to remediate
 
-Security gaps (broken access control, injection, secrets, missing authz — see `broken-access-control`) · missing/weak test coverage · bad code (dead code, silent error-swallow, unguarded edge cases) · **duplication** (the same or near-same logic repeated instead of one method/abstraction) · **stale version-idioms** (code written for an older language/framework version than the project actually runs).
+Security gaps (broken access control, injection, secrets, missing authz — see `broken-access-control`) · missing/weak test coverage · bad code (dead code, silent error-swallow, unguarded edge cases) · **duplication** (the same or near-same logic repeated instead of one method/abstraction) · **stale version-idioms** (code written for an older language/framework version than the project actually runs) · **a failing check you already ran** (below).
+
+## A check you already ran is a spotted issue
+
+A red gate, a failing test, a lint or type error — output the tooling already put
+in front of you — is **spotted**, exactly like a defect read in a file, and
+enters the ladder on the same terms. "It was already red before I got here"
+decides *which* tier, never whether the ladder applies.
+
+Two bounds: **only output you already have** (never an obligation to go run a
+check — the remote CI stays the authoritative gate), and **ownership picks the
+tier, never the silence**. Classification + worked example: the mechanics
+guideline below.
 
 ## The ladder — three tiers
 
 **Fix now** — small + task-aligned; ALL five conditions hold: same request path/module · ≤ ~10 changed lines in one production file (plus its test file) · no public-API / response-shape change · no dependency bump, no migration · verification ships in the same commit. Anything outside → next tier. · **Note + ask** (batched, one numbered-options prompt after delivery) · **Follow-up PR** (many spots; creation stays permission-gated). Per-tier detail + version-gated modernization + guardrails: the mechanics guideline below.
 
+## Every noted issue ends in one of three states
+
+**Fixed**, **decided by the user** (an explicit "leave it" is terminal and is not
+raised again, per [`scope-control`](scope-control.md)), or **in front of the user
+right now** as the batched ask. A line in the closing summary is none of the
+three: it leaves the issue open while sounding like it was handled, and it is the
+failure this rule exists to stop. An undecided item survives the turn — raised
+once more at the next task boundary, never aged out. A declined batch is closed.
+
+## The ask carries fixes, not a flag
+
+"There are 7 lint errors — shall I fix them?" hands the problem back untouched.
+Each numbered option is a candidate the user can pick without a follow-up
+question — what changes, where, roughly how large, what it costs — grouped by fix
+shape rather than one per finding, with an explicit **leave it as is** last and
+one recommendation line (per [`user-interaction`](user-interaction.md)).
+
+The ask is subordinate to [`no-cheap-questions`](no-cheap-questions.md): its
+Pre-Send Self-Check runs first, and a finding with no nameable benefit or no real
+trade-off is dropped silently instead of becoming a question. That check forbids
+a content-free ask, never the surfacing of a genuine defect.
+
 ## Live-security carve-out (priority)
 
 A **live cross-user / cross-tenant data exposure** (per `broken-access-control`) is not a "note for later": it is a potential GDPR-notifiable breach (Art. 33, 72 h from discovery). If it meets the fix-now bar → fix it now with its negative test. If not → **stop and surface it immediately** (a safety surface, visible even under an autonomous mandate — like the `no-pr-progress-comments` safety carve-out). Never defer it silently, never look away.
@@ -56,6 +95,16 @@ While implementing/modifying code you pass an issue outside the literal task. Al
 
 - No issue spotted. Prose/docs-only. The user fenced the scope ("just this one line").
 - 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`
+
+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
+[`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.
 
 Body migrated to [`guideline:agent-infra/active-remediation-mechanics`](../docs/guidelines/agent-infra/active-remediation-mechanics.md) (per P4 of `road-to-kernel-and-router.md`) — per-tier fix-now/note+ask/follow-up-PR criteria, version-gated modernization, anti-nagging guardrails.
 Trigger-set above activates this routing on demand, independent of the discipline profile (ADR-110).
@@ -68,3 +117,5 @@ Trigger-set above activates this routing on demand, independent of the disciplin
 - [`source-discovery-gate`](source-discovery-gate.md) — establishing the verified project version before modernizing.
 - [`scope-control`](scope-control.md), [`commit-policy`](commit-policy.md) — PR/commit creation stays permission-gated.
 - [`improve-before-implement`](improve-before-implement.md) — the pre-work challenge (before); this is the during/after remediation.
+- [`verify-before-complete`](verify-before-complete.md) — an undecided issue is unfinished work, not a caveat to report.
+- [`no-cheap-questions`](no-cheap-questions.md) — the floor the batched ask clears before it is asked at all.

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

@@ -2,7 +2,7 @@
 type: "auto"
 tier: "2a"
 alwaysApply: false
-description: "Porting/adapting external code (algorithm, structure, >~10 lines) — close the source, re-derive; conscious borrows need a ledger entry + license check"
+description: "Porting external code, or asserting an externally-sourced claim — close the source, re-derive; borrows need a ledger entry + license check, harvested claims an id or an own-analysis label"
 triggers:
   - keyword: "port this"
   - keyword: "adapt this"
@@ -12,6 +12,8 @@ triggers:
   - keyword: "borrow"
   - keyword: "vendored"
   - keyword: "reference implementation"
+  - keyword: "harvest"
+  - keyword: "adopt from"
 routes_to:
   - "skill:license-compliance-borrow-check"
   - "skill:license-compliance-credits"
@@ -21,7 +23,7 @@ packs: [engineering-base]
 roles: [developer, reviewer, tester, po, incident, planner]
 enforced_by:
   - "none"
-# obligation: line 38
+# obligation: line 40
 obligation_frequency: "per-edit"
 ---
 
@@ -64,6 +66,40 @@ An **unknown** source license is never permissive-by-default. Stop and
 escalate (numbered options, per
 [`ask-when-uncertain`](ask-when-uncertain.md)) instead of guessing.
 
+## The knowledge layer — cite a harvest id, or label it own analysis
+
+The clauses above cover borrowed **code**. The same failure has a prose half:
+a comparative pass concludes "their citation registry is worth adopting", the
+sentence lands in a skill, and six months later nobody can say where it came
+from or whether it was ever true. An unattributed idea is not a licensing
+problem, which is why it needs its own clause rather than a wider reading of
+the one above — it is an **epistemic** one, and it fails silently.
+
+```
+AN ARTEFACT ASSERTING AN EXTERNALLY-SOURCED CLAIM EITHER CITES A HARVEST ID
+OR LABELS THE STATEMENT AS OWN ANALYSIS. SILENCE IS NEITHER.
+```
+
+Fires when a skill, rule, command, guideline, or roadmap states a heuristic, a
+number, or a mechanism taken from a source outside this repo. Two acceptable
+discharges, and the choice is the author's:
+
+1. **Cite** — append `<!-- harvest:<id> -->` and add the row to
+   `provenance/harvests.jsonl` (shape: `provenance/README.md`). The row pins
+   the source to a revision, or names it opaquely when
+   [`source-confidentiality`](source-confidentiality.md) keeps it out of the
+   tracked tree.
+2. **Label** — say in the text that this is own analysis. A stated derivation
+   is a complete discharge; the ledger exists for what came from elsewhere.
+
+Only `adopt` and `adapt` findings produce a row. A rejected or already-present
+finding has no artefact citing it and belongs in the analysis document.
+
+**The prose carve-out below does not reach this section.** "Prose/docs-only
+edits" excuses the *code* clauses, where there is no borrowed code to record;
+prose is precisely where a harvested claim lands, so excluding it here would
+empty the obligation of everything it applies to.
+
 ## Self-interrogation clause (AUXILIARY — never a control)
 
 Before finalizing any non-trivial function, ask internally: *"Did I derive
@@ -96,16 +132,42 @@ 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
 `security-sensitive-stop` and `untrusted-input-defense`.
 
+`lint_harvest_provenance.ts` stands in exactly the same relation to the
+knowledge layer, and the sentence is worth repeating rather than assuming
+transferred: it validates the harvest ledger's own rows and citations — schema,
+uniqueness, pinning, dead rows, orphan ids — and **cannot see a claim nobody
+recorded**. A harvested assertion that was never cited and never labelled
+passes every gate in this repo. That is the honest coverage statement, and it
+is why the discipline is the control on both layers.
+
 ## When NOT to fire
 
 - A well-known, unpatentable algorithm shape (a hash map, a for-loop) with
   no specific source in mind.
 - Reusing your **own** prior code within this repo.
-- Prose/docs/config-only edits.
+- Prose/docs/config-only edits — **for the code clauses only**. The knowledge
+  layer fires on exactly these surfaces; see its own note above.
+- Common knowledge with no nameable source, on either layer. "Indexes speed up
+  lookups" needs no row; a specific number, threshold, or mechanism read
+  somewhere does.
+- **A design artifact the user handed over** — a prototype, an exported
+  `design.html`, a token sidecar. That is the user's own material, not
+  third-party external code, so adapting its markup/CSS/JS is not a borrow and
+  needs no ledger entry. Same carve-out
+  [`content-quoting-floor`](content-quoting-floor.md) makes for user-owned text.
+  **The carve-out is authorship, not delivery:** a vendored component or a
+  licensed template that merely *arrives inside* a handover stays under this
+  rule in full. Boundary stated from the other side in
+  [`design-fidelity-mechanics`](../docs/guidelines/design-fidelity-mechanics.md)
+  § Adopt the code.
+  **It exempts the code clauses only.** A claim *about* the artifact's origin —
+  that a pattern in it came from somewhere nameable — is a knowledge-layer
+  statement and takes a harvest id or an own-analysis label like any other.
 
 ## See also
 
 - [`license-compliance-borrow-check`](../skills/license-compliance-borrow-check/SKILL.md), [`license-compliance-credits`](../skills/license-compliance-credits/SKILL.md), [`license-compliance-audit`](../skills/license-compliance-audit/SKILL.md) — the borrowing / notices / on-demand-scan skill family this rule routes to.
-- `provenance/README.md`, `src/scripts/lint_provenance.ts`, `src/scripts/detect_target_license.ts` — the ledger, its linter, and the S1.2 policy derivation.
+- `provenance/README.md`, `src/scripts/lint_provenance.ts`, `src/scripts/detect_target_license.ts` — the code ledger, its linter, and the S1.2 policy derivation.
+- `provenance/harvests.jsonl`, `src/scripts/lint_harvest_provenance.ts` — the knowledge ledger and its linter. Neither is `docs/CLAIMS.md` / `check_claims.ts`, which govern public claims this package makes about **itself**; the shared vocabulary is a grep hazard, so `provenance/README.md` states the three-way split.
 - [`secret-vcs-guard`](secret-vcs-guard.md) — sibling detect → ask → act discipline for a different leak class.
 - [`ask-when-uncertain`](ask-when-uncertain.md) — the escalation shape for `conditional`/`unknown` verdicts.

package/dist/agent-src/rules/content-quoting-floor.md

@@ -82,6 +82,12 @@ does not substitute for engaging with the source.
   treating fetched content as data vs instructions; this rule governs
   how much of that data may be reproduced verbatim once it IS being
   used as source material.
+- [`code-provenance`](code-provenance.md) +
+  [`design-fidelity-mechanics`](../docs/guidelines/design-fidelity-mechanics.md)
+  § Adopt the code — this rule's user-owned-text carve-out extended to
+  **markup**: a design artifact the user hands over is their own material, so
+  adapting its code is not a borrow. Third-party code arriving inside that
+  handover is not covered, on either side.
 - [`docs/contracts/write-engine.md`](../docs/contracts/write-engine.md) —
   ghostwriter's disclosure-footer contract; this rule's quote floor
   applies to any ghostwriter draft that cites an external source.

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

@@ -60,8 +60,28 @@ A PROVIDED PROTOTYPE / DESIGN SYSTEM IS THE SPEC, NOT A SUGGESTION.
 BUILD IT 1:1. NEVER SWAP FONTS, CONTROLS, COMPONENTS, LAYOUT, SPACING,
 OR COLOUR — AND NEVER OMIT OR ADD AN ELEMENT — WITHOUT EXPLICIT CONFIRMATION.
 A "BETTER IDEA" IS A PROPOSAL TO SURFACE, NEVER A CHANGE TO MAKE.
+WHENEVER THE SOURCE IS REACHABLE, THE SOURCE IS THE DATA BASIS.
+A SCREENSHOT IS VALIDATION, NEVER THE INPUT YOU BUILD FROM,
+WHILE ANY HIGHER RUNG IS REACHABLE. WHEN THE HANDOVER *IS* AN IMAGE,
+THE IMAGE IS THE SPEC AND THE 1:1 FLOOR ABOVE APPLIES TO IT UNCHANGED.
+WHERE THE ARTIFACT'S OWN MARKUP / CSS / JS IS STACK-COMPATIBLE, ADAPTING
+THAT CODE IS THE DEFAULT — A FROM-SCRATCH RE-DERIVATION IS A DEVIATION
+AND NEEDS THE SAME CONFIRMATION AS A SWAPPED CONTROL.
 ```
 
+The qualifier is load-bearing, not hedging. Unqualified, the screenshot line
+contradicts this rule's own opening sentence and its § What counts as the spec,
+both of which name a screenshot as a legitimate spec — and it would forbid the
+image-only handover class the rule exists to govern. What it forbids is
+narrower: reaching for pixels **while the code is sitting there**.
+
+The five new lines route to
+[`design-fidelity-mechanics`](../docs/guidelines/design-fidelity-mechanics.md)
+§ Data-basis ladder (the first three) and § Adopt the code (the last two) —
+including the scope line that keeps the adopt-the-code duty from colliding with
+[`code-provenance`](code-provenance.md). Read that scope line before acting on
+either rule; the boundary is stated from both sides.
+
 ## What counts as the spec
 
 A user-provided, finished design artifact the user points at and says "match
@@ -114,6 +134,21 @@ Two further handover shapes carry the artifact without any of the above:
   conventional location for a handed-over token/component set. The prefix is the
   vendor-scoped directory, never a bare `design-system/`, which is a normal
   source folder in a large fraction of frontend repos.
+- **A third-party builder's share link — UNCOVERED, deliberately.** A page built
+  in Lovable / v0 / bolt and handed over as a link is a finished spec, and this
+  rule does not route it. The obvious trigger was tried on this branch and
+  **withdrawn**: matching is plain substring containment, so `https://v0.dev/`
+  also fires on `https://v0.dev/docs`, a pricing page, or a changelog link — it
+  would treat every mention of the tool's own site as a spec handover. That is
+  the `claude.ai` failure the capability-URL entry above exists to avoid, and by
+  this rule's own standard it is worse than the gap it closes. The alternatives
+  are a bare-host keyword (broader still) or guessing each vendor's share-path
+  segment, and a trigger built on a guessed path is not evidence.
+  **What closes it:** a verified share-path segment per vendor, or a
+  handover-word co-occurrence the matcher cannot express today. Until then the
+  class needs one word in the prompt, like any other unlisted filename.
+  `near-bare-host-mention` in the matrix pins the bare-host direction silent so
+  a future attempt cannot reintroduce the broad form unnoticed.
 
 The trigger set is deliberately phrase-heavy on the German side and on
 `artifact`: a bare `artifact` keyword fires on "the CI build artifact is 40 MB".
@@ -121,9 +156,20 @@ The trigger set is deliberately phrase-heavy on the German side and on
 [`design_fidelity_routing.test.ts`](../../tests/scripts/design_fidelity_routing.test.ts)
 pins both halves — every class that must route, and the near-misses that must
 stay silent (fixture `daf-port-trigger-de`). Extending the set without adding a
-near-miss row there is how an over-broad trigger lands: each of the two triggers
-above ships with its own near-miss row (`near-claude-ai-chat-link`,
-`near-generic-design-system-dir`).
+near-miss row there is how an over-broad trigger lands: each of the two shipped
+trigger classes above carries its own near-miss row
+(`near-claude-ai-chat-link`, `near-generic-design-system-dir`), and the
+withdrawn builder-URL class left `near-bare-host-mention` behind so the broad
+form stays pinned silent.
+
+**The near-miss must test the direction the new trigger opens, not a direction
+that was already closed.** The withdrawn class is the worked example: its first
+near-miss row tested a protocol-less mention, which was silent *before* the
+change and therefore could not have caught the over-broadness the change
+introduced. The row that would have caught it is
+`near-builder-host-non-handover-url` — a documentation URL on the same host —
+and it exists only because a review asked for it after the trigger had already
+shipped. Write that row first next time; it is the cheap half.
 
 Body migrated to [`guideline:design-fidelity-mechanics`](../docs/guidelines/design-fidelity-mechanics.md) (per P4 of `road-to-kernel-and-router.md`) — surgical visual edits (targeted-edit vs redesign-trigger discipline, stable anchors), asset & imagery discipline (owned-asset path, third-party delivery is self-hosted by default, real-imagery-as-proof, iconography floor, no unrequested filler), deviation-surfacing shape, failure-mode catalog, `daf-*` fixtures.
 Trigger-set above activates this routing on demand, independent of the discipline profile (ADR-110).

package/dist/agent-src/skills/design-review/references/verification-automation.md

@@ -29,7 +29,25 @@ Don't just screenshot the default state. Capture:
 
 ### Mockup-to-code verification
 
-When implementing from a design mockup or screenshot:
+**Branch on what the artifact actually is before you open anything.** The two
+kinds carry different workflows, and running the image workflow over a code
+artifact is the failure this branch exists to prevent — it rebuilds from pixels
+what was handed over as source.
+
+**Code artifact** — an HTML/JSX/Vue file, an archive, a repo, a live page whose
+DOM you can reach:
+
+1. **Read the code** — it is the data basis (`design-fidelity-mechanics`
+   § Data-basis ladder, rungs 1–2). Markup, styles, scripts.
+2. **Implement** — adapting the artifact's own code where it is
+   stack-compatible; a from-scratch re-derivation is a deviation, not a default.
+3. **Screenshot afterwards** — for an after-the-fact visual diff only, never as
+   the input you built from.
+4. **Flag deviations** — including behaviour: a handler or keyframe that did not
+   survive is a deviation, not an implementation detail.
+
+**Image artifact** — a PNG/JPG screenshot, a Figma export you cannot open as
+source, a photograph of a whiteboard:
 
 1. **Open the mockup** — use the provided image/screenshot.
 2. **Implement** — build the UI component.
@@ -38,6 +56,10 @@ When implementing from a design mockup or screenshot:
 
 This is especially useful when the user provides a screenshot or Figma export as a reference.
 
+> **Near-miss worth naming:** an HTML file *opened in a browser* is still a code
+> artifact. The browser makes it look like an image; the file on disk is rung 1.
+> Take the code path.
+
 ## Async-verifier pattern (keep the main context clean)
 
 For a review that needs browser probing, use an **async background verifier**

package/dist/agent-src/skills/fe-design/SKILL.md

@@ -1,7 +1,7 @@
 ---
 model_tier: medium
 name: fe-design
-description: "Frontend design heuristics — and, outside the ticket engine, the loop that applies them: audit, brief, build, review. Use when building or changing any UI, not only when planning one."
+description: "Frontend design heuristics — and, outside the ticket engine, the loop that applies them: audit, brief, inventory, build, review. Use when building or changing any UI, not only when planning one."
 personas:
   - frontend-engineer
 domain: engineering
@@ -40,8 +40,32 @@ else runs the loop.
    `layout`, `components`, `states`, `microcopy`, `a11y`. `states` means all
    five of `empty`, `loading`, `error`, `success`, `disabled` — a brief missing
    one is unfinished, not concise.
-3. **Build** — against the audit's primitives, in the project's stack.
-4. **Review** — run [`design-review`](../design-review/SKILL.md) before calling
+3. **Inventory — only when an artifact was provided, and before you build.**
+   List the artifact's **interactions, keyframes, and script includes** from its
+   source (`design-fidelity-mechanics` § Data-basis ladder — read it, do not
+   look at a picture of it). Then place **every** listed item in exactly one
+   bucket, using the engine's own names (`apply.ts`, `COVERAGE_BUCKETS`) so the
+   two surfaces read the same. **Nothing enforces that they stay the same** —
+   this is a copied vocabulary, not a shared constant, and no test pins it;
+   renaming a bucket in the engine leaves this list stale and silent:
+
+   | Bucket | Meaning |
+   |---|---|
+   | `honoured` | carried over as-is |
+   | `translated` | carried over in a different shape (a handler became a framework binding) |
+   | `flagged` | **not** carried over — with the reason, in the output |
+
+   Dropping a handler stays allowed; hiding one does not. An item in no bucket
+   is the failure this step exists to catch — "missing JavaScript" is what it
+   looks like from the user's side. Inside the engine this is enforced
+   (`apply.ts`, `COVERAGE_BUCKETS`, an unaccounted item is a halt); out here it
+   is a duty you carry, and nothing checks it for you. (fixture:
+   `daf-adhoc-port-coverage`.)
+4. **Build** — against the audit's primitives, in the project's stack. Where the
+   artifact's own markup/CSS/JS is stack-compatible, adapt **that code**;
+   re-deriving it from scratch is a deviation needing confirmation
+   (`design-fidelity-mechanics` § Adopt the code).
+5. **Review** — run [`design-review`](../design-review/SKILL.md) before calling
    it done, and scope the verdict honestly: render-scoped when you can render
    it, otherwise explicitly static-scoped, naming which checks actually ran.
    "Looks good" with neither scope named is a verdict without evidence.

package/dist/agent-src/skills/judge-synthesis/SKILL.md

@@ -103,6 +103,36 @@ contested.
 Each entry carries **provenance**: which judge(s) raised it. Never merge two
 judges' findings into one unattributed line.
 
+### 4b. Mark an uncited assertion — never drop it
+
+A panelist assertion carrying neither fresh evidence produced this run (a
+`file:line`, a command's output, a diff hunk) nor a citation is **marked
+`uncited`** where it appears. It still ships.
+
+```
+FLAG THE UNCITED ASSERTION. NEVER DROP IT.
+A SUPPRESSED FINDING IS INDISTINGUISHABLE FROM A FINDING NOBODY MADE.
+```
+
+The distinction is load-bearing and it is the reason this is a marking rule
+rather than a filter: an unevidenced assertion may still be the most valuable
+line in the report — a judge noticing something it could not yet prove is
+exactly the signal a human wants. What the reader needs is to know which
+category they are reading, not to be protected from one of them.
+
+**Drop was considered and rejected against this file.** The formulation this
+was adapted from offers "drop or flag"; the drop half contradicts § 4's
+Advisory tier three paragraphs up — *"Emitted in full, never elided … a finding
+that reached a judge and not the reader was suppressed by the aggregator"*.
+Taking it would have put two rules in one skill in direct conflict, with the
+newer one silently winning. Marking satisfies the same goal (the reader can
+tell evidence from assertion) at zero information cost.
+
+Scope: this marks **panelist** assertions inside a synthesis. It does not reach
+the reviewed change, and it is not the `code-provenance` knowledge-layer
+obligation, which governs what a durable artefact asserts rather than what a
+transient review does.
+
 ### 5. Overall recommendation
 
 One sentence, not a number: `block` (any worst-tier verdict), `revise` (any

package/dist/agent-src/skills/learning-to-rule-or-skill/SKILL.md

@@ -31,6 +31,17 @@ Use this skill when:
   a repeated phase pattern via
   [`extract_audit_patterns.ts`](../../../scripts/extract_audit_patterns.ts)
   — the pattern's `count` ≥ 2 already satisfies the repetition gate
+* A comparative analysis handed over a **`### SEED —` block** from its
+  `## Seeds` section ([`/analyze:reference-repo`](../../agent-src/commands/analyze/reference-repo.md)
+  § 6). This is an accepted intake shape: the block already carries the
+  proposed name, kind, target template, one-line description, and the
+  `Extends instead?` answer, so step 4's overlap search starts from a stated
+  candidate rather than a blank page — it does **not** skip that search, and a
+  seed whose `Extends instead?` line is missing is incomplete intake, not a
+  shortcut. The repetition gate is satisfied differently here: the evidence is
+  the anchored ADOPT/ADAPT verdict behind the seed rather than a recurrence
+  count — a mechanism confirmed once against a named own-repo defect is not the
+  one-off case the gate exists to filter.
 
 Do not use this skill when:
 

package/dist/agent-src/skills/roadmap-writing/SKILL.md

@@ -152,14 +152,14 @@ Sign-off" phases are authoring bugs; replace each with an
 agent-verifiable check (a command, a targeted test, a grep). Never
 restate run-time safety floors as steps.
 
-Gate-test before any checkpoint: *"Could the agent clear this with a
-tool or command during the run?"* Yes → step, not gate. No →
-structured `## Blockers` entry (§ 5b), distinguishing per rule 22:
-**human gate** (only a human can decide/authorize — Hard-Floor
-authorization, billable spend, contested decision) vs **external
-blocker** (agent cannot resolve but CAN probe status — CI run, package
-release, upstream PR; `Resolved when:` carries the probe, owner is
-not a human). Merge is never a completion requirement — it may appear
+Gate-test — three rungs in order (rule 22 owns the detail): **1.** agent-clearable
+by tool/command → step. **2.** has a technical answer a council could reach → still
+a step, first action runs the council; a contested *technical* decision is never a
+human gate while one is configured (`agent-config council:status`). **3.** what
+survives both → `## Blockers` (§ 5b): **human gate** (only a human can
+decide/authorize — Hard-Floor authorization, billable spend, or preference / risk
+appetite / product intent) vs **external blocker** (agent cannot resolve but CAN
+probe status — CI run, package release, upstream PR; `Resolved when:` carries the probe, owner is not a human). Merge is never a completion requirement — it may appear
 as a blocker only when later roadmap work depends on the merged state.
 `lint_roadmap_complexity` warns on human-gate patterns in every mode.
 

package/dist/agent-src/skills/skill-writing/SKILL.md

@@ -102,6 +102,10 @@ Do NOT create a skill or rule for:
 → See `docs/guidelines/agent-infra/size-and-scope.md` for full limits.
 
 * Target: 300–900 words. Review for split above 1200 words. Strongly consider split above 1500 words.
+* Over the 400-line K6 cap → the **router-head contract** in `templates/skill.md`
+  applies: entry head (when-to-use · mode table · routing) plus one `tasks/` or
+  `references/` file per mode, and the head never inlines more than one mode's
+  procedure. Gated by `lint_skill_router_head` with a shrink-only allowlist.
 * If multiple workflows exist → split into multiple skills
 * If two skills overlap heavily → merge
 * If a skill becomes "read the guideline" → it lost its purpose, restore the workflow

package/dist/agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.ts (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "10.2.0"
+agent_config_version: "10.3.0"
 
 # --- Project identity ---
 project:

package/dist/agent-src/templates/persona.md

@@ -38,6 +38,32 @@ source: package
   - mode            optional — advisory link to a role-contracts workflow mode
   - version         required — semantic version; bump on breaking changes
   - source          required — "package" for personas shipped in dist/agent-src/
+  - sources         optional — harvest_id list this persona may cite as external
+                    doctrine (provenance/harvests.jsonl). OMIT IT unless you mean
+                    one of the two scoped states; absent is the normal case and
+                    the one every existing persona is in.
+-->
+
+<!-- SOURCES — an epistemic scope, not a bibliography.
+
+  A persona declares a voice. `sources:` optionally declares what that voice is
+  allowed to assert as *external doctrine* — as opposed to its own reasoning,
+  which needs no declaration and is never restricted.
+
+  | State | Meaning |
+  |---|---|
+  | field absent | Unscoped. Today's behaviour for every persona; nothing changes. |
+  | `sources: []` | Explicitly asserts nothing harvested — its positions are its own. |
+  | `sources: [id, …]` | May cite those harvest ids as doctrine. |
+
+  Every declared id must resolve to a row in `provenance/harvests.jsonl`;
+  `lint_harvest_provenance` fails an id that does not. Do NOT invent a row to
+  populate the field — an empty ledger and an absent field is the correct
+  resting state, and `[]` is for a persona where the distinction is worth
+  stating out loud.
+
+  This does not touch the Unique-Questions heuristic. A scoped persona still
+  earns its place by asking what nobody else asks.
 -->
 
 # {Role name}

package/dist/agent-src/templates/roadmaps.md

@@ -197,9 +197,22 @@ Templates for roadmap files stored in `agents/roadmaps/` or `{module_root}/{Modu
       "user approves", "looks good", or "sign-off".
     - A **human gate** is allowed only when only a human can **decide or
       authorize**: a Hard-Floor action (deploy, prod data/infra),
-      billable spend, or a contested product / architecture decision.
-      Record it as a structured `## Blockers` entry (rule 20) — never as
-      an inline checkbox step scattered through phases.
+      billable spend, or a decision bound to the user's own preference,
+      risk appetite, or product intent.
+    - A **contested technical decision is not a human gate while a
+      council is configured.** Which design is sound, whether a contract
+      still holds, which of N implementations to pick — these have
+      technical answers, and `decision_resolution` already classes a
+      contract or architecture change as `medium_impact → council`
+      (`docs/contracts/ai-council-config.md`). Authoring them as human
+      gates contradicts that classification and spends the user's
+      attention on a question the council answers. Run it, record the
+      verdict in the phase, and the gate becomes a step.
+      `agent-config council:status` says whether one is configured —
+      never infer it from the project tree (`council-availability`).
+      Record a genuine gate as a structured `## Blockers` entry
+      (rule 20) — never as an inline checkbox step scattered through
+      phases.
     - An **external dependency is a blocker, not a human gate**, whenever
       the agent can probe its status (CI run finished, package version
       published, upstream PR merged, API reachable, DNS propagated):
@@ -216,10 +229,17 @@ Templates for roadmap files stored in `agents/roadmaps/` or `{module_root}/{Modu
       `security-sensitive-stop`, and `commit-policy` fire at run time on
       their own; an authored "STOP: confirm with user before X" duplicates
       them and only adds interruptions.
-    Gate-test before writing any checkpoint: *"Could the agent clear this
-    with a tool or command during the run?"* Yes → it is a step, not a
-    gate. No → structured blocker with a decidable `Resolved when:`,
-    owned by a human only when the blocker is a genuine human gate.
+    Gate-test before writing any checkpoint, asked in this order:
+    1. *"Could the agent clear this with a tool or command during the
+       run?"* Yes → it is a step, not a gate.
+    2. *"Does it have a technical answer a council could reach?"* Yes →
+       it is a step whose first action runs the council.
+    3. Only what survives both — preference, risk appetite, product
+       intent, authorization, spend — becomes a structured blocker with
+       a decidable `Resolved when:`, owned by a human.
+    Stopping at question 1 is the authoring bug this ordering exists to
+    prevent: it sends every decision the agent cannot compute straight to
+    the user, including the ones the council exists to answer.
     `task lint-roadmap-complexity` warns on human-gate step patterns,
     human-gate phase headings, and human-approval exit criteria.
 

package/dist/agent-src/templates/skill.md

@@ -207,8 +207,42 @@ Before considering a skill complete, verify it passes all 5 checks:
 - [ ] **K3: No obvious content** — doesn't teach the model what it already knows; only project-specific conventions and non-obvious patterns
 - [ ] **K4: Has Gotcha section** — documents real failure patterns, not theoretical advice; seeded with 2-3 entries
 - [ ] **K5: Has Output format** — numbered list with 2-4 deliverables describing what the skill produces
-- [ ] **K6: Under 400 lines** — if larger, extract reference tables or templates into separate files in the skill folder
+- [ ] **K6: Under 400 lines** — if larger, restructure as a router head per the contract below (gate: `lint_skill_router_head`)
 - [ ] **English only** — all content in English
 - [ ] **No duplication** — doesn't repeat rules or guidelines that are already enforced elsewhere
 - [ ] **No "Related skills" section for mid-tier / untiered skills** — the agent discovers them via `<available_skills>` descriptions; cross-links waste tokens. Senior-tier skills (`tier: senior`) MUST include the block per `skill-quality.md` § Senior-Tier Required Structure (linter-enforced).
 
+## The router-head contract (K6, over the cap)
+
+A `SKILL.md` over the 400-line cap restructures instead of growing. The shape:
+
+| Part | Holds | Budget |
+|---|---|---|
+| **Entry head** — `SKILL.md` | When-to-use · a mode table · the routing that picks a mode · anything true across *all* modes | the cap |
+| **Mode bodies** — `tasks/*.md` or `references/*.md` in the skill folder | One file per mode: the procedure, its examples, its tables | unbudgeted |
+
+One binding constraint on the head: **it never inlines the procedure body for
+more than one mode.** A head that carries mode A in full and points at modes
+B and C has not been restructured — it has been relabelled, and the next edit
+will grow it back.
+
+### What this contract does NOT claim
+
+It does not claim a token win. The host loads `SKILL.md` whole on trigger, and
+whether it then follows a pointer into `tasks/` is host behaviour **nothing in
+this tree observes**. Anyone proposing a retrofit of an existing oversized skill
+on activation grounds is asserting something currently unmeasurable, and
+ADR-202's lesson binds: an activation claim goes behind a measured instrument or
+it is not made.
+
+What the contract does is narrower and real: the 400-line cap was already this
+repo's published position, sitting in a checklist nothing enforced. The gate
+makes an existing contract true for **new** skills. Restructuring the current
+offenders is a separate decision with its own evidence bar.
+
+### Grandfathering
+
+`lint_skill_router_head` carries a shrink-only allowlist seeded with the skills
+that already exceed the cap. Entries may be removed, never added — a new
+oversized monolith fails the gate rather than joining the list.
+