@event4u/agent-config 9.8.0 → 9.9.0

package/docs/contracts/prelaunch-diagnostics.md

@@ -1,151 +0,0 @@
-# Pre-Launch Diagnostics — finding IDs, epistemics, regression gate
-
-> Contract for the consumer-facing launch diagnostic
-> (road-to-ecosystem-harvest-prelaunch-diagnostics, Source L — a
-> production-readiness diagnostic skill; provenance in the harvest index).
-> The consumer-side sibling of the suite's own claims-ledger: a "ready"
-> verdict cannot be reached by assertion.
->
-> Schema: [`prelaunch-report.schema.json`](../../src/scripts/schemas/prelaunch-report.schema.json) ·
-> Area vocabulary: [`prelaunch-areas.yml`](../../src/config/prelaunch-areas.yml) ·
-> Tooling: [`prelaunch_diagnostics.ts`](../../src/scripts/prelaunch_diagnostics.ts) ·
-> Skill surface: [`launch-readiness`](../../src/skills/launch-readiness/SKILL.md).
-
-## 1 — Finding-ID grammar (immutable, diff-stable)
-
-```
-AC-<AREA>-NNN        e.g. AC-AUTH-003, AC-RBK-001
-```
-
-- `<AREA>` — the uppercase code of a coverage area from
-  [`prelaunch-areas.yml`](../../src/config/prelaunch-areas.yml). The vocabulary
-  is **append-only**: codes are never renamed or re-used.
-- `NNN` — zero-padded, monotonically assigned per area, **never re-assigned**.
-  A finding that is retitled, re-scoped, or resolved keeps its ID forever; a
-  genuinely new problem gets the next number. Resolved findings stay in the
-  report with a flipped `status` — the entry never disappears, so baselines
-  diff cleanly across months.
-- The **ID is the diff key**. Titles, evidence, and severity are mutable
-  metadata; two runs are compared by ID set + per-ID state, never by prose.
-
-## 2 — Epistemics (Pass needs evidence; Unknown ≠ Pass)
-
-Every coverage area carries exactly one state:
-
-| State | Meaning | Requirement |
-|---|---|---|
-| `pass` | Diagnosed clean | **Cited evidence required** — file:line, command output, run URL. A pass without evidence fails validation: that is assertion, not diagnosis. |
-| `finding` | At least one open finding | The finding IDs live in `findings[]`. |
-| `unknown` | Not diagnosed | The honest default. **Absence of findings is `unknown`, never an automatic `pass`.** An area missing from the report entirely is `unknown` by definition. |
-| `not-applicable` | Does not exist on this surface | **Reason required** ("no DB → no migrations"). |
-
-Verdict rule (the launch gate):
-
-```
-ANY OPEN P0 FINDING → NOT READY, REGARDLESS OF EVERY OTHER AREA.
-ANY OPEN P1, OR A launch_gate AREA NOT AT pass/not-applicable → NOT READY.
-READY IS THE RESIDUAL STATE, NEVER THE DEFAULT.
-```
-
-`launch_gate: true` areas (auth, migrations, secrets, rollback) block the
-verdict while `unknown`; non-gate areas (observability, agent-governance)
-surface as unknowns + questions but do not block alone.
-
-## 3 — Coverage backbone
-
-The area vocabulary is deliberately pruned to the stacks this suite targets:
-**auth · migrations · secrets · observability · rollback · agent-governance**.
-It is not a generic compliance matrix — new areas enter by appending to
-`prelaunch-areas.yml` with a maintainer-reviewed `launch_gate` decision.
-
-Every report may carry a `questions` list — **questions that would change the
-diagnosis** ("is the admin panel exposed on the same origin?"). Questions are
-the actionable rendering of unknowns; the next run should convert them into
-evidence or findings.
-
-## 4 — Regression gate (findings diff)
-
-`prelaunch_diagnostics.ts diff <baseline.json> <current.json>` compares two
-reports **by ID**:
-
-- **new** — ID in current, not in baseline.
-- **resolved** — open in baseline, `fixed` in current.
-- **regressed** — a `launch_gate` area that was `pass` in the baseline and is
-  `finding`/`unknown` in current (Pass→Finding flip).
-- **retitled findings do not appear in the diff** — the ID survives the
-  rename (acceptance-tested).
-
-`--ci` mode exits non-zero when the diff contains a **new open P0/P1** or a
-**Pass→Finding flip in a launch-gate area** — the consumer-side sibling of the
-suite's claims-ledger CI. Everything else (new P2/P3, resolved findings,
-question churn) reports informationally and exits 0.
-
-## 5 — Suppression (evidence-backed, never silent)
-
-A consumer may suppress a finding via the project-local suppression file
-`agents/settings/prelaunch-suppressions.yml`:
-
-```yaml
-schema_version: prelaunch-suppressions-v1
-suppressions:
-  - id: AC-OBS-002
-    reason: "Dashboards land with the Q3 observability epic; alerting for the launch path exists."
-    evidence: "agents/evidence/prelaunch/obs-alerting.png"
-```
-
-- A finding with `status: suppressed-with-evidence` MUST have a matching
-  suppression entry carrying **both** `reason` and `evidence` — validation
-  fails otherwise.
-- Suppressed findings are excluded from the `--ci` triggers but **render in a
-  collapsible "suppressed" section** of the report output — the same
-  transparency contract as the review cluster's dropped-false-positives list.
-  Suppression hides nothing; it moves the item behind a fold with its receipt.
-- Suppressing a P0 does not restore a ready verdict — P0 caps the verdict
-  regardless (§ 2).
-
-## 6 — Consumer recipe (opt-in CI gating)
-
-1. Run the diagnostic (via `launch-readiness` § epistemics) and save the
-   report to `agents/evidence/prelaunch/baseline.json`. Commit it.
-2. Before a launch, produce a fresh `current.json` and run
-   `prelaunch_diagnostics.ts diff baseline.json current.json --ci` in the
-   pipeline — red on a new P0/P1 or a launch-gate Pass→Finding flip.
-3. After the launch settles, promote `current.json` to the new committed
-   baseline (a reviewed diff, like any lockfile bump).
-
-## 7 — Fix-loop discipline (Phase 3)
-
-- Rank open findings by severity, then by launch-gate membership.
-- Propose the **safest first approval batch** — explicitly the first *safe*
-  batch (reversible, small blast radius), not the full backlog. Approval is
-  the user's; the diagnostic never self-authorizes fixes
-  ([`autonomous-execution`](../../src/rules/autonomous-execution.md) and the
-  reversibility floor govern, unrestated).
-- Per-finding status vocabulary (schema-enforced): `open · fixed ·
-  accepted-risk · deferred-with-reason · suppressed-with-evidence ·
-  not-applicable` — everything except open/fixed carries a `reason`.
-- **Rescore whenever evidence changes** — a fix, a new probe, or an answered
-  question re-runs the affected area, never the memory of it.
-
-## 8 — Read-only guarantee
-
-The diagnostic **never mutates a consumer project**: the tooling reads
-reports and writes nothing outside its own output. Fixes flow through the
-normal approval-gated engines, not through this contract.
-
-## 9 — Score: council-locked (do not add)
-
-The pass-1 council **dropped the 0–100 readiness score** (gameable false
-precision). A severity-capped, never-published internal-ordering variant is
-**surfaced for council re-evaluation in the roadmap's revisit note — not
-adopted**. Until that revisit resolves: no numeric score field in the schema,
-no score in any rendered output, no score in CI messages. The ID scheme,
-epistemics, diff gate, and suppression above stand on their own.
-
-## See also
-
-- [`launch-readiness`](../../src/skills/launch-readiness/SKILL.md) — the skill
-  surface that produces the report.
-- [`docs/proof.md`](../proof.md) — the suite-side claims-ledger this mirrors.
-- `road-to-ecosystem-harvest-reliability-measurement` (archived) — measures the
-  *suite itself*; this contract measures the *consumer's launch surface*.

package/docs/contracts/profile-system.md

@@ -1,167 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-14
----
-
-# Profile System — Contract
-
-> **Status:** beta · **Owner:** package maintainer · **Last reviewed:** 2026-05-16
->
-> Schema and semantics for the **Profile** axis introduced in step-15
-> Phase 1 item 1. Profile answers *who is the user?* — audience
-> taxonomy that selects the default skill/command surface, README
-> entry-paragraph, and persona pre-selection. Boundary against
-> `preset.id`, `pack.id`, and `rule_loading_tier`:
-> [`ADR-010`](../decisions/ADR-010-profile-pack-preset-boundary.md).
-
-## Decision
-
-A **profile** declares the user's audience identity. Six seed profiles
-ship; users can declare their own under
-`.agent-src.uncondensed/profiles/<id>.yml`.
-
-| `profile.id` | Audience | README entry-paragraph | Default `preset.id` |
-|---|---|---|---|
-| `founder` | Solo / early-stage founder; wears every hat | "Ship the company, not the codebase" | `fast` |
-| `developer` | IC engineer; primary day-to-day user today | "Pair with a senior reviewer that never sleeps" | `balanced` |
-| `content_creator` | Writers, ghostwriters, marketers | "Your voice, my hands" | `balanced` |
-| `agency` | Multi-client delivery shop | "Same playbook across every client repo" | `strict` |
-| `finance` | CFO / fractional finance / FP&A | "Forecasts and memos with the receipts attached" | `strict` |
-| `ops` | RevOps, support, SRE-adjacent | "Procedures that get followed, not skipped" | `strict` |
-
-The seed set is **fixed for v2.x**. Adding a seventh profile requires
-an ADR — the contract surface that ships in the wizard
-(`/onboard` role-selection) treats this set as exhaustive.
-
-## Profile shape
-
-```yaml
-profile:
-  id: developer
-  packs: [engineering-base]              # base capability packs (scoped projection)
-  audience:
-    label: "IC engineer"
-    readme_anchor: "developer"          # selects README first-screen block
-  defaults:
-    preset_id: balanced                  # may be overridden by .agent-settings.yml
-    personas: [reviewer, security]       # pre-selected persona ids
-    skills_hint: [developer-like-execution, verify-before-complete, minimal-safe-diff]
-  surface:
-    commands_hint: [work, implement-ticket, review-changes, fix]
-    docs_first_pointer: "docs/getting-started-by-role.md#developer"
-```
-
-### `packs` — base capability packs (6.0.0-B)
-
-`profile.packs` is the **base capability-pack set** the projector resolves
-when `projection.mode: scoped` (ADR-040). At projection time the selected set
-is `profile.packs ∪ runtime.active_packs` (the session overlay), expanded over
-the `requires` graph ([`capability-packs.md`](capability-packs.md)); the
-overlay can only **widen**, so `packs` is the floor of the default surface.
-
-**`skills_hint` is a guarantee, not a teaser.** Every skill named in a
-profile's `skills_hint` MUST resolve from that profile's `packs` (the
-self-sufficient contract). A profile must not advertise a skill its base packs
-hide. The six seed profiles satisfy this; the budget lint in 6.0.0-C will
-enforce it in CI.
-
-> Resolved by AI council (claude-sonnet-4-5 + gpt-4o, 2026-06-03): Option A
-> (self-sufficient base packs) for 6.0.0-B — no new mechanism, opt-in, default
-> stays `legacy-all`. Deferred to 6.0.0-C: a `skills_discoverable` field,
-> reactive just-in-time pack activation, the per-pack budget lint, and
-> telemetry.
-
-Per [ADR-010](../decisions/ADR-010-profile-pack-preset-boundary.md), a
-profile **MAY** set `defaults.preset_id` but **MAY NOT** set any
-preset-owned knob directly. The lint task (`task lint-config-schema`)
-enforces this.
-
-## Loader contract
-
-The Phase 1 loader lives at `scripts/config/profiles.py`. Resolution
-chain (last writer wins):
-
-1. `pack.profile_id` (if pack active) → `profile.id`.
-2. `.agent-settings.yml` top-level `profile:` block → `profile.id`
-   and any user overrides for `audience` / `defaults` / `surface`.
-3. Environment variable `AGENT_CONFIG_PROFILE_ID` → `profile.id`.
-4. Runtime CLI flag `--profile=<id>` → `profile.id`, single session.
-
-If no profile resolves, the loader **does not pick a default
-silently** — it falls back to `developer` only when
-`.agent-settings.yml` is missing entirely (fresh install before
-`/onboard`). With a settings file present but no `profile:` block,
-the loader raises a structured warning pointing to `/onboard`.
-
-```
-RATIONALE: a silent default would hide the "I never picked an audience"
-state from the wizard, breaking the council v3 observation that audience
-choice must be a deliberate act of the user, not an agent inference.
-```
-
-## Resolution outcome
-
-After the loader runs, the session has:
-
-```python
-{
-  "id": "developer",
-  "packs": ["engineering-base"],
-  "audience": {"label": "IC engineer", "readme_anchor": "developer"},
-  "preset_id": "balanced",
-  "personas": ["reviewer", "security"],
-  "skills_hint": ["developer-like-execution", ...],
-  "commands_hint": ["work", "implement-ticket", ...],
-  "source": "user-settings | env | runtime | pack | default",
-}
-```
-
-The `source` field is mandatory and feeds the
-`/agent-config explain`
-command (Phase 1 item 3).
-
-## User-defined profiles
-
-A consumer project MAY ship a custom profile under
-`.agent-src.uncondensed/profiles/<id>.yml`. Constraints:
-
-- `id` MUST be unique across seed + user-defined profiles.
-- Shape MUST match the seed contract above (audience / defaults / surface).
-- `defaults.preset_id` MUST reference an existing preset
-  ([`config-presets.md`](config-presets.md)).
-- The lint task hard-fails on schema violations.
-
-User-defined profiles do **not** require an ADR — they are project-local.
-Only changes to the **seed set** require an ADR.
-
-## Drift detection
-
-`task lint-config-schema` (added in Phase 1) hard-fails when:
-
-- A profile YAML names a preset-owned knob (cost cap, autonomy,
-  confidence, risk).
-- A profile YAML references a non-existent `preset_id`.
-- The seed-profile count diverges from this contract's table.
-- `defaults.personas` references a persona id that does not exist
-  under `.agent-src.uncondensed/personas/`.
-
-## Non-goals
-
-- This contract does **not** define preset knobs. See
-  [`config-presets.md`](config-presets.md).
-- It declares **base capability packs** (`profile.packs`, 6.0.0-B) for scoped
-  projection, but does **not** define workflow-pack *bundles*. See
-  [`capability-packs.md`](capability-packs.md) (capability layer) and
-  `workflow-packs.md` (bundle layer).
-- It does **not** override `rule_loading_tier`. The rule-tier loader keeps
-  its independent axis per
-  [`cost-profile-defaults.md`](cost-profile-defaults.md).
-- It does **not** ship a UI. Profile selection happens in `/onboard`
-  (step-15 Phase 1 item 2).
-
-## See also
-
-- [`ADR-010`](../decisions/ADR-010-profile-pack-preset-boundary.md) — axis boundary.
-- [`config-presets.md`](config-presets.md) — preset knobs.
-- [`cost-profile-defaults.md`](cost-profile-defaults.md) — rule-tier axis (orthogonal).
-- `step-15-product-refinement` — Phase 1 item 1.

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

@@ -1,83 +0,0 @@
----
-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/release-pr-gating.md

@@ -1,151 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-09-04
----
-
-# Release-PR Gating Contract
-
-> **Status:** active · **Owner:** maintainer (`src/scripts/release.ts`) · **Opened:** 2026-05-26
->
-> Release PRs are opened by either entry point into `release.ts`: `task
-> release` (interactive, local) or `.github/workflows/release.yml` (the
-> `release`-labeled-PR CI path, author `github-actions[bot]`) — see
-> [`ADR-113`](../decisions/ADR-113-ci-native-release-label-trigger.md).
-> This contract's shape checks are author-agnostic by design; both entry
-> points produce the identical PR shape below.
->
-> Source: `road-to-optimized-ci-and-release-gates.md` Phase A Step 1. Measured
-> baseline (`gh run list --branch main --limit 50`): `Public Install Smoke`
-> avg **413 s** (3-OS × 2-Node matrix), `Tests` avg **218 s** (Linux + macOS
-> + Windows). Both trigger on `package.json`. Release PRs (`release/X.Y.Z`)
-> only touch `package.json`, `CHANGELOG.md`, `marketplace.json`,
-> `packages/*/pack.yaml`, `packages/*/README.md`, and the CHANGELOG era
-> archive `docs/archive/CHANGELOG-pre-*.md` — verified against PR #238
-> (3.3.0). They cannot regress install or runtime behaviour by construction.
-
-## Release-PR shape
-
-A pull request qualifies as a **release PR** when **both** of the following
-hold:
-
-1. **Head branch matches** `^release/\d+\.\d+\.\d+$` — same regex as
-   `src/scripts/release.ts` § `_RELEASE_BRANCH_RE`.
-2. **Diff file set is a subset of the version-bump allowlist:**
-   - `package.json`
-   - `CHANGELOG.md`
-   - `.claude-plugin/marketplace.json`
-   - `packages/*/pack.yaml`
-   - `packages/*/README.md`
-   - `docs/archive/CHANGELOG-pre-*.md` — emitted by `release.ts`'s
-     automatic CHANGELOG era split (see `docs/contracts/CHANGELOG-conventions.md`
-     § Era splits) when the current era crosses its line cap on an
-     era-boundary release.
-
-Both predicates are enforced by `src/scripts/check_release_pr_shape.ts`.
-The script exits 0 when both hold; non-zero with a per-file diff naming any
-out-of-allowlist entry otherwise. It reads the diff shape only — it does
-not check the PR author, so it passes identically for a `task
-release`-opened PR and a `release.yml`-opened one.
-
-## Cut surface — heavy jobs that skip on release PRs
-
-Skipped via `if: !startsWith(github.head_ref, 'release/')` guards on the
-heavy install/test jobs. These are the jobs that release PRs cannot regress
-by construction (no install scripts, no runtime code, no test source in the
-release-PR allowlist):
-
-| Workflow | Job | Why it cuts |
-|---|---|---|
-| `tests.yml` | `install-tests` | release-PR diff has no `install.sh` / `scripts/install.py` / `tests/test_install.sh` |
-| `tests.yml` | `install-aux-tests` | same — orchestrator, key contracts, one-liner smoke all untouched |
-| `tests.yml` | `python-tests` | release-PR diff has no `scripts/**` or `tests/**` (other than CHANGELOG via path filter — see below) |
-| `tests.yml` | `node-tests` | release-PR diff has no `src/**`, `tests/{cli,server,ui}/**`, `packages/core/installer/**` |
-| `tests.yml` | `windows-lockfile-export` | release-PR diff has no `scripts/install_global*.py`, `scripts/cmd_export.py`, lockfile test surface |
-| `smoke-public-install.yml` | `smoke` | release-PR diff has no `scripts/install*`, `setup.sh`, `templates/**`, `package.json` runtime behaviour |
-
-`push:` to `main` and the weekly cron on `smoke-public-install.yml` stay
-**unconditional** — those catch drift the PR matrix can't see.
-
-## Kept surface — release PRs still prove these
-
-The release-PR required-check floor stays equivalent (smaller, faster) to
-the feature-PR floor by adding:
-
-| Workflow | Job | Proves |
-|---|---|---|
-| `consistency.yml` | (existing) | `task consistency` — source-of-truth integrity |
-| `smoke.yml` | `smoke-contracts` | Contract self-checks (kernel, router, hashes) |
-| `release-guard.yml` | `assert-version-matches-tag` | already gates `npm publish`; remains tag-trigger |
-| `migration-dry-run.yml` | (existing) | Migration plan dry-runs |
-| `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 |
-| (maintainer-local) | `task smoke-host-loadability REQUIRE=1` | real-host loadability — `claude plugin validate` + temp-home plugin install + metadata cross-consistency (marketplace ↔ plugin dirs ↔ docs). Optional in CI (runners lack the claude CLI, the step self-skips); **required before a release is cut** — `REQUIRE=1` turns a missing CLI into a failure |
-
-## 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
-
-The optimisation is **opt-in by shape, not by branch name**. A release-PR
-whose diff contains a stray file outside the allowlist (e.g. a last-minute
-CHANGELOG fixup that also touches `src/scripts/release.ts`) trips the shape
-detector:
-
-1. `check_release_pr_shape.ts` exits non-zero with a per-file diff.
-2. The CI dashboard surfaces "release-shape" red.
-3. The maintainer either narrows the diff (move the script edit to a
-   separate PR) or accepts the heavy matrix re-running on the next push.
-
-In other words: the cut applies only when shape is **provably** safe. Branch
-name alone never bypasses the heavy matrix.
-
-## What this contract is not
-
-- **Not a test-deletion contract.** Every existing assertion still runs
-  somewhere in the cadence (PR for feature PRs, push-to-main + weekly cron
-  for smoke).
-- **Not a coverage-reduction contract.** The release-validation jobs are
-  additive, not substitutive.
-- **Not a release-velocity contract.** Release cadence is driven by
-  Conventional Commits in `src/scripts/release.ts`, not by CI cost.
-- **Not a Hard-Floor lift.** No security check is removed.
-  `release-guard.yml`'s `assert-version-matches-tag` job is independent of
-  `Tests` / `Public Install Smoke` and stays mandatory on every tag.
-
-## See also
-
-- `docs/contracts/branch-protection-policy.md` — per-PR-shape required-check
-  matrix (Phase D).
-- `docs/contracts/ci-cost-budget.md` — measured baselines + quarterly review
-  cadence (Phase C).
-- `.github/workflows/release-validation.yml` — the tight release-shape
-  validation workflow (Phase B).
-- `src/scripts/check_release_pr_shape.ts` — the shape detector (Phase A).
-- `src/scripts/release.ts` § `_RELEASE_BRANCH_RE` — source of truth for the
-  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

@@ -1,107 +0,0 @@
----
-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)).
-
-### Primary goal declaration
-
-Every release PR body carries one literal line:
-
-```
-Primary-Goal: <one sentence>
-```
-
-A release bundling multiple major themes anyway annotates the
-**exception + reason** in the release notes ("this release bundles N
-themes because <reason>; future releases return to one primary goal").
-The declaration keeps the norm visible and the exception deliberate.
-
-Explicitly REJECTED (council, anthropic/claude-sonnet-4-5 +
-openai/gpt-4o, 2026-07-10): a mechanical subsystem-count lint on the
-release PR. A file→subsystem map is its own maintenance burden, and
-changed-file counts are a bad proxy for scope (a one-line kernel change
-has a larger blast radius than 50 lines in a niche skill). Sizing stays
-a norm enforced by declaration + human judgment; if the maintainer
-wrote a nine-theme release, the maintainer already judged it — the
-header makes that judgment explicit, not automatic.
-
-## 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).