@event4u/agent-config 2.9.0 → 2.11.0

package/.agent-src/templates/scripts/work_engine/scoring/memory_visibility.py

@@ -4,6 +4,12 @@ Implements the v1 line shape from
 ``docs/contracts/memory-visibility-v1.md``:
 
     🧠 Memory: <hits>/<asks> · ids=[<comma-separated-ids>]
+    🧠 Memory: <hits>/<asks> · ids=[<...>] · affected: <keys>
+
+The optional ``· affected: <keys>`` trailing segment surfaces which
+closed-list decision-trace keys diverged because memory was
+consulted — see ``docs/contracts/decision-trace-v1.md`` "Memory
+consequence keys".
 
 The semantics matched to the work-engine model:
 
@@ -23,6 +29,8 @@ from __future__ import annotations
 
 from typing import Any, Iterable
 
+from .decision_trace import derive_confidence_band, derive_risk_class
+
 ICON = "\U0001F9E0"  # 🧠
 DEFAULT_MAX_INLINE_IDS = 5
 DEFAULT_ASKED_TYPES = (
@@ -32,6 +40,13 @@ DEFAULT_ASKED_TYPES = (
     "historical-patterns",
 )
 
+CONSEQUENCE_KEYS: tuple[str, ...] = (
+    "confidence_band",
+    "risk_class",
+    "applied_rules",
+    "test_plan",
+)
+
 
 def summarise_visibility(
     memory: Any,
@@ -69,16 +84,111 @@ def summarise_visibility(
     return {"asks": asks, "hits": hits, "ids": ids}
 
 
+def _normalise_key_value(value: Any) -> Any:
+    """Return a comparable shape for a consequence-key value.
+
+    List-shaped keys (``applied_rules``, ``test_plan``) compare as
+    sorted tuples so order is not a divergence; scalar keys
+    (``confidence_band``, ``risk_class``) compare as-is.
+    """
+    if isinstance(value, list):
+        return tuple(sorted(str(item) for item in value))
+    return value
+
+
+def diff_consequence_keys(
+    trace_with: dict[str, Any], trace_without: dict[str, Any],
+) -> list[str]:
+    """Return sorted keys whose values diverge between two traces.
+
+    Iterates the closed ``CONSEQUENCE_KEYS`` list defined in
+    ``docs/contracts/decision-trace-v1.md``. A key is considered
+    *diverged* when its normalised value differs between the two
+    traces. Per the contract, when both sides are ``None`` the key
+    is suppressed from the diff entirely.
+    """
+    affected: list[str] = []
+    for key in CONSEQUENCE_KEYS:
+        a = trace_with.get(key)
+        b = trace_without.get(key)
+        if a is None and b is None:
+            continue
+        if _normalise_key_value(a) != _normalise_key_value(b):
+            affected.append(key)
+    return sorted(affected)
+
+
+def compute_affected(
+    *,
+    memory_hits: int,
+    verify_claims: int = 0,
+    verify_first_try_passes: int = 0,
+    ambiguity_flag: bool = False,
+    changes: Any = None,
+    applied_rules: list[str] | None = None,
+    test_plan: list[str] | None = None,
+) -> list[str] | None:
+    """Compute the ``affected`` consequence keys for the visibility line.
+
+    Returns:
+        * ``None`` when no memory was consulted (``memory_hits <= 0``)
+          — caller MUST omit the ``· affected: …`` segment.
+        * ``[]`` when memory was consulted but no closed-list key
+          diverged — caller MUST render ``· affected: none``.
+        * sorted list of keys otherwise.
+
+    The counterfactual trace is "what the heuristics would have
+    emitted if ``memory_hits`` had been ``0``". v1 covers
+    ``confidence_band`` and ``risk_class`` via the existing scoring
+    helpers; ``applied_rules`` and ``test_plan`` pass through
+    unchanged because they are not yet memory-derived in the
+    engine — the keys stay in the closed list so the diff
+    infrastructure is in place when they wire in.
+    """
+    if memory_hits <= 0:
+        return None
+    trace_with = {
+        "confidence_band": derive_confidence_band(
+            memory_hits=memory_hits,
+            verify_claims=verify_claims,
+            verify_first_try_passes=verify_first_try_passes,
+            ambiguity_flag=ambiguity_flag,
+        ),
+        "risk_class": derive_risk_class(changes),
+        "applied_rules": list(applied_rules) if applied_rules else None,
+        "test_plan": list(test_plan) if test_plan else None,
+    }
+    trace_without = {
+        "confidence_band": derive_confidence_band(
+            memory_hits=0,
+            verify_claims=verify_claims,
+            verify_first_try_passes=verify_first_try_passes,
+            ambiguity_flag=ambiguity_flag,
+        ),
+        "risk_class": derive_risk_class(changes),
+        "applied_rules": list(applied_rules) if applied_rules else None,
+        "test_plan": list(test_plan) if test_plan else None,
+    }
+    return diff_consequence_keys(trace_with, trace_without)
+
+
 def format_line(
     summary: dict[str, Any],
     *,
     max_inline_ids: int = DEFAULT_MAX_INLINE_IDS,
+    affected: list[str] | None = None,
 ) -> str | None:
     """Render the visibility line; return ``None`` when ``asks == 0``.
 
     Cap inline ids at ``max_inline_ids`` and append ``…+N`` when the
     list is longer. Returning ``None`` enforces the contract clause
     "If ``asks == 0``, the engine MUST suppress the line entirely".
+
+    When ``affected`` is not ``None``, append the
+    ``· affected: <keys>`` trailing segment from
+    ``docs/contracts/memory-visibility-v1.md``: empty list renders as
+    ``affected: none`` (consulted but no key diverged);
+    non-empty list renders the comma-separated keys.
     """
     asks = int(summary.get("asks", 0) or 0)
     if asks <= 0:
@@ -94,7 +204,39 @@ def format_line(
     if overflow > 0:
         suffix = ", " if rendered_ids else ""
         rendered_ids = f"{rendered_ids}{suffix}\u2026+{overflow}"
-    return f"{ICON} Memory: {hits}/{asks} \u00b7 ids=[{rendered_ids}]"
+    line = f"{ICON} Memory: {hits}/{asks} \u00b7 ids=[{rendered_ids}]"
+    if affected is not None:
+        rendered_affected = ",".join(affected) if affected else "none"
+        line = f"{line} \u00b7 affected: {rendered_affected}"
+    return line
+
+
+def format_changed_decisions_block(
+    ids: Iterable[str], affected: Iterable[str] | None,
+) -> str | None:
+    """Render the end-of-run "Memory changed decisions" report block.
+
+    Per ``docs/contracts/memory-visibility-v1.md``: lists
+    ``<id> → <key>`` rows derived from the same diff source as the
+    visibility line's ``affected`` segment. Returns ``None`` when
+    no key diverged (``affected`` empty / ``None``) so the caller
+    suppresses the block entirely.
+
+    Attribution in v1 is aggregate: each consulted id pairs with
+    each affected key. Per-id attribution is captured as a
+    follow-up risk in the roadmap Risk register.
+    """
+    if not affected:
+        return None
+    affected_list = sorted(affected)
+    id_list = [str(i) for i in ids if isinstance(i, (str, int))]
+    if not id_list:
+        return None
+    lines = ["Memory changed decisions:"]
+    for entry_id in id_list:
+        for key in affected_list:
+            lines.append(f"- {entry_id} \u2192 {key}")
+    return "\n".join(lines)
 
 
 def should_emit(
@@ -116,9 +258,13 @@ def should_emit(
 
 
 __all__ = [
+    "CONSEQUENCE_KEYS",
     "DEFAULT_ASKED_TYPES",
     "DEFAULT_MAX_INLINE_IDS",
     "ICON",
+    "compute_affected",
+    "diff_consequence_keys",
+    "format_changed_decisions_block",
     "format_line",
     "should_emit",
     "summarise_visibility",

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "2.9.0",
+    "version": "2.11.0",
     "keywords": [
       "agent-config",
       "skills",
@@ -219,6 +219,7 @@
         "./.claude/skills/module-explore",
         "./.claude/skills/module-management",
         "./.claude/skills/multi-tenancy",
+        "./.claude/skills/nextjs-patterns",
         "./.claude/skills/okr-tree-modeling",
         "./.claude/skills/onboard",
         "./.claude/skills/onboarding-design",
@@ -316,6 +317,7 @@
         "./.claude/skills/sql-writing",
         "./.claude/skills/stakeholder-tradeoff",
         "./.claude/skills/subagent-orchestration",
+        "./.claude/skills/symfony-workflow",
         "./.claude/skills/sync-agent-settings",
         "./.claude/skills/sync-gitignore",
         "./.claude/skills/sync-gitignore-fix",

package/CHANGELOG.md

@@ -429,6 +429,71 @@ our recommendation order, not its support status.
 > that forces a new era split (`# Era: 2.8.x`, etc.) — see
 > [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
+## [2.11.0](https://github.com/event4u-app/agent-config/compare/2.10.0...2.11.0) (2026-05-14)
+
+### Features
+
+* **stability:** add beta-review marker protocol and CI gate (P5.4) ([9b6cdfe](https://github.com/event4u-app/agent-config/commit/9b6cdfe9f9167e3e80551dfa2a88f80fff85646a))
+* **lint:** add 'type: orchestrator' frontmatter tag for cluster routers (P5.3) ([e6385bb](https://github.com/event4u-app/agent-config/commit/e6385bbaf022dc3763f55c2dd54fe85046c59fd4))
+* **skills:** add nextjs-patterns and symfony-workflow workflow skills (P4) ([038522b](https://github.com/event4u-app/agent-config/commit/038522b7ad2bd2ba1d8d8c4f9a61692694b7ebc8))
+* **onboard:** add Quickstart pointer step and surface balanced default (P3.3) ([5879b4c](https://github.com/event4u-app/agent-config/commit/5879b4cc66fc9f49fa42c99e72794e4c60f43739))
+* **install:** default cost_profile to balanced (P3.2) ([75caac2](https://github.com/event4u-app/agent-config/commit/75caac20fa2986222b5bd45a7cb63f07f9c4179f))
+* **work-engine:** wire decision_gate hook into runner ([c41a89d](https://github.com/event4u-app/agent-config/commit/c41a89d38c7eb4892358b5c931abbe9a5889038c))
+* **work-engine:** add decision_engine schema and gate evaluator ([fd1e8e2](https://github.com/event4u-app/agent-config/commit/fd1e8e2bb2e45e2288727ccd4a3bda4f809c6151))
+* **release:** release-trunk-sync contract and CI gate (P1.2, P1.3) ([a3e0d12](https://github.com/event4u-app/agent-config/commit/a3e0d12c156c367c995e84c7c0bb5d6a21ff6325))
+
+### Bug Fixes
+
+* **readme:** rename 'For contributors' to 'Development' for linter ([7957274](https://github.com/event4u-app/agent-config/commit/7957274c65895d80fa4801f95df876979362ee86))
+
+### Documentation
+
+* **roadmap:** close + archive road-to-productization (Level-6) ([7ee50e8](https://github.com/event4u-app/agent-config/commit/7ee50e8b16f1ce7d4461f1466d9a6e46f4138101))
+* **roadmap:** mark P3.1-P3.3 + P3.1a done in road-to-productization ([b0ff24f](https://github.com/event4u-app/agent-config/commit/b0ff24f23cb38d4ac556106c9ed060f104f83c8c))
+* **readme:** add 3-step Quickstart and move contributor detail below the fold (P3.1) ([b98152e](https://github.com/event4u-app/agent-config/commit/b98152eb86607d6b34f63ea9ad4c152951de58a6))
+* **roadmap:** mark P2.1-P2.3 done in road-to-productization ([189c780](https://github.com/event4u-app/agent-config/commit/189c780faef19cfbd9bceb3ad51ec42cb8cb05b7))
+
+### CI
+
+* **install:** add structural Quickstart smoke test (P3.1a) ([228445b](https://github.com/event4u-app/agent-config/commit/228445b97eefb20118bbea2872640c54225a1355))
+* **work-engine:** validate decision_engine block in agent-settings ([1a1f428](https://github.com/event4u-app/agent-config/commit/1a1f428bec4832f8ffb222a8b450719ba6409605))
+
+### Chores
+
+* **generate-tools:** expose nextjs-patterns + symfony-workflow skills ([3422ac7](https://github.com/event4u-app/agent-config/commit/3422ac7e3f273497a0cbb176b2580a0cf1256522))
+* **sync:** align orchestrator frontmatter + hash registry ([0e9ba2d](https://github.com/event4u-app/agent-config/commit/0e9ba2d50463ca99baf86651ea67ed82ca63d7f6))
+* **gitignore:** ignore python coverage artifacts ([e1a3289](https://github.com/event4u-app/agent-config/commit/e1a328921f08fad03325adc256b63a544582efb7))
+
+Tests: 3718 (+55 since 2.10.0)
+
+## [2.10.0](https://github.com/event4u-app/agent-config/compare/2.9.0...2.10.0) (2026-05-14)
+
+### Features
+
+* **ci:** lint-hook-concern-budget Tier-1 fail-closed gate ([8d60b8a](https://github.com/event4u-app/agent-config/commit/8d60b8ab464c4c5bdc6d072bb2a9b0123942e13b))
+* **cli:** settings:check command + YAML subset contract ([638e740](https://github.com/event4u-app/agent-config/commit/638e74017ffea8d7c08073a949e86fde047db109))
+* **hooks:** hooks:doctor + hooks:replay subcommands + fixture corpus ([3156e25](https://github.com/event4u-app/agent-config/commit/3156e25fd3253fc926a57b92e14b407a9ed54b58))
+* **work-engine:** add decision-trace memory_visibility hook + scoring ([bf056ac](https://github.com/event4u-app/agent-config/commit/bf056ace877a696afa5fe758053ea1eb350e5dff))
+
+### Bug Fixes
+
+* **roadmap:** point productization P6 gate at archived proof-not-features path ([35a1009](https://github.com/event4u-app/agent-config/commit/35a1009cffdfde28c7b0384c890c31a7e62b70cf))
+
+### Documentation
+
+* **roadmap:** complete road-to-proof-not-features 16/16 + sync dashboard ([89af72d](https://github.com/event4u-app/agent-config/commit/89af72d5514b74c19d533b5a2e69ff7ddf16ecbc))
+* **readme:** split README by audience + audience-order contract ([60a87c0](https://github.com/event4u-app/agent-config/commit/60a87c056555a80585d25555f3d5b87d54c7283a))
+
+### Refactoring
+
+* **check-council-references:** structural carve-outs for immutable inputs and decision provenance ([3ed7784](https://github.com/event4u-app/agent-config/commit/3ed77841c42c5e3ebf4191611bb7fa4a52ed2fa0))
+
+### Chores
+
+* **roadmap:** archive road-to-proof-not-features (16/16 done, Phase 1 deferred) ([9d05aed](https://github.com/event4u-app/agent-config/commit/9d05aed79a46023b1e95c5488a1e3d5e78748e67))
+
+Tests: 3663 (+60 since 2.9.0)
+
 ## [2.9.0](https://github.com/event4u-app/agent-config/compare/2.8.0...2.9.0) (2026-05-13)
 
 ### Features

package/README.md

@@ -7,24 +7,68 @@ 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>
 
 ---
 
-## Start here
+## Use it in your project
+
+You run the package from a consumer repo — bootstrap via `npx`, let the
+agent pick up your stack, and ship work end-to-end. New install? Start
+with the [Quickstart](#quickstart) to write `.agent-settings.yml`,
+`.augment/`, `.claude/`, …. Already installed? [Supported Tools](#supported-tools)
+shows which AIs the package wires up, and [Featured Commands](#featured-commands)
+lists the end-to-end workflows (`/implement-ticket`, `/work`, `/commit`,
+`/create-pr`). For a deeper tour, see the
+[2-minute demo: `/implement-ticket`](#2-minute-demo-implement-ticket).
+
+## Prove it
+
+The package is audit-disciplined by construction — every memory consult,
+decision key, and hook concern lands in `agents/state/` so you can
+replay it. [Core Principles](#core-principles) names the four invariants.
+[What this package is — and what it isn't](#what-this-package-is--and-what-it-isnt)
+draws the scope boundary. [Documentation](#documentation) lists the
+contracts the package ships against, including
+[`memory-visibility-v1`](docs/contracts/memory-visibility-v1.md) and
+[`decision-trace-v1`](docs/contracts/decision-trace-v1.md).
+
+## Contribute
+
+Working on the package itself rather than with it?
+[Development](#development) covers the `task ci` pipeline,
+[Requirements](#requirements) the toolchain, and
+[Maintainer telemetry](#maintainer-telemetry-opt-in-default-off) the
+opt-in measurement loop. The source-of-truth tree is
+`.agent-src.uncompressed/`; never hand-edit the generated `.augment/`
+or `.agent-src/`.
 
-Three ways in, depending on what you're doing today:
+## Quickstart
 
-| Path | Audience | What it does |
-|---|---|---|
-| **[`/onboard`](.agent-src/commands/onboard.md)** | New user, fresh install | Captures name, IDE, rtk, and cost profile; sets `onboarding.onboarded=true` |
-| **[`task ci`](docs/development.md#ci--verification)** | Contributor working **on** this package | Runs the full sync + lint + test pipeline; must be green before push |
-| **[`task generate-tools`](docs/development.md#tool-generation)** | Multi-agent user / consumer project | Rebuilds `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules` from the source |
+**Three steps. Five minutes. Decision-traced first task.**
 
-If none of those apply yet — start with the [Quickstart](#quickstart) and pick a path once it's installed.
+```bash
+# 1. Install (writes .agent-settings.yml, .augment/, .claude/, …)
+npx @event4u/agent-config init
 
-## Quickstart
+# 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.
@@ -431,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.
 
 ---
 
@@ -510,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
@@ -632,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

@@ -390,6 +390,91 @@ memory:
   # Example: ["api[_-]?key", "/Users/[a-z]+/Library"]
   redact_patterns: []
 
+# --- Hooks ---
+#
+# Configuration surface for the hook dispatcher (see
+# docs/contracts/hook-architecture-v1.md). Each subkey targets one
+# concern script under scripts/hooks/ or scripts/. Defaults are safe;
+# tune only when CI surfaces a real signal.
+hooks:
+  # Concern budget gate (P3.3, lint_hook_concern_budget.py). Caps how
+  # many concerns may bind to a single (platform, event) cell and
+  # restricts fail_closed=true to an explicit Tier-1 allowlist.
+  #
+  # max_per_event — placeholder until Phase 1 of
+  # road-to-proof-not-features.md captures real session evidence.
+  # Threshold rule per roadmap: max(observed-in-Phase-1) × 1.5, rounded
+  # up. 8 = current-observed-max (5) × 1.5 = 7.5 → 8.
+  #
+  # tier1_concerns — concerns allowed to block agent execution on
+  # failure (fail_closed: true in the manifest). Promotion is explicit
+  # opt-in; keep empty until Phase 1 evidence justifies an entry.
+  #
+  # hard_fail — false = warn-only (default). Flip to true after ≥10
+  # captured sessions across host agents per
+  # road-to-distribution-and-adoption.md.
+  concern_budget:
+    max_per_event: 8
+    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