@event4u/agent-config 6.1.0 → 7.0.1

package/docs/decisions/ADR-097-mission-recipe-privilege-boundary.md

@@ -0,0 +1,121 @@
+---
+adr: 097
+status: accepted
+date: 2026-06-15
+decision: mission-recipe-privilege-boundary
+supersedes: —
+superseded_by: —
+phase: road-to-mission-mode · Phase 0
+type: security
+---
+
+# ADR-097 — Mission recipes vs user recipes — privilege boundary
+
+## Status
+
+**Accepted** · 2026-06-15. Lands Phase 0 of `road-to-mission-mode`.
+Council-flagged risk: a user recipe smuggling a file-edit skill into a
+trusted mission's gated sequence.
+
+## Context
+
+Mission-Mode introduces two artifact classes that compose AC skills:
+
+1. **Mission recipes** — shipped in `src/missions/*`, version-controlled,
+   reviewed, and released as part of the AC package.
+2. **User / cookbook recipes** — authored by consumers in their own
+   `agents/missions/` or via the cookbook pattern; not package-controlled.
+
+Both can invoke `/work` directives and, in principle, reference AC skills
+by name. Without a privilege boundary, a user recipe could inject an
+arbitrary skill (e.g. a file-write or secrets skill) between the gated
+steps of a trusted mission, bypassing the human-gate sequence the mission
+was designed around. This is a privilege-escalation vector analogous to
+a confused-deputy attack.
+
+The `lethal-trifecta-guard` rule (private-data + untrusted-content +
+external-comms) identifies this shape as the canonical high-risk agent
+pattern. A user recipe that can call any skill is a potential trifecta
+assembler.
+
+## Decision
+
+### Trusted missions (`src/missions/*`) — TRUSTED tier
+
+- May invoke any AC skill directly by name in their phase sequence.
+- May read `inputs`, `catalog`, and `verification` fields from their manifest.
+- Shipped, reviewed, and signed off as part of AC's release process.
+- The manifest schema (`src/scripts/schemas/mission.schema.json`) governs
+  their structure; the linter enforces it.
+
+### User / cookbook recipes — SANDBOXED tier
+
+- **May** invoke trusted missions by name (e.g. `/mission:upgrade`).
+- **May** invoke other user recipes.
+- **May NOT** inject arbitrary AC skills between a trusted mission's steps.
+- **May NOT** reference a skill unless that skill's frontmatter declares
+  `user_invokable: true`.
+- The `user_invokable` frontmatter key does not exist yet; it is reserved
+  for the Phase 2 skill-annotation pass. Until Phase 2 ships, user recipes
+  may invoke missions only — no direct skill invocation at all.
+
+### Enforcement surface
+
+| Layer | Mechanism |
+|---|---|
+| **Linter** | `scripts/lint_mission_recipes.py` (Phase 2) checks that recipe files under `agents/missions/` do not reference skills lacking `user_invokable: true` |
+| **Schema** | `mission.schema.json` covers trusted missions; a separate `recipe.schema.json` (Phase 2) will cover user recipes |
+| **Rule** | `lethal-trifecta-guard` remains the runtime defense; the privilege boundary is a pre-execution authoring gate |
+| **Code review** | PRs adding `user_invokable: true` to any skill require the security-sensitive-stop review flow |
+
+## Rationale
+
+A user recipe that can call arbitrary skills can assemble the lethal
+trifecta (read secrets → pass through untrusted web content → write to
+filesystem) without the human-gate sequence a trusted mission provides.
+Sandboxing user recipes to missions-only until `user_invokable` is
+annotated keeps the threat surface minimal during Phase 0 and Phase 1,
+when the execution model is still a validation PoC.
+
+The `user_invokable` annotation approach (rather than a blanket allow/deny
+at the recipe layer) lets the suite grow the safe surface incrementally as
+each skill is audited — consistent with how `allowed_tools` works in skill
+execution blocks.
+
+## Consequences
+
+### Accepted
+
+- User recipes in Phase 0 and Phase 1 are limited to mission invocation
+  only. This is intentional — Phase 1 is a PoC, not a product.
+- Skill authors who want their skill callable from user recipes must
+  explicitly opt in via `user_invokable: true` after security review.
+- The linter gate ships in Phase 2, not Phase 0. Phase 0 is authoring-only;
+  no executable recipes exist yet.
+
+### Trade-offs
+
+- More friction for power users who want to compose skills in recipes.
+  Mitigation: the `user_invokable` path provides an explicit, auditable
+  escape hatch rather than a blanket block.
+- `user_invokable` key adds one more frontmatter field to the skill schema.
+  Cost is low (one boolean); benefit is a machine-checkable privilege
+  boundary.
+
+## Alternatives considered
+
+- **Allow user recipes to invoke any skill.** Rejected — directly creates
+  the privilege-escalation vector this ADR is designed to prevent.
+- **Block user recipes entirely.** Rejected — removes a legitimate power-user
+  use case and makes the sandbox permanent rather than an interim gate.
+- **Runtime enforcement only (lethal-trifecta-guard).** Rejected as
+  insufficient — runtime detection is a safety net, not a substitute for
+  authoring-time prevention, which is AC's stated differentiator.
+
+## References
+
+- `docs/contracts/no-runtime-boundary.md` — the boundary contract missions operate within
+- `src/scripts/schemas/mission.schema.json` — trusted mission manifest schema
+- `.agent-src.uncondensed/rules/lethal-trifecta-guard.md` — runtime defense layer
+- `.agent-src.uncondensed/rules/security-sensitive-stop.md` — review gate for `user_invokable` additions
+- `agents/roadmaps/archive/road-to-mission-mode.md` § Phase 0 — authoring context

package/docs/decisions/ADR-098-evidence-first-structure-discovery.md

@@ -0,0 +1,154 @@
+---
+adr: 098
+status: accepted
+date: 2026-06-15
+decision: evidence-first-structure-discovery
+supersedes: —
+superseded_by: ADR-100 (Decision-10 only)
+phase: structure-grounding
+type: structural
+---
+
+# ADR-098 — Evidence-first structure discovery
+
+## Status
+
+Accepted (2026-06-15). Council-gated, four rounds (claude-sonnet-4-5 + gpt-4o,
+design mode). Implements `agents/roadmaps/archive/road-to-structure-grounding.md` v1.
+
+## Context
+
+Agents hallucinate structure — they invent fields, endpoints, columns, and enum
+values and then plan or code against them, running in the wrong direction. The
+ask was for a discipline that makes the agent inspect the **real** structures it
+is about to work with (DB schema, API/GraphQL shape, DTO/Model/Entity, vendor
+package docs) **before** planning, plus a maintained lean knowledge layer kept
+both globally (per-user) and in the consumer repo with a usage registry and
+auto-promotion ("used in 2+ projects → global").
+
+The global/registry/auto-promotion layer is **runtime-shaped** and re-opens the
+2026-06-14 Layer-2 sunset (no daemon, no vector DB, no writable per-user store).
+The durable, defensible core is the **evidence discipline** itself, not a
+knowledge database.
+
+A measured smoke eval confirmed the premise is not a null signal: on a DB fixture
+whose task wording tempted three wrong names, discovery-off invented 3/3
+structural names; discovery-on invented 0. The full per-surface eval (DB / API /
+vendor) reproduced this — discovery-off averaged 1.67–2.33 invented names per
+run; discovery-on drove it to 0 on every surface.
+
+## Decision
+
+1. **The evidence-first invariant.** No structural claim without evidence from a
+   real source — every field/endpoint/column/value traces to `file:line` · SDL ·
+   migration · probe. Local before remote, real source before guessing.
+
+2. **The Evidence Report** (gitignored session scratchpad, soft-capped ~10–20
+   decision-relevant facts) in three buckets — **Verified** (confirmed this
+   session, or durable card negative-facts/pointers), **Assumed (from card)**,
+   **Gaps** — produced before the plan. A committed card's **positive structure
+   is filed under "Assumed (from card)", never "Verified"**, even with a green
+   pointer (R4 P1), and is re-confirmed against the live source before use.
+
+3. **Card trust-tiering.** A knowledge card is an *optional cache of expensive
+   (remote) evidence* — never a source of truth, never a build input. Its
+   `trust: durable` core is **negative facts + pointers**; positive structure is
+   a per-line, last-verified **hypothesis** carrying `observed_at`/`source_version`.
+
+4. **Cards are remote-only; local is always fresh; no persistent index.**
+   In-codebase structure is resolved **fresh** (`rg`/glob) and read fresh each
+   task — no persistent resolution index (deferred until a measured `rg`-latency
+   problem appears). Session reads invalidate on `HEAD` change and **fail-fast**
+   mid git-op (rebase/merge/cherry-pick).
+
+5. **The DB-not-in-codebase boundary.** A schema defined by repo migrations /
+   models / ORM / app code — **including** schemaless stores the app controls
+   (Mongoose / Prisma / Firestore rules) — is in-codebase → local, read fresh,
+   no card. Only a DB whose schema is not in the repo **and** not app-controlled
+   (vendor SaaS / partner / legacy) is card-worthy.
+
+6. **Honest enforcement reality.** The Evidence Report / `card_claims` self-log
+   is **instrumentation, not enforcement** — a model that invents a field can
+   write a false "verified". The teeth are **pointer-CI** (`check_knowledge_cards.py`:
+   size ≤ 150, mandatory authoritative pointer, trust tagging, multi-evidence
+   git-ancestry consistency, `--strict` content-compare) + the **per-surface
+   anti-hallucination eval** with a variance baseline.
+
+7. **`anti-hallucination` kept over `invariant`** as the card frontmatter `type`
+   (R3 F-2) — a card is a current-state observation, not an inviolable law.
+
+8. **A negative fact is a current-state fact**, not a card-worthiness decision —
+   written only after an *exhausted* search logging `searched`/`not_searched`,
+   with a `revalidate_if` trigger (R4 P4).
+
+9. **Ships as a core extension, not a pack.** The discipline extends existing
+   primitives — `think-before-action` (one-line pointer), `context-document`
+   (the card is a specialized context type), `agents/settings/contexts/`,
+   `size-enforcement` — rather than forking a parallel system. The
+   `think-before-action` edit is to a tier-2b `auto` rule (not a kernel
+   `type: always` rule), so the kernel slow-rollout guarantee does not apply;
+   the edit is a minimal additive pointer.
+
+10. **The global/registry layer is gated v2.** Phase 4 only **instruments**
+    (a v1-safe usage counter keyed by card + repo-slug, never paths/contents) and
+    **measures** cross-project reuse over weeks, then **decides** against
+    kill-criteria: near-zero reuse → kill global + registry + promotion (the
+    discipline + project cards stood on their own); real reuse → a gated
+    follow-up roadmap (pointer-CI green incl. strict-mode, global cards
+    leads/negative-facts only, **manual** promotion — no auto "≥2", a
+    `forget`/inspect command, store under the install `global` scope). Killing
+    the global layer never kills the cards.
+
+    **RESOLVED 2026-06-15 — v2 KILLED.** The operator exercised the kill option
+    directly rather than wait out the measurement window: the global / registry
+    / promotion layer will **not** be built, and the v1-safe usage counter
+    (`knowledge_card_usage.py`) is **retired/removed** (its only purpose was to
+    feed the now-abandoned promotion gate). No follow-up roadmap is spawned. The
+    durable value stood in the v1 discipline + committed project cards, exactly
+    as the kill path anticipated. The roadmap is closed/archived.
+
+    **REVERSED 2026-06-15 → see [ADR-100](ADR-100-global-knowledge-card-sharing.md).**
+    The operator reversed this kill the same day: the global cross-project layer
+    **is** built — but **file-first** (lazy-read plain files, no daemon / DB /
+    vector / decay), which preserves the Layer-2 sunset's *core* (no runtime)
+    rather than re-opening it. Promotion stays **hybrid** (suggest ≥2 + manual
+    confirm, never silent), global cards are **leads / negative-facts only**, and
+    **origin-tier scoping** keeps proprietary structure manual-only. **This
+    Decision-10 is superseded by ADR-100; the rest of ADR-098 stands.**
+
+## Consequences
+
+- A new tier-2b `auto` rule (`source-discovery-gate`) + skill (`source-discovery`)
+  fire before coding/DB/API/vendor work, with a gate-skip for trivial work.
+- A new committed-card home (`agents/knowledge/`) + gitignored session cache
+  (`agents/memory/knowledge/session/`); a `knowledge-card` template; two new
+  scripts (`evidence_report.py`, `check_knowledge_cards.py`). A third v1-safe
+  usage counter shipped initially but was **retired with the 2026-06-15 v2 kill**.
+- A new CI gate (`check-knowledge-cards`) enforces card referential integrity.
+- v1 is complete; the gated v2 (global layer / registry / promotion) was
+  **killed 2026-06-15** (Decision 10) and the roadmap archived.
+
+## Alternatives
+
+- **Build the global layer + registry + auto-promotion now** — rejected as
+  runtime-shaped (re-opens the Layer-2 sunset); gated behind measured reuse.
+- **A persistent local resolution index** — rejected for v1 (resolve fresh);
+  deferred until `rg`-latency is measured to hurt on large monorepos.
+- **Treat the self-log as hard enforcement** — rejected; honest framing only,
+  with deterministic teeth in pointer-CI + the eval.
+- **`type: invariant` cards** — rejected for `anti-hallucination` (current-state,
+  not law).
+- **A standalone knowledge-database pack** — rejected for a core extension of
+  existing primitives.
+
+## References
+
+- `agents/roadmaps/archive/road-to-structure-grounding.md` — the roadmap (R1–R4 council
+  convergence inlined in its header).
+- `src/rules/source-discovery-gate.md`, `src/skills/source-discovery/SKILL.md`,
+  `src/agent-src/contexts/execution/evidence-discipline.md`.
+- `src/scripts/check_knowledge_cards.py`, `evidence_report.py` (the v2 usage
+  counter was retired with the 2026-06-15 kill).
+- `internal/evals/structure-grounding/` — smoke + per-surface eval fixtures and
+  results.
+- ADR-035 (model-tier ≠ host band), the 2026-06-14 Layer-2 sunset decision.

package/docs/decisions/ADR-099-file-first-pattern-library.md

@@ -0,0 +1,87 @@
+---
+adr: 099
+status: accepted
+date: 2026-06-15
+decision: file-first-pattern-library
+supersedes: —
+superseded_by: —
+phase: harvest-small-enhancements
+type: structural
+---
+
+# ADR-099 — File-first pattern library (`src/patterns/`)
+
+## Status
+
+Accepted (2026-06-15). Implements `road-to-harvest-small-enhancements` Phase 1.
+The pattern library was an earlier competitive-harvest **REJECT that the council
+reversed** (two-member, deep + peer-review, 2026-06-15): a static `patterns/`
+dir is materially different from the sunset runtime memory store and is not
+persona proliferation.
+
+## Context
+
+A competitive-harvest pass surfaced a recurring need: reusable **refactor/fix
+recipes** (e.g. "N+1 → eager load", "enum switch → Strategy") that an agent
+should be reminded of when the matching problem appears. The first instinct —
+fold this into a runtime "continuous-learning" store — was rejected with the
+pgvector/MCP memory layer ([`ADR-094`](ADR-094-agent-memory-layer-removal.md),
+[[council-agent-memory-sunset]]): no daemon, no writable per-user store, no decay.
+
+The council reversed the blanket REJECT for the **file-first** shape: a
+`patterns/` directory of markdown + frontmatter — read at authoring time, like
+`rules/` — enables cross-project recipe reuse **without** any runtime, and is not
+persona-proliferation (so `persona-governance`'s ≤2-per-domain cap does not apply).
+
+## Decision
+
+Add `src/patterns/` as a **file-first reference library**:
+
+- Each `src/patterns/<slug>.md` is a recipe (Problem / Before / After /
+  **Verification** / Gotchas) with frontmatter `applies_to`, `reliability`,
+  `last_verified`. Contract: [`src/patterns/README.md`](../../src/patterns/README.md).
+- **Not a registered condensation source root.** Patterns are reference material
+  (read on demand, like `docs/guidelines/`), **not** projected into per-tool
+  context. This is the deliberate boundary that keeps them file-first and
+  out of the always-loaded budget.
+- **Surfaced, never forced.** [`learning-to-rule-or-skill`](../../src/skills/learning-to-rule-or-skill/SKILL.md)
+  adds `patterns/` to its overlap-search surfaces and routes recurring fix-recipes
+  here; the human decides whether to apply a surfaced pattern.
+- **Cross-project sharing is manual + redacted.** `src/scripts/pattern_share.py`
+  (a maintainer dev script, not a user command) exports/imports patterns through
+  the same redactor as [`low-impact-corpus-privacy-floor`](../../src/rules/low-impact-corpus-privacy-floor.md);
+  it overlaps [[council-team-shared-memory]] only in governance (redaction), not
+  storage (patterns are recipes, not memory entries).
+
+## Consequences
+
+- **Positive:** recurring fixes become a discoverable, reliability-tagged library;
+  cross-project learning without a runtime; clear boundary vs `rules/`
+  (always-on), `guidelines/` (prose conventions), `skills/` (workflows).
+- **Cost:** a fifth knowledge surface to keep honest. Mitigated by `last_verified`
+  + the surfaced-not-forced rule.
+- **Rollback / sunset (council Phase-1 caution):** patterns must earn their keep.
+  If a pattern (or the whole surface) sees no surfacing hit and no edit across two
+  review cycles, it is a removal candidate — `git rm` the file, no migration
+  needed (nothing is projected). The surface adds no CI gate and no runtime, so
+  removal is a clean revert.
+
+## Alternatives
+
+- **Fold into a runtime continuous-learning store** — rejected (re-opens the
+  Layer-2 sunset; daemon/decay/auto-write all out of scope).
+- **Put recipes in `docs/guidelines/`** — rejected: guidelines are prose
+  conventions read for style; patterns are keyed, reliability-tagged recipes with
+  a verification step, surfaced by problem-detection. Different read trigger.
+- **A new user-facing command** — rejected: surfacing belongs inside the existing
+  authoring-time `learning-to-rule-or-skill` flow; export/import is a maintainer
+  dev script, not a user command.
+
+## References
+
+- `road-to-harvest-small-enhancements.md` Phase 1 (council-reversed ADOPT).
+- [`ADR-094`](ADR-094-agent-memory-layer-removal.md) — the runtime memory sunset
+  this surface deliberately stays clear of.
+- [`src/patterns/README.md`](../../src/patterns/README.md) — the surface contract.
+- Council: live two-member run (claude-sonnet-4-5 + gpt-4o, deep, peer-review,
+  2026-06-15).

package/docs/decisions/ADR-100-global-knowledge-card-sharing.md

@@ -0,0 +1,133 @@
+---
+adr: 100
+status: accepted
+date: 2026-06-15
+decision: global-knowledge-card-sharing
+supersedes: ADR-098
+superseded_by: —
+phase: structure-grounding-v2
+type: structural
+---
+
+# ADR-100 — Global cross-project knowledge-card sharing
+
+## Status
+
+Accepted (2026-06-15). Council-designed (claude-sonnet-4-5 + gpt-4o, design
+mode — both members converged independently). Implements
+`agents/roadmaps/archive/road-to-structure-grounding-v2.md`. **Partially supersedes
+[ADR-098](ADR-098-evidence-first-structure-discovery.md) Decision-10 only** —
+the rest of ADR-098 (the evidence-first invariant, the Evidence Report,
+card trust-tiering, the project-local layer) stands unchanged.
+
+## Context
+
+ADR-098 shipped the v1 evidence discipline + project-local knowledge cards and
+**killed** the global/registry/promotion layer (Decision-10, "v2 KILLED"): the
+operator exercised the kill option directly rather than wait out the measurement
+window, because the layer looked **runtime-shaped** and re-opened the 2026-06-14
+Layer-2 sunset (no daemon, no vector DB, no writable per-user store).
+
+The operator **reversed that kill on 2026-06-15**: build the global
+cross-project sharing layer now, gated by a user-global setting, **default ON**,
+off-able later. The council was asked whether this can be done without
+re-opening the Layer-2 sunset.
+
+## Decision
+
+1. **File-first is not a runtime — the sunset's core is preserved.** Global
+   cards are plain files under `~/.event4u/agent-config/knowledge/`, lazy-read,
+   with **no daemon, no DB, no vector index, no background decay**. This is the
+   reconciliation: the 2026-06-14 sunset killed *runtime* (a writable per-user
+   service), not *storage*. A lazy-read file store is storage.
+
+2. **The global store is storage, not governed.** It is **unversioned** (not in
+   git), so unlike a committed project-local card it carries no git provenance.
+   It is a **cache, never a source of truth, never a build input**. The per-card
+   **provenance footer** (`first_seen` · `promoted_at` · `last_verified` ·
+   `tier` · `seen_in`) is its audit trail — the deliberate substitute for git
+   history (accepted risk).
+
+3. **Leads only.** A global card's `trust: durable` core (negative facts +
+   pointers) is usable as a lead. Its **positive structure loads as "Assumed
+   (from card · GLOBAL, unverified)"** and must be re-confirmed against the live
+   source *this session* before use — never "Verified" on the global card alone
+   (version skew / schema drift across projects).
+
+4. **Origin-tier scoping is the privacy floor that makes default-on defensible.**
+   `public` (registry / GitHub / docs) auto-shareable; `vendor` (Stripe / AWS /
+   …) shareable **post-redaction**; `proprietary` (in-house DB / private API /
+   client schemas) **manual-only, default-off regardless of `enabled`** — so no
+   client-A schema leaks into client-B's session. Unknown / hostless sources
+   classify conservatively as `proprietary`.
+
+5. **Redaction on write, halt-on-trigger.** Promotion runs the
+   `low-impact-corpus-privacy-floor` + `source-confidentiality` pattern set and
+   **halts** on any hit — never silent-shares, never auto-rewrites. The manual
+   proprietary override does **not** bypass redaction.
+
+6. **Promotion is hybrid, never silent.** A `public`/`vendor` card seen in
+   ≥ `auto_promote_threshold` (default 2) distinct repos triggers a one-tap
+   **suggestion**; the write happens only on confirm. Default-on turns *sharing*
+   on, not *promotion* automatic — preserving the v1 manual prereq.
+
+7. **Full kill-switch.** `knowledge.global_sharing.enabled: false` no-ops the
+   layer: the store is never read or written, no promotion is suggested, Evidence
+   Reports revert to project-local, existing global cards go inert. v1 is
+   byte-for-byte unaffected. `knowledge global purge --confirm` removes the store
+   and strips provenance from project cards.
+
+## Accepted risks
+
+- **Unversioned cache.** No git history on the global store; the provenance
+  footer is the only audit trail (Decision 2).
+- **Last-write-wins.** Concurrent promotions of the same card-id race on the
+  file; no locking (file-first, no runtime). The footer records the last write.
+- **Lazy freshness.** No background decay — staleness is surfaced at read/validate
+  time (≥90d → hypothesis, ≥180d → stale), never auto-pruned.
+- **Residual manual-promotion leak.** A determined operator can `--manual`-promote
+  a proprietary card; redaction still halts on confidential patterns, but tier
+  misclassification of a *novel* host defaults conservative (proprietary), not
+  permissive.
+
+## Consequences
+
+- New user-global setting `knowledge.global_sharing` (whitelisted in
+  `MERGEABLE_KEYS`), default on for `public`/`vendor`.
+- New `_lib` modules: `knowledge_global` (store path / config / tier detection /
+  provenance footer), `knowledge_global_redaction` (gate + redaction scan),
+  `knowledge_global_promote` (file-first usage signal + suggestion).
+- New command surface `src/scripts/knowledge_global_cli.py`
+  (`list|show|trace|forget|promote|validate|lead-check|purge`) + `task
+  knowledge-global[-validate]`. Deliberately **not** a `/knowledge` slash
+  sub-command — that cluster is unrelated local-file ingestion; the
+  structure-grounding global store is a separate concern.
+- `check_knowledge_cards.py --global` adds G1 (tier) / G2 (provenance footer) /
+  G3 (redaction-clean) checks; `evidence_report.py add --origin global` tags
+  GLOBAL leads; the `source-discovery` skill + `evidence-discipline` context
+  document the leads-only consumption.
+- ADR-098 Decision-10 is marked `superseded_by: ADR-100`.
+
+## Alternatives
+
+- **Keep the kill (do nothing).** Rejected — the operator reversed it; measured
+  v1 reuse + the cross-project value case justified building it.
+- **A writable per-user service / DB / vector index.** Rejected — that *is* the
+  Layer-2 runtime the sunset killed. File-first preserves the sunset's core.
+- **Auto-promote on ≥2 without confirm.** Rejected — silent cross-project writes
+  break the v1 manual prereq and the privacy posture.
+- **A `/knowledge global` slash sub-command.** Rejected — collides semantically
+  with the existing local-file-ingestion `/knowledge` cluster (whose `forget`
+  means something else). A standalone CLI is v1-consistent
+  (`check_knowledge_cards.py` / `evidence_report.py`) and collision-free.
+
+## References
+
+- `agents/roadmaps/archive/road-to-structure-grounding-v2.md` — the roadmap (council
+  convergence inlined in its header).
+- [ADR-098](ADR-098-evidence-first-structure-discovery.md) — v1; Decision-10
+  partially superseded here.
+- The 2026-06-14 Layer-2 sunset decision (no runtime) — reconciled, not reversed.
+- `src/scripts/_lib/knowledge_global*.py`, `src/scripts/knowledge_global_cli.py`,
+  `src/scripts/check_knowledge_cards.py` (`--global`),
+  `src/agent-src/contexts/execution/evidence-discipline.md` § Global layer.

package/docs/decisions/ADR-101-ticket-bundle-emission.md

@@ -0,0 +1,109 @@
+---
+adr: 101
+status: proposed
+date: 2026-06-15
+decision: ticket-bundle-emission
+supersedes: —
+superseded_by: —
+phase: ticket-bundles (road-to-ticket-bundles, Phase 0)
+type: structural
+---
+
+# ADR-101 — Roadmaps emit durable, self-contained ticket bundles; tracker import is a projection
+
+## Status
+
+**Proposed** · 2026-06-15. Promote to `accepted` after the Phase-1 probes
+(build pilot + transport spike) confirm the format holds.
+
+## Context
+
+The package separates planning concerns cleanly: roadmaps own the *what/when*
+(`roadmap-writing`, `agents/roadmaps/`), ADRs own the *why* (`adr-create`,
+`docs/decisions/`), and the `work_engine` (`/implement-ticket`) owns execution.
+[ADR-035](ADR-035-model-capability-tiers.md) expresses the capability split
+(`high→opus, medium→sonnet, lite→haiku`).
+
+Missing is the artifact that lets an **expensive planning agent** hand a **cheap
+building agent** a closed unit of work. A roadmap step is a one-line checkbox;
+the full spec is spread across the roadmap, ADRs, and the code. A `high`-tier
+agent holds that together; a `lite`-tier agent re-derives, drifts, or asks. The
+ticket-side skills (`refine-ticket`, `estimate-ticket`, `implement-ticket`) all
+operate on a ticket that already exists in a tracker; none *materialise* one.
+The only Linear surface is `build_linear_digest.py` (coding *rules*, not
+tickets). Assets are transient (`agents/roadmap-assets/`).
+
+Goal: *one expensive agent plans, a cheap agent or subagent builds it* — which
+requires a planning output that is a complete, portable, verifiable build spec.
+
+## Decision
+
+A roadmap may be **materialised** into a durable ticket bundle under
+`agents/tickets/{slug}/` (Markdown tickets + durable assets + a `manifest.yml`).
+Markdown is the source of truth; the tracker (Linear) is a generated projection.
+Full schema + mapping: [`ticket-bundle-format`](../contracts/ticket-bundle-format.md).
+
+The design converged across **two AI-council rounds** (2026-06-15, deep, members
+`anthropic/claude-sonnet-4-5` + `openai/gpt-4o`) plus an external review pass,
+reasoning from established empirical facts (Linear CSV import is create-only;
+Linear GraphQL auto-uploads markdown image URLs into auth-gated storage; the
+industry spec-driven-development pattern of spec→plan→isolation-testable-tasks).
+
+- **R1 — Layout = separate `agents/tickets/{slug}/`** (not co-located). The
+  flat-file dashboard/archival machinery is concrete; co-location's traceability
+  gain is speculative. Discovery via a machine-generated
+  `agents/tickets/_registry.yml` (no recursive glob, no roadmap↔manifest cycle).
+- **R2 — Transport = GraphQL API canonical**; CSV is create-only (non-idempotent)
+  → demoted to an optional one-shot bootstrap. Idempotency is **query/map-first**
+  via `linear_state.linear_id` (Linear has no documented external-key upsert).
+  GraphQL batch partial-failure must be resumable.
+- **R3 — Explicit `manifest.yml`** carrying the acyclic `dependency_graph` and
+  the `linear_state` idempotency map (without it, "idempotent re-export" is
+  vaporware).
+- **R4 — Risk-ordering:** two independent Phase-1 probes — 1a build-pilot (the
+  premise; the gate) and 1b transport-spike. The build pilot needs no export.
+- **R5 — `model_tier` per ticket**, enforced by a buildability lint
+  (`lint_ticket_buildable.py`): a `lite` ticket must carry runnable,
+  isolation-testable acceptance, exact paths, enforceable `boundaries`, and
+  resolvable assets — else rejected or escalated to `medium`. This is the
+  load-bearing guard of the expensive→cheap handoff.
+- **R6 — v1 tickets are immutable** (a source change spawns a NEW bundle, no
+  in-place issue update); a `linear_id` map still makes create idempotent.
+  Mutable mode (+`last_synced_sha` sync) is deferred until issue bloat is proven.
+- **Staleness split severity:** `adr_refs` SHA drift HARD-blocks (semantic,
+  rare); `source_refs` SHA drift only WARNS (source churns constantly).
+- **Boundaries enforceable:** `must_touch/may_touch/must_not_touch`, validated by
+  the work_engine boundary guard before commit — prose "do not touch" does not
+  bind a cheap agent.
+- **Build gate is qualitative, not a hard percentage on small n.**
+
+## Consequences
+
+- **Positive.** A roadmap is decomposed into closed build units by one expensive
+  pass; cheap agents execute them. Linear import is a one-command idempotent
+  projection. Design context (screenshots, wireframes) stops being lost. The
+  `model_tier` band gains operational teeth.
+- **Negative / cost.** A new artifact axis (`agents/tickets/`), a contract, a
+  template, a generator, two linters, and a skill to maintain. The dashboard
+  scanner must learn the registry. Live Linear export needs a token.
+- **Neutral.** Roadmaps remain the planning surface; tickets are an optional
+  downstream materialisation. Small roadmaps need not emit tickets.
+
+## Alternatives considered
+
+1. **Co-located bundle under the roadmap.** Rejected (R1) — forces a migration
+   of the flat-file dashboard/archival machinery for a speculative gain.
+2. **CSV-first transport.** Rejected (R2) — the native Linear importer is
+   create-only; re-import duplicates, making "MD is truth" a lie.
+3. **Derived `_index.md` instead of `manifest.yml`.** Rejected (R3) — the
+   idempotency map + dependency graph must be a persisted, validatable lock-file.
+4. **Single-file tickets (no folder).** Rejected — cannot carry binary assets
+   next to the spec, which the maintainer requires.
+5. **Mutable tickets in v1.** Deferred (R6) — the diff/sync logic is complexity
+   v1 does not need until issue bloat is observed.
+
+## References
+
+- [`ticket-bundle-format`](../contracts/ticket-bundle-format.md) — the full contract.
+- [ADR-035](ADR-035-model-capability-tiers.md) — model_tier bands.
+- `agents/roadmaps/archive/road-to-ticket-bundles.md` — the roadmap that implements this ADR.