@event4u/agent-config 2.10.0 → 2.11.0

package/README.md

@@ -7,7 +7,7 @@ Give your AI agents an audit-disciplined orchestration contract — testing, Git
 > Your agent picks up the project's stack, runs tests, prepares PRs, fixes CI — and follows your team's coding standards while doing it. Stack-aware skill sets ship for PHP (Laravel · Symfony · Zend/Laminas), JavaScript (Next.js · React · Node), and cross-stack concerns (API · testing · security · observability).
 
 <p align="center">
-  <strong>206 Skills</strong> · <strong>61 Rules</strong> · <strong>106 Commands</strong> · <strong>72 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>208 Skills</strong> · <strong>61 Rules</strong> · <strong>106 Commands</strong> · <strong>72 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
@@ -46,6 +46,30 @@ or `.agent-src/`.
 
 ## Quickstart
 
+**Three steps. Five minutes. Decision-traced first task.**
+
+```bash
+# 1. Install (writes .agent-settings.yml, .augment/, .claude/, …)
+npx @event4u/agent-config init
+
+# 2. First-run setup (sets your name, IDE, cost profile)
+#    Open your AI agent (Claude Code, Cursor, …) and type:
+/onboard
+
+# 3. First real task — agent refines, plans, logs a decision_result
+/work "your first real task"
+```
+
+A `decision_result` entry lands in `agents/state/` confirming the
+work-engine phases ran end-to-end. Stack-aware skills auto-load.
+
+> Pick specific AIs, switch to global scope, deploy MCP on Cloudflare,
+> or wire optional memory — see [**Detailed installation**](#detailed-installation)
+> below. Contributors rebuilding the package — jump to
+> [**Development**](#development).
+
+### Detailed installation
+
 Two minutes from `npx` to a better-behaved agent — no install, no
 vendored package, no postinstall hook.
 
@@ -451,12 +475,14 @@ kernel set: [`docs/contracts/kernel-membership.md`](docs/contracts/kernel-member
 | Stack | Coverage |
 |---|---|
 | Laravel · modern PHP | Skills, rules, project-analysis, quality-tool wiring (Pest · PHPStan · Rector · ECS) |
-| Symfony · Zend / Laminas | Project-analysis skills + shared PHP coder/quality skills |
-| Next.js · React · Node / Express | Project-analysis skills + UI directive set (`react-shadcn`) |
+| Symfony | Workflow skill (`symfony-workflow`) + project-analysis + shared PHP coder/quality skills |
+| Zend / Laminas | Project-analysis skills + shared PHP coder/quality skills |
+| Next.js · App Router | Workflow skill (`nextjs-patterns`) + project-analysis + UI directive set (`react-shadcn`) |
+| React · Node / Express | Project-analysis skills + UI directive set (`react-shadcn`) |
 | Vue · plain HTML | UI directive set (`vue` / `plain`) — analysis skills as they ship |
 | Cross-stack | API design · testing · security · database · Docker · Git · CI · review · threat modeling · observability |
 
-**Deepest reference stack today: Laravel.** Skill density covers Pest, PHPStan, Rector, Eloquent, Livewire/Flux, Horizon, Pulse, Reverb, Pennant — the stack the package was first proven on. Other stacks ship in the order they are battle-tested, not second-class. Adopting on a thin stack? Open an issue so we can prioritize the right skills for extraction.
+**Deepest reference stack today: Laravel** — Pest, PHPStan, Rector, Eloquent, Livewire/Flux, Horizon, Pulse, Reverb, Pennant. **Workflow-grade second tier: Symfony** (`symfony-workflow` — DI, Doctrine, Messenger, voters, Twig) and **Next.js App Router** (`nextjs-patterns` — RSC boundaries, Server Actions, caching, route handlers). Other stacks ship in the order they are battle-tested, not second-class. Adopting on a thin stack? Open an issue so we can prioritize the right skills for extraction.
 
 ---
 
@@ -530,7 +556,7 @@ slash-commands) &nbsp; 📌 = informational marker only (no auto-discovery
 or manual wiring required)
 
 > **What this means in practice:** Claude Code gets the full project-scoped
-> package (rules + 206 skills + 106 native commands); Augment Code gets the
+> package (rules + 208 skills + 106 native commands); Augment Code gets the
 > same content but only from a single global install at `~/.augment/`.
 > Cursor, Cline, Windsurf, Gemini CLI, GitHub Copilot, Roo Code, Codex CLI,
 > and Continue.dev only get the **rules** natively; skills and commands are
@@ -652,11 +678,14 @@ re-enabled or the chat ends. Full scoring contract and hardening:
 
 ## Development
 
-Edit in `.agent-src.uncompressed/`, compress, verify:
+Working on the package itself? Edit in `.agent-src.uncompressed/`,
+then regenerate compressed and projected trees:
 
 ```bash
-task ci            # Run all CI checks
-task test          # Run all tests
+task sync             # regenerate .agent-src/ and .augment/
+task generate-tools   # regenerate .claude/, .cursor/, .clinerules/, .windsurfrules
+task ci               # full pipeline — green before PR
+task test             # unit + integration tests
 ```
 
 → Full commands and project structure: [**docs/development.md**](docs/development.md)

package/config/agent-settings.template.yml

@@ -418,6 +418,63 @@ hooks:
     tier1_concerns: []
     hard_fail: false
 
+# --- Decision engine ---
+#
+# Controllable gates layered over the observability surface. Absent
+# block = current behaviour (observe-only, no gates fire). Enforcement
+# is strictly opt-in; the engine never silently rejects work without
+# a configured gate. See docs/contracts/decision-engine-gates.md for
+# the full schema, gate-conflict matrix, and non-TTY timeout protocol.
+#
+# Gate-conflict resolution (only the first firing gate per phase
+# surfaces a reason; downstream gates are skipped):
+#   1. block_on_risk         (Phase=Implement, highest impact)
+#   2. require_memory_hits   (Phase=Refine)
+#   3. min_confidence        (Phase=Plan, lowest impact)
+#
+# Unknown keys are rejected hard by scripts/validate_decision_engine.py
+# (wired into `task ci`). Removing the entire block restores observe-only.
+decision_engine:
+  # Opt-in for DecisionTraceHook (default false). Mirrored into
+  # hooks.decision_trace.enabled by work_engine.hooks.settings.
+  surface_traces: false
+
+  # Confidence-band floor for Phase=Plan.
+  #   off    = no floor (default)
+  #   low    = refuse to advance when band is below low
+  #   medium = refuse when below medium
+  #   high   = refuse when below high
+  min_confidence: off
+
+  # Risk-class ceiling for Phase=Implement.
+  #   off    = no ceiling (default)
+  #   low    = refuse when risk_class >= low (most aggressive)
+  #   medium = refuse when risk_class >= medium
+  #   high   = refuse only when risk_class == high
+  block_on_risk: off
+
+  # Phase=Refine demands at least one memory hit when true (default false).
+  # Gated on road-to-proof-not-features.md P2 (memory-consequence trace);
+  # leaving this off avoids opaque rejections until the trace can explain
+  # which memory entry was missing.
+  require_memory_hits: false
+
+  # What happens when a gate fires.
+  #   stop = halt the engine with reason on the trace (default)
+  #   ask  = prompt the user; falls back to on_block_fallback in CI
+  #   warn = log the reason but advance
+  on_block: stop
+
+  # Non-TTY timeout (seconds) when on_block=ask runs without a TTY
+  # (CI=true env or stdin not a TTY). After the timeout, the engine
+  # applies on_block_fallback and surfaces block_reason=ask_timeout.
+  ask_timeout_seconds: 30
+
+  # Resolution after ask_timeout fires.
+  #   stop = halt the engine (default — fail-safe)
+  #   warn = log and advance
+  on_block_fallback: stop
+
 # --- Update check ---
 #
 # Daily background check against the npm registry for a newer

package/docs/architecture.md

@@ -141,7 +141,7 @@ note, package-internal path-swap, description budget, and the
 
 | Layer | Count | Purpose |
 |---|---|---|
-| **Skills** | 206 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
+| **Skills** | 208 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
 | **Rules** | 61 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
 | **Commands** | 106 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
 | **Guidelines** | 72 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |

package/docs/contracts/STABILITY.md

@@ -83,6 +83,22 @@ Promotion criteria:
   with the contract unchanged, or the contract has been explicitly
   frozen as part of a roadmap step.
 
+## Beta-review markers
+
+Every `stability: beta` contract MUST carry exactly one of the
+following frontmatter markers (audit-acceptance for the periodic beta
+review; see `road-to-productization.md` § P5.4):
+
+| Marker | Shape | Meaning |
+|---|---|---|
+| `promote-to: stable` | literal | Contract has been ≥ 30 days in beta, zero breaking changes in the last 14 days, ≥ 1 consumer reference. Schedule promotion in the next release. |
+| `keep-beta-until: YYYY-MM-DD` | ISO date | API still moving or consumer count = 0. Date is the next review deadline (max 90 days from the last review). |
+| `superseded-by: <contract-id>` | string | Replaced by a stable contract. Slated for deprecation, not deletion. |
+
+The audit is repeated whenever the `keep-beta-until` date passes for
+≥ 25 % of beta contracts, or at the start of any roadmap phase that
+touches the contract surface.
+
 ## Current contracts
 
 See the file headers themselves for current levels. The frontmatter is

package/docs/contracts/adr-chat-history-split.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # ADR — Chat-history rule split

package/docs/contracts/adr-forecast-construction-shape.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # ADR — `forecast-construction-shape`: the O2 ↔ H10 interface

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

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # ADR — GTM context-spine: Wing-3 slot extension

package/docs/contracts/adr-level-6-productization.md

@@ -0,0 +1,147 @@
+---
+stability: stable
+---
+
+# ADR — Level-6 Productization Closure
+
+> **Status:** Decided · 2026-05-14
+> **Context:** Closure record for `road-to-productization.md` and its
+> two sibling roadmaps (`road-to-proof-not-features.md`,
+> `road-to-better-skills-and-profiles.md` Block A). PR #43 lifted the
+> package from Level-4 (execution engine) to Level-5 (observable
+> decision system); this roadmap was the Level-5 → Level-6 jump:
+> **steerable + provable + onboardable**.
+> **Cross-links:**
+> [`road-to-productization.md`](../../agents/roadmaps/road-to-productization.md) ·
+> [`road-to-proof-not-features.md`](../../agents/roadmaps/archive/road-to-proof-not-features.md) ·
+> [`road-to-better-skills-and-profiles.md`](../../agents/roadmaps/archive/road-to-better-skills-and-profiles.md).
+
+## What shipped
+
+### Decision-Engine steerability (Phase 2)
+
+- [`decision-engine-gates.md`](decision-engine-gates.md) — additive
+  `decision_engine:` block in `.agent-settings.yml` with
+  `min_confidence`, `block_on_risk`, `require_memory_hits`, `on_block`,
+  `ask_timeout_seconds`, `on_block_fallback`. Absent block = unchanged
+  observe-only behaviour.
+- Gate-conflict resolution matrix (P2.1a) + non-TTY timeout fallback
+  (P2.1b) shipped before the gates themselves; the engine refuses to
+  evaluate downstream gates after the first rejection and falls back
+  to `on_block_fallback` in non-interactive contexts.
+- Confidence-band gate (P2.2) and risk-class gate (P2.3) wired into
+  the scoring path. Memory-required policy (P2.4) unblocks on P6.2
+  shipping (`affected` keys in the decision trace).
+
+### UX simplification (Phase 3)
+
+- README "Quickstart" block — install → `/onboard` → `/work "first
+  real task"`, contributor detail moved below the `## For contributors`
+  fold.
+- Default `cost_profile` flipped from `minimal` to `balanced`;
+  rationale in [`cost-profile-defaults.md`](cost-profile-defaults.md).
+- `/onboard` step 11 prints the Quickstart command list inline.
+- CI gate: `task smoke-quickstart` runs the installer into a tmpdir
+  and validates the documented default surface deterministically.
+
+### Multi-stack skill depth (Phase 4)
+
+- `symfony-workflow` skill (~8.6 KB) — DI, Doctrine, Messenger,
+  voters, Twig, console.
+- `nextjs-patterns` skill (~9.9 KB) — App Router, RSC boundaries,
+  Server Actions, caching, route handlers, 14.x↔15.x deltas.
+- README stack table now separates Symfony / Next.js / Zend-Laminas
+  rows; "Deepest reference stack" paragraph names the workflow-grade
+  second tier explicitly.
+
+### Architecture cleanup (Phase 5)
+
+- Auto-rules (`non-destructive-by-default`, `scope-control-policy`)
+  audited: already refactored to trigger + Iron Law + pointer shape;
+  bound by the kernel-budget linter at 4 000-char override ceiling
+  (P5.1).
+- Rule-Interaction matrix marked rule-only by design;
+  [`rule-interactions.md`](rule-interactions.md) § "Out of scope —
+  orchestration surfaces" points at `decision-engine-gates`,
+  `decision-trace-v1`, `agent-memory-contract`, `memory-visibility-v1`,
+  and the `ai-council` skill for Council × Memory × Work-Engine
+  interactions (P5.2).
+- `type: orchestrator` frontmatter tag exempts cluster routers from
+  the `command_missing_skill_references` linter check; 15 commands
+  carry the tag (P5.3).
+- Beta-review marker protocol shipped in [`STABILITY.md`](STABILITY.md)
+  § Beta-review markers; `scripts/check_beta_review_markers.py` wired
+  into `task ci`; 39 beta contracts back-filled (P5.4).
+- Test-redundancy audit produced
+  [`road-to-test-cleanup.md`](../../agents/roadmaps/road-to-test-cleanup.md)
+  — audit-only, no deletions (P5.5).
+
+### Release-trunk discipline (Phase 1)
+
+- [`release-trunk-sync.md`](release-trunk-sync.md) protocol; CI gate
+  fails the release-prep branch when `main` is more than one tagged
+  release behind (P1.3).
+
+### Proof + cognition layers (Phases 6 + 7)
+
+- Memory-consequence in the trace: `affected` keys in
+  [`decision-trace-v1.md`](decision-trace-v1.md) (sibling P2.1a–c).
+- README three-audience split (sibling P2.2a–c).
+- Hook doctor (sibling P2.3).
+- Persona spine: Core-tier 5-section + Specialist-tier 7-section
+  spines locked in [`persona-schema.md`](persona-schema.md) (sibling
+  Block A).
+
+## What got cancelled
+
+- **P6.1 — Three real showcase sessions** (sibling P1.1–P1.4).
+  Cancelled upstream — capturing real host-agent sessions requires a
+  hosted-LLM runner that is out of scope for this roadmap. P1.0
+  pre-flight shipped; the capture surface is ready when a runner
+  exists. Reopen as `road-to-showcase-capture.md` once a runner is
+  on the table.
+- **P8.1 — End-to-end Level-6 smoke** — same gating as P6.1.
+  Structural coverage (`task smoke-quickstart` + decision-engine
+  schema validator + gate-evaluator unit tests) covers the
+  configuration surface deterministically; the live smoke remains
+  the manual pre-tag gate.
+
+## What stayed beta
+
+39 contracts carry `keep-beta-until: 2026-08-12` (next audit
+deadline). None met the 30-day promotion floor at audit time.
+First-commit age range: 0–12 days. Audit cap is 90 days from the
+audit date; CI rejects undated betas, multiple markers, and
+keep-beta-until dates beyond the window.
+
+## What got deferred to siblings
+
+- **Showcase capture** → future `road-to-showcase-capture.md` when a
+  hosted-LLM runner is on the table.
+- **Test-suite deletion** →
+  [`road-to-test-cleanup.md`](../../agents/roadmaps/road-to-test-cleanup.md)
+  (audit-only sibling spawned by P5.5; non-destructive by default).
+- **Persona Block B** (Architect / Risk-Officer extension) —
+  anti-recommended per the sibling closure decision; not deferred,
+  closed.
+- **Distribution / adoption** →
+  `road-to-distribution-and-adoption.md`, gated on this roadmap
+  closing (which this ADR records).
+- **MCP server work** — own strand, out of scope.
+
+## Consequences
+
+- **Steerable:** the Decision Engine now gates on configurable
+  thresholds; the configuration surface is documented and CI-tested.
+- **Provable:** memory hits/misses surface as `affected` keys in the
+  decision trace; the trace shape is contract-stable.
+- **Onboardable:** a fresh user can land at a working `/work`
+  invocation in three Quickstart steps without scrolling past the
+  fold.
+- **Multi-stack credible:** Laravel stays the deepest reference;
+  Symfony and Next.js shipped at workflow-grade depth; other stacks
+  remain project-analysis-only with the honest delta language in the
+  README.
+- **Architecturally tidy:** orchestrator commands no longer warn,
+  beta contracts cannot rot undated, and the contract surface itself
+  carries a periodic review obligation.

package/docs/contracts/adr-settings-sync-engine.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # ADR — Settings sync engine: stdlib-only round-trip

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

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # ADR — Wing-4 context-spine: Money / Strategy / Ops slot extension

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

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Agent-Memory Contract (as expected by `agent-config`)

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

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Tech stack — deep detail

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

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Audit-log v1

package/docs/contracts/command-clusters.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Command-cluster contract

package/docs/contracts/command-surface-tiers.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 

package/docs/contracts/context-paths.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Context-file path conventions

package/docs/contracts/cost-profile-defaults.md

@@ -0,0 +1,105 @@
+# Cost-Profile Defaults — Contract
+
+> **Status:** beta · **Owner:** package maintainer · **Last reviewed:** 2026-05-14
+>
+> Normative contract for the **default `cost_profile`** new installs receive.
+> Profile semantics themselves are documented in
+> [`docs/customization.md` § cost_profile](../customization.md) and
+> [`docs/contracts/rule-router.md`](rule-router.md); this file owns only the
+> **default-selection decision** and the rationale behind it.
+
+## Decision
+
+```
+DEFAULT_PROFILE = "balanced"
+```
+
+`scripts/install.py` and `npx @event4u/agent-config init` write
+`cost_profile: balanced` into `.agent-settings.yml` for fresh installs
+unless the user passes `--profile=minimal` or `--profile=full`.
+
+## Profile table
+
+| Profile | Contents | Token footprint | Use when |
+|---|---|---|---|
+| `minimal` | Kernel only (9 always-loaded Iron-Law rules, ≤ 26 k chars) | Lowest | Token-constrained agents (small context windows, free-tier models) or projects that opt out of routing |
+| **`balanced`** *(default)* | Kernel + tier-1 auto-rules (workflow + safety floor) | Medium | Every productized install — the documented "current behaviour superset" |
+| `full` | Kernel + tier-1 + tier-2 (every rule, every guideline-cited skill) | Highest | Teams running large-context models (Opus 4, GPT-5) that want maximum guardrail coverage |
+| `custom` | Ignore profile; every matrix value set explicitly | Variable | Power users tuning per-rule load decisions |
+
+## Why `balanced`, not `minimal`
+
+The kernel-only `minimal` profile predates the tier-1 router. It was the
+correct default while tier-1 was experimental, but four signals now point
+at `balanced`:
+
+1. **Documented intent already says so.** Both
+   `config/agent-settings.template.yml` (the source the installer projects
+   from) and `docs/customization.md` describe `balanced` as
+   "default — current behaviour superset". The code default of `minimal`
+   was a drift artifact, not a deliberate stance.
+2. **Productization (Level-6) demands sensible-default-out-of-the-box.**
+   A fresh `npx init` followed immediately by `/work` should engage the
+   full workflow guardrail set — `developer-like-execution`,
+   `verify-before-complete`, `minimal-safe-diff`, `scope-control`.
+   These live in tier-1, not the kernel. With `minimal`, the
+   work-engine runs unanchored against most quality guardrails.
+3. **Decision-engine gates assume tier-1 is present.** The P2.x gates
+   (`min_confidence`, `block_on_risk`, `require_memory_hits`) are
+   harmless under `minimal` but only reach their documented behaviour
+   under `balanced` and above — because the confidence model and
+   risk-classification rules they read live in tier-1.
+4. **Opt-out is cheap, opt-in is invisible.** A team that wants the
+   `minimal` floor flips one YAML value. A team that doesn't know
+   tier-1 exists never finds it. The default should err toward
+   guardrail coverage.
+
+## Opt-out path
+
+Token-budget pressure → flip in `.agent-settings.yml`:
+
+```yaml
+cost_profile: minimal
+```
+
+…or pass `--profile=minimal` to `npx @event4u/agent-config init`.
+No migration is required: removing tier-1 rules from a session has no
+state-machine impact because the kernel carries the Iron-Law floor.
+
+## Drift detection
+
+CI must keep three surfaces in sync:
+
+- `scripts/install.py` — `DEFAULT_PROFILE` constant.
+- `config/agent-settings.template.yml` — comment block on the
+  `cost_profile:` key.
+- `docs/customization.md` — cost-profile table default column.
+
+Reviewer guidance: a PR that changes any one of these must touch the
+other two **plus** this file's `Last reviewed:` field. The
+`docs-sync` rule enforces the cross-reference check; a missing update
+trips it.
+
+## Re-review schedule
+
+`re-review: 2026-11-14` (six months out). Triggers for earlier
+re-review:
+
+- Tier-1 rule count drops below 5 (the router would carry too little
+  to justify the load cost).
+- Median `npx init` token cost grows past 40 k for a fresh agent
+  session (then re-evaluate `minimal` as the default).
+- A consumer-project tally shows ≥ 80 % of installs override the
+  default within seven days (the default is wrong for the population).
+
+## Non-goals
+
+- This contract does **not** dictate what tier-1 contains. That belongs
+  to [`rule-router.md`](rule-router.md) and the `kernel-membership.md`
+  contract.
+- It does **not** add a fourth profile. `custom` covers the
+  per-tenant-tuning case; no new tier needed.
+- It does **not** auto-migrate existing installs. Projects already
+  pinned to `minimal` keep `minimal` until a developer edits the file
+  or runs `npx @event4u/agent-config migrate` (which preserves
+  user-set values per [`migration/v1-to-v2.md`](../migration/v1-to-v2.md)).

package/docs/contracts/cross-wing-handoff.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 

package/docs/contracts/decision-engine-gates.md

@@ -0,0 +1,115 @@
+# Decision-engine gates (v1)
+
+**Status:** beta — landed 2026-05-14 via `road-to-productization.md` Phase 2.
+**Owners:** `work_engine` maintainers.
+**Scope:** the optional `decision_engine:` block in `.agent-settings.yml`.
+
+## Purpose
+
+Cross the package from **observable** (Level-5) to **controllable**
+(Level-6). The engine has scored confidence-bands, risk-classes, and
+memory-hits since Phase 4 of `road-to-decision-trace`; this contract
+turns those signals into refusal gates the user opts into.
+
+Absent block = unchanged behaviour. Enforcement is opt-in only; the
+engine never silently halts on a signal the user did not configure.
+
+## Schema
+
+All keys optional. Unknown keys are rejected hard by
+`scripts/validate_decision_engine.py` and by
+`work_engine.scoring.decision_engine.parse`.
+
+| Key                    | Type            | Default | Notes |
+|------------------------|-----------------|---------|-------|
+| `surface_traces`       | bool            | `false` | Mirrored to `DecisionTraceHook`. Predates the gates; lives here so the block has one schema. |
+| `min_confidence`       | enum            | `off`   | `low` \| `medium` \| `high` \| `off`. Phase=Plan floor. |
+| `block_on_risk`        | enum            | `off`   | `low` \| `medium` \| `high` \| `off`. Phase=Implement ceiling. |
+| `require_memory_hits`  | bool            | `false` | Phase=Refine demands `memory_hits >= 1`. |
+| `on_block`             | enum            | `stop`  | `stop` \| `ask` \| `warn`. Action when a gate fires. |
+| `ask_timeout_seconds`  | int (>= 0)      | `30`    | Non-TTY wait before applying `on_block_fallback`. |
+| `on_block_fallback`    | enum            | `stop`  | `stop` \| `warn`. Resolution after `ask_timeout`. |
+
+## Gate-to-phase mapping
+
+Each gate fires on exactly one phase. The dispatcher emits gate
+decisions on `AFTER_STEP` for that phase only.
+
+| Gate                  | Phase     | Signal compared             | Fires when                          |
+|-----------------------|-----------|-----------------------------|-------------------------------------|
+| `min_confidence`      | Plan      | `confidence_band`           | actual < floor                      |
+| `require_memory_hits` | Refine    | `state.memory.hits`         | hits < 1                            |
+| `block_on_risk`       | Implement | `risk_class`                | actual >= ceiling                   |
+
+`low` < `medium` < `high` for both confidence and risk. `off` disables
+the gate.
+
+## Conflict matrix
+
+Only one gate fires per phase, so cross-phase conflicts are impossible
+by construction. Within a phase, **only the highest-impact gate
+applies**; downstream gates are evaluated against the same phase but
+skipped if a higher-priority gate already fired.
+
+Priority (highest → lowest):
+
+1. `block_on_risk` (Implement)
+2. `require_memory_hits` (Refine)
+3. `min_confidence` (Plan)
+
+This priority surfaces only when a future schema adds gates that
+overlap on the same phase; today each gate owns a unique phase and the
+priority is documentary. The order is locked so future additions
+inherit the contract.
+
+### Worked examples
+
+| Config                                                                                | Phase     | confidence | risk     | hits | Outcome                          |
+|---------------------------------------------------------------------------------------|-----------|------------|----------|------|----------------------------------|
+| `min_confidence: medium`                                                              | Plan      | `low`      | -        | -    | `min_confidence` fires, action=stop |
+| `min_confidence: medium`                                                              | Plan      | `high`     | -        | -    | no fire — band at/above floor    |
+| `block_on_risk: medium`                                                               | Implement | -          | `high`   | -    | `block_on_risk` fires, action=stop |
+| `block_on_risk: high`                                                                 | Implement | -          | `medium` | -    | no fire — below ceiling          |
+| `require_memory_hits: true`                                                           | Refine    | -          | -        | 0    | `require_memory_hits` fires      |
+| `require_memory_hits: true`                                                           | Refine    | -          | -        | 2    | no fire                          |
+| `min_confidence: high, block_on_risk: low, require_memory_hits: true` (all on)        | Plan      | `low`      | `low`    | 0    | `min_confidence` fires (Plan-owning gate) — Refine/Implement gates inert this phase |
+
+## Non-TTY timeout protocol
+
+`on_block=ask` is interactive. In a non-interactive context the
+engine cannot block waiting for keystrokes that will never arrive.
+Detection follows two signals (either disables interactivity):
+
+- environment variable `CI` set to `1`, `true`, `yes` (case-insensitive)
+- `sys.stdin.isatty()` or `sys.stdout.isatty()` returns false
+
+When non-interactive, `on_block=ask` collapses to action `ask_timeout`.
+The consumer (CLI / dispatcher) is expected to:
+
+1. wait `ask_timeout_seconds` for a stdin response;
+2. apply `on_block_fallback` (`stop` or `warn`) when the timeout
+   elapses or stdin is closed;
+3. surface `block_reason=ask_timeout` on the decision trace so the
+   reason is replay-visible.
+
+Default fallback is `stop` (fail-safe). Flip to `warn` only when CI
+explicitly wants advisory gates.
+
+## Rollback
+
+The block is config-only. Remove the `decision_engine:` block and
+the engine reverts to observe-only behaviour — no migration, no DB
+state, no schema lock. Per-key removal also works (each key has a
+safe default).
+
+## Test surface
+
+Coverage lives in `tests/work_engine/scoring/test_decision_engine.py`:
+
+- schema parser: defaults, unknown-key rejection, bad-type rejection;
+- gate evaluation: per-phase, per-signal, conflict isolation;
+- TTY detection: env-var detection, fallback to `ask_timeout`;
+- action resolution: `stop` / `warn` short-circuit interactivity.
+
+Wiring tests (dispatcher + hook) live in
+`tests/work_engine/test_decision_gate_hook.py`.

package/docs/contracts/decision-trace-v1.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Decision-trace v1

package/docs/contracts/file-ownership-matrix.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # File-ownership matrix