@event4u/agent-config 6.1.0 → 7.0.0

package/docs/contracts/no-runtime-boundary.md

@@ -0,0 +1,56 @@
+# No-Runtime Boundary Contract
+
+> **Audience:** Every Mission-Mode decision, skill author, and recipe reviewer.
+> Read this before asking "is X allowed in a mission step?"
+
+AC is a **file-first, no-runtime suite** — skills and missions emit text and
+files; they do not spawn processes, own state stores, or poll the environment.
+This contract makes that boundary explicit for the Mission-Mode layer.
+
+See also: `lethal-trifecta-guard` (no private-data + untrusted-content +
+external-comms in one autonomous path), and the internal agent-memory sunset
+decision (cross-session persistent stores rejected as architecturally unsound
+and violating the no-runtime principle).
+
+---
+
+## Allowed
+
+| Category | Examples | Notes |
+|---|---|---|
+| **Codegen / file emit** | Write a migration file, emit a `UPGRADE.md` plan, produce a diff patch | The canonical mission output |
+| **File I/O** | Read `composer.json`, write `.work-state.json`, append to a report | Single-invocation scope only |
+| **Multi-turn prompting** | Agent asks user to run `php artisan migrate`, user pastes result back | Human stays in the loop; agent interprets the pasted output |
+| **git-as-state** | `git commit -m "mission:upgrade step=11 status=ok"`, `git revert HEAD`, `git reset --soft HEAD~1` | AC shells out to git constantly — structured commit messages are logging, not a daemon; rollback is `git revert` / branch reset on a provisional `mission/…` branch |
+| **Shell invocation (single-shot)** | `composer install`, `php artisan test --filter=…` run once per step and their output piped back | One-shot, result returned immediately; never a background job |
+| **Report / plan files** | Write `agents/evidence/mission-upgrade-decision.md`, emit a breaking-change checklist | Authoring-time output, not a runtime artifact |
+
+---
+
+## Prohibited
+
+| Category | Why |
+|---|---|
+| **Background processes / daemons** | No spawned subprocesses that outlive the current agent turn |
+| **Cross-session persistent state stores** | No SQLite, pgvector, MCP memory servers, Redis, or any store that persists beyond the git working tree — agent-memory layer sunset applies here |
+| **Event loops / polling** | No `while true; do …; done`, no `inotifywait`, no cron-inside-mission |
+| **Auto-PR / auto-push** | Hard-Floor (`non-destructive-by-default`): missions never push to remote or open PRs autonomously; those gates require explicit user confirmation every turn |
+| **Network egress from mission scripts** | Mission scripts may not initiate outbound HTTP calls; skills that need network access declare `allowed_tools` explicitly and go through the normal lethal-trifecta gate |
+
+---
+
+## Gray — requires council review before adopting
+
+| Pattern | Risk | Gate |
+|---|---|---|
+| **Conditional branching on prior step outputs** | Missions could become implicit state machines, defeating the no-runtime constraint | Must be expressed as a skill decision tree with explicit LLM judgment — not a script `if`/`else`; council sign-off required per mission |
+| **File-based state within a single invocation** | `.work-state.json` already exists and may gain a `mission_history` key — that is allowed; adding new control-flow primitives (loops, conditional keys that drive execution) is **not** | Extension of `.work-state.json` for logging is OK; adding execution-control semantics requires a new ADR |
+| **Nested sub-missions** | Could create unbounded depth; Phase 1 PoC must first prove a flat sequence is sufficient | Defer until Phase 1 evidence shows a real need |
+
+---
+
+## Decision authority
+
+A mission step that is unclear against this contract goes to the AI Council
+(`python3 src/scripts/council_cli.py`) before any build work starts.
+The council verdict becomes an ADR if it changes this table.

package/docs/contracts/package-self-orientation.md

@@ -22,6 +22,30 @@ as `event4u/agent-config` / `@event4u/agent-config`. No application
 runtime. Installed via `scripts/install.sh` (Bash) and
 `scripts/install.py` (Python bridge).
 
+## Authoring-time vs. runtime — the scope line
+
+The package is an **authoring-time orchestration toolkit, not an agent
+runtime.** This single distinction decides what belongs in the package
+and what is out of charter — cite it instead of re-deriving the boundary
+per proposal.
+
+- **Authoring-time (in scope).** Code that runs during prompt
+  construction or in response to an explicit user command, assembling
+  context / skills for the agent to *review* — e.g. `compile_router.py`
+  (deploy-time routing table) and `work_engine` (assembles directives
+  when the user types `/work`; the **agent**, not the engine, decides
+  whether to execute the next step — there is no `while not
+  task_complete:` LLM loop in `dispatcher.py`).
+- **Runtime (out of scope).** Code that executes autonomously *during
+  agent operation*, making decisions or LLM calls without per-step human
+  approval — auto-retry loops, autonomous tool-calling, self-modifying
+  skill selection.
+
+When a proposal (a competitor surface, an external-LLM suggestion, a new
+skill idea) would require the package to *run* an agent loop, it crosses
+this line and is rejected on scope, not on merit. Durable application:
+`road-to-capability-discoverability.md` (disposition of "fable-feedback-3").
+
 ## The four wings
 
 Four wings compose via [`cross-wing-handoff.md`](cross-wing-handoff.md)

package/docs/contracts/provider-lifecycle.md

@@ -36,11 +36,11 @@ the human noticing.
    `agents/reference/ai-video/smoke-traces/<provider>.md` with timestamp,
    model id, and **redacted** response shape.
 2. **Secret-redaction confirmation** — the captured trace, re-read
-   through `scripts/ai-video/lib/redact.sh`, shows zero residual
+   through `scripts/media/lib/redact.sh`, shows zero residual
    key fragments.
 3. **Contract conformance** — the adapter's four-method shell
    surface (`submit / poll / fetch / dry-run` *or* `run / dry-run`)
-   matches `scripts/ai-video/lib/adapter-contract.md` verbatim.
+   matches `scripts/media/lib/adapter-contract.md` verbatim.
 
 A maintainer flipping the tier in `agents/templates/.ai-video.xml.example`
 **and** the adapter header comment is the promotion event. There is
@@ -117,6 +117,6 @@ snapshot — older snapshots live in git history, not in this file.
 ## See also
 
 - [`provider-lifecycle-discipline`](../../dist/agent-src/rules/provider-lifecycle-discipline.md) — the tier-2 routing rule that surfaces this contract when a provider is touched.
-- [`scripts/ai-video/lib/adapter-contract.md`](../../src/scripts/ai-video/lib/adapter-contract.md) — the four-method shell contract every adapter implements.
+- [`scripts/media/lib/adapter-contract.md`](../../src/scripts/media/lib/adapter-contract.md) — the four-method shell contract every adapter implements.
 - [`agents/templates/.ai-video.xml.example`](../../agents/templates/.ai-video.xml.example) — operator-facing provider configuration template (carries the tier tag inline).
 - [`agents/settings/policies/media/README.md`](../../agents/settings/policies/media/README.md) — the agent-in-the-loop enforcement model this contract participates in.

package/docs/contracts/reasoning-discipline-protocol.md

@@ -0,0 +1,83 @@
+---
+stability: beta
+keep-beta-until: 2026-09-14
+---
+
+# Reasoning Discipline Protocol (RDP) — User Contract
+
+> **Status:** beta · **Owner:** package maintainer · **Last reviewed:** 2026-06-16
+>
+> The one-screen, user-facing contract for the `reasoning.*` settings. It says
+> what RDP does, when it engages, and how to switch it off. The sourced design
+> rationale lives in the dossier
+> [`docs/guidelines/agent-infra/frontier-reasoning-operating-profile.md`](../guidelines/agent-infra/frontier-reasoning-operating-profile.md);
+> the runtime cost-gate mechanic lives in
+> [`contexts/execution/rdp-gate.md`](../../src/agent-src/contexts/execution/rdp-gate.md). <!-- ref-ignore -->
+> This file is the entry point; depth stays there.
+
+## What RDP does
+
+RDP transplants the **operating discipline** of a frontier reasoning model onto
+whatever host model you run — the steps a strong model takes on its own that a
+weaker one skips unless prompted. When engaged, it nudges the agent toward:
+
+- **notes-first** — keeping multi-hypothesis reasoning, predictions, and
+  decisions in the session notes rather than the response;
+- **complexity-first** — resolving the load-bearing unknown before writing code;
+- **verifier** — a fresh-context check on structurally risky work
+  (branching · multiple constraints · stateful · irreversible);
+- **orchestrator** — a single coordination point that sequences the chain.
+
+These are disciplines the agent *applies*, not guarantees it *enforces*: how much
+of each applies is decided by the gate below, and a strong-reasoning host may
+apply them lightly or skip them where they would not pay.
+
+```
+CAPABILITY DOES NOT TRANSFER. DISCIPLINE DOES.
+```
+
+RDP makes the agent **work** more like a frontier model on under-specified and
+long-horizon tasks. It does **not** make a weaker model as *capable* as one — no
+prompt closes the weights gap.
+
+## When it engages
+
+RDP never runs on every turn. It engages only where it pays, decided by three
+**table-free** signals (there is no runtime model→band lookup — ADR-035):
+
+1. **Settings** — your `reasoning:` block (below). `enabled: false` stops here.
+2. **Task signal** — skips trivial / short / fully-specified tasks (rename, typo,
+   one-line edit, list files); engages on complex / ambiguous / multi-component /
+   long-horizon / stateful / irreversible work.
+3. **Host self-assessment** — a strong-reasoning host applies the discipline
+   **lightly / as a suggestion**; a standard host applies it **fully**. The agent
+   introspects; no maintained model list exists.
+
+The verifier carries its own stricter gate — it fires only on genuinely risky,
+non-trivial work, so the most expensive component stays rare. The exact
+condition lives in the gate context (it may evolve; this contract does not pin
+it).
+
+## How to turn it off
+
+All switches live in the `reasoning:` block of `.agent-settings.yml` (repo root;
+full schema in [`docs/customization.md`](../customization.md) § Available
+settings):
+
+| Goal | Setting |
+|---|---|
+| Disable the whole layer (zero overhead) | `reasoning.enabled: false` |
+| Keep the layer, drop the host self-assessment | `reasoning.auto_gate: false` (gate on task-signal + toggles only) |
+| Disable one behaviour | `reasoning.components.<name>: false` (e.g. `verifier_default`) |
+
+A component fires only when `reasoning.enabled` is `true` **and** the `auto_gate`
+test passes.
+
+## Why it is not a Fable / Mythos copy
+
+A frontier model's edge lives in its weights, which no prompt copies — so RDP
+copies the *discipline*, never the model. It ships **one** constraint-light
+scaffold with no "heavy" variant (two variants would be a hidden model→band
+table, forbidden by ADR-035); a host that wants more asks at turn time. The
+sourced evidence — including why over-prescription degrades a strong host — is in
+the dossier.

package/docs/contracts/rule-classification.md

@@ -29,7 +29,7 @@ document is the disposition map P2 / P4 will execute against.
 | auto | 47 | 142 297 | ≤ 60 000 |
 | **total** | **56** | **174 700** | **≤ 85 000** |
 
-Source: `python3 scripts/measure_rule_budget.py`.
+Source: `./scripts-run src/scripts/measure_rule_budget`.
 
 ## § 3 — Disposition table
 
@@ -142,8 +142,8 @@ Reference / examples / mechanics. Body migrates into
 
 | check | command | acceptance |
 |---|---|---|
-| Coverage | `python3 scripts/measure_rule_budget.py` | 56 rules total → 9 kernel + 22 condense + 18 skill + 7 guideline |
-| Determinism | `python3 scripts/measure_rule_budget.py --json` × 2 | byte-identical output |
+| Coverage | `./scripts-run src/scripts/measure_rule_budget` | 56 rules total → 9 kernel + 22 condense + 18 skill + 7 guideline |
+| Determinism | `./scripts-run src/scripts/measure_rule_budget --json` × 2 | byte-identical output |
 | No-edits | `git diff --stat .agent-src.uncondensed/rules/` | clean (this is plan-only) |
 
 ## § 5 — Open questions

package/docs/contracts/skill-domains.md

@@ -100,7 +100,7 @@ artifact**, not its auxiliary side-effects.
 
 ## § 4 — Skill assignment by domain
 
-Snapshot from B3 back-fill (regenerate via `python3 scripts/_emit_domain_table.py`).
+Snapshot from B3 back-fill (regenerate via `./scripts-run src/scripts/_emit_domain_table`).
 Source-of-truth for the assignment is each skill's `domain:` frontmatter —
 this table is a derived view, kept readable for reviewers.
 

package/docs/contracts/smoke-contracts.md

@@ -59,7 +59,7 @@ constant in the script body and the row below.
   is the **dispatch index** (priority table pointing at the other four
   authority rules); it is structurally exempt from the Iron-Law-fence
   requirement and listed in the script's `EXEMPT_FROM_FENCE` set.
-- **≤ 2 budget breaches** — `python3 scripts/measure_rule_budget.py
+- **≤ 2 budget breaches** — `./scripts-run src/scripts/measure_rule_budget
   --kernel-budget-check` currently reports 2 breaches
   (`kernel-bucket > 26000`, `no-cheap-questions > 4000`). The smoke
   asserts the count does not grow; reductions update `EXPECTED_BREACHES`

package/docs/contracts/surface-tiers.md

@@ -0,0 +1,81 @@
+---
+stability: beta
+keep-beta-until: 2026-09-15
+---
+
+# Surface tiers — core vs lab
+
+Every shipped artefact carries a **surface tier** so lab churn cannot
+destabilise the lean engine users install (road-to-install-contract-stability
+Phase 2).
+
+- **`core`** — the lean stable multi-host engine: rules + skills + install +
+  condensation, plus the engineering/authoring packs and the script tooling
+  that build and ship them. This is the adoptable surface.
+- **`lab`** — experimental / pilot meta-tooling that must not ride the same
+  release train as the core: AI media pipelines, the multi-model council, the
+  MCP server, prediction-pool, cost analytics, chat-history, benchmarking.
+
+The split is council-locked (2026-06-17, claude-sonnet-4-5 + gpt-4o, design
+mode, full convergence). Where it lives:
+
+- **Packs/domains** carry `surface_tier: core | lab` in their `pack.yaml`
+  manifest (default `core`; sourced from `src/config/discovery/packs.yml`).
+- **`src/scripts/` clusters** are mapped in
+  [`src/scripts/surface-tiers.yml`](../../src/scripts/surface-tiers.yml)
+  (exhaustive over cluster directories).
+- A **boundary guard** (`scripts/check_surface_tiers.py`) asserts the registry
+  is exhaustive and that no `core` module hard-imports a `lab` module.
+
+## Pack / domain tiers
+
+| Pack / domain | Tier | Reason |
+|---|---|---|
+| engineering-base, git, php, laravel, symfony | core | framework-neutral engineering hygiene + language patterns |
+| javascript, typescript, react, nextjs, python | core | language / framework pattern packs |
+| frontend-design, brand | core | design-intelligence + brand-consistency corpus |
+| product-basic, product-discovery | core | PO/PM + discovery surface |
+| finance-basic, finance-advanced | core | cash/runway + valuation cognition |
+| gtm-sales, gtm-marketing | core | pipeline + positioning surface |
+| ops-people, founder-strategy, small-business, construction | core | stable role/vertical packs |
+| analysis-workbench | core | RCA / post-mortem learning loop, no lab deps |
+| meta, memory, analytics, product-reasoning | core | always-on maintainer engine |
+| **ai-video** | **lab** | AI video pipeline, `trust_level_default: experimental` |
+| **ai-image** | **lab** | AI image generation, `trust_level_default: experimental` |
+| **fun** | **lab** | prediction-pool tips, non-essential, experimental |
+
+## Script-cluster tiers
+
+Authoritative map: [`src/scripts/surface-tiers.yml`](../../src/scripts/surface-tiers.yml).
+
+| Cluster | Tier | Reason |
+|---|---|---|
+| `_cli`, `_lib` | core | install / condense / CLI engine |
+| `adr`, `config`, `hooks`, `schemas`, `skill_tools`, `tools`, `smoke`, `repro` | core | engine tooling: ADR, discovery vocab, hooks, schemas, linters, fixtures |
+| `ai_council` | lab | multi-model council orchestration, external API deps |
+| `mcp_server` | lab | MCP stdio server, separate runtime, pilot distribution |
+| `media`, `ai-video`, `ai-image` | lab | AI media adapters + shared substrate (experimental consumers only) |
+| `command_suggester` | lab | context-aware suggestion engine, pilot; no core caller |
+| `prediction-pool` | lab | prediction-pool optimizer (fun pack) |
+| `cost` | lab | cost tracking / budget gate, observability (not a core/CI dep) |
+| `_archive` | lab | archived / deprecated scripts |
+
+Top-level lab scripts (`council_cli`, `chat_history`, `mine_session`,
+`mcp_render`, `bench_ab_*`, `cost_*`, `build_cloud_bundle`,
+`build_linear_digest`, `build_mcp_registry_manifest`, `memory_report`,
+`memory_signal`, …) are listed under `lab_modules` in the registry; every other
+top-level script defaults to `core`.
+
+## Core → lab coupling
+
+The boundary guard forbids a `core` module from **hard**-importing a `lab`
+module. A `try/except ModuleNotFoundError` *optional* import is allowed —
+core degrades gracefully when lab is absent. The only existing core→lab edges
+are three such guarded optional imports (`_lib/knowledge_global_redaction.py`
+and `_cli/cmd_doctor.py` → `ai_council`); they are tolerated by design.
+
+## See also
+
+- [`install-layout.md`](install-layout.md) — the install-ABI freeze this split builds on.
+- [`src/scripts/surface-tiers.yml`](../../src/scripts/surface-tiers.yml) — the cluster registry.
+- [`docs/architecture.md`](../architecture.md) — core vs full install (the consumer-facing framing).

package/docs/contracts/ticket-bundle-format.md

@@ -0,0 +1,228 @@
+# Ticket-bundle format
+
+> The contract every downstream artifact reads from: the `emit-tickets` skill,
+> the buildability/manifest linters, and the `implement-ticket` bundle
+> input path. Authoritative for the frontmatter
+> schema, the body doctrine, the tracker mapping, and the self-containedness
+> floor. Locked by [ADR-101](../decisions/ADR-101-ticket-bundle-emission.md).
+
+## 1. Why this exists
+
+A roadmap step is a one-line checkbox; the full build spec is spread across the
+roadmap (what), ADRs (why), and the code (how). A `high`-tier agent holds that
+together; a `lite`-tier agent (Haiku) cannot. A **ticket bundle** is the closed,
+durable, importable artifact that lets an expensive planning agent hand a cheap
+building agent a complete unit of work. Markdown is the source of truth; a
+tracker issue (Linear/Jira) is a copy you make by paste or via MCP — not a
+generated export (§8).
+
+## 2. Layout
+
+A bundle is a directory, one per roadmap, under `agents/tickets/`:
+
+```
+agents/tickets/{roadmap-slug}/
+  manifest.yml                 # machine index: dependency graph
+  T-001-{slug}.md              # one ticket = one Markdown build contract
+  T-001-{slug}.assets/         # durable design context for that ticket
+    before.png  wireframe.png  example-io.md
+  T-002-{slug}.md
+  ...
+agents/tickets/_registry.yml   # machine-generated index of all bundles
+```
+
+- **Separate tree, not co-located** under the roadmap — the flat-file dashboard
+  and archival machinery (`update_roadmap_progress.py`,
+  `archive_completed_roadmaps.py`) assume `agents/roadmaps/*.md` are flat files;
+  a separate tree keeps that untouched (ADR-101 R1).
+- **Discovery** is via the generated `agents/tickets/_registry.yml` — one scan,
+  no recursive glob, no roadmap↔manifest circular dependency.
+- **Lifecycle**: a bundle is durable (unlike transient `agents/roadmap-assets/`);
+  when its roadmap archives, the bundle moves with it to
+  `agents/tickets/archive/{slug}/`.
+
+## 3. Ticket frontmatter (schema: `src/scripts/schemas/ticket.schema.json`)
+
+```yaml
+---
+id: T-001                      # bundle-local id; stable handle for the ticket
+roadmap: road-to-xyz           # back-link (traceability spine)
+phase: 2                       # roadmap phase number
+title: "…"                     # → Linear Title
+status: ready                  # ready | draft | done
+model_tier: lite               # lite | medium | high — WHO may build it (ADR-035)
+estimate: 3                    # story points (from estimate-ticket)
+priority: 2                    # 0–4, Linear-compatible
+labels: [backend, mcp]
+parent: T-000                  # → Linear "Parent issue"; null at phase root
+blocked_by: [T-000]            # dependency edges (must be acyclic)
+adr_refs:                      # the "why", SHA-pinned (drift here HARD-blocks)
+  - { path: docs/decisions/ADR-101-ticket-bundle-emission.md, sha: <git-blob-sha> }
+source_refs:                   # files the build reads/changes, SHA-pinned (drift WARNS)
+  - { path: src/scripts/build_linear_digest.py, sha: <git-blob-sha> }
+assets: [T-001.assets/wireframe.png]   # relative to the bundle dir
+acceptance:                    # runnable AND isolation-testable; no prose-only
+  - "python3 src/scripts/lint_ticket_buildable.py exits 0"
+boundaries:                    # ENFORCED by the work_engine boundary guard
+  must_touch:    [src/scripts/lint_ticket_buildable.py]
+  may_touch:     [Taskfile.yml]
+  must_not_touch: [src/scripts/work_engine/**, ".github/**"]
+---
+```
+
+`status` is `done` only after the work landed + verification passed.
+
+## 4. Ticket body doctrine (the build contract)
+
+A lite ticket is autonomous only with this fixed section order:
+
+| Section | Purpose |
+|---|---|
+| `## Why` | 1–3 lines; the outcome, not backstory |
+| `## Context spine` | exact paths (`file.py:142`), the sibling-to-mirror, the producer of any shape it consumes — so the builder never searches |
+| `## Do` | ordered, mechanical steps |
+| `## Do NOT touch` | hard boundaries (mirrors frontmatter `boundaries`) |
+| `## Acceptance` | points at frontmatter `acceptance` (runnable, isolation-testable) |
+| `## Quality gates` | the concrete commands (not "run CI") |
+| `## Assets` | relative links into `T-NNN.assets/` (UI tickets) |
+
+**Self-containedness rule:** if the builder must read a file that is not in the
+context spine or `source_refs`, the ticket is incomplete.
+
+## 5. Self-containedness floor (per `model_tier`)
+
+Enforced by `lint_ticket_buildable.py`. A ticket FAILS the gate if its tier's
+row is not satisfied:
+
+| tier | acceptance | ≥1 concrete path | non-empty boundaries | resolvable assets | size floor |
+|---|---|---|---|---|---|
+| `lite` | required, runnable + isolation-testable | required | required | required (or `assets: none`) | ≤ 5 files AND ≤ 200 lines, else split or escalate to `medium` |
+| `medium` | required | required | recommended | recommended | — |
+| `high` | required | recommended | — | — | — |
+
+A failing `lite` ticket is rejected or auto-escalated to `medium`.
+
+## 6. Manifest (schema: `src/scripts/schemas/ticket-manifest.schema.json`)
+
+```yaml
+status: ready
+planner_tier: high
+builder_tier: lite
+import_targets: { linear: true, jira: false }
+dependency_graph:              # acyclic (no topological layering in v1)
+  T-001: { status: ready, blocks: [T-002] }
+  T-002: { status: ready, blocks: [] }
+```
+
+The manifest carries no tracker state — there is no API export to keep
+idempotent (§8). The bundle is the source of truth; a tracker issue is created
+by paste or by the agent via MCP, never synced back into the manifest.
+
+## 7. Registry (`agents/tickets/_registry.yml`, machine-generated)
+
+```yaml
+bundles:
+  road-to-ticket-bundles:
+    manifest_path: agents/tickets/road-to-ticket-bundles/manifest.yml
+    source_roadmap: agents/roadmaps/archive/road-to-ticket-bundles.md
+    status: in_progress        # derived from manifest
+```
+
+`update_roadmap_progress.py` reads this one file; never recursive-globs bundles.
+
+## 8. Tracker handoff — paste-ready, or via MCP (no API export)
+
+A ticket goes into Linear/Jira **by copy/paste** or, when programmatic, by the
+**agent using a tracker MCP server**. There is **no bundled API client and no
+automatic export** — the ticket Markdown *is* the handoff artifact.
+
+| Ticket field | Tracker issue |
+|---|---|
+| frontmatter `title` | issue title |
+| the Markdown **body** (everything after the frontmatter) | issue description — paste it; Markdown renders in Linear/Jira |
+| `priority` / `estimate` / `labels` | the matching issue fields (set during paste / by MCP) |
+| `parent` (phase root) | parent issue, when the tracker supports sub-issues |
+
+- **Copy/paste (default):** the ticket body is clean, render-ready Markdown.
+  Paste it into a new Linear/Jira issue; set title from `title`. Asset images
+  are relative repo paths — attach them in the tracker, or (public repo) paste a
+  `raw.githubusercontent.com` URL.
+- **MCP (programmatic):** to create issues without pasting, the agent calls the
+  Linear/Jira **MCP server** with the ticket as input. The package ships **no**
+  API wiring of its own — MCP is the integration surface.
+- **One direction only:** the bundle is the source of truth; a tracker issue is
+  a copy, never read back into the bundle (no sync, no `linear_state`).
+
+## 9. Traceability spine (bidirectional)
+
+`roadmap ↔ ticket ↔ ADR ↔ PR`. Each ticket frontmatter names its `roadmap` +
+`adr_refs`; each materialized roadmap step carries an inline
+`<!-- ticket: T-NNN -->` marker. The `work_engine` ticket envelope
+(`{id, title, body, acceptance_criteria}`) is a strict subset of this
+frontmatter, so `/implement-ticket` consumes a bundle with no schema fork.
+
+## 10. Staleness — split severity
+
+`lint_ticket_stale` recomputes the pinned SHAs:
+
+- **`adr_refs` drift → HARD block** (`not build-ready`); ADRs are semantic
+  decisions, rarely change → resolution = re-emit the bundle.
+- **`source_refs` drift → WARN only**; source files churn constantly, so a hard
+  block would keep most tickets perma-stale and multiply bundles. The builder
+  proceeds on a warning.
+
+## 11. Assets — durable, size-capped (LFS deferred)
+
+Git LFS is **not** configured in this repo today, and wiring it (install +
+remote LFS store) is heavier than v1 needs. v1 decision: assets are git-tracked
+binaries under a **size cap** — ≤ 500 KB per asset — and authors prefer vector /
+text context (Mermaid, ASCII, SVG, example-I/O Markdown) over raster where it
+carries the same information. `lint_ticket_buildable.py` warns on any asset over
+the cap. LFS is revisited only if `agents/tickets/**` binary weight is proven a
+real problem (same "defer until observed" discipline as the mutable-tickets
+mode). Non-binary design context lives as plain Markdown in the `.assets/` folder.
+
+## 12. Kill-switch & rollback
+
+Two reversal surfaces, since a bundle is git-tracked and the tracker is a
+projection:
+
+- **Per-ticket.** A ticket is reverted by `git`-restoring its `T-NNN-*.md`
+  (and `.assets/`) to a prior commit. A `lite` build gone wrong is bounded by
+  the ticket's `boundaries` (the work_engine boundary guard halts out-of-scope
+  edits before commit) — so the blast radius is the ticket's `must_touch` set.
+- **Per-bundle.** To abandon a bundle entirely, `git mv` it to
+  `agents/tickets/archive/{slug}/` (it moves with its roadmap on archival,
+  §2) — never delete in place, so the audit trail survives.
+
+A tracker issue created by paste/MCP from a ticket is a one-way copy (§8); the
+bundle is the source of truth, so reverting the bundle needs no tracker
+coordination — fix the issue in the tracker by hand if it was already created.
+
+## 13. Status projection — one direction only
+
+Three surfaces show a ticket's progress; exactly one is the truth and the other
+two are derived. The writeback is **single-directional** so they never become
+rival truths:
+
+```
+ticket `status` (MD)  ──►  roadmap checkbox  ──►  agents/roadmaps-progress.md (dashboard)
+```
+
+- The ticket file's `status` (`ready` / `draft` / `done`) is the **truth**.
+- When a ticket flips to `done`, its roadmap step's `<!-- ticket: T-NNN -->`
+  checkbox flips `[x]` in the **same edit**, and the dashboard regenerates
+  (`./agent-config roadmap:progress`) — the existing `roadmap-progress-sync`
+  cadence, unchanged.
+- A tracker issue (created by paste/MCP, §8) is a point-in-time copy; its state
+  is **not** read back into the ticket. If you keep a tracker issue in sync, do
+  it from the ticket outward (re-paste / MCP update), never the reverse.
+
+Never wire the reverse (tracker → ticket): that recreates the two-drifting-truths
+failure the whole format avoids.
+
+## See also
+
+- [ADR-101](../decisions/ADR-101-ticket-bundle-emission.md) — the format commitment + council convergence.
+- [`roadmaps.md`](../../src/agent-src/templates/roadmaps.md) — the sibling planning artifact.
+- [ADR-035](../decisions/ADR-035-model-capability-tiers.md) — the `model_tier` bands.