@event4u/agent-config 6.0.0 → 7.0.0

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.

package/docs/decisions/ADR-102-ticket-handoff-paste-and-mcp.md

@@ -0,0 +1,72 @@
+---
+adr: 102
+status: accepted
+date: 2026-06-16
+decision: ticket-handoff-paste-and-mcp
+supersedes: —
+superseded_by: —
+phase: ticket-bundles (rework)
+type: structural
+---
+
+# ADR-102 — Ticket handoff is paste/MCP, not an API export
+
+## Status
+
+**Accepted** · 2026-06-16. Supersedes the **transport decision** of
+[ADR-101](ADR-101-ticket-bundle-emission.md) (its R2/R4 GraphQL-export +
+idempotency, and the `linear_state` part of R3). The rest of ADR-101 — the
+bundle format, the buildability gate, `model_tier` per ticket, the traceability
+spine, v1-immutable — stands unchanged.
+
+## Context
+
+ADR-101 specified that a roadmap-materialised ticket bundle projects into Linear
+via a GraphQL exporter (`build_ticket_export.py`) with query/map-first
+idempotency tracked in a manifest `linear_state` map (CSV as a bootstrap).
+
+The maintainer's actual requirement is simpler: **be able to copy/paste an MD
+ticket into a Linear (or Jira) issue.** An automatic API export is unwanted —
+"the agent can do that via MCP anyway; we don't need to wire it through an API."
+The GraphQL client, the idempotency map, the transport spike, and the drift
+check were solving a problem that does not exist.
+
+## Decision
+
+1. **No bundled API client, no automatic export.** Remove
+   `build_ticket_export.py` and the planned `tickets:export` CLI.
+   The package ships zero Linear/Jira API wiring.
+2. **The MD ticket is the handoff artifact.** Its frontmatter `title` is the
+   issue title; its Markdown body is the issue description (renders in
+   Linear/Jira). A human pastes it; the body is authored render-ready.
+3. **MCP is the programmatic surface.** To create issues without pasting, the
+   agent uses a tracker **MCP server** (Linear/Jira) with the ticket as input.
+   Integration lives at the MCP layer, not in this package.
+4. **No tracker state in the bundle.** Drop `linear_state` from the manifest +
+   its schema. A tracker issue is a one-way copy; nothing is read back. The
+   bundle is the source of truth (ADR-101 D7, unchanged).
+
+## Consequences
+
+- **Positive.** Far less machinery to maintain (no API client, no idempotency
+  map, no transport spike, no drift check). No token dependency — the whole
+  thing works offline. Matches how the maintainer actually moves tickets.
+- **Negative / cost.** No one-command bulk import; bulk creation is paste-by-paste
+  or an MCP loop. Acceptable — bundles are small and the agent can drive MCP.
+- **Neutral.** Re-creating an edited ticket in the tracker is a re-paste / MCP
+  update; there is no automatic reconciliation (there was none worth keeping).
+
+## Alternatives considered
+
+1. **Keep the GraphQL exporter (ADR-101 R2).** Rejected by the maintainer —
+   unwanted API surface; MCP already covers programmatic creation.
+2. **CSV bootstrap.** Rejected — same "automatic export" we are removing.
+3. **A thin "render paste-ready" helper.** Not needed — the ticket body is
+   already paste-ready Markdown; a helper would be ceremony.
+
+## References
+
+- [ADR-101](ADR-101-ticket-bundle-emission.md) — the bundle format (transport
+  decision superseded here).
+- [`ticket-bundle-format`](../contracts/ticket-bundle-format.md) §8 — the
+  paste/MCP handoff (rewritten).

package/docs/decisions/ADR-103-global-knowledge-default-off-until-measured.md

@@ -0,0 +1,92 @@
+---
+adr: 103
+status: accepted
+date: 2026-06-16
+decision: global-knowledge-default-off-until-measured
+supersedes: —
+superseded_by: —
+phase: evidence-v2
+type: structural
+---
+
+# ADR-103 — Global knowledge sharing defaults OFF until cross-project reuse is measured
+
+## Status
+
+Accepted (2026-06-16). Council-reviewed (claude-sonnet-4-5 + gpt-4o, design mode,
+2 rounds + peer-review) as part of Evidence v2 Phase 0. **Amends
+[ADR-100](ADR-100-global-knowledge-card-sharing.md) Decision-6/Consequences**
+(the `knowledge.global_sharing.enabled` default) only. The rest of ADR-100 — the
+file-first store, origin-tier scoping, redaction-on-write, hybrid promotion,
+kill-switch — stands unchanged.
+
+## Context
+
+[ADR-098](ADR-098-evidence-first-structure-discovery.md) Decision-10 killed the
+global/registry/promotion layer with an explicit gate: *measure cross-project
+reuse over the measurement window, then decide*. [ADR-100](ADR-100-global-knowledge-card-sharing.md)
+reversed that kill on the **same day** and shipped the layer **default-ON**,
+justified by "measured v1 reuse + the cross-project value case".
+
+An independent review of the shipped v1 (claude-sonnet-4-5 + gpt-4o) found that
+justification circular: v1 was ~1 day old, the measurement window was never
+waited out, so there is **no measured reuse** — "measured v1 reuse" is a
+rationale, not a data point. The global layer thus shipped having bypassed the
+very gate that was the point of the gating exercise. Default-ON cross-project
+data movement also sits poorly with the otherwise privacy-first posture of a tool
+**other people install**: the tier-classifier can misclassify, and redaction is
+regex-based (can miss novel formats) — both listed as accepted risks in ADR-100.
+
+## Decision
+
+1. **`knowledge.global_sharing.enabled` defaults to `false`.** The store is
+   opt-in, not opt-out, until cross-project reuse exists as a measured signal.
+   The kill-switch from ADR-100 is excellent; this ADR only inverts its default.
+
+2. **The measure-then-decide gate is restored, concretely.** The default flips
+   back to `true` only when reuse is instrumented across **≥ 2 real projects**
+   and shown positive — the `_lib/knowledge_global_promote.py record-seen`
+   sightings are the instrument that already exists. Until then, opt-in stands.
+
+3. **v1 is byte-for-byte unaffected.** Project-local discipline + cards do not
+   read or write the global store regardless of this default. Only the
+   cross-project layer is gated off.
+
+4. **No new mechanism.** Promotion stays suggest-then-confirm; tier scoping,
+   redaction-on-write, and the purge command are unchanged. This ADR changes one
+   default value and the obligation to measure before flipping it back.
+
+## Consequences
+
+- `knowledge.global_sharing.enabled` default flips `true → false` in
+  `src/config/agent-settings.template.yml`, `src/server/schemas/settings.ts`,
+  and the `src/agent-src/templates/agent-settings.md` settings table.
+- `evidence-discipline.md` § Global layer notes the default-off posture and the
+  reuse-gate condition for flipping it back on.
+- A consuming operator who wants cross-project sharing sets `enabled: true`
+  explicitly — a deliberate, informed opt-in.
+- The reuse measurement (Evidence v2 Phase 5 / global-promotion gate) is the
+  evidence that would justify flipping the default back; until that data exists,
+  the question is not re-litigated.
+
+## Alternatives
+
+- **Keep default-on (do nothing).** Rejected — restates the skipped-gate failure
+  the v1 review flagged; default cross-project data movement on an installed tool
+  is the wrong default before reuse is measured.
+- **`public`-only on, `vendor` off.** Considered; rejected as the default because
+  it still moves data cross-project by default. Off-until-measured is the cleaner
+  privacy-first default. An operator may set `allowed_tiers: [public]` after
+  opting in if they want the narrower surface.
+- **Delete the global layer.** Rejected — ADR-100's file-first design is sound;
+  the issue is the *default*, not the mechanism.
+
+## References
+
+- [ADR-100](ADR-100-global-knowledge-card-sharing.md) — the global layer; Decision-6
+  default amended here.
+- [ADR-098](ADR-098-evidence-first-structure-discovery.md) — the original
+  measure-then-decide gate this ADR restores.
+- `agents/roadmaps/archive/road-to-evidence-v2-project-intelligence.md` — Evidence v2
+  Phase 0 (council convergence inlined in its header; archived on completion).
+- `src/agent-src/contexts/execution/evidence-discipline.md` § Global layer.