@event4u/agent-config 8.9.0 → 8.10.0

package/docs/contracts/design-artifact-lifecycle.md

@@ -0,0 +1,93 @@
+# Design-Artifact Lifecycle Contract
+
+Phase 1 of `road-to-design-artifact-fidelity`.
+One lifecycle every design/artifact skill points at, so "context before taste"
+and "rendered artifact before claim" are a shared workflow, not per-skill folklore.
+Design work is a **pipeline** — understand, inspect, plan, build, verify, hand
+off — not a bag of styling tips.
+
+This contract is advisory (staged-rollout stage 1 per
+[`design-artifact-verification` § Staged rollout](design-artifact-verification.md#staged-rollout)):
+skills reference these stages; nothing here is a default gate yet.
+
+## The lifecycle
+
+Six stages. Every design task runs the stages its branch (below) selects — never
+skips straight to "build".
+
+| # | Stage | What it does | Exercised by fixtures |
+|---|---|---|---|
+| 1 | **Understand** | Medium, audience, fidelity, target host. What *kind* of artifact (screen, deck, doc, component, prototype), for whom, at what polish, verifiable how (per the capability table). | `daf-no-context` |
+| 2 | **Inspect** | Read the existing design system + code **before** styling — code over screenshots when available; copy the visual vocabulary; confirm assets exist. Ask when no context is attached. | `daf-inaccessible-design-system`, `daf-missing-asset` |
+| 3 | **Plan** | Define the visual system + the variation plan: which axis varies, how many options, labelled. No unrequested variations. | `daf-requested-variations`, `daf-unwanted-variations` |
+| 4 | **Build** | Produce the artifact against the system. Surgical on edits; no invented filler (§ Design constraints). | `daf-edit-preservation` |
+| 5 | **Verify** | Prove the rendered artifact — render / load / responsive / export — via a primitive the host has, else caveat honestly (never fake). | `daf-overlapping-text`, `daf-mobile-fit`, `daf-export-readback-failure` |
+| 6 | **Handoff** | Brief, honest handoff: what was built, what is verified vs caveated, implementation intent, preserved comment anchors. | `daf-export-readback-failure` |
+
+Fixtures are defined in [`tests/design-artifacts/eval-fixtures.md`](../../tests/design-artifacts/eval-fixtures.md);
+the ids are stable so skill edits in later phases can prove the stage is operational.
+
+## Skill → stage map
+
+Skills own the *depth* at each stage; the lifecycle owns the *order*. A skill
+cites the stage(s) it serves instead of re-describing the workflow.
+
+| Stage | Primary skills |
+|---|---|
+| Understand | [`fe-design`](../../src/skills/fe-design/SKILL.md), [`design-review`](../../src/skills/design-review/SKILL.md) |
+| Inspect | [`existing-ui-audit`](../../src/skills/existing-ui-audit/SKILL.md), [`brand-audit`](../../src/skills/brand-audit/SKILL.md), [`brand-to-tokens`](../../src/skills/brand-to-tokens/SKILL.md) |
+| Plan | [`fe-design`](../../src/skills/fe-design/SKILL.md), [`ui-component-architect`](../../src/skills/ui-component-architect/SKILL.md) |
+| Build | [`ui-component-architect`](../../src/skills/ui-component-architect/SKILL.md), [`html-deck`](../../src/skills/html-deck/SKILL.md) (decks), [`doc-coauthoring`](../../src/skills/doc-coauthoring/SKILL.md) (documents) |
+| Verify | [`playwright-testing`](../../src/skills/playwright-testing/SKILL.md), [`design-review`](../../src/skills/design-review/SKILL.md), [`markitdown`](../../src/skills/markitdown/SKILL.md) (export readback) |
+| Handoff | [`design-review`](../../src/skills/design-review/SKILL.md), [`design-system-capture`](../../src/skills/design-system-capture/SKILL.md) |
+
+(The roadmap's conceptual "presentations" / "PDF / document" skills map to the
+real `html-deck`, `markitdown`, and `doc-coauthoring` skills above.)
+
+## Branch rules
+
+The lifecycle is not linear for every task. Pick the branch first; it selects
+which stages run and which fixtures gate it (each branch has ≥1 fixture).
+
+| Branch | Trigger | Stages run | Gating fixtures |
+|---|---|---|---|
+| **New design** | Greenfield artifact, no prior version | 1→2→3→4→5→6 (full) | `daf-no-context`, `daf-inaccessible-design-system`, `daf-requested-variations` |
+| **Targeted edit** | Change one named thing in an existing artifact | 2 (light) → 4 → 5 | `daf-edit-preservation`, `daf-unwanted-variations` |
+| **Iteration** | Refine an existing artifact across a version bump | 1 (delta) → 3 → 4 → 5; **preserve the prior version** on a major revision | `daf-requested-variations` |
+| **Design-system extraction** | Derive tokens/components from existing artifacts | 2 (deep) → 6 | `daf-inaccessible-design-system` |
+| **Handoff to production code** | Turn a design into implementation intent | 5 → 6 | `daf-overlapping-text`, `daf-mobile-fit`, `daf-export-readback-failure` |
+
+**Targeted edit stays surgical** — no redesign of neighbours, no reformatting of
+untouched regions, comment anchors preserved (the `daf-edit-preservation`
+contract; mirrors [`minimal-safe-diff`](../../src/rules/minimal-safe-diff.md) for
+visual work). **Iteration preserves the prior version** on a major revision so a
+regression is recoverable.
+
+## Design constraints — do not invent filler
+
+```
+EMPTY SPACE IS A COMPOSITION PROBLEM, NOT PERMISSION TO ADD MATERIAL.
+NEVER INVENT FAKE SECTIONS, FAKE METRICS, LOREM-STYLE COPY, OR STOCK
+DECORATION TO FILL A LAYOUT. ASK BEFORE ADDING MATERIAL THAT ISN'T IN THE BRIEF.
+```
+
+- **Do not invent filler.** A sparse layout is solved with composition
+  (spacing, scale, hierarchy), not with fabricated content. Fake KPIs, invented
+  testimonials, placeholder charts with made-up numbers, and decorative
+  stock-like imagery are content the user did not ask for and cannot trust.
+- **Ask before adding material.** If the artifact genuinely needs content that
+  isn't supplied (a section the brief implies but doesn't provide), surface the
+  gap and ask — do not silently manufacture it. Realistic placeholder clearly
+  labelled as placeholder is acceptable when the user asked for a mock; passing
+  invented data off as real is not.
+
+This is the design-surface instance of the no-invented-facts discipline
+([`direct-answers`](../../src/rules/direct-answers.md) Iron Law 2) and the
+no-placeholder-slop rule ([`output-discipline`](../../src/rules/output-discipline.md)).
+
+## Related
+
+- [`design-artifact-verification`](design-artifact-verification.md) — the Phase-0 host-capability & degrade contract this lifecycle's Verify stage runs against.
+- [`tests/design-artifacts/eval-fixtures.md`](../../tests/design-artifacts/eval-fixtures.md) — the nine fixtures the stages + branches gate on.
+- [`design-fidelity`](../../src/rules/design-fidelity.md) — the provided-design-is-the-spec rule the Inspect stage enforces.
+- [`fe-design`](../../src/skills/fe-design/SKILL.md), [`existing-ui-audit`](../../src/skills/existing-ui-audit/SKILL.md), [`design-review`](../../src/skills/design-review/SKILL.md), [`ui-component-architect`](../../src/skills/ui-component-architect/SKILL.md) — the design skills that cite these stages.

package/docs/contracts/design-artifact-verification.md

@@ -1,6 +1,6 @@
 # Design-Artifact Verification — Host-Capability & Degrade Contract
 
-Phase 0 substrate for [`road-to-design-artifact-fidelity`](../../agents/roadmaps/road-to-design-artifact-fidelity.md).
+Phase 0 substrate for `road-to-design-artifact-fidelity`.
 Design work is only production-grade if the agent **verifies the rendered
 artifact** — but a verification step the host cannot run must degrade honestly,
 never block the work or fake a green check.
@@ -78,6 +78,35 @@ When the needed primitive is `❌` (or a `⚠️` probe fails):
    console errors") for a check that did not run — that is an invented fact
    ([`direct-answers`](../../src/rules/direct-answers.md) Iron Law 2).
 
+## Verification checklist
+
+Run before claiming a design artifact done. Each step is gated by the primitive
+it needs — a step whose primitive is absent is **skipped with a caveat**, never
+faked (§ Honest-degrade). "Looks good" is not a verification result.
+
+1. **Open the artifact** (`local_browser` / `playwright` / `pdf_render` / `doc_export`) — it opens and paints; a static-only host inspects the source instead.
+2. **Console / load errors** (`console_inspect`) — no runtime errors or failed loads on open.
+3. **Desktop + mobile viewport** (`screenshot`) — inspect a desktop width and ~375px; no overflow / clipping.
+4. **Text fit / no overlap** (`screenshot`, degrade `static_inspect`) — no collisions or truncation at the target breakpoints.
+5. **Referenced assets decode** (`image_decode`) — every referenced image / font resolves and decodes (no broken `src`).
+6. **Key interaction state** (`playwright`) — the primary interaction (open / submit / toggle) behaves; description-only where unavailable.
+7. **Capture evidence only when supported** (`screenshot`) — attach a screenshot / diff when the host can; otherwise cite what was statically checked.
+
+**Completion contract.** A design task with render capability present cannot
+claim "done" without at least steps 1–5 as evidence. Where capability is absent
+(no browser / renderer), report that plainly (§ Rollback language) and keep the
+completion claim scoped to what was actually checked. The checklist is exercised
+by the verification golden tasks in
+[`eval-fixtures.md`](../../tests/design-artifacts/eval-fixtures.md)
+(`daf-nonblank-canvas`, `daf-mobile-fit`, `daf-missing-asset`,
+`daf-overlapping-text`, `daf-broken-interaction`, `daf-export-readback-failure`).
+
+Skills wire this in: [`playwright-testing`](../../src/skills/playwright-testing/SKILL.md)
+runs it when a browser primitive is present; [`design-review`](../../src/skills/design-review/SKILL.md)
+gates its verdict on it; static decks / documents use the deck / PDF / document
+verification path ([`html-deck`](../../src/skills/html-deck/SKILL.md),
+[`markitdown`](../../src/skills/markitdown/SKILL.md) readback).
+
 ## Staged rollout
 
 Design-artifact fidelity rolls out in three stages so nothing becomes a hard

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-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/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, 102 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 102 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` (98 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/proof.md

@@ -27,7 +27,7 @@ evidence pointer, or `task check-claims` fails the build.
 | Claim | Kind | Evidence | Resolves |
 |---|---|---|---|
 | The release process is documented as an inheritable runbook + succession doc, and the project's bus-factor (trailing-90-day distinct human reviewers) is tracked and reported truthfully — currently 1, not implied to be more. | qual | `docs/succession.md#trailing 90 days` | ✅ |
-| 172 commands. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| 177 commands. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
 | The retrieval economy cuts always-loaded context tokens ~65.6% measured against the FULL always-loaded projection — 98,529 → 33,897 tokens (eager rule load + skill/command descriptions + MCP schemas, thin-flipped). Method: `agent-config benchmark` over the pinned token baseline; the baseline is the honest "what the user pays if everything loads eagerly", NOT a synthetic full-corpus strawman (council Q4). | quant | `internal/bench/reports/token-baseline.json#eager_rule_load` | ✅ |
 | On a weak host (claude-haiku-4-5) the package produces a significant, placebo-controlled discipline lift on scope/downstream traps; on a strong host the same measurement is a published null — the package transplants discipline a weak model lacks, not model intelligence. | quant | `docs/benchmark.md#weak-host-specific` | ✅ |
 | The non-coding domain skills (finance/founder/ops/content) are forged on TS/PHP and labeled unvalidated until they pass a sourced domain-truth fixture; no public prose implies proven domain correctness, and the validated count is CI-ratcheted. | qual | `src/scripts/domain_soundness_status.ts#checkRatchet` | ✅ |
@@ -36,11 +36,11 @@ evidence pointer, or `task check-claims` fails the build.
 | Behavioural-eval coverage is measured per tier and CI-ratcheted so it can only rise; the current coverage and its gap are published, never implied as "264 evaluated skills". | qual | `src/scripts/skill_eval_coverage.ts#checkRatchet` | ✅ |
 | A hand-rolled, dependency-free BM25 + trigram lexical index resolves the "recalls but does not rank" gap: on the retrieval-precision corpus (9 keyword-overlapping-confuser tasks) it drives the mean top tie-set from 3.333 (the `_score` bucket scorer) to 1.0 — every needed decision uniquely top-ranked — with precision@1 and precision@5 unchanged at 1.0. Method: deterministic, model-free re-ranking of the SAME retrieved entry set; both scorers measured over the identical store via `measure_lexical_ranking.ts`. | quant | `internal/bench/reports/lexical-ranking.json` | ✅ |
 | The whole layer is compiled into host agents with zero runtime daemon. | qual | `docs/contracts/no-runtime-boundary.md#file-first, no-runtime suite` | ✅ |
-| 102 governed rules. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| 103 governed rules. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
 | On a deterministic multi-session recall corpus, the memory substrate produces a measured, placebo-controlled recall lift — memory-on 27/27 vs no-memory 10/27 and vs equal-byte placebo 9/27 (claude-haiku-4-5, n=9 tasks x 3 seeds, sign test p=0.031 for BOTH pairings). Scoped honestly: this is the context-value upper bound (perfect retrieval on a one-fact-per-task corpus), not retrieval precision under a large store. | quant | `internal/bench/reports/second-brain-delta.json` | ✅ |
 | Removing the perfect-retrieval assumption, the substrate's REAL keyword retrieval recalls the needed decision into the top-5 under keyword-overlapping confusers (precision@5 9/9) and the model disambiguates it from the co-injected confusers — retrieval-on 27/27 vs no-memory 5/27 and vs equal-count placebo 5/27 (claude-haiku-4-5, 9 tasks x 3 seeds, sign test p=0.008 both). Named limit: retrieval RECALLS but does not RANK (mean tie-set 3.3, ties broken by store order, not relevance) — the discrimination gap that motivates the SQLite-FTS5 activation path (ADR-116) at larger scale. | quant | `internal/bench/reports/second-brain-retrieval.json` | ✅ |
 | Every artifact the package ships — source AND the condensed projection that reaches consumers — is machine-scanned in CI for hidden-Unicode, mixed-script-confusable, and instruction-smuggling payloads (the rules-file-backdoor class); a finding blocks the release before `npm publish`, not just the merge. | qual | `.github/workflows/publish-npm.yml#lint_agent_security` | ✅ |
-| 267 skills (README hero + feature list). | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| 270 skills (README hero + feature list). | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
 | Removes only its own keys from a shared host config (matched by JSON-pointer + SHA-256), never a neighbour tool's entries. | qual | `docs/contracts/install-layout.md#JSON-pointer` | ✅ |
 
 **16 backed claim(s)** — all evidence pointers resolve in CI.
@@ -78,7 +78,7 @@ deliberately, not overnight.
 runway, RICE, incident command, messaging), but the skills are forged on
 TS/PHP — "promising, not proven" off those stacks. A disclaimer floor
 bounds *liability*, not *correctness*: a skill can be format-correct,
-disclaimered, and still embed a wrong domain assumption. Today **5 of 20**
+disclaimered, and still embed a wrong domain assumption. Today **9 of 20**
 default-surface domain skills carry a sourced `domain-truth` fixture
 (`./scripts-run src/scripts/domain_soundness_status`); the rest are labeled
 `unvalidated` and the validated count is CI-ratcheted. The fixtures landed

package/docs/release-runbook.md

@@ -37,6 +37,9 @@ the **workflow_dispatch** on `release.yml` (inputs: `bump`, `version`,
       to recover a partial run — see § 5).
 - [ ] You have read [`succession.md`](succession.md) if any secret-gated
       downstream (npm publish, cloud deploy) must succeed this release.
+- [ ] The release satisfies [`release-sizing.md`](contracts/release-sizing.md) —
+      one primary product goal, and a `Rollback:` line for every new /
+      substantially reworked subsystem (gate: `src/scripts/lint_changelog_rollback.ts`).
 
 ## 2. The pipeline — what `release.ts` does (9 steps)