@event4u/agent-config 6.1.0 → 7.0.0

package/dist/agent-src/skills/typography-system/SKILL.md

@@ -0,0 +1,138 @@
+---
+model_tier: inherit
+name: typography-system
+description: "Derive a type system from a style constraint — query curated font pairings, set scale/line-height/weights, emit DTCG tokens via design-tokens. Use when choosing fonts or building a typographic scale."
+domain: product
+personas: []
+workspaces:
+  - engineering
+packs:
+  - frontend-design
+trust:
+  level: professional
+install:
+  removable: true
+execution:
+  type: manual
+---
+
+# typography-system
+
+Turn a style constraint into a full typographic system: pick a verified font
+pairing, derive a modular scale, and emit DTCG `$type: "typography"` tokens
+through the `design-tokens` toolchain.
+
+A **two-stage Method**: stage 1 (below) is the **style path** — a mood/idiom
+constraint drives the pairing. Stage 2 is the **brand-aware path** — when a
+brand layer exists, the brand archetype filters the pairing first. The skill
+degrades gracefully: with no brand layer, only stage 1 runs.
+
+## When to use
+
+- Choosing heading/body fonts for a new product or rebrand.
+- Building or overhauling a typographic scale (sizes, line-height, weights).
+- Any request to "set the typography" or "pick fonts" for a design system.
+- Before calling `design-tokens` for a new project — typography tokens belong
+  in `tokens.json` alongside color tokens, not hand-coded in CSS.
+
+## Procedure
+
+1. **Take a style/idiom constraint** from the `design-intelligence` idiom
+   corpus — a mood keyword (e.g. `elegant`, `modern`, `playful`) or a
+   named idiom that carries typographic intent.
+2. **Query `font-pairings-reference.csv`** (Reference layer) — filter by the
+   `Mood/Style Keywords` column; surface the top 1–2 matching pairings with
+   their Heading Font, Body Font, Best For, and Google Fonts URL.
+3. **Derive the type scale** — pick a modular ratio (1.25 Minor Third or 1.333
+   Perfect Fourth for most products); compute sizes for `xs / sm / base / lg /
+   xl / 2xl / 3xl`; set `line-height` (1.5 for body, 1.2 for display);
+   assign weights (400 body, 600–700 heading).
+4. **Emit DTCG `$type: "typography"` tokens** through `design-tokens`
+   (`scripts/tokens.py`) — add a `typography` section to `tokens.json` with
+   `$type: "typography"` and `$value` objects carrying `fontFamily`,
+   `fontSize`, `fontWeight`, `lineHeight`.
+5. **Verify** — confirm both chosen fonts exist on Google Fonts (check the
+   `Google Fonts URL` column in the CSV); run
+   `python3 <skills-root>/design-tokens/scripts/tokens.py validate --dir src/`
+   to confirm no hardcoded font-size or font-family values remain outside the
+   token file; exit code 0 is the evidence.
+
+## Stage 2 — brand-aware path (when a brand layer exists)
+
+When a brand archetype is known (a confirmed `brand-strategy` /
+`brand-identity` constraint set, or a consumer brand profile), filter the
+pairing by the archetype **before** the mood match — the brand constrains the
+style, not the other way around.
+
+1. **Resolve the archetype** from the active brand layer (e.g. `Ruler`,
+   `Lover`, `Magician`).
+2. **Query the brand `typography` Grounding domain** for the archetype →
+   pairing-filter (Heading Class, Body Class, Mood, plus confidence +
+   evidence gap):
+
+   ```bash
+   python3 <skills-root>/corpus-grounding/scripts/ground.py search \
+     --manifest <skills-root>/brand/data/manifest.json \
+     "<archetype + sector>" --domain typography --json
+   ```
+
+3. **Filter `font-pairings-reference.csv` by that pairing-filter** — keep only
+   pairings whose Heading/Body classes satisfy the archetype filter (e.g. a
+   `Ruler` / law-firm brief keeps serif-containing pairings; a `Magician` /
+   SaaS brief keeps geometric-sans pairings). Then apply the stage-1 mood match
+   within the filtered set.
+4. **Surface the corpus `confidence` + `evidence_gap`** for the archetype row,
+   then emit DTCG type tokens exactly as stage 1 (steps 4–5 above).
+5. **Trigger-eval invariant:** a "law-firm redesign" brief MUST route to a
+   serif-containing pairing (the archetype filter is `Ruler` → serif). This is
+   the recorded brand-aware regression test (recorded in Phase D).
+
+Consumer brand tokens outrank the corpus filter
+([`brand-source-of-truth`](../../rules/brand-source-of-truth.md)) — if the
+brand already registers fonts, use them and skip the filter.
+
+## Output format
+
+1. **Chosen pairing + rationale** — heading font, body font, the CSV row's
+   `Best For` field, and the one-line mood match that drove the selection.
+2. **DTCG type-token block** — the `typography` section ready to paste into
+   `tokens.json` (DTCG `$type: "typography"`, `$value` with `fontFamily`,
+   `fontSize`, `fontWeight`, `lineHeight` per level).
+3. **CSS/Tailwind import line** — the `@import url(…)` from the CSV's
+   `CSS Import` column, and the Tailwind `fontFamily` config snippet from
+   `Tailwind Config`.
+
+## Gotcha
+
+- **Stale CSV URL → silent system-font fallback.** `font-pairings-reference.csv`
+  is Reference data on a freshness contract — never substitute a live Google
+  Fonts API call. If a font was retired or renamed, the `@import` URL 404s at
+  build time and the browser silently falls back to the system font, shipping
+  broken visual design with no obvious error. Always verify the URL resolves
+  (Step 5) before emitting the import line; if it 404s, surface the error and
+  ask the user to pick an alternative pairing from the CSV.
+
+## Do NOT
+
+- Do NOT hardcode font sizes outside the token scale (e.g. `font-size: 18px`
+  inline) — every size belongs in `tokens.json` under the `typography` layer.
+- Do NOT bypass `design-tokens` and write raw CSS custom properties for fonts
+  — `tokens.json` is the single source; hand-crafted `--font-*` vars drift.
+- Do NOT treat `font-pairings-reference.csv` as decision logic — it is
+  Reference data; the agent picks based on the style constraint, not by
+  iterating the CSV as a rules engine.
+- Do NOT skip step 5 (validate) before claiming the type system is complete —
+  unchecked hardcoded values in component files are the canonical failure mode.
+
+## See also
+
+- [`design-tokens`](../design-tokens/SKILL.md) — toolchain that generates CSS
+  vars and the Tailwind snippet from `tokens.json`.
+- [`design-intelligence`](../design-intelligence/SKILL.md) — idiom corpus that
+  supplies the style constraint consumed in Step 1.
+- [`iconography`](../iconography/SKILL.md) — companion visual-identity skill
+  (icon set selection, sizing scale).
+- [`fe-design`](../fe-design/SKILL.md) — broader frontend design skill that
+  consumes the token system produced here.
+- [`brand`](../brand/SKILL.md) — supplies the archetype → pairing-filter
+  Grounding (`typography` domain) consumed by stage 2.

package/dist/agent-src/skills/typography-system/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "skill": "typography-system",
+  "last_eval": "2026-06-16",
+  "description": "5 should-trigger + 5 should-not-trigger. Should-trigger covers font selection, scale derivation, and DTCG type token authoring. Should-not-trigger covers near-miss neighbors: icon set selection (iconography), raw design-token authoring without a typography constraint (design-tokens), brand archetype requests that require Stage 2 / Phase B, and general color token work.",
+  "queries": [
+    {"q": "pick fonts for our new SaaS product — something modern and professional", "trigger": true},
+    {"q": "build a typographic scale for our design system with DTCG tokens", "trigger": true},
+    {"q": "we need a type system for a luxury fashion brand — choose pairings and emit tokens", "trigger": true},
+    {"q": "what heading and body fonts match an elegant, editorial mood?", "trigger": true},
+    {"q": "set up font-size tokens and line-height for our Tailwind project", "trigger": true},
+    {"q": "which icon set should we use for our dashboard?", "trigger": false, "note": "icon selection → iconography skill"},
+    {"q": "author a 3-layer DTCG token system for colors with dark mode", "trigger": false, "note": "color token authoring without typography constraint → design-tokens skill"},
+    {"q": "define our brand archetype so the font pairing fits our personality", "trigger": false, "note": "brand archetype → pairing-filter is Stage 2 / Phase B, not authored yet"},
+    {"q": "generate CSS variables for our button component tokens", "trigger": false, "note": "component token generation → design-tokens skill"},
+    {"q": "run validate to find hardcoded hex values in our codebase", "trigger": false, "note": "token-discipline lint step → design-tokens skill (tokens.py validate)"}
+  ]
+}

package/dist/agent-src/skills/upstream-contribute/SKILL.md

@@ -170,9 +170,9 @@ The files must:
 ### 6. Run quality gates (if working in the package repo)
 
 ```bash
-python3 scripts/skill_linter.py --all          # 0 FAIL required
-python3 scripts/check_condensation.py            # No errors for this file
-python3 scripts/condense.py --generate-tools    # Regenerate symlinks
+./scripts-run src/scripts/skill_linter --all          # 0 FAIL required
+./scripts-run src/scripts/check_condensation            # No errors for this file
+./scripts-run src/scripts/condense --generate-tools    # Regenerate symlinks
 bash scripts/condense.sh --check                # dist/agent-src/ in sync with source
 bash scripts/condense.sh --check-hashes         # All hashes match
 ```

package/dist/agent-src/skills/verify-repair-loop/SKILL.md

@@ -0,0 +1,209 @@
+---
+model_tier: inherit
+name: verify-repair-loop
+description: "Use to iterate a change until tests/quality checks pass — bounded run→revise→re-run gated by a numeric threshold, then a judge confirms. Triggers 'iterate to green', 'keep fixing until tests pass'."
+domain: process
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# verify-repair-loop
+
+> Bounded **generate → run → revise → re-run** cycle; pass signal = the
+> **executed verdict** (real test/quality output, scored vs a numeric
+> threshold), escalated to a **judge** for qualitative confirmation only
+> *after* the numeric gate passes (staged escalation). Loop is the
+> conversation, not a process: no daemon, no persistent cross-session state.
+> Use to drive a change to green when the verdict source is *runtime
+> execution*, not a judge reading a diff.
+
+## When to use
+
+* Change must converge against the project's **test runner / quality tools**;
+  iterate until checks pass before review.
+* Test/quality coverage is the authoritative signal (high coverage, actionable
+  failures) — not subjective craft.
+* Bounded auto-repair with a hard stop, not an open-ended fix loop.
+
+Do NOT use when:
+
+* Verdict is **subjective craft** (naming, architecture, style) or coverage
+  incomplete → `do-and-judge` in
+  [`subagent-orchestration`](../subagent-orchestration/SKILL.md) (judge reads the
+  diff, sovereign).
+* Only a **one-shot** multi-judge review of a finished diff →
+  [`/review-changes`](../../commands/review-changes.md).
+* Verdict must come from a **live app** (Playwright vs running services) →
+  **deferred** (see Scope); use test/quality verdicts until that trigger fires.
+
+## The Iron Law
+
+```
+THE NUMERIC VERDICT IS NEVER SOVEREIGN.
+TESTS DECIDE WHEN TO ESCALATE — A JUDGE DECIDES WHETHER TO APPLY.
+A REVISION THAT BREAKS A PREVIOUSLY-GREEN CHECK STOPS THE LOOP,
+EVEN IF THE OVERALL SCORE ROSE.
+GENERATOR NEVER APPROVES ITS OWN CHANGE.
+```
+
+A loop optimizing for `pass_count ≥ N` can game the metric — delete tests, skip
+assertions, weaken checks — and still hit the threshold. The numeric gate only
+decides **when to escalate**; a judge with veto confirms the change is real.
+
+## Procedure
+
+### 1. Freeze the contract (spec fingerprint)
+
+Before the first run, snapshot what "done" means:
+
+* the task's acceptance criteria / requirement,
+* the check set defining the verdict (test files + quality commands),
+* a **spec fingerprint** = hash of (requirement text + check set).
+
+Record the **baseline green set** — checks passing *before* any edit — so
+regressions are detectable. Pick verdict commands per the project's
+[`toolchain-resolver`](../../contexts/execution/toolchain-resolver.md) (PHP / JS-TS
+/ Python / Go / Rust), not a hardcoded runner.
+
+### 2. Set the gate
+
+| Knob | Default | Meaning |
+|---|---|---|
+| `threshold` | all targeted checks green | numeric pass bar, **absolute** (fraction of total), not "± N tests" |
+| `allow_regressions` | `false` | a revision breaking a baseline-green check stops the loop |
+| `max_attempts` | **3** | hard cap (test feedback is more actionable than diff critique → one more than `do-and-judge`'s 2; bounded by [`autonomous-execution`](../../rules/autonomous-execution.md) N=3) |
+| `plateau_window` | 3 | stop if the last *window* scores sit within `tolerance` |
+| `tolerance` | small absolute fraction | flake jitter that does **not** count as improvement |
+
+### 3. The loop (multi-turn — the conversation IS the loop)
+
+Each iteration is agent turns, never executing control-flow code:
+
+1. **Generate / revise** — smallest change toward the contract.
+2. **Run** — execute verdict commands; parse the **structured** result
+   (green/total, which checks failed). One tool call, read in context.
+3. **Score + regression check** — compute the score; compare failures vs the
+   baseline green set.
+   * **Regression** (a baseline-green check now fails) → STOP, hand back with the
+     regression named, even if the score rose. No whack-a-mole.
+   * **Plateau** (last `plateau_window` scores within `tolerance`) → STOP; surface
+     suspected flakiness or a stuck point. Do not thrash.
+   * **`attempts == max_attempts`** → STOP, hand back the best envelope.
+4. **Numeric gate** — score `< threshold` and attempts remain → back to step 1
+   (attempts++). Score `≥ threshold`, no regression → **escalate** (step 4).
+
+### 4. Judge escalation (only after the numeric gate passes)
+
+Dispatch the judge as a **subagent with fresh context** (the `judge-*` cluster via
+[`subagent-orchestration`](../subagent-orchestration/SKILL.md)) seeing **only the
+diff + executed results** — never the generator's reasoning. This is the real
+generator ≠ judge separation; single-agent persona-switching is theater.
+
+* judge `apply` → DONE.
+* judge `revise` → back to step 3.1 (attempts++; bounded).
+* judge `reject` → STOP, hand back; the approach must change.
+
+### 5. Mid-loop invalidation (user-interrupt-priority)
+
+Re-check the spec fingerprint each iteration. If the user changes the requirement
+mid-loop (a new instruction in the conversation), the fingerprint changes →
+**abort and hand back** per
+[`user-interrupt-priority`](../../rules/user-interrupt-priority.md). Never iterate
+against a stale contract.
+
+## Scope — what runs, what is deferred
+
+| Verify context | In scope | Why |
+|---|---|---|
+| Unit / integration tests | ✅ | fast, deterministic, sandboxed — runtime-free |
+| Static quality (lint, type-check, format) | ✅ | fast, deterministic, no side effects (auto-fixable failures may bypass the revise step) |
+| Live-app Playwright / E2E | ⛔ **deferred** | needs running services (DB, API) = a runtime; trigger = a UI-observable mission output + Playwright wired into a consumer CI |
+
+State lives in the conversation, optionally mirrored to a re-read working file —
+**never** a daemon or persistent cross-session store (honors
+[`no-runtime-boundary`](../../../docs/contracts/no-runtime-boundary.md)).
+
+## Validation
+
+Before finalizing, confirm:
+
+1. The numeric gate **escalated to a judge** — it did not apply on its own.
+2. No baseline-green check regressed (or the loop stopped and said so).
+3. The loop stopped at `max_attempts`, a plateau, or a judge `apply` — never ran
+   unbounded.
+4. The judge saw only the diff + results, dispatched in fresh context.
+5. No daemon / persistent runtime introduced.
+
+## Output format
+
+```
+verify-repair-loop
+Contract:   <one-line requirement> · threshold <X> · allow_regressions false
+Attempts:   <k>/<max>  scores: [s1, s2, …]   stop: threshold|plateau|cap|regression|reject
+Verdict:    DONE | DONE_WITH_CONCERNS | BLOCKED
+Judge:      <judge skill> → apply|revise|reject
+Evidence:   <green/total> · regressions: none | <named checks>
+```
+
+Required fields (ordered):
+
+1. **Contract** — frozen requirement + threshold + `allow_regressions`.
+2. **Attempts** — `k/max`, score history, exact stop reason
+   (`threshold` / `plateau` / `cap` / `regression` / `reject`).
+3. **Verdict** — `DONE`, `DONE_WITH_CONCERNS`, or `BLOCKED`.
+4. **Judge** — dispatched judge skill + its `apply` / `revise` / `reject` verdict
+   (omit only when the loop stopped before escalation).
+5. **Evidence** — final `green/total` and any regressed checks by name.
+
+## Examples
+
+Good — staged, bounded, judge confirms:
+```
+iter1 84/100 (<90) → revise
+iter2 93/100 (≥90, no regression) → escalate → judge apply → DONE
+```
+
+Bad — numeric verdict treated as sovereign (rejected by the Iron Law):
+```
+iter1 91/100 ≥ threshold → "PASS, done"   ✗ no judge escalation; metric may be gamed
+iter2 fixes A, breaks B, 92% → "PASS"      ✗ regression ignored
+```
+
+## Gotcha
+
+* **Metric gaming** — agent "passes" by deleting a failing test or weakening an
+  assertion. The numeric gate can't catch this; the fresh-context judge is the
+  safeguard. A diff that *removes* checks is a `reject`, not a `pass`.
+* **Flake mistaken for a plateau** — one non-deterministic test flips the score
+  and the window-comparison reads "no improvement". Re-run the suspected check
+  before declaring a plateau; surface flakiness instead of thrashing.
+* **Score rose, but a regression hid inside it** — fixing 6 checks while breaking
+  2 still raises the total. Without the regression guard the loop ships a
+  regression. Diff failures against the baseline green set, not just the aggregate.
+* **Persona-switch theater** — asking the same agent to "now judge what you wrote"
+  is not separation. Dispatch the judge as a fresh-context subagent that never saw
+  the generator's reasoning.
+* **Stale contract** — iterating against a requirement the user changed mid-loop.
+  Re-check the spec fingerprint each turn; a change aborts.
+
+## Do NOT
+
+* NEVER let the numeric score apply a change without judge confirmation.
+* NEVER continue past a regression because the overall score improved.
+* NEVER run the live-app Playwright path here — it is deferred (needs a runtime).
+* NEVER judge with the generator's own context — dispatch a fresh-context judge.
+* NEVER loop past `max_attempts` or a detected plateau.
+
+## See also
+
+* [`subagent-orchestration`](../subagent-orchestration/SKILL.md) — `do-and-judge`
+  (judge-sovereign, diff-read) is the sibling; this skill is test-verdict-gated.
+* [`/review-changes`](../../commands/review-changes.md) — one-shot multi-judge
+  review; wires this loop as an opt-in step.
+* [`playwright-testing`](../playwright-testing/SKILL.md),
+  [`quality-tools`](../quality-tools/SKILL.md) — verdict sources.
+* [`autonomous-execution`](../../rules/autonomous-execution.md) — the N=3 cap.
+* [`no-runtime-boundary`](../../../docs/contracts/no-runtime-boundary.md) — the
+  runtime-free constraint this loop honors.

package/dist/agent-src/skills/verify-repair-loop/evals/output-schema.yml

@@ -0,0 +1,20 @@
+# Behavior-schema contract for `verify-repair-loop`.
+#
+# Locks the load-bearing safeguard sections so a refactor cannot
+# silently drift the skill away from its council-mandated guarantees
+# (numeric verdict not sovereign, judge escalation, regression guard,
+# bounded loop). Enforced by `scripts/skill_linter.py`
+# (`lint_output_schema`, matches `^## <header>$`) — a missing section
+# is a hard error.
+#
+# Governed by: road-to-autonomous-verify-loop.md Phase 2; the seven
+# safeguards in agents/evidence/analysis/verify-repair-loop-phase1-gate.md.
+
+version: 1
+
+required_headers:
+  - "The Iron Law"
+  - "Procedure"
+  - "Validation"
+  - "Output format"
+  - "Do NOT"

package/dist/agent-src/skills/verify-repair-loop/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "skill": "verify-repair-loop",
+  "last_eval": "2026-06-16",
+  "description": "5 should-trigger + 5 should-not-trigger. Should-trigger covers the bounded test-verdict-gated iterate-to-green loop (numeric threshold → judge escalation). Should-not-trigger covers near-miss neighbors: subjective-craft revision (do-and-judge), one-shot multi-judge review (review-changes), a single test run with no loop, judging a diff without execution, and the deferred live-app Playwright verdict.",
+  "queries": [
+    {"q": "keep fixing until the tests pass", "trigger": true},
+    {"q": "iterate this change to green, run the suite each time", "trigger": true},
+    {"q": "verify and repair until quality checks pass, then have a judge confirm", "trigger": true},
+    {"q": "loop: run tests, fix failures, re-run, stop when green or after 3 tries", "trigger": true},
+    {"q": "drive this to passing tests but don't let it break anything that was green", "trigger": true},
+    {"q": "is this diff clean — naming, structure, conventions?", "trigger": false, "note": "subjective craft, no executed verdict → do-and-judge / judge-code-quality"},
+    {"q": "review my changes before I open the PR", "trigger": false, "note": "one-shot multi-judge review → /review-changes"},
+    {"q": "run the test suite once and show me the failures", "trigger": false, "note": "single run, no iterate-to-green loop"},
+    {"q": "judge this patch and tell me if it's correct", "trigger": false, "note": "judge reads a diff, no execution loop → do-and-judge"},
+    {"q": "loop the Playwright end-to-end tests against the live app until the UI passes", "trigger": false, "note": "live-app verdict is deferred (needs a runtime); not this skill's scope"}
+  ]
+}

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

@@ -519,6 +519,13 @@ the canonical narrative lives in
 | `telemetry.artifact_engagement.output.path` | path | `.agent-engagement.jsonl` | Append-only JSONL log path, relative to the project root. Always gitignored. |
 | `linked_projects` | list of `{path, include}` | `[]` | IDE-attached sibling repos in scope for proactive cross-repo awareness. **Belongs in `.agent-settings.local.yml` (in agents/settings/)** (per-machine, gitignored). See [cross-repo guide](../../docs/guides/cross-repo-linked-projects.md) + ADR-032. |
 | `linked_projects_max_files` | integer | `20000` | File-count ceiling above which a detected sibling is flagged `large` (awareness only). Never excludes. |
+| `knowledge.global_sharing.enabled` | `true`, `false` | `false` | **User-global** (keep in `~/.event4u/agent-config/agent-settings.yml`). Master switch for the file-first global knowledge-card store (ADR-100; default-off per ADR-101 / Evidence v2 Phase 0 until cross-project reuse is measured). `false` fully no-ops the layer; v1 project-local cards unaffected. |
+| `knowledge.global_sharing.allowed_tiers` | list of `public`,`vendor`,`proprietary` | `[public, vendor]` | Origin tiers auto-eligible to cross a project boundary. `proprietary` is manual-only regardless (the gate hard-codes it). |
+| `knowledge.global_sharing.redaction.enabled` | `true`, `false` | `true` | Run the privacy-floor + source-confidentiality scan before any card goes global. |
+| `knowledge.global_sharing.redaction.halt_on_trigger` | `true`, `false` | `true` | Halt-and-surface on a confidential-pattern hit; never silent-share, never auto-rewrite. |
+| `knowledge.global_sharing.auto_promote_threshold` | integer | `2` | Distinct-repo count that triggers a promotion **suggestion** (never a silent write). |
+| `knowledge.global_sharing.freshness.hypothesis_after_days` | integer | `90` | Global card older than this is lead-only (positive structure re-confirmed before use). |
+| `knowledge.global_sharing.freshness.stale_after_days` | integer | `180` | Global card older than this is skipped until re-verified. |
 
 ### Rename-Map (migration)
 

package/dist/agent-src/templates/contexts/knowledge-card.md

@@ -0,0 +1,69 @@
+---
+type: anti-hallucination
+trust: durable
+# tier — origin classification for global cross-project sharing (ADR-100).
+# public = registry/GitHub/docs · vendor = known SaaS API · proprietary =
+# in-house DB / private API / client schema (manual-only, never auto-shared).
+# Optional for project-local cards; required (plus a provenance footer) once a
+# card is promoted to the global store. Resolve via knowledge_global.classify_tier.
+tier: "<public | vendor | proprietary>"
+origin: "<brief description — e.g. npm package / remote API / legacy DB>"
+url: "<canonical upstream URL>"
+ref: "<pinned version tag or commit SHA — never blind main>"
+version: "<installed version, e.g. 3.2.1>"
+links:
+  authoritative: "<canonical docs URL>"
+  local: "<relative path to node_modules/vendor file, e.g. node_modules/<pkg>/index.d.ts>"
+observed_at: "YYYY-MM-DD"
+revalidate_if: "<condition — e.g. version bumped, API contract changed, new fields added>"
+---
+
+<!--
+  Template shipped by event4u/agent-config.
+  Copy to `agents/knowledge/<source>.md` in the consumer project and fill in.
+  Frontmatter MUST stay at line 1 (the card linter anchors on it).
+  Delete this HTML comment after filling in.
+-->
+
+# Knowledge Card — <source>
+
+## Negative facts (trust: durable)
+
+<!--
+  Write a negative fact ONLY after exhausting the search across all relevant
+  sources for that claim. Log both what was searched and what was not searched.
+  Attach a revalidate_if trigger. Negative facts are current-state observations
+  ("searched X, did not find Y") — not design decisions.
+-->
+
+| claim | searched | not_searched | observed_at | revalidate_if | next_step |
+|---|---|---|---|---|---|
+| `<method/field/pattern> does not exist` | `<files / docs / SDL inspected>` | `<surfaces not yet checked>` | YYYY-MM-DD | `<condition that would invalidate>` | `<e.g. check if version X adds it>` |
+
+## Positive structure — last-verified HYPOTHESIS (Assumed-from-card, confirm before use)
+
+<!--
+  Positive structural claims are HYPOTHESES, never Verified — even when the
+  pointer below resolves green (R4 P1). Always confirm per-line before coding.
+  Each line MUST carry observed_at and source_version.
+-->
+
+**These are NOT Verified.** Load this card into the Evidence Report as
+"Assumed (from card)" and re-confirm against the real source this session. One
+entry per line; **each line MUST carry `observed_at:` and `source_version:`** in
+the keyed form below — the card linter (C5 multi-evidence consistency + the
+freshness signal) reads those keys, and `source_version`s on one card must sit in
+a single git-ancestry chain / within a 7-day window.
+
+- `<field/method>` (`<type/signature>`) — observed_at: YYYY-MM-DD · source_version: "<version-or-sha>" · `<note>`
+- `<field/method>` (`<type/signature>`) — observed_at: YYYY-MM-DD · source_version: "<version-or-sha>" · `<note>`
+
+## Pointers
+
+- **Authoritative:** <canonical docs URL>
+- **Local:** `<node_modules/<pkg>/index.d.ts>` or vendor equivalent
+
+## See also
+
+- [`evidence-discipline`](dist/agent-src/contexts/execution/evidence-discipline.md) — report format, provenance rules, honest enforcement reality
+- [`source-discovery`](dist/agent-src/skills/source-discovery/SKILL.md) — procedure for discovering each surface type

package/dist/agent-src/templates/contexts/lesson-card.md

@@ -0,0 +1,73 @@
+---
+class: C
+type: learned-lesson
+trust: low
+# Class-C learned lesson (Evidence v2). The LOWEST-trust context type: an
+# inference about why something went wrong. Evidence (symptom) is falsifiable
+# fact; diagnosis (hypothesis) is a decaying theory, NEVER a durable lesson
+# until repeatedly confirmed. Subject-based, project-local by default (never
+# person-based in a committed team repo). See project-intelligence.md § Class C.
+scope: "project-local"          # project-local | global (global only via the measure-then-decide gate)
+subject: "<the module / surface / integration — NOT a person>"
+symptom: "<real error text / failing test name / reverted commit SHA — falsifiable>"
+hypothesis: "<the causal theory — LOW TRUST, a decaying hypothesis>"
+confidence: 0.0
+observed_at: "YYYY-MM-DD"
+last_confirmed: "YYYY-MM-DD"
+decay:
+  no_confirmation_for_days: 90    # past this with no `confirmed` event → demote to hypothesis
+  counter_evidence_ratio_gt: 0.3  # ≥30% of events are counter_evidence → demote to hypothesis
+revalidate_if: "<condition that would invalidate — e.g. the endpoint gains a schema>"
+---
+
+<!--
+  Template shipped by event4u/agent-config (Evidence v2, Class C).
+  Copy to agents/memory/curated/lessons/<slug>.md ONLY via the human promotion
+  gate — a Class-C lesson is NEVER auto-committed and NEVER auto-trusted.
+  Frontmatter MUST stay at line 1. Delete this HTML comment after filling in.
+
+  RULE: the symptom is fact (cite it); the hypothesis is a theory (mark it).
+  The lesson is read for HEURISTICS ONLY and never bypasses a fresh structural
+  read (the v1↔v2 isolation contract). Delete this card / let it decay rather
+  than let a wrong cause-theory harden into superstition.
+-->
+
+# Learned lesson — <subject>
+
+## Symptom (fact — falsifiable, cite it)
+
+<!-- The real, observable failure. Error text / failing test / reverted commit.
+     Timestamped. This is the durable, falsifiable half. -->
+
+- **What went wrong:** `<verbatim error / test name / revert SHA>`
+- **Where:** `<file:line / surface / task>`
+- **Observed at:** YYYY-MM-DD
+
+## Hypothesis (theory — LOW TRUST, decaying)
+
+<!-- The agent's causal theory for WHY. Never treated as durable. Demoted by the
+     anti-calcification check on either decay trigger above. -->
+
+- **Diagnosis:** `<why it likely happened — a hypothesis, not a fact>`
+- **Confidence:** `<0.0-1.0>`
+
+## Test-tracking history (makes anti-calcification enforceable)
+
+<!-- Log an event ONLY when a situation the lesson claims to govern recurs.
+     `confirmed` = the claim held · `not_applicable` = situation changed, lesson
+     no longer governs · `counter_evidence` = the claim failed. Absence of
+     recurrence is NOT confirmation. -->
+
+| date | event | context |
+|---|---|---|
+| YYYY-MM-DD | confirmed \| not_applicable \| counter_evidence | `<task / where>` |
+
+## Pointers
+
+- **Evidence:** `<link to the failing test / error log / revert commit>`
+- **Revalidate if:** `<condition>`
+
+## See also
+
+- [`project-intelligence`](../contexts/execution/project-intelligence.md) — Class C safety spec, evidence/diagnosis split, decay rules, privacy floor.
+- [`evidence-discipline`](../contexts/execution/evidence-discipline.md) — v1 spine, trust tiers, the rollback target.

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

@@ -21,9 +21,10 @@ Templates for roadmap files stored in `agents/roadmaps/` or `{module_root}/{Modu
 10. **Keep docs up to date:** If changes affect documented behavior, update the relevant agent docs.
 11. **One task per file.** Don't combine unrelated work.
 12. **Lifecycle:** Every roadmap ends in exactly one folder:
-    - `agents/roadmaps/` — active (in progress or planned)
+    - `agents/roadmaps/` — active (in progress or planned **and workable now**)
     - `agents/roadmaps/archive/` — work happened (fully or partially); no further work planned
     - `agents/roadmaps/skipped/` — decision against pursuit; typically 0 items `[x]` (superseded, scope rejected)
+    - `agents/roadmaps/later/` — open work remains but is **blocked-for-later** (gated on an external trigger or a decision); **will resume**. Set `status: later` + a `Blocked until` / `Trigger` line. Roadmaps with open tasks deferred for later are **always** moved here, never left active. Excluded from the dashboard and `/roadmap:process-*`; enforced by `lint_roadmap_later_disposition`.
 
     See the `roadmap-management` skill for the exact trigger matrix and user-confirmation flow.
 13. **No tags, releases, or version numbers.** Roadmaps describe work, not shipping.
@@ -78,6 +79,26 @@ Templates for roadmap files stored in `agents/roadmaps/` or `{module_root}/{Modu
     dashboard surfaces roadmap, readers honor body convention.
     Authoring contract: [`roadmap-writing § 7`](../skills/roadmap-writing/SKILL.md);
     spawn procedure: [`roadmap-management § Spawn follow-up`](../skills/roadmap-management/SKILL.md).
+18. **Source-derived roadmaps carry a gap-table + provenance; internally
+    originated roadmaps carry neither.** Fires **only** when a roadmap
+    originates from an external input (suggestion, competitive/capability
+    harvest, external LLM ideation thread) or adopts external capabilities
+    into the suite. Does **not** fire for ordinary internally-originated
+    roadmaps — those add no Provenance block, no gap-table ritual. When it
+    fires:
+    - **(a) Gap-table before drafting.** Audit each proposed item against
+      the existing skill / command / rule surface; keep only verified gaps
+      — `KEEP` (genuine gap) / `FOLD` (into existing artefact) / `CUT`
+      (already covered). Plan integrates, doesn't dump.
+    - **(b) `## Provenance` block** — source by a **neutral descriptor**
+      (never the raw competitor / tool name, per
+      [`source-confidentiality`](../rules/source-confidentiality.md));
+      retain the real link as an `ENC1:` token via
+      `src/scripts/_lib/link_crypto.ts encrypt --value <url>`.
+    - **(c) Council convergence inlined** with date + members — never a
+      session filepath ([`no-roadmap-references`](../rules/no-roadmap-references.md)).
+    Authoring contract:
+    [`roadmap-writing § 8`](../skills/roadmap-writing/SKILL.md).
 
 ---
 
@@ -167,6 +188,13 @@ complexity: lightweight
 ## Notes
 
 {Optional: edge cases, decisions, links to related docs.}
+
+<!-- ## Provenance — INCLUDE ONLY for source-derived / harvest / capability-adoption
+     roadmaps (rule 18). OMIT entirely for internally-originated roadmaps —
+     do NOT ship an empty Provenance section.
+- Source: <neutral descriptor> (anonymized per source-confidentiality);
+  link via `src/scripts/_lib/link_crypto.ts decrypt`: ENC1:<token>
+- Council: <members>, <date>, <depth>; convergence inlined above. -->
 ```
 
 ---