@event4u/agent-config 3.3.0 → 4.1.0

package/docs/contracts/adr-command-suggestion.md

@@ -5,7 +5,7 @@ stability: stable
 # ADR — Context-Aware Command Suggestion
 
 > **Status:** Decided · Phases 1–7 shipped · 2026-04-30
-> **Rule:** [`command-suggestion`](../../.agent-src.uncompressed/rules/command-suggestion-policy.md)
+> **Rule:** [`command-suggestion`](../../.agent-src.uncondensed/rules/command-suggestion-policy.md)
 > **Eligibility table:** [`command-suggestion-eligibility.md`](command-suggestion-eligibility.md)
 > **Engine:** `scripts/command_suggester/`
 > **Orthogonal to:** R1 (`adr-work-engine-rename.md`) — the suggester is a
@@ -89,7 +89,7 @@ suppression when they signal real intent.
 
 ## Hardening — what suggestion must never do
 
-The rule (`.agent-src.uncompressed/rules/command-suggestion-policy.md`)
+The rule (`.agent-src.uncondensed/rules/command-suggestion-policy.md`)
 binds the engine to five non-negotiables, mirrored as goldens:
 
 1. **No execution without user pick.** `SUGGEST. NEVER INVOKE.` is the
@@ -138,7 +138,7 @@ retirement candidates without a hard SLA.
 
 ## See also
 
-- [`command-suggestion`](../../.agent-src.uncompressed/rules/command-suggestion-policy.md) — runtime rule
+- [`command-suggestion`](../../.agent-src.uncondensed/rules/command-suggestion-policy.md) — runtime rule
 - [`command-suggestion-eligibility.md`](command-suggestion-eligibility.md) — locked eligibility table
 - [`adr-prompt-driven-execution.md`](adr-prompt-driven-execution.md) — `/work` entrypoint that explicit slash invocations route to
-- [`agent-settings`](../../.agent-src.uncompressed/templates/agent-settings.md) — `commands.suggestion.*` reference
+- [`agent-settings`](../../.agent-src.uncondensed/templates/agent-settings.md) — `commands.suggestion.*` reference

package/docs/contracts/adr-gtm-context-spine.md

@@ -111,6 +111,6 @@ Three signals that this decision is wrong and the ADR needs revisiting:
   — `context_spine.items.enum` extended in this ADR.
 - `agents/roadmaps/` § Block G — the authorising roadmap (archived
   after merge; this ADR is the durable record).
-- [`.agent-src.uncompressed/rules/skill-quality.md`](../../.agent-src.uncompressed/rules/skill-quality.md)
+- [`.agent-src.uncondensed/rules/skill-quality.md`](../../.agent-src.uncondensed/rules/skill-quality.md)
   § Senior-Tier Required Structure — the four blocks every senior
   skill ships independently of spine opt-in.

package/docs/contracts/adr-implement-ticket-runtime.md

@@ -13,12 +13,12 @@ stability: stable
 The `/implement-ticket` orchestrator ships on **Python 3.10+** (stdlib + `pyyaml`).
 
 Bash is rejected as the runtime. It stays only where it already lives —
-the install driver, compression helper, and test runner — not the
+the install driver, condensation helper, and test runner — not the
 delivery flow.
 
 ## Why this was a real question
 
-The repo already ships a Bash install + compression toolchain. A
+The repo already ships a Bash install + condensation toolchain. A
 shell-native dispatcher would have reused the existing muscle memory and
 avoided adding Python as a delivery-runtime dependency. The spike
 existed to verify whether Bash could still carry the 8-step linear flow
@@ -85,7 +85,7 @@ Python is 3 files with shared types.
 ## Tradeoffs we accept
 
 - **New hard dependency on Python 3.10+ and `pyyaml`.** Mitigated: Python 3
-  is already a build/test dependency of this repo (linters, compression,
+  is already a build/test dependency of this repo (linters, condensation,
   `update_counts.py`). `pyyaml` is already pinned in `pyproject.toml` /
   `requirements-*.txt`. Zero new install surface for contributors.
 - **We lose the "just-shell" story.** The install script stays Bash. The
@@ -100,7 +100,7 @@ Python is 3 files with shared types.
   on its own evidence.
 - Does not commit to a specific framework (click, typer, bare argparse);
   that is chosen during Phase 1 and kept minimal.
-- Does not move the compression/install scripts off Bash.
+- Does not move the condensation/install scripts off Bash.
 
 ## Consequences — unblocks
 

package/docs/contracts/adr-install-user-type-axis.md

@@ -14,7 +14,7 @@ keep-beta-until: 2026-08-13
 ## Decision
 
 Install-time skill filtering uses a dedicated axis seeded under
-`user-types/` (package root, not `.agent-src.uncompressed/`). The
+`user-types/` (package root, not `.agent-src.uncondensed/`). The
 selection lands in the consumer's `.agent-settings.yml` under
 `personal.user_type: <id>` via `agent-config install --user-type=<id>`.
 Runtime skill discovery intersects each skill's

package/docs/contracts/adr-layout.md

@@ -38,7 +38,7 @@ Reserved areas (bootstrap pass — step-11 Phase 4 Step 3):
 | Area | Scope | Owner contract |
 |---|---|---|
 | `cost` | Budget ladder, hard-stop hook, cost reporting | [`cost-enforcement.md`](cost-enforcement.md) |
-| `caveman` | Caveman-speak compression, decompression, reversibility | [`compression-default-kill-criterion.md`](compression-default-kill-criterion.md) |
+| `telegraph` | Telegraph-speak condensation, decondensation, reversibility | [`condensation-default-kill-criterion.md`](condensation-default-kill-criterion.md) |
 | `schema` | Frontmatter schemas, v2 rigor, lint behaviour | [`schema-versioning.md`](schema-versioning.md) (when published) |
 | `router` | `router.json` shape, tier semantics, dispatch precedence | [`rule-router.md`](rule-router.md) |
 | `smoke` | Per-tier smoke contracts, baseline locks | [`smoke-contracts.md`](smoke-contracts.md) |
@@ -91,7 +91,7 @@ Default mode is **warn** at the consumer surface; **fail** under `task ci`. Rati
 
 ## Relationship to `adr-create` skill
 
-[`adr-create`](../../.agent-src.uncompressed/skills/adr-create/SKILL.md) accepts an optional `<area>` argument (added in step-11 Phase 4 Step 4):
+[`adr-create`](../../.agent-src.uncondensed/skills/adr-create/SKILL.md) accepts an optional `<area>` argument (added in step-11 Phase 4 Step 4):
 
 - No `<area>` → flat surface, `docs/decisions/`.
 - `<area>` matches inventory → per-area surface, `docs/adrs/<area>/`.

package/docs/contracts/adr-product-ui-track.md

@@ -16,9 +16,9 @@ stability: stable
 R3 ships four directive sets — `backend` (R1/R2), **`ui`**, **`ui-trivial`**,
 and **`mixed`** — dispatched at the engine boundary on
 `state.directive_set`. The slot wiring is fixed by
-[`directives/ui/__init__.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/ui/__init__.py),
-[`directives/ui_trivial/__init__.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/ui_trivial/__init__.py),
-and [`directives/mixed/__init__.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/mixed/__init__.py);
+[`directives/ui/__init__.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/ui/__init__.py),
+[`directives/ui_trivial/__init__.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/ui_trivial/__init__.py),
+and [`directives/mixed/__init__.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/mixed/__init__.py);
 the contract for each lives in [`ui-track-flow.md`](ui-track-flow.md).
 
 The UI set drives `audit → design → apply → review → polish → report`
@@ -26,7 +26,7 @@ with three load-bearing properties:
 
 1. **Existing-UI-audit is a hard gate.** No `apply` runs without
    `state.ui_audit` populated. The gate lives at directive level **and**
-   at always-on rule level ([`ui-audit-gate`](../../.agent-src.uncompressed/rules/ui-audit-gate.md))
+   at always-on rule level ([`ui-audit-gate`](../../.agent-src.uncondensed/rules/ui-audit-gate.md))
    so an agent acting outside the engine cannot bypass it.
 2. **Design brief is locked microcopy.** `apply` consumes the brief
    verbatim — `PLACEHOLDER_PATTERNS` (`<placeholder>`, `lorem`, `todo:`,
@@ -84,10 +84,10 @@ the gate emits `@agent-directive: existing-ui-audit` and refuses to advance.
 Two enforcement layers, deliberately redundant:
 
 - **Dispatcher layer** —
-  [`directives/ui/audit.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/ui/audit.py)
+  [`directives/ui/audit.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/ui/audit.py)
   refuses to write `outcomes["refine"] = "success"` without a populated
   audit. Purely structural; no LLM, no heuristic.
-- **Agent layer** — [`ui-audit-gate`](../../.agent-src.uncompressed/rules/ui-audit-gate.md)
+- **Agent layer** — [`ui-audit-gate`](../../.agent-src.uncondensed/rules/ui-audit-gate.md)
   is an always-on rule that fires when the agent is about to write a
   component file outside the engine (free-form edit, side conversation,
   cloud surface). The rule encodes the same Iron Law in prose so cloud
@@ -102,7 +102,7 @@ the failure modes are different enough to justify it.
 ### Confidence-path resolution
 
 Audit findings carry a confidence label and per-candidate similarity.
-[`directives/ui/audit.py::_decide_path`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/ui/audit.py)
+[`directives/ui/audit.py::_decide_path`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/ui/audit.py)
 resolves to one of:
 
 - `high_confidence` — confidence `high` + ≥1 match with similarity
@@ -176,7 +176,7 @@ adjustment), the Phase-1 intent classifier writes
 `directive_set = "ui-trivial"`. The slot wiring collapses to
 `refine → ⊘ → ⊘ → ⊘ → apply → test → ⊘ → report` with
 `MAX_FILES = 1` and `MAX_LINES_CHANGED = 5` enforced inside
-[`directives/ui_trivial/apply.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/ui_trivial/apply.py).
+[`directives/ui_trivial/apply.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/ui_trivial/apply.py).
 
 **Mandatory reclassification at apply time.** When a trivial edit
 exceeds the preconditions, apply flips
@@ -193,7 +193,7 @@ preconditions don't hold.
 
 ## Stack detection and dispatch
 
-[`scripts/work_engine/stack/detect.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/stack/detect.py)
+[`scripts/work_engine/stack/detect.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/stack/detect.py)
 reads `composer.json` and `package.json` once, applies a four-rule
 priority table, and writes `state.stack.frontend`:
 
@@ -223,7 +223,7 @@ direct executor. R3 splits the responsibilities:
 
 - **Reference (kept):** layout patterns, form / table design,
   responsive strategy, a11y heuristics. Cited by
-  [`directives/ui/design.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/ui/design.py).
+  [`directives/ui/design.py`](../../.agent-src.uncondensed/templates/scripts/work_engine/directives/ui/design.py).
 - **Executor (removed):** code-writing responsibilities migrated to
   the stack-specific apply / review / polish skills (`flux`,
   `livewire`, `blade-ui`, `react-shadcn-ui`, `ui-apply-vue`).

package/docs/contracts/adr-user-types-axis.md

@@ -35,10 +35,10 @@ axes, one orthogonal product.
 
 ## Decision
 
-Split into a parallel axis. Add `.agent-src.uncompressed/user-types/`
+Split into a parallel axis. Add `.agent-src.uncondensed/user-types/`
 as a first-class directory mirroring the persona pipeline:
 
-- Source dir: `.agent-src.uncompressed/user-types/`
+- Source dir: `.agent-src.uncondensed/user-types/`
 - Schema doc: [`user-type-schema`](user-type-schema.md) — 7-section spine, ≤ 120 lines
 - JSON schema: [`scripts/schemas/user-type.schema.json`](../../scripts/schemas/user-type.schema.json)
 - Linter: `scripts/skill_linter.py § lint_usertype`
@@ -102,7 +102,7 @@ Markdown prose + frontmatter), completely different consumer
 (`scripts/install.sh` vs. `refine-ticket`). Co-locating them would
 force a single `kind:` discriminator on a directory whose two halves
 do not share a schema. The separation is in different physical paths
-(`user-types/` root vs. `.agent-src.uncompressed/user-types/`) and
+(`user-types/` root vs. `.agent-src.uncondensed/user-types/`) and
 the vocabulary overlap is deliberate per [`adr-install-user-type-axis`](adr-install-user-type-axis.md).
 
 **Alt-3 — Defer the axis until end-user lenses prove themselves in

package/docs/contracts/adr-wing4-context-spine.md

@@ -121,6 +121,6 @@ re-opens the slot-sprawl risk and needs a separate ADR.
   reference ADR this one composes against.
 - [`scripts/schemas/skill.schema.json`](../../scripts/schemas/skill.schema.json)
   — `context_spine.items.enum` extended in this ADR.
-- [`.agent-src.uncompressed/rules/skill-quality.md`](../../.agent-src.uncompressed/rules/skill-quality.md)
+- [`.agent-src.uncondensed/rules/skill-quality.md`](../../.agent-src.uncondensed/rules/skill-quality.md)
   § Senior-Tier Required Structure — the four blocks every senior
   skill ships independently of spine opt-in.

package/docs/contracts/agent-memory-contract.md

@@ -136,7 +136,7 @@ call. File-drop is the always-works path.
   to pick the curated YAML target when a signal carries two tags
   (e.g. `[gotcha, invariant]` → primary `gotcha` JSONL, promote target
   resolved by the reviewer at promotion time). See
-  [`memory-consolidation`](../../.agent-src.uncompressed/skills/memory-consolidation/SKILL.md)
+  [`memory-consolidation`](../../.agent-src.uncondensed/skills/memory-consolidation/SKILL.md)
   § Phase 3 for the schema-routing table.
 - `confidence: low | medium | high` — producer-supplied estimate; the
   inline-review hook in `/memory load` ranks the top-3 by this field.
@@ -155,5 +155,5 @@ holds:
 ## See also
 
 - [`memory-access guideline`](../../docs/guidelines/agent-infra/memory-access.md)
-- [`scripts/memory_status.py`](../../.agent-src.uncompressed/templates/scripts/memory_status.py)
-- [`scripts/memory_lookup.py`](../../.agent-src.uncompressed/templates/scripts/memory_lookup.py)
+- [`scripts/memory_status.py`](../../.agent-src.uncondensed/templates/scripts/memory_status.py)
+- [`scripts/memory_lookup.py`](../../.agent-src.uncondensed/templates/scripts/memory_lookup.py)

package/docs/contracts/agents-md-tech-stack.md

@@ -51,7 +51,7 @@ Mechanical enforcement: the structural-malice check in
 - Shell injection in subprocess calls (string-concat shell commands
   with user-controlled input).
 
-See `.agent-src.uncompressed/rules/skill-quality.md` § Structural
+See `.agent-src.uncondensed/rules/skill-quality.md` § Structural
 Malice Floor for the full rule.
 
 ## Distribution mechanics
@@ -69,7 +69,7 @@ Malice Floor for the full rule.
 - [`AGENTS.md`](../../AGENTS.md) — front-door (kernel orientation only)
 - [`docs/architecture.md`](../../docs/architecture.md) — package
   architecture and cloud-bundle pipeline
-- [`.agent-src.uncompressed/rules/skill-quality.md`](../../.agent-src.uncompressed/rules/skill-quality.md)
+- [`.agent-src.uncondensed/rules/skill-quality.md`](../../.agent-src.uncondensed/rules/skill-quality.md)
   — Structural Malice Floor
 - [`.agent-src/skills/markitdown/SKILL.md`](../../.agent-src/skills/markitdown/SKILL.md)
   — markitdown skill entry point

package/docs/contracts/ai-council-config.md

@@ -166,7 +166,7 @@ Schema v1:
 ### Advisor block (Phase 6, replace-mode)
 
 Five built-in advisor keys ship under
-[`.agent-src.uncompressed/personas/advisors/`](../../.agent-src.uncompressed/personas/advisors/):
+[`.agent-src.uncondensed/personas/advisors/`](../../.agent-src.uncondensed/personas/advisors/):
 `contrarian`, `first-principles`, `expansionist`, `outsider`,
 `executor`. Each entry binds one advisor to one enabled provider. When
 `enabled: true`, the orchestrator REPLACES that provider's plain-member
@@ -446,7 +446,7 @@ Transparency markers on every fast-path attempt:
 
 The marker is mandatory; the agent never silently substitutes a
 fast-path verdict for its own answer. See
-[`ai-council § Lightweight-QA fast-path`](../../.agent-src.uncompressed/skills/ai-council/SKILL.md#lightweight-qa-fast-path-phase-11)
+[`ai-council § Lightweight-QA fast-path`](../../.agent-src.uncondensed/skills/ai-council/SKILL.md#lightweight-qa-fast-path-phase-11)
 for the orchestration contract and session-artefact format.
 
 ### Solo-member dispatch (step-9 P8/P9 · U1 · U2 · U3)

package/docs/contracts/at-rest-encryption.md

@@ -1,3 +1,7 @@
+---
+stability: experimental
+---
+
 # At-Rest Encryption Contract
 
 > **Status** · v0 / design · 2026-05-24. Phase 8 of the

package/docs/contracts/audit-log-v1.md

@@ -138,6 +138,6 @@ majors.
 - Per-phase JSON the producer reads: [`decision-trace-v1.md`](decision-trace-v1.md).
 - Pattern-extraction consumer: [`extract_audit_patterns.py`](../../scripts/extract_audit_patterns.py).
 - Skill that consumes promoted patterns:
-  [`learning-to-rule-or-skill`](../../.agent-src.uncompressed/skills/learning-to-rule-or-skill/SKILL.md).
+  [`learning-to-rule-or-skill`](../../.agent-src.uncondensed/skills/learning-to-rule-or-skill/SKILL.md).
 - Append-only JSONL precedent:
   [`adr-chat-history-split.md`](adr-chat-history-split.md).

package/docs/contracts/benchmark-ab-contract.md

@@ -0,0 +1,101 @@
+# Package-Impact A/B Benchmark — Contract
+
+> Lifecycle, cache invalidation, and reader-side semantics for `docs/benchmark.md` and the underlying A/B bench reports. Companion to `docs/contracts/benchmark-report-schema.md` (which owns the per-report JSON shape this contract layers an axis onto).
+
+## Scope
+
+This contract covers the **variant axis** (`with` vs. `without` agent-config) that the package-impact A/B bench adds on top of the existing version-over-time bench. It does NOT redefine the underlying report schema — see `benchmark-report-schema.md` for the per-report JSON shape.
+
+## Producer / consumer surface
+
+| Concern | Owner |
+|---|---|
+| Materialising the variant clones | `scripts/bench_ab_clone.py` |
+| Verifying the clones differ only at the agent-config surface | `scripts/bench_ab_integrity.py` |
+| Track A (behavioural) runner | `scripts/bench_ab_tracka_run.py` |
+| Track B (task) runner | `scripts/bench_ab_task_runner.py` |
+| Track B scoring | `scripts/_lib/bench_ab_scoring.py` |
+| Cache key + lookup | `scripts/_lib/bench_ab_cache.py` |
+| Variant diff | `scripts/bench_ab_diff.py` |
+| Rendered report | `scripts/render_benchmark_md.py` → `docs/benchmark.md` |
+| Corpus / doc linter | `scripts/lint_bench_ab.py` |
+| Task orchestration | `taskfiles/bench-ab.yml` (`task bench:ab*`) |
+
+## When `docs/benchmark.md` regenerates
+
+`docs/benchmark.md` is **derived**. It regenerates from the latest paired reports under `internal/bench/reports/ab/` whenever:
+
+1. `task bench:ab` runs (the full pipeline ends with `bench:ab:diff` which calls the renderer).
+2. `task bench:ab:diff` runs alone (no fresh bench, just re-render).
+3. The renderer is invoked directly: `python3 scripts/render_benchmark_md.py`.
+
+The renderer is deterministic: same reports → same output. It never runs a bench. If no reports exist, it writes a placeholder document — never errors out.
+
+## Cache key + invalidation
+
+The Phase 2 cache exists so a daily `task bench:ab` does not re-run the expensive `without` arm when nothing the model would see has changed. The cache key is a tuple:
+
+```
+(corpus_hash, claude_cli_version, target_shape_hash)
+```
+
+A cached `without` report is **fresh** when its recorded `cache_key` matches the current key for every component. Otherwise it is **stale** and the `--reuse-cache` path either refreshes (default in interactive mode) or reuses with a stale flag (`--non-interactive`).
+
+Invalidation triggers:
+
+| Trigger | Component that drifts |
+|---|---|
+| Edit `internal/bench/corpora/ab-tracka.yaml` or `ab-trackb.yaml` | `corpus_hash` |
+| Upgrade the local `claude` CLI | `claude_cli_version` |
+| Add / remove a `WITH_SURFACE` in `scripts/bench_ab_clone.py` | `target_shape_hash` |
+| Edit any file under `internal/bench/ab/fixture/` | `target_shape_hash` |
+
+## How a reader interprets the staleness flag
+
+`docs/benchmark.md` carries a methodology section naming the cache key for the latest run. A reader who suspects the page is stale should:
+
+1. Check the **Last rendered** timestamp at the bottom of the Methodology section.
+2. Inspect `internal/bench/reports/ab/` for newer reports than what the doc reflects.
+3. Re-run `task bench:ab:diff` to re-render from the latest reports (cheap; no bench).
+4. Re-run `task bench:ab` for a full refresh (re-runs the `with` arm, reuses the `without` baseline if the cache is fresh).
+
+## Modes — what the reader can trust
+
+Track B carries an explicit `mode` in every report header:
+
+- `dry-run` — no `claude` CLI invocation; transcripts are stubs. Both variants score 0/N by construction. This is the CI-cheap mode; **do NOT cite Track B numbers in a dry-run report as evidence of package impact**.
+- `live` — real `claude --print` invocation per task. The numbers are real; the cost is real. This is the mode that produces evidence.
+
+The renderer surfaces `mode` prominently in the Track B section. A `dry-run` Track B block is a plumbing-health check, not a measurement.
+
+## Track A is always cheap, always meaningful
+
+Track A measures **surface availability** — does the rule/skill body the prompt would activate exist in the agent's reachable context? This is the precondition for the rule-router to fire. It does not need the `claude` CLI; it is a file-grep over the materialised clone. By construction:
+
+- `without` MUST score 0% — no agent-config surface present → no expected_target file exists.
+- `with` should score close to 100% — every expected_target file should exist with the expected_keywords.
+
+The integrity check `bench_ab_tracka_run.py::integrity_check` fails the run if `without` ever scores non-zero. That's the safety boundary: if `without` scores anything, the variant axis leaked and the bench is invalid.
+
+## Acceptance criteria for a "real" run
+
+A bench run counts as a real measurement (rather than a plumbing health check) when:
+
+- `python3 scripts/bench_ab_integrity.py` exits 0 (the variant axis is clean).
+- Track A runs in BOTH variants and produces `integrity_ok: true` (with scoring close to 100%, without scoring 0%).
+- Track B runs in BOTH variants in `--mode live` (not dry-run).
+- `python3 scripts/lint_bench_ab.py` passes.
+- The rendered `docs/benchmark.md` carries the Headline + Track A + Track B + Methodology + History sections.
+
+## Out of scope for this contract
+
+- The per-report JSON schema details — see `docs/contracts/benchmark-report-schema.md`.
+- Statistical significance / sample-size policy — `--samples N` is opt-in per run; the bench default is n=1 (daily-quick-read goal, not a research-grade study).
+- LLM-judge scoring — explicitly deferred to a follow-up roadmap.
+- Cross-model comparison — out of scope; the bench measures one model (whatever the local `claude` CLI points to).
+
+## See also
+
+- `agents/roadmaps/road-to-package-impact-benchmark.md` — the roadmap that built this surface.
+- `internal/bench/ab/README.md` — the Shape A vs. Shape B decision and the layout.
+- `docs/contracts/benchmark-report-schema.md` — per-report JSON shape (sibling contract).

package/docs/contracts/benchmark-corpus-spec.md

@@ -93,5 +93,5 @@ without tripping CI.
 - Runner — [`scripts/bench_runner.py`](../../scripts/bench_runner.py)
 - Linter — `scripts/lint_bench_corpus.py` (Phase 1 Step 3)
 - Existing non-dev corpus — [`tests/eval/corpus-non-dev.yaml`](../../tests/eval/corpus-non-dev.yaml)
-- Language gate — [`language-and-tone`](../../.agent-src.uncompressed/rules/language-and-tone.md)
+- Language gate — [`language-and-tone`](../../.agent-src.uncondensed/rules/language-and-tone.md)
 - Report schema — `docs/contracts/benchmark-report-schema.md` (Phase 2 Step 4)

package/docs/contracts/branch-protection-policy.md

@@ -0,0 +1,98 @@
+# Branch Protection Policy
+
+> **Status:** active · **Owner:** maintainer (GitHub UI ruleset) ·
+> **Opened:** 2026-05-26
+>
+> Codifies the per-PR-shape required-status-check floor. Companion to
+> [`release-pr-gating.md`](release-pr-gating.md) (Phase A) and
+> [`ci-cost-budget.md`](ci-cost-budget.md) (Phase C). Branch protection
+> itself is applied by the maintainer in the GitHub Settings → Rules UI;
+> this doc is the source of truth the UI mirrors.
+
+## The floor
+
+Every PR proves a floor of CI checks before it can merge. The floor differs
+by **PR shape** — a feature PR proves more (it carries runtime / install
+risk) than a release PR (whose diff is structurally limited to version
+bumps). Shape is detected by the same predicates documented in
+`release-pr-gating.md`; the workflows enforce the cut.
+
+The optimisation is **never** subtractive: a PR whose shape can't be proved
+falls back to the full feature-PR floor. The cut is opt-in per push, not
+per branch name.
+
+## Per-PR-shape required-check matrix
+
+| Required check | Feature PR | Release PR | Docs-only PR |
+|---|:---:|:---:|:---:|
+| `Consistency` | ✅ | ✅ | ✅ |
+| `Smoke Contracts` (smoke.yml) | ✅ | ✅ | ✅ |
+| `Skill Lint` | ✅ | — | — |
+| `Tests / install-tests (ubuntu)` | ✅ | — | — |
+| `Tests / install-tests (macos)` | ✅ | — | — |
+| `Tests / install-aux-tests (ubuntu)` | ✅ | — | — |
+| `Tests / install-aux-tests (macos)` | ✅ | — | — |
+| `Tests / python-tests (ubuntu × 3.10–3.13)` | ✅ | — | — |
+| `Tests / python-tests (macos × 3.12)` | ✅ | — | — |
+| `Tests / node-tests (ubuntu)` | ✅ | — | — |
+| `Tests / node-tests (macos)` | ✅ | — | — |
+| `Tests / windows-lockfile-export` | path-filter only | — | — |
+| `Public Install Smoke / smoke (matrix)` | ✅ | — | — |
+| `Release Validation / release-shape` | — | ✅ | — |
+| `Release Validation / changelog-entry` | — | ✅ | — |
+| `Release Validation / version-consistency` | — | ✅ | — |
+| `Migration Dry-Run` | path-filter only | path-filter only | — |
+| `Release Guard` (tag-trigger) | — | (post-merge tag) | — |
+
+**Definitions:**
+
+- **Feature PR** — head branch does not match `release/X.Y.Z` (the default).
+- **Release PR** — head branch matches `^release/\d+\.\d+\.\d+$` AND the
+  diff stays within the version-bump allowlist (see `release-pr-gating.md`).
+  Either condition failing falls the PR back to feature-PR mode.
+- **Docs-only PR** — diff is entirely inside `docs/**` or matches only
+  top-level Markdown (`README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`,
+  `AGENTS.md`). No code, tests, workflows, or scripts. This shape is
+  detected by an opt-in linter (`task ci:required-checks`); branch
+  protection still defaults to the feature-PR floor unless the linter
+  asserts the docs-only shape.
+
+## Failure mode — the cut never silently lifts
+
+If a release-PR's diff exits the allowlist mid-stream (e.g. a last-minute
+CHANGELOG fixup that also touches `scripts/release.py`):
+
+1. `Release Validation / release-shape` exits non-zero.
+2. The required-check set for the PR effectively flips back to the
+   feature-PR floor because:
+   - `tests.yml` / `smoke-public-install.yml` jobs carry
+     `if: !startsWith(github.head_ref, 'release/')`, so they still skip on
+     the branch name — but
+   - the maintainer is expected to either narrow the diff (move the
+     out-of-shape edit to a separate PR) or close-and-reopen the release
+     PR off a freshly-bumped branch so the heavy matrix runs.
+3. Branch protection still blocks the merge because `release-shape` is red.
+
+The branch name alone never bypasses the heavy matrix — the diff has to
+prove it can't regress runtime / install paths.
+
+## Why path-filter only for some checks
+
+`Tests / windows-lockfile-export` and `Migration Dry-Run` are path-filtered
+at the workflow level (not branch-protection level). They run on every PR
+whose diff hits their declared paths and skip on every other PR. Branch
+protection lists them as "must pass if they run" — the GitHub Rules UI
+under "Required status checks" honours this when "Require branches to be
+up to date before merging" is enabled and the check's most recent run
+on the head SHA is green.
+
+## See also
+
+- [`release-pr-gating.md`](release-pr-gating.md) — shape predicates, cut
+  surface, kept surface, fail-closed contract.
+- [`ci-cost-budget.md`](ci-cost-budget.md) — measured baseline durations
+  per job + quarterly review cadence (Phase C).
+- `.github/workflows/release-validation.yml` — the three release-PR jobs.
+- `scripts/check_release_pr_shape.py` — the shape detector.
+- `scripts/release.py` — emits release PRs; release cadence stays driven
+  by Conventional Commits, not CI cost.

package/docs/contracts/ci-cost-budget.md

@@ -0,0 +1,106 @@
+# CI Cost Budget
+
+> **Status:** active · **Owner:** maintainer · **Opened:** 2026-05-26 ·
+> **Review cadence:** quarterly (next: 2026-08-26)
+>
+> Measured durations + trigger surfaces for every PR-blocking CI job in
+> `.github/workflows/`. Sets a per-job wall-clock budget (5 min average)
+> beyond which the job either earns its cost in writing or gets a
+> follow-up optimisation step. Companion to
+> [`release-pr-gating.md`](release-pr-gating.md) and
+> [`branch-protection-policy.md`](branch-protection-policy.md).
+
+## Baseline (pre-optimisation, 2026-05-26)
+
+Captured via `gh run list --branch main --limit 50 --json
+name,createdAt,updatedAt`. Wall-clock figures are the average of the most
+recent 50 main-branch runs.
+
+| Workflow | Job | OS × variant | Avg duration | Trigger surface |
+|---|---|---|--:|---|
+| `tests.yml` | `install-tests` | 4 shards × 2 OS | 218 s | `scripts/**`, `tests/**`, `src/**`, manifest pins |
+| `tests.yml` | `install-aux-tests` | 2 OS | 90 s | same as above |
+| `tests.yml` | `python-tests` | 4 versions × ubuntu + 3.12 × macOS | ~210 s | same as above |
+| `tests.yml` | `node-tests` | 2 OS | 180 s | same as above |
+| `tests.yml` | `windows-lockfile-export` | windows-latest | 60–90 s | same as above (over-broad — see Phase C Step 1) |
+| `smoke-public-install.yml` | `smoke` | 3 OS × 2 Node | 413 s | install paths + setup.sh + templates |
+| `consistency.yml` | (single) | ubuntu | 27 s | always-on (PR / push) |
+| `smoke.yml` | smoke-contracts | ubuntu | 18 s | `scripts/schemas/**` |
+| `migration-dry-run.yml` | (single) | ubuntu | 20 s | migration-touching paths |
+| `skill-lint.yml` | (single) | ubuntu | 64 s | `.agent-src*/**`, schemas |
+| `release-guard.yml` | (single) | ubuntu | < 10 s | tag-trigger only |
+
+**Critical path observations:**
+
+- `smoke-public-install.yml` and `tests.yml` dominate non-release-PR
+  wall-clock. Both trigger on `package.json` — a release PR (which only
+  touches `package.json` + CHANGELOG + marketplace + pack manifests)
+  pulled the full matrix on every bump pre-Phase A.
+- `tests.yml` `python-tests` ran four Python versions on Linux + 3.12 on
+  macOS on every PR touching `scripts/**`. The 3.10 / 3.11 / 3.13 legs
+  are extras: they prove the supported range but rarely surface a
+  Python-version-only regression. Moved to a path-filtered sibling
+  workflow in Phase C Step 2.
+- `tests.yml` `windows-lockfile-export` fired on every PR touching
+  `scripts/**` even when the PR never went near `install_global` /
+  `cmd_export`. Moved to its own path-filtered workflow in Phase C
+  Step 1.
+
+## Expected savings (post-optimisation)
+
+The Phase A guards on `tests.yml` + `smoke-public-install.yml` cut
+release-PR critical-path from `218 s + 413 s` (serial worst case ≈ 11
+min) to `~30 s` (`Consistency` + `Smoke Contracts` + new `Release
+Validation`). Phase C cuts feature-PR critical-path by removing the
+Windows leg (60–90 s) and the 3-version Python sweep from PRs that
+don't touch Python paths.
+
+| Scenario | Pre | Post | Reduction |
+|---|--:|--:|--:|
+| Release PR (release/X.Y.Z) | ~660 s | ~60 s | –91 % |
+| Feature PR touching scripts/** but no install_global / cmd_export | ~700 s | ~600 s | –14 % |
+| Feature PR touching only docs/** | ~30 s (consistency) | ~30 s | unchanged |
+| Feature PR touching Python paths only on 3.12 | ~700 s | ~700 s | unchanged (baseline still runs) |
+
+## Per-job cost ceiling — 5-min average
+
+Any job averaging **> 5 min wall-clock** across the most-recent 50
+main-branch runs requires one of:
+
+1. A documented justification in this file ("This job protects
+   property X; shrinking it would mean losing the regression Y").
+2. A follow-up optimisation step opened in the next quarterly review.
+3. An ADR superseding the ceiling for this specific job (e.g. integration
+   smoke that proves a real consumer-visible promise).
+
+Current jobs above the ceiling: `smoke-public-install.yml` (413 s) —
+ceiling violation is acknowledged. The Phase A skip on release PRs
+mitigates it; an ADR will follow if it re-exceeds 5 min on feature PRs
+post-Phase C.
+
+## Quarterly review checklist
+
+Run the first Monday of every quarter:
+
+1. Re-capture the baseline table via `gh run list --branch main --limit
+   50 --json name,createdAt,updatedAt` + arithmetic.
+2. Compare each row against the previous quarter; flag any > 25 %
+   regression.
+3. For every row over the 5-min ceiling, file a follow-up step in the
+   open CI-roadmap (or in this file's history if no roadmap is
+   currently active).
+4. Update the "Expected savings" table once optimisations land so the
+   delta is provable, not asserted.
+5. Audit the path-filter surfaces — when a workflow keeps firing on
+   PRs that don't touch its real scope, tighten the filter.
+
+## See also
+
+- [`release-pr-gating.md`](release-pr-gating.md) — release-PR shape
+  predicates, cut surface, kept surface.
+- [`branch-protection-policy.md`](branch-protection-policy.md) — required
+  status check floor per PR shape.
+- `.github/workflows/python-version-sweep.yml` — extras Python versions
+  (3.10 · 3.11 · 3.13) on Python-path PRs.
+- `.github/workflows/windows-lockfile-export.yml` — Windows leg gated by
+  `install_global` / `cmd_export` paths.