@event4u/agent-config 8.8.0 → 8.10.0

package/docs/contracts/mcp-tool-inventory.md

@@ -23,34 +23,34 @@ keep-beta-until: 2026-08-14
 
 | Tool | Side-effect | Transports | Catalog | Handler |
 |---|---|---|---|---|
-| `lint_skills` | `ro` | stdio | [`consumer_tool_catalog.json:7`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L7) | [`tools.ts:1183`](../../src/scripts/mcp_server/tools.ts#L1183) |
-| `chat_history_append` | `fs-write` | stdio | [`consumer_tool_catalog.json:24`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L24) | [`tools.ts:1211`](../../src/scripts/mcp_server/tools.ts#L1211) |
-| `chat_history_read` | `ro` | stdio | [`consumer_tool_catalog.json:43`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L43) | [`tools.ts:1272`](../../src/scripts/mcp_server/tools.ts#L1272) |
-| `memory_lookup` | `ro` | stdio | [`consumer_tool_catalog.json:63`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L63) | [`tools.ts:1348`](../../src/scripts/mcp_server/tools.ts#L1348) |
-| `memory_get` | `ro` | stdio | [`consumer_tool_catalog.json:80`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L80) | [`tools.ts:1404`](../../src/scripts/mcp_server/tools.ts#L1404) |
-| `memory_signal` | `fs-write` | stdio | [`consumer_tool_catalog.json:94`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L94) | [`tools.ts:1513`](../../src/scripts/mcp_server/tools.ts#L1513) |
-| `memory_status` | `ro` | stdio | [`consumer_tool_catalog.json:110`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L110) | [`tools.ts:1428`](../../src/scripts/mcp_server/tools.ts#L1428) |
-| `skill_trigger_eval` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:117`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L117) | _stub-only_ |
-| `suggest_command` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:133`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L133) | _stub-only_ |
-| `suggest_skill_for_task` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:148`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L148) | _stub-only_ |
-| `mine_session` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:163`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L163) | _stub-only_ |
-| `update_form_request_messages` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:177`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L177) | _stub-only_ |
-| `sync_gitignore` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:192`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L192) | _stub-only_ |
-| `sync_agent_settings` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:205`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L205) | _stub-only_ |
-| `run_tests` | `shell` | stdio | [`consumer_tool_catalog.json:219`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L219) | [`tools.ts:1688`](../../src/scripts/mcp_server/tools.ts#L1688) |
-| `run_quality_checks` | `shell` | _(stub)_ | [`consumer_tool_catalog.json:233`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L233) | _stub-only_ |
-| `list_skills` | `ro` | stdio | [`consumer_tool_catalog.json:246`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L246) | [`tools.ts:1442`](../../src/scripts/mcp_server/tools.ts#L1442) |
-| `list_commands` | `ro` | stdio | [`consumer_tool_catalog.json:253`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L253) | [`tools.ts:1457`](../../src/scripts/mcp_server/tools.ts#L1457) |
-| `list_rules` | `ro` | stdio | [`consumer_tool_catalog.json:260`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L260) | [`tools.ts:1472`](../../src/scripts/mcp_server/tools.ts#L1472) |
-| `compile_router` | `shell` | _(stub)_ | [`consumer_tool_catalog.json:267`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L267) | _stub-only_ |
-| `read_resource_body` | `ro` | stdio | [`consumer_tool_catalog.json:280`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L280) | [`tools.ts:1488`](../../src/scripts/mcp_server/tools.ts#L1488) |
-| `roadmap_progress` | `fs-write` | stdio | [`consumer_tool_catalog.json:294`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L294) | [`tools.ts:1547`](../../src/scripts/mcp_server/tools.ts#L1547) |
-| `roadmap_archive` | `fs-write` | stdio | [`consumer_tool_catalog.json:307`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L307) | [`tools.ts:1570`](../../src/scripts/mcp_server/tools.ts#L1570) |
-| `capabilities_index` | `fs-write` | stdio | [`consumer_tool_catalog.json:314`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L314) | [`tools.ts:1586`](../../src/scripts/mcp_server/tools.ts#L1586) |
-| `doctor_report` | `ro` | stdio | [`consumer_tool_catalog.json:327`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L327) | [`tools.ts:1609`](../../src/scripts/mcp_server/tools.ts#L1609) |
-| `conformance_check` | `ro` | stdio | [`consumer_tool_catalog.json:334`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L334) | [`tools.ts:1623`](../../src/scripts/mcp_server/tools.ts#L1623) |
-| `telemetry_report` | `ro` | stdio | [`consumer_tool_catalog.json:341`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L341) | [`tools.ts:1637`](../../src/scripts/mcp_server/tools.ts#L1637) |
-| `council_estimate` | `ro` | stdio | [`consumer_tool_catalog.json:354`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L354) | [`tools.ts:1659`](../../src/scripts/mcp_server/tools.ts#L1659) |
+| `lint_skills` | `ro` | stdio | [`consumer_tool_catalog.json:7`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L7) | [`tools.ts:1200`](../../src/scripts/mcp_server/tools.ts#L1200) |
+| `chat_history_append` | `fs-write` | stdio | [`consumer_tool_catalog.json:24`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L24) | [`tools.ts:1228`](../../src/scripts/mcp_server/tools.ts#L1228) |
+| `chat_history_read` | `ro` | stdio | [`consumer_tool_catalog.json:43`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L43) | [`tools.ts:1289`](../../src/scripts/mcp_server/tools.ts#L1289) |
+| `memory_lookup` | `ro` | stdio | [`consumer_tool_catalog.json:63`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L63) | [`tools.ts:1365`](../../src/scripts/mcp_server/tools.ts#L1365) |
+| `memory_get` | `ro` | stdio | [`consumer_tool_catalog.json:81`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L81) | [`tools.ts:1432`](../../src/scripts/mcp_server/tools.ts#L1432) |
+| `memory_signal` | `fs-write` | stdio | [`consumer_tool_catalog.json:95`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L95) | [`tools.ts:1541`](../../src/scripts/mcp_server/tools.ts#L1541) |
+| `memory_status` | `ro` | stdio | [`consumer_tool_catalog.json:111`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L111) | [`tools.ts:1456`](../../src/scripts/mcp_server/tools.ts#L1456) |
+| `skill_trigger_eval` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:118`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L118) | _stub-only_ |
+| `suggest_command` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:134`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L134) | _stub-only_ |
+| `suggest_skill_for_task` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:149`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L149) | _stub-only_ |
+| `mine_session` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:164`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L164) | _stub-only_ |
+| `update_form_request_messages` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:178`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L178) | _stub-only_ |
+| `sync_gitignore` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:193`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L193) | _stub-only_ |
+| `sync_agent_settings` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:206`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L206) | _stub-only_ |
+| `run_tests` | `shell` | stdio | [`consumer_tool_catalog.json:220`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L220) | [`tools.ts:1716`](../../src/scripts/mcp_server/tools.ts#L1716) |
+| `run_quality_checks` | `shell` | _(stub)_ | [`consumer_tool_catalog.json:234`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L234) | _stub-only_ |
+| `list_skills` | `ro` | stdio | [`consumer_tool_catalog.json:247`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L247) | [`tools.ts:1470`](../../src/scripts/mcp_server/tools.ts#L1470) |
+| `list_commands` | `ro` | stdio | [`consumer_tool_catalog.json:254`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L254) | [`tools.ts:1485`](../../src/scripts/mcp_server/tools.ts#L1485) |
+| `list_rules` | `ro` | stdio | [`consumer_tool_catalog.json:261`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L261) | [`tools.ts:1500`](../../src/scripts/mcp_server/tools.ts#L1500) |
+| `compile_router` | `shell` | _(stub)_ | [`consumer_tool_catalog.json:268`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L268) | _stub-only_ |
+| `read_resource_body` | `ro` | stdio | [`consumer_tool_catalog.json:281`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L281) | [`tools.ts:1516`](../../src/scripts/mcp_server/tools.ts#L1516) |
+| `roadmap_progress` | `fs-write` | stdio | [`consumer_tool_catalog.json:295`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L295) | [`tools.ts:1575`](../../src/scripts/mcp_server/tools.ts#L1575) |
+| `roadmap_archive` | `fs-write` | stdio | [`consumer_tool_catalog.json:308`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L308) | [`tools.ts:1598`](../../src/scripts/mcp_server/tools.ts#L1598) |
+| `capabilities_index` | `fs-write` | stdio | [`consumer_tool_catalog.json:315`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L315) | [`tools.ts:1614`](../../src/scripts/mcp_server/tools.ts#L1614) |
+| `doctor_report` | `ro` | stdio | [`consumer_tool_catalog.json:328`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L328) | [`tools.ts:1637`](../../src/scripts/mcp_server/tools.ts#L1637) |
+| `conformance_check` | `ro` | stdio | [`consumer_tool_catalog.json:335`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L335) | [`tools.ts:1651`](../../src/scripts/mcp_server/tools.ts#L1651) |
+| `telemetry_report` | `ro` | stdio | [`consumer_tool_catalog.json:342`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L342) | [`tools.ts:1665`](../../src/scripts/mcp_server/tools.ts#L1665) |
+| `council_estimate` | `ro` | stdio | [`consumer_tool_catalog.json:355`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L355) | [`tools.ts:1687`](../../src/scripts/mcp_server/tools.ts#L1687) |
 
 ## Glossary
 

package/docs/contracts/release-pr-gating.md

@@ -80,6 +80,27 @@ the feature-PR floor by adding:
 | `release-validation.yml` (Phase B) | `release-shape` | shape detector — fails closed if diff exits the allowlist |
 | `release-validation.yml` (Phase B) | `changelog-entry` | CHANGELOG carries an entry matching the head-branch version |
 | `release-validation.yml` (Phase B) | `version-consistency` | `package.json` / `marketplace.json` / pack manifests agree on the version |
+| `consumer-matrix.yml` | `consumer-matrix` · `publish-dry-run` · `mcp-worker-dry-run` · `plugin-bootstrap` | pack-based consumer E2E + pre-tag dry-runs of the release-adjacent workflows — see the exemption note below |
+
+## Consumer-matrix exemption — the tarball window
+
+The cut surface above rests on "release PRs cannot regress install or
+runtime behaviour by construction". That argument covers the **source
+diff** — it is blind to the **published tarball**. Every historical
+packaging incident (tarball missing `src/install/` across two minors,
+`tsx` absent from the package, npm-pin drift, the MCP worker deploy red
+across five releases) entered `main` on ordinary PRs and manifested only
+at publish time — exactly the window between merge and tag where nothing
+pack-based ran.
+
+[`consumer-matrix.yml`](../../.github/workflows/consumer-matrix.yml) is
+therefore **exempt from the release-PR skip and runs ON release PRs** (its
+primary trigger), packing the tarball and exercising it as a consumer,
+plus dry-running `publish-npm.yml` and `deploy-mcp-worker.yml` before the
+tag exists. Contract + counterfactual map:
+[`docs/distribution/consumer-matrix.md`](../distribution/consumer-matrix.md).
+The source-level skips above stay unchanged — the exemption adds the
+tarball dimension, it does not reopen the source matrices.
 
 ## Rollback trigger — fail-closed
 
@@ -122,3 +143,8 @@ name alone never bypasses the heavy matrix.
   release-branch naming convention.
 - [`ADR-113`](../decisions/ADR-113-ci-native-release-label-trigger.md) — the
   CI-native (`release`-label) entry point into the same script.
+- [`docs/distribution/consumer-matrix.md`](../distribution/consumer-matrix.md) —
+  pack-based consumer E2E; the documented exemption from the cut surface.
+- [`release-sizing.md`](release-sizing.md) — release scope floor: one primary
+  goal per minor, `Rollback:` lines for new / reworked subsystems (gate:
+  `src/scripts/lint_changelog_rollback.ts`).

package/docs/contracts/release-sizing.md

@@ -0,0 +1,85 @@
+---
+stability: beta
+keep-beta-until: 2026-09-10
+---
+
+# Release Sizing
+
+> **Status:** active · v0 / beta · 2026-07-10. Governs how much a
+> minor release may carry and what every shipped subsystem owes the
+> reader: one primary goal, a disable path, and a named rollback.
+> No version numbers appear here as commitments — this contract
+> shapes releases, it does not schedule them.
+
+## One primary product goal per minor release
+
+Every minor release names **exactly one primary product goal** — the
+one-sentence answer to "why does this release exist?". Secondary
+changes may ride along, but the release notes lead with the primary
+goal, and a release that cannot name one is not ready to cut.
+Scope discipline, not a ratio: what qualifies is a judgment call the
+maintainer makes when labeling the release PR
+([`release-pr-gating.md`](release-pr-gating.md)).
+
+## Major subsystems are independently disableable where feasible
+
+A major subsystem shipped or substantially reworked in a release is
+**independently disableable** where feasible — a settings key in
+`.agent-settings.yml`, a pack that can stay uninstalled, or an
+explicit opt-in flag. The release notes **name the flag / config
+key** so a consumer who hits a regression can switch the subsystem
+off without downgrading the whole package. "Where feasible" is a
+real qualifier: kernel rules and the install skeleton have no
+sensible off-switch; everything above that floor should.
+
+## Rollback path — the `Rollback:` line
+
+Every CHANGELOG entry that **introduces or substantially reworks a
+subsystem** names its rollback path in the entry itself via a
+`Rollback:` line:
+
+```md
+* **workspace:** task-orchestration layer behind `/work` ([abc1234](…))
+  Rollback: set `workspace.enabled: false` in `.agent-settings.yml`.
+```
+
+The rollback path is the disable flag from the section above, a
+revert instruction, or a downgrade note — whatever actually undoes
+the subsystem for a consumer. Enforced mechanically:
+`src/scripts/lint_changelog_rollback.ts` fails when a new minor /
+major section (`## [X.Y.0]`) contains no `Rollback:` line. The gate
+only fires for versions **strictly greater** than the version in
+`package.json` at lint time, so historical sections never retro-fail;
+entry shape stays governed by
+[`CHANGELOG-conventions.md`](CHANGELOG-conventions.md).
+
+## Consumer matrix is the floor for every release
+
+The pack-based consumer matrix —
+[`../distribution/consumer-matrix.md`](../distribution/consumer-matrix.md)
+(authored in parallel; forward link) — is the **floor** for every
+release: no release ships a change that knowingly breaks a supported
+cell of that matrix without the break being declared under
+`### BREAKING CHANGES` and reflected in the matrix in the same
+release.
+
+## REJECTED — consumer-facing effort ratio
+
+The proposed meta-ratio *"≥ 2/3 of effort per release must be
+consumer-facing"* was **CUT by council 2026-07-10**
+(claude-sonnet-4-5 + gpt-4o, unanimous) as a **gameable vanity
+metric**: effort is unmeasurable at review time, "consumer-facing"
+is reclassifiable at will, and the ratio punishes necessary
+infrastructure releases. Recorded here so it is not re-proposed;
+re-opening it requires new evidence per the decision-revisit gate.
+
+## Cross-references
+
+- [`CHANGELOG-conventions.md`](CHANGELOG-conventions.md) — entry
+  shape the `Rollback:` line extends.
+- [`release-pr-gating.md`](release-pr-gating.md) — release-PR shape
+  detection; the sizing judgment happens at labeling time.
+- [`../release-runbook.md`](../release-runbook.md) — the cut
+  procedure this contract's pre-flight check lives in.
+- `src/scripts/lint_changelog_rollback.ts` — the mechanized
+  `Rollback:` gate (run `--selftest` for its fixture proof).

package/docs/contracts/surface-agent-contracts.md

@@ -0,0 +1,153 @@
+# Surface-Agent Contracts — medium invariants, not one generic agent
+
+Backbone for `road-to-surface-specific-agent-contracts`.
+One generic agent does every medium badly. Each **surface** (spreadsheet, deck,
+document, browser, mobile/chat, code, …) has non-negotiable local invariants and
+its own verification truth source. This contract names them, maps them to owner
+skills, and defines how the agent detects a surface, resolves conflicts, and
+hands off between surfaces — advisory first (staged rollout below).
+
+Capability + honest-degrade for the *verification* primitives these contracts
+rely on is the sibling [`design-artifact-verification`](design-artifact-verification.md)
+(browser / screenshot / pdf_render / doc_export / image_decode / static_inspect);
+this contract adds the office/data primitives and the surface-routing layer.
+
+## Iron Law — the medium's truth source verifies the work
+
+```
+EACH SURFACE HAS A NON-NEGOTIABLE INVARIANT AND ITS OWN TRUTH SOURCE.
+VERIFY WITH THE MEDIUM'S TRUTH SOURCE — A FORMULA READ-BACK, A RENDERED SLIDE,
+A FETCHED PAGE — NEVER A GENERIC "LOOKS RIGHT". WHEN THE SURFACE TOOL IS
+ABSENT, SAY WHAT COULD NOT BE VERIFIED — NEVER PRETEND THE MEDIUM STEP RAN.
+```
+
+## Surface detection — before applying any surface rule
+
+Resolve the surface from these signals, in priority order:
+
+1. **Explicit file type** — `.xlsx`/`.csv` → spreadsheet, `.pptx`/`.key` → deck, `.docx`/`.md` → document, `.ipynb` → notebook.
+2. **Requested output format** — "as a deck", "export to PDF", "a spreadsheet".
+3. **Named tool / plugin / connector** — a named app connector wins over generic browsing.
+4. **User environment** — mobile/chat host vs desktop IDE vs CI.
+5. **Data shape** — tabular/numeric → spreadsheet; slides → deck; prose → document.
+6. **Task verb** — "chart", "model", "present", "browse", "refactor".
+7. **Target deliverable** — what the user will actually use.
+
+**Ambiguity handling.** When ≥2 surfaces plausibly apply and the choice changes
+the work materially, ask ONE compact question (per
+[`ask-when-uncertain`](../../src/rules/ask-when-uncertain.md)); when the user
+already constrained it, proceed and state the surface assumption.
+
+## Surface conflict rule
+
+When the user asks for output **native to a different connected surface**,
+delegate to (or ask to enable) that surface — do not force a local workaround.
+A request for a spreadsheet answered with a markdown table, or a deck answered
+with prose, is a surface violation. Prefer the connected surface; if it is
+unavailable, say so and offer the degraded form explicitly as degraded.
+
+## Surface taxonomy
+
+Each surface records: **owner** skills/commands · **allowed** tools · **forbidden**
+shortcuts · **truth source** (how the medium verifies) · **handoff** in/out ·
+**trigger** examples · **capability** requirement · **degrade** language.
+
+| Surface | Owner skills | Forbidden shortcut | Truth source | Capability → degrade |
+|---|---|---|---|---|
+| **code** | `scope-control`/`verify-before-complete` (rules), stack skills | edit unread files; broad refactor around a fix | tests + type-checker + fresh run | local exec → static-only caveat |
+| **design** | `fe-design`, `design-review`, `existing-ui-audit` | taste before inspecting the system | rendered artifact ([design-artifact-verification](design-artifact-verification.md)) | browser/screenshot → static caveat |
+| **spreadsheet** | `spreadsheet-authoring` (Phase 2) | hardcode a computed value; unofficial financial source unmarked | formula read-back after write | native tooling → exported-file only → "cannot verify" |
+| **document** | `doc-coauthoring`, `markitdown` | rasterize selectable text to PDF | open/export readback | doc parser → format caveat |
+| **deck** | `html-deck` | build slides before an outline; tiny text | export + slide render | deck export → outline-only caveat |
+| **browser** | `browser` surface (Phase 4), MCP fetch | invent a URL; fetch when not needed | the fetched page itself | fetch → "not fetched, cannot confirm" |
+| **mobile/chat** | interaction floor (Phase 5) | markdown tables in narrow chat; multi-question walls | the host's rendering | tappable UI → concise text choices |
+| **research** | `research:deep`/`research:report` | claim without a retrieved source | per-part grounding + disconfirmation | — |
+| **visualizer/diagram** | `html-deck`, image skills | decorative chart over the data's shape | the rendered diagram | render → described-structure caveat |
+| **cowork/dispatch** | `subagent-orchestration` | one agent doing parallel-safe work serially | verified subagent returns | spawn primitive → in-session |
+| **MCP/app connector** | `mcp` | generic web search when a connector fits | the connector's own result | connector present → suggest/opt-in |
+
+This taxonomy table **is** the canonical work-surface map. (Note: the existing
+`src/config/surface-matrix.yml` is a *different* concept — per-tool **install-surface**
+de-duplication, set-equality-enforced against `install.ts::USER_SCOPE_PATHS` by
+`lint_surface_matrix`; extending it with *work* surfaces would break that
+linter, so the work-surface map lives here, not there.) Host verification
+capability is `src/config/host-capabilities.yml` +
+[`design-artifact-verification`](design-artifact-verification.md). Carrier
+choice vs host capability vs these invariants stay aligned with the
+artifact-routing work — do not let the three diverge.
+
+## Staged rollout
+
+Each surface contract: **advisory** (skills reference the invariant) →
+**routed** (owner skills updated + eval fixtures pass) → **default-on** only
+once the host capability/degrade behaviour is documented for that surface. A
+contract is never default-on for a host class that cannot run the surface's
+truth-source check — it stays advisory + caveat there.
+
+## Cross-surface handoff envelope
+
+When work moves between surfaces (spreadsheet → deck, research → document,
+browser evidence → report, design prototype → production code), the source
+surface emits a **handoff envelope** the target consumes instead of redoing
+work:
+
+```
+source_surface · target_surface · user_goal · assets/files ·
+constraints · verification_already_done · pending_checks ·
+capability_limits · assumptions · privacy/source_restrictions
+```
+
+- The target surface **trusts `verification_already_done`** and does not repeat
+  it; it runs only `pending_checks`.
+- The target honours `privacy/source_restrictions` — a source-specific
+  restriction (e.g. an internal-only dataset) is never widened by the handoff.
+- **Degrade:** if the target surface's tooling is absent, the envelope remains a
+  durable **plan** (what to do + what is verified) — never a faked generated
+  artifact.
+
+## Mobile/chat interaction floor
+
+Interaction style is host-sensitive, not one verbose desktop default.
+
+- **Narrow-chat output.** Avoid markdown tables in a narrow chat host; use short
+  prose/bullets. Keep post-tool summaries short.
+- **Ask at most one compact question**, and only when it changes the work:
+  - **No options** when the user asked for the agent's *analysis* of A vs B — give the recommendation (fixture `ssac-a-or-b-analysis`).
+  - **Offer options** when *eliciting a preference* — tappable choices where the host supports them, degrading to concise text choices otherwise (fixture `ssac-preference-elicitation`).
+  - **Proceed on stated constraints** when the prompt already fixes them — no redundant questions (fixture `ssac-enough-constraints-no-question`).
+
+## Code surface — audit dispositions (Phase 6)
+
+The external code-prompt mechanisms, audited against existing rules — **covered**
+(cite the owner, do not duplicate), **tightened** (a note added), or **rejected**
+(host-specific):
+
+| Mechanism | Disposition | Owner / note |
+|---|---|---|
+| Read before proposing | **covered** | `think-before-action`, `source-discovery-gate` (fixture `ssac-edit-unread-file`) |
+| Minimal scoped changes | **covered** | `minimal-safe-diff` (fixture `ssac-broad-refactor-around-bugfix`) |
+| Todo/task visibility | **covered** | host task tooling + roadmap loop; no new rule |
+| Parallel independent exploration | **tighten** | note in `subagent-orchestration` / this contract's cowork row — sequential independent reads when parallel is available is a miss |
+| Specialized tools over shell | **covered** | `mcp` § tool-tier ladder (execution-discipline harvest) |
+| No shell as user communication | **covered** | `output-discipline` / `direct-answers` |
+| Line-specific references | **covered** | `file_path:line` convention in host instructions |
+| No time estimates | **covered** | `direct-answers` § no-duration (execution-discipline harvest) |
+| Fresh verification before "done" | **covered** | `verify-before-complete` (fixture `ssac-claim-done-without-verification`) |
+
+No new code-surface rule is created — the deltas are already owned; the one
+**tighten** (parallel-safe exploration) is recorded here + in the cowork row. No
+Codex/host-specific phrasing is adopted.
+
+## Rejected (host/vendor-specific — not adopted)
+
+Vendor-specific tool names, per-host UI affordance details, and single-provider
+prompt phrasings from the source family are **not** adopted here — this contract
+encodes surface invariants, not one vendor's tooling. Per-phase rejects are
+recorded in the roadmap.
+
+## Related
+
+- [`design-artifact-verification`](design-artifact-verification.md) — verification-primitive capability + honest-degrade (design surface).
+- [`design-artifact-lifecycle`](design-artifact-lifecycle.md) — the design surface's own lifecycle.
+- [`host-capability-manifest`](../../src/agent-src/contexts/execution/host-capability-manifest.md) — subagent primitives (cowork/dispatch surface).
+- [`tests/surface-contracts/eval-fixtures.md`](../../tests/surface-contracts/eval-fixtures.md) — the surface-contract eval fixtures.

package/docs/decisions/ADR-061-corpus-grounding-layer.md

@@ -215,3 +215,16 @@ marking. The shared grounding engine is still attributed via
 Implementing roadmap: `road-to-image-brand-typography` (Phase A–D),
 archived 2026-06-16; live-validation + command-surface follow-on tracked in
 its sibling follow-up roadmap.
+
+## Resolution note — retrieval ranking at scale (2026-07-09)
+
+The "no engine fork / no minisearch-class dependency" decision is honoured at
+memory/knowledge retrieval scale by a **hand-rolled BM25 + trigram index**
+(`src/scripts/_lib/lexical_index.ts`, pure Node stdlib) rather than SQLite-FTS5
+or any embedded search engine. It activates at the `lint_knowledge_scale`
+tripwire (>200/type or >500 total files) and replaces the coarse `_score`
+bucket scorer's ranking; measured lift on the retrieval-precision corpus is a
+mean top tie-set of 3.333 → 1.0 with precision@1/@5 unchanged
+(`internal/bench/reports/lexical-ranking.json`). This closes the ADR-061 ↔
+FTS5 open question flagged in `road-to-retrieval-substrate-hardening` (B2): the
+BM25 core ADR-061 sanctioned is realised without an engine dependency.

package/docs/decisions/ADR-115-command-cluster-consolidation-phase-4.md

@@ -85,7 +85,7 @@ not exploit: **nesting `bug-fix` as `bug/fix` keeps the invoked slug
 
 - `docs/contracts/command-clusters.md` — locked table (Phase 4 rows) + the
   new "Bare invocation" section.
-- `agents/roadmaps/road-to-command-structure-optimization.md` — inventory,
+- `agents/roadmaps/archive/road-to-command-structure-optimization.md` — inventory,
   council verdicts, phases.
 - ADR-003 (flat clusters), ADR-041 (controlled verbs), ADR-044 (path-derived
   hyphen slugs).

package/docs/decisions/ADR-116-memory-tripwire-activation-path.md

@@ -38,6 +38,15 @@ apart:
 The whole point of a pre-decided path is that the tripwire firing needs no
 new debate; in this state, firing would have required one.
 
+Additional evidence for the engine swap (2026-07-10, labelled replay of real
+maintainer queries): `_score()`'s raw-substring match has a
+**separator-recall gap** — hyphen/underscore query keys (`ai_council`,
+`roadmap-progress`, `force-push`) score 0 against space-normalized stored
+keys that spaced variants hit at 0.8. A tokenizing engine (FTS5 unicode61 /
+BM25 tokenizer) splits on separators and closes this class structurally;
+see `docs/second-brain-scope.md` § second named limit for the scoped-out
+claim boundary.
+
 ## Decision
 
 1. **One engine: SQLite FTS5 via Node's built-in `node:sqlite`.**

package/docs/distribution/consumer-matrix.md

@@ -0,0 +1,96 @@
+# Consumer Matrix — pack-based release E2E
+
+> **Status:** active · **Owner:** maintainer · **Opened:** 2026-07-10
+>
+> Workflow: [`.github/workflows/consumer-matrix.yml`](../../.github/workflows/consumer-matrix.yml)
+> · Runner: [`src/scripts/consumer_matrix.ts`](../../src/scripts/consumer_matrix.ts)
+> · Tripwire: [`.github/workflows/release-adjacent-health.yml`](../../.github/workflows/release-adjacent-health.yml)
+> · Source roadmap: road-to-proof-under-real-conditions (Phase 1)
+
+The consumer matrix exercises the **published tarball** the way a consumer
+does — pack → fresh global install into an isolated prefix → `init` into a
+fresh project → `doctor` → `conformance` → MCP stdio handshake →
+`hooks:doctor` → projection presence (`validate`) → uninstall — plus an
+upgrade leg (last published minor from the registry → packed tarball →
+`doctor` stays green) and pre-tag dry-runs of every release-adjacent
+workflow.
+
+## Why it exists — the tarball window
+
+Ordinary PRs run source-level matrices; release PRs run shape checks and
+(correctly) skip the source matrices per
+[`release-pr-gating`](../contracts/release-pr-gating.md). That skip is sound
+for the *diff* but blind to the *tarball*: every packaging incident below
+entered `main` on an ordinary PR and manifested only at publish time —
+exactly the window where nothing pack-based ran. The consumer matrix is the
+documented exemption from the release-PR cut surface and runs **on** release
+PRs, plus weekly against registry drift.
+
+## Counterfactual map — five historical failures → the leg that catches each
+
+Recorded per the roadmap's acceptance criterion 1. "Leg" names either a
+`consumer_matrix.ts` leg or a `consumer-matrix.yml` job.
+
+| # | Historical failure | Caught by |
+|---|---|---|
+| 1 | Published tarball missing `src/install/` while published code imported it (two minors; `ERR_MODULE_NOT_FOUND` in global installs of `doctor`/`conformance`) | `fresh-install` leg (`--version` + every subsequent CLI leg runs from the tarball) **and** `publish-dry-run` job's `prepack-check.mjs` import-completeness step |
+| 2 | `tsx` absent from the published package — hooks and TS commands failed for consumers | `fresh-install` + `hooks` legs (installed binary + `hooks:doctor` run from the isolated prefix, no repo `node_modules` to lean on) |
+| 3 | Release workflow failed on missing `go-task` in the CI environment | `publish-dry-run` job replicates the publish path pre-tag; any missing binary in a release-adjacent workflow surfaces on the release PR, not post-tag (see also the runbook note in [`release-pr-gating`](../contracts/release-pr-gating.md)) |
+| 4 | npm publish failed on `npm@latest` → npm 12 requiring Node 22 while the job ran Node 20 | `publish-dry-run` job: asserts `publish-npm.yml` pins an npm **major** (fails on `npm@latest`), then installs that exact pin on both Node 20 and 22 and runs the publish steps sans `npm publish` |
+| 5 | MCP worker deploy red across five consecutive releases, undetected (worker deps installed, root `tsx` missing) | `mcp-worker-dry-run` job (same pack + `wrangler deploy --dry-run` path, pre-tag, including the root `npm ci`) **and** the daily `release-adjacent-health` tripwire (fails loudly when any watched workflow's last completed run is non-success for > 48h) |
+
+**Rule for future failures:** a release incident with no leg in this table
+gets a new leg in the same fix PR — or a recorded reason why it is out of
+scope. The table is the audit trail.
+
+## Triggers
+
+| Trigger | What runs | Why |
+|---|---|---|
+| `pull_request` with `release/*` head | all four jobs | the pre-tag gate — release PRs are the primary trigger |
+| weekly cron (Tue 06:00 UTC) | all four jobs | registry/upstream drift between releases — the class the 48h tripwire alone cannot see pre-release |
+| `workflow_dispatch` | all four jobs | on-demand verification (e.g. after a packaging change) |
+| daily cron 06:30 UTC | `release-adjacent-health` | the > 48h durably-red detector |
+
+## Headless default-scope trap (matrix finding, 2026-07-10)
+
+Building this matrix surfaced a live consumer trap: on a fresh machine,
+headless `agent-config init --tools=… --yes` (no `--scope`) picks "project
+default for backward compatibility" and then hard-fails with
+`--scope=project is reserved for maintainers (ADR-020)` — the bare README
+invocation is red in any non-TTY context (CI, scripts), while the TTY path
+escapes into the browser wizard. `--scope=auto` honors detection and
+completes the documented global-only consumer install (`~/.claude`,
+`~/.cursor`, `~/.codeium/windsurf`, `~/.event4u` lockfile). The matrix
+therefore runs `init --scope=auto --yes` and pins that behaviour; whether
+the backward-compatibility default should flip to `auto` is a product
+decision tracked outside this contract (it changes installer behaviour, not
+the gate). Two adjacent facts the matrix also pins: standalone `doctor` is
+project-manifest-scoped (exit 2 without a project lockfile — expected on a
+global-only install; `conformance` embeds `doctor --ci` and is the health
+probe the matrix asserts), and consumer uninstall is `uninstall --global`.
+
+## Branch-protection note
+
+Marking the four jobs as **required** checks for `release/*` PRs is a
+repository setting (Settings → Branches), not something this repo's files
+can enforce. Until flipped, the jobs still run and fail visibly on the
+release PR; flipping them to required is the intended end state.
+
+## Local run (carve-out verification)
+
+```bash
+npm ci && npm run build
+npx tsx src/scripts/consumer_matrix.ts --json           # all legs
+npx tsx src/scripts/consumer_matrix.ts --skip-registry  # offline: skips the upgrade leg
+```
+
+## See also
+
+- [`release-pr-gating`](../contracts/release-pr-gating.md) — the cut surface
+  this matrix is exempt from, and why.
+- [`public-install-smoke`](public-install-smoke.md) — OS × Node entrypoint
+  matrix (installer correctness); the consumer matrix owns tarball shape +
+  runtime surface instead.
+- [`release-sizing`](../contracts/release-sizing.md) — names this matrix as
+  the floor for every release.

package/docs/featured-skills.md

@@ -1,6 +1,6 @@
 # Featured Skills
 
-A curated subset of the 267 skills. Three tiers, one per primary audience. Full catalog lives in [`dist/agent-src/skills/`](../dist/agent-src/skills/); see also [`docs/catalog.md`](catalog.md) for the complete index and [`docs/featured-commands.md`](featured-commands.md) for command-level highlights.
+A curated subset of the 270 skills. Three tiers, one per primary audience. Full catalog lives in [`dist/agent-src/skills/`](../dist/agent-src/skills/); see also [`docs/catalog.md`](catalog.md) for the complete index and [`docs/featured-commands.md`](featured-commands.md) for command-level highlights.
 
 > **Eval-gated messaging note.** Until `task bench --corpus non-dev` reports `selection_accuracy >= 0.60` (see `road-to-product-adoption.md` Phase 1), this page is documentation, not marketing. The entries below are the candidates the corpus tests against; their description quality is what the eval validates.
 
@@ -92,4 +92,4 @@ task lint-featured-skills
 
 CI runs this in `taskfiles/ci-fast.yml`. Stale entries (renamed / removed skill or command) fail the build. See [`scripts/lint_featured_skills.py`](../src/scripts/lint_featured_skills.py) for the matcher.
 
-→ Browse all 267 skills: [`dist/agent-src/skills/`](../dist/agent-src/skills/) · all 172 commands: [`dist/agent-src/commands/`](../dist/agent-src/commands/)
+→ Browse all 270 skills: [`dist/agent-src/skills/`](../dist/agent-src/skills/) · all 177 commands: [`dist/agent-src/commands/`](../dist/agent-src/commands/)

package/docs/getting-started-by-role.md

@@ -2,7 +2,7 @@
 
 > Pick the entry that matches what you do day-to-day. Each section names the three skills you will reach for first and shows whether MCP (no terminal) or CLI (terminal) is the simpler install path for that role.
 
-`agent-config` ships 267 skills, 100 governed rules, and 172 commands. You do not need all of them. Each role below filters to the slice that pays back in week one; the rest stays available and shows up on demand when a task references it.
+`agent-config` ships 270 skills, 103 governed rules, and 177 commands. You do not need all of them. Each role below filters to the slice that pays back in week one; the rest stays available and shows up on demand when a task references it.
 
 > **Taglines at a glance →** [`docs/role-experiences.md`](role-experiences.md) — the one-line pitch per role experience, in one table.
 

package/docs/getting-started.md

@@ -134,7 +134,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 100 rules. No configuration needed.
+This is enforced automatically by 103 rules. No configuration needed.
 
 ---
 
@@ -174,7 +174,7 @@ Your agent now understands slash commands:
 | `/fix quality` | Run and fix all quality checks |
 | `/chat-history import` | Pull a prior session into the current chat (resume) |
 
-→ [Browse all 172 active commands](../dist/agent-src/commands/)
+→ [Browse all 177 active commands](../dist/agent-src/commands/)
 
 ---
 

package/docs/governance-advantage.md

@@ -33,7 +33,7 @@ the host lacks (a static host gives it no runtime attention guarantee, but a
 runtime-only system gives it nothing at all here). A runtime-only system contributes *nothing* on these hosts.
 
 ### 2. Intent routing, not a 500-artefact dump
-A prompt does not load all 267 skills. `dist/router.json` (96 routed rules, intent →
+A prompt does not load all 270 skills. `dist/router.json` (99 routed rules, intent →
 skill, keyword/phrase/path triggers) carries the right skill on intent. The
 governance value is *selection discipline* — the host gets the relevant rule
 set, not the whole catalogue as context ballast.

package/docs/guidelines/agent-infra/asking-and-brevity-examples.md

@@ -106,6 +106,33 @@ that matters for the claim. When in doubt, treat it as fresh-lookup — the
 cost of one extra search is far lower than a stale claim stated with
 confidence.
 
+### No duration estimates (Iron Law 2 family)
+
+An LLM has no wall-clock and no latency training signal, so a duration estimate
+is a fabricated fact wearing a number:
+
+- Never predict how long **the agent's own work** will take ("this refactor is
+  ~2 hours", "I'll have it in a few minutes").
+- Never predict how long **the user's work** will take ("this is a 2–3 week
+  project", "should take you an afternoon").
+- Instead: break the work into **actionable steps** and let the user judge
+  timing against their own context — they have the clock, the agent does not.
+
+A step list is honest ("A → B → C, C depends on B"); a schedule is invention.
+
+### Never cite the rule as the reason
+
+When declining or constraining an action, give the **actual, substantive
+reason** — never "my rules / guidelines / instructions require X":
+
+- ❌ "I can't do that, my guidelines don't allow it." / "A rule requires me to ask first."
+- ✅ "Sending this would post publicly and can't be undone, so confirm the recipient first." / "This edits a production branch — I need your go-ahead."
+
+Appealing to a hidden rule (a) replaces real reasoning the user can evaluate,
+and (b) widens the prompt-extraction surface (it advertises that hidden
+instructions exist and invites probing them). State the real-world consequence,
+not the rule's existence.
+
 ## Direct-answers — failure modes the user will call out
 
 Companion to `direct-answers` § Failure modes. The rule lists the

package/docs/guidelines/agent-infra/emphasis-budget.md

@@ -0,0 +1,45 @@
+# Emphasis budget
+
+Authoring guideline. **This is a review-time discipline, NOT a merge-blocking
+linter** — there is no CI gate; PR review owns the judgment.
+
+## The principle
+
+Emphasis is a currency, and inflation debases it. Reserve the loud channels —
+ALL-CAPS, `## Iron Law` fences, spaced repetition of the same imperative — for
+**asymmetric, irreversible harm**: data loss, credential/secret exposure, a
+safety floor, a legal/compliance breach. When everything shouts, nothing does:
+an over-emphasized doc trains the reader to skim past the caps, so the one caps
+line that guards a `DROP TABLE` loses its signal.
+
+## The discipline
+
+When you add emphasis, be able to answer — in the artifact or the PR — two
+questions:
+
+1. **What specific harm does this prevent?** Name it (not "this is
+   important" — *what* goes wrong, to *whom*, how badly).
+2. **Why is post-hoc correction insufficient?** Emphasis is justified when the
+   harm is irreversible or asymmetric (a wrong send/delete/charge can't be
+   taken back). If a normal-weight sentence + a later fix would do, use normal
+   weight.
+
+If you cannot answer both, down-weight to plain prose.
+
+## Why not a linter
+
+A mechanical caps-quota is unenforceable — semantic substitution ("Critically:
+never…", bold, block quotes) defeats a caps count while keeping the shout — and
+it blocks ready work on a cosmetic metric. The Iron-Law *count* is also a
+denominator artifact: most existing Iron Laws already guard data-loss /
+credential / safety domains, so the raw number is not evidence of inflation.
+Judgment at review time, keyed to the harm-asymmetry test above, is the control.
+
+## Overlap (why a separate guideline)
+
+Distinct from [`preservation-guard`](../../../src/rules/preservation-guard.md)
+(preserve existing emphasis through a transform — this governs *adding* it),
+[`size-enforcement`](../../../src/rules/size-enforcement.md) (line budgets, not
+emphasis weight), and [`token-budget-discipline`](../../../src/rules/token-budget-discipline.md)
+(load cost, not signal-to-noise). None owns the emphasis-rationing judgment;
+this guideline does.