@event4u/agent-config 10.2.0 → 10.4.0

package/README.md

@@ -4,7 +4,7 @@
 
 [![Smoke](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml) [![Public install smoke (3 OS × 2 Node)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml) [![npm](https://img.shields.io/npm/v/@event4u/agent-config?style=flat-square&label=npm&color=orange)](https://www.npmjs.com/package/@event4u/agent-config) [![agent-config MCP server](https://glama.ai/mcp/servers/event4u-app/agent-config/badges/score.svg)](https://glama.ai/mcp/servers/event4u-app/agent-config) [![MCP Toplist](https://mcptoplist.com/badge/glama%2Fevent4u-app%2Fagent-config.svg)](https://mcptoplist.com/server/glama%2Fevent4u-app%2Fagent-config)
 
-[![Skills](https://img.shields.io/badge/Skills-289-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-116-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-196-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-105-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/)
+[![Skills](https://img.shields.io/badge/Skills-289-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-116-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-200-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-105-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/)
 
 **Try it in 30 seconds** — drop one read-only subagent into any repo and watch it gate "done": `@production-validator check this branch is actually done`. No wizard, no lock-in, nothing else installed — the [30-second wedge ↓](#quickstart) is the whole first step. Start at the proof, not the catalog: **[event4u-app.github.io/agent-config/proof/](https://event4u-app.github.io/agent-config/proof/)**.
 

package/dist/agent-src/commands/analyze/reference-repo.md

@@ -254,9 +254,35 @@ incomplete document. Never a drawer to fill.}
 
 {Only if --no-roadmap was not set.}
 
+## Seeds
+
+{One block per ADOPT/ADAPT row whose adoption lands in a NEW skill or rule —
+omit the section entirely when every row extends something that exists.}
+
+### SEED — {proposed-name}
+
+> Proposal. Nothing is created from this block without an explicit ask.
+
+- **Kind:** skill | rule
+- **Target template:** `src/agent-src/templates/skill.md` | `.../rule.md`
+- **One-line description:** {what it does, in the voice the template wants}
+- **Cites:** {harvest ids this artefact will carry, once § 8 records them}
+- **Extends instead?** {the nearest existing artefact considered, and why it
+  does not fit — a seed that skipped this line is not ready to hand over}
+
 ## Open questions for the maintainer
 ```
 
+The `## Seeds` section is the handoff shape
+[`learning-to-rule-or-skill`](../../../../skills/learning-to-rule-or-skill/SKILL.md)
+accepts as intake. It is a **proposal artifact, never an auto-created file** —
+the block says so in its own first line, so the property survives being read out
+of context. The `Extends instead?` field is load-bearing rather than decorative:
+it makes the four-surface overlap scan that
+[`artifact-drafting-protocol`](../../../../rules/artifact-drafting-protocol.md)
+requires visible at handoff time, when the analysis is still open, instead of
+re-derived later by whoever picks the seed up.
+
 ### 7. Offer next steps
 
 After writing the file, present:
@@ -270,6 +296,42 @@ After writing the file, present:
 
 Never create the roadmap without explicit confirmation.
 
+### 8. Close the loop — offer the ledger rows
+
+**Only after a roadmap draft is accepted** (option 1 or 2 above). This step
+exists because the command otherwise ends with the knowledge it harvested
+recorded nowhere citable: the analysis document is archived evidence, and the
+next comparative pass re-litigates the same provenance from scratch.
+
+Offer — never write unasked, same confirmation floor as every other write here:
+
+> Record {N} harvest row(s) in `provenance/harvests.jsonl`?
+> {one preview line per row}
+
+One row per **anchored ADOPT or ADAPT** finding, and nothing else:
+
+| Field | Filled from |
+|---|---|
+| `harvest_id` | a kebab-case slug for the mechanism |
+| `stated_in` | the roadmap file the user just accepted |
+| `source_ref` | the reference's `<url>@<sha>` — the § 2 pin, already recorded in the document header |
+| `evidence_locator` | the reference-side `file:line` from that row of the comparison matrix |
+| `harvested_at` | today |
+| `verdict` | `adopt` or `adapt` |
+
+**REJECT, ALREADY, and UNCLEAR rows produce nothing.** Not an oversight: the
+ledger's integrity gate asserts that every row's `stated_in` artefact exists,
+and a rejected finding has no artefact — it is recorded in this analysis
+document, which is where a later harvest goes to learn the question was already
+settled. Writing rejections into the ledger would either break the gate or
+force it to stop checking the thing it exists to check.
+
+**Confidential sources.** When [`source-confidentiality`](../../../../rules/source-confidentiality.md)
+keeps the reference's name out of the tracked tree, `source_ref` takes the
+opaque form (`opaque:<id>` / an `ENC1:` token) instead of the URL. The row still
+pins something; it just does not name it. Contract and field shapes:
+`provenance/README.md`.
+
 ## Safety
 
 - Read-only on the reference. Never execute it, never submit PRs to it. Never

package/dist/agent-src/commands/analyze.md

@@ -5,7 +5,7 @@ disable-model-invocation: true
 argument-hint: "[postmortem|premortem|decision|near-miss|incident|reference-repo|inbox] [subject]"
 pack: analysis-workbench
 intent: "Analysis dispatcher — classify input by keywords, propose a weighted framework path, let the user pick"
-routes_to: [analyze-postmortem, analyze-premortem, analyze-decision, analyze-near-miss, analyze-incident, analyze-reference-repo, analyze-inbox]
+routes_to: [analyze-postmortem, analyze-premortem, analyze-decision, analyze-near-miss, analyze-incident, analyze-reference-repo, analyze-inbox, analyze-conformance]
 replaces: []
 tier: 1
 visibility: advanced
@@ -40,6 +40,7 @@ to the chosen sub-command. Never auto-selects silently.
 | `/analyze:incident` | `analyze/incident/command.md` | Full incident flow: commander → RCA → post-mortem → memory candidate |
 | `/analyze:reference-repo` | `analyze/reference-repo/command.md` | Deep-dive an external reference repo (competitor, inspiration, peer) → structured comparison + adoption plan |
 | `/analyze:inbox` | `analyze/inbox/command.md` | Deep-dive a LOCAL artifact dropped in `agents/tmp/` (review, prompt, spec, transcript) → claim verification against the current tree + artefact mapping + roadmap |
+| `/analyze:conformance` | `analyze/conformance/command.md` | Audit recent local sessions for rule violations → deterministic scan + subagent passes, root-caused per class, and a roadmap for what is mechanisable |
 
 ## Dispatch
 

package/dist/agent-src/commands/design-system/capture.md

@@ -0,0 +1,44 @@
+---
+model_tier: medium
+name: design-system-capture
+pack: engineering-base
+tier: 2
+visibility: internal
+cluster: design-system
+sub: capture
+skills: [existing-ui-audit, design-system-capture]
+description: Inventory this repo's own components and tokens and emit them in the design-system.json shape, so the import path is identical to an external extraction.
+argument-hint: "[path]"
+suggestion:
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
+workspaces:
+  - engineering
+packs:
+  - frontend-design
+---
+
+# /design-system:capture
+
+Run [`existing-ui-audit`](../../skills/existing-ui-audit/SKILL.md) over the
+current repo and emit its inventory as a `design-system.json` artifact — the
+same shape an external extraction tool produces, so the import path is identical
+either way. Args: optional `[path]` to narrow the scan.
+
+Two sources, one shape: use this for **this** repo, and
+[`/design-system:import`](../import/command.md) for a site or repo you do not
+own.
+
+## Then hand it over
+
+Pass the emitted artifact to [`design-system-capture`](../../skills/design-system-capture/SKILL.md)'s
+import step, which confirms it per field into `DESIGN.md`.
+
+## Rules
+
+- **Set `source` honestly** — `kind: dir`, `ref` = the scanned path,
+  `captured_at` = now. An artifact with no provenance is rejected downstream.
+- **Observation is not a token.** Anything the audit *noticed* rather than
+  *decided* belongs under `_meta`, per the contract's field rules.
+- **The audit's own grouping is not the contract's shape.** Map it deliberately;
+  do not rename the audit's output keys and call it done.

package/dist/agent-src/commands/design-system/generate.md

@@ -0,0 +1,53 @@
+---
+model_tier: high
+name: design-system-generate
+pack: engineering-base
+tier: 2
+visibility: internal
+cluster: design-system
+sub: generate
+skills: [corpus-grounding, design-intelligence, design-system-capture]
+description: Ground a design system in the curated design corpus from a product or industry brief, then optionally persist it as MASTER.md or seed DESIGN.md.
+argument-hint: "<product / industry / keywords>"
+suggestion:
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
+workspaces:
+  - engineering
+packs:
+  - frontend-design
+---
+
+# /design-system:generate
+
+Run the grounded one-shot over the curated corpus and print the full
+recommendation. Args: `"<product / industry / keywords>"`.
+
+```bash
+npx tsx node_modules/@event4u/agent-config/src/skills/corpus-grounding/scripts/ground.ts \
+    ground "<query>" \
+    --manifest node_modules/@event4u/agent-config/src/skills/design-intelligence/data/manifest.json
+```
+
+Add `--persist <dir> --project-name <name>` to write
+`design-system/<slug>/MASTER.md`, and `--page <name>` for a page-override stub
+alongside it. The engine is read-only without `--persist`.
+
+## After the recommendation
+
+Offer both destinations, and let the human pick — they are different artifacts,
+not two spellings of one:
+
+- **`MASTER.md` + page overrides** (`--persist`) — the interchange format, good
+  for handing a system to another tool or to a designer.
+- **`DESIGN.md`** via [`design-system-capture`](../../skills/design-system-capture/SKILL.md)
+  — this package's canonical design memory, the file every later design task
+  reads. Seed it when the system is for *this* repo's own work.
+
+## Rules
+
+- **Generated output is a proposal.** A provided artifact, registered brand
+  tokens, and a confirmed `DESIGN.md` outrank it — never overwrite a confirmed
+  decision with a generated default.
+- **Never persist silently.** `--persist` is the human's choice, and `DESIGN.md`
+  is seeded per field, not written wholesale.

package/dist/agent-src/commands/design-system/import.md

@@ -0,0 +1,63 @@
+---
+model_tier: medium
+name: design-system-import
+pack: engineering-base
+tier: 2
+visibility: internal
+cluster: design-system
+sub: import
+skills: [design-system-capture]
+description: Run an extraction tool's output through the three-lane adapter into the design-system.json contract, then hand it to the per-field confirmation import.
+argument-hint: "<file>"
+suggestion:
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
+workspaces:
+  - engineering
+packs:
+  - frontend-design
+---
+
+# /design-system:import
+
+Transform an extracted design system into the `design-system.json` contract,
+then import it per field. Args: `<file>`.
+
+```bash
+npx tsx node_modules/@event4u/agent-config/src/scripts/design_system_import.ts <file> \
+    [--lane native|dtcg|dembrandt] \
+    [--source-kind url|repo|dir --source-ref <ref>] [--captured-at <ISO>] \
+    [--format json|summary]
+```
+
+The lane is detected from the file's own shape; `--lane` only forces which
+mapper runs and never reshapes the input. Lane behaviour, the documented
+producers, and the never-force-a-lane degradation are specified in
+[`design-system-json.md`](../../skills/design-system-capture/references/design-system-json.md)
+§ Extractor compatibility.
+
+## The easy path, in two lines
+
+1. Connect an extractor once — e.g.
+   `claude mcp add --transport stdio dembrandt -- npx -y --package dembrandt dembrandt-mcp`.
+2. Run `/design-system:import` over its output.
+
+No extractor available? Skip step 1 and use
+[`/design-system:generate`](../generate/command.md) from the corpus instead, or
+[`/design-system:capture`](../capture/command.md) for this repo.
+
+## Then hand it over
+
+Pass the result to [`design-system-capture`](../../skills/design-system-capture/SKILL.md)'s
+import step. Do not write `DESIGN.md` from here.
+
+## Rules
+
+- **Provenance is mandatory.** A file with no `source` and no `--source-ref` is
+  rejected — you cannot confirm what you cannot trace. Supplying it by flag is
+  recorded as caller-asserted, not extracted.
+- **The artifact is observed, not authoritative.** Every field is confirmed by
+  the human; a value conflicting with a registered brand token is flagged, never
+  auto-applied.
+- **The adapter is offline.** It reads a file and writes the contract shape — it
+  never fetches, crawls, or launches a browser.

package/dist/agent-src/commands/design-system.md

@@ -0,0 +1,66 @@
+---
+model_tier: inherit
+name: design-system
+pack: engineering-base
+tier: 2
+visibility: internal
+cluster: design-system
+type: orchestrator
+description: Design-system onramp — generate one from the corpus, import an extractor's output, or capture the current repo's. Three doors onto machinery that already ships.
+argument-hint: "[generate|import|capture] [args]"
+suggestion:
+  eligible: true
+  trigger_description: "generate a design system, import extracted design tokens, capture this repo's design system, seed DESIGN.md from a site"
+  trigger_context: "user explicitly wants a design system produced, imported, or captured — never suggested for ordinary UI work"
+workspaces:
+  - engineering
+packs:
+  - frontend-design
+---
+
+# /design-system
+
+Three doors onto machinery this package already ships and nothing could reach.
+The grounded generator, its `MASTER.md` persistence, the `design-system.json`
+import contract, and the current-repo inventory all existed before this cluster;
+what was missing was a way in. So every sub-command below is an entry point, not
+a new subsystem.
+
+**Optional means invoked or not invoked.** This cluster adds no settings key, no
+always-on rule, and no auto-trigger. It is suggestion-eligible only when a
+design-system question is explicit, and otherwise silent.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/design-system:generate "<product / industry / keywords>"` | `commands/design-system/generate.md` | Ground a design system in the curated corpus; optionally persist `MASTER.md` + page overrides, or seed `DESIGN.md` |
+| `/design-system:import <file>` | `commands/design-system/import.md` | Run an extractor's output through the three-lane adapter, then the per-field confirmation import |
+| `/design-system:capture` | `commands/design-system/capture.md` | Inventory *this* repo's components and tokens and emit the same `design-system.json` shape |
+
+## Dispatch
+
+1. Parse `/design-system <sub-command> [args]`. Sub-command = first token; match
+   against the table's exact names only.
+2. Look up the sub-command and execute its file verbatim with the remaining args.
+3. Unknown / missing sub-command → print the table and ask which door to take.
+
+## Rules
+
+- **Do NOT commit, push, or open a PR** — subcommands never do this.
+- **Do NOT chain subcommands.** One `/design-system <sub>` per turn.
+- **Generated and imported output is a proposal.** A provided artifact,
+  registered brand tokens, and a confirmed `DESIGN.md` all outrank it; a value
+  that conflicts with a registered brand token is flagged, never auto-applied
+  (per [`brand-source-of-truth`](../rules/brand-source-of-truth.md)).
+- **No crawler, browser runtime, or font-bundler is shipped.** Extraction tools
+  are user-installed and user-connected; this package's share is the adapter,
+  the instructions, and the validation.
+- **Edit `src/` only.** Generated mirrors regenerate.
+
+## See also
+
+- [`design-system-capture`](../../skills/design-system-capture/SKILL.md) — owns `DESIGN.md` and the per-field-confirmation import.
+- [`corpus-grounding`](../../skills/corpus-grounding/SKILL.md) · [`design-intelligence`](../../skills/design-intelligence/SKILL.md) — the grounded generator behind `:generate`.
+- [`existing-ui-audit`](../../skills/existing-ui-audit/SKILL.md) — the current-repo inventory behind `:capture`.
+- [`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md) — `design-system` cluster registration.

package/dist/agent-src/commands/roadmap/create.md

@@ -268,7 +268,10 @@ Write the pick to frontmatter as `execution.mode:`
   rewrite each hit as an agent-verifiable check (a command, a targeted
   test) **before saving**, or promote it to a structured `## Blockers`
   entry: a **human gate** only when only a human can decide/authorize
-  (Hard-Floor authorization, billable spend, contested decision); an
+  (Hard-Floor authorization, billable spend, or a decision bound to
+  preference, risk appetite, or product intent). A contested **technical**
+  decision is not a human gate while a council is configured — it is a
+  step whose first action runs the council (template rule 22); an
   **external dependency** becomes a blocker whose `Resolved when:`
   names an agent-checkable status probe — never a human gate. Do not
   author safety floors as steps — they fire at run time on their own.

package/dist/agent-src/personas/advisors/first-principles.md

@@ -7,6 +7,12 @@ mode: reviewer
 version: "1.0"
 source: package
 council_advisor: true
+# Explicitly empty, not merely unset: reconstructing a problem from its
+# irreducible constraints is this advisor's whole function, so "asserts no
+# harvested doctrine" is a statement about the lens rather than a gap in one.
+# Every other persona leaves the field absent (unscoped) — see the sources
+# block in templates/persona.md for the three states.
+sources: []
 ---
 
 # First-Principles Advisor

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.