@event4u/agent-config 1.18.0 → 1.19.0

package/README.md

@@ -14,13 +14,15 @@ Give your AI agents an audit-disciplined orchestration contract — testing, Git
 
 ## Start here
 
-New to agent-config? 60 seconds, three links:
+Three ways in, depending on what you're doing today:
 
-1. **[Install](#quickstart)** — `composer require` or `npm install`, then run the installer.
-2. **[First command](#2-minute-demo-implement-ticket)** — `/implement-ticket` or `/work` walkthrough.
-3. **[Where the rules live](#documentation)** — `.augment/`, `.claude/`, `.cursor/`, and friends.
+| 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 |
 
----
+If none of those apply yet — start with the [Quickstart](#quickstart) and pick a path once it's installed.
 
 ## Quickstart
 
@@ -63,6 +65,14 @@ project-locally for all supported AI tools. Task is required for
 *contributors* who want to rebuild the compressed content locally — see
 [CONTRIBUTING.md](CONTRIBUTING.md).
 
+**Verify hook coverage** after installing — every supported platform
+(Augment, Claude, Cursor, Cline, Windsurf, Gemini CLI, Copilot fallback)
+is wired through one universal dispatcher per
+[`hook-architecture-v1`](docs/contracts/hook-architecture-v1.md). Run
+`./agent-config hooks:status` for the matrix (`--strict` for CI,
+`--format json` for tooling). The installer also dry-fires the
+dispatcher per bridge as a post-install smoke test (skip: `--no-smoke`).
+
 ### For individual use (optional)
 
 Install directly in your agent for global, cross-project use:
@@ -479,20 +489,10 @@ task lint-skills   # Lint skills, rules, commands
 
 ## Requirements
 
-**To install the package into a consumer project:**
-
-- **Bash** — primary installer is `scripts/install`, orchestrating
-  `scripts/install.sh` (payload sync) and `scripts/install.py` (bridges).
-  Available on macOS, Linux, and WSL.
-- **Python 3.10+** — required for the bridge stage only. Pre-installed
-  on macOS 12.3+ and all major Linux distros. If missing, the
-  orchestrator skips bridges and completes the payload sync.
-- **Composer or npm** — to pull the package itself.
-
-**Platform support:** macOS 12.3+, Linux (modern distros), and Windows
-(WSL2) are fully supported. Git Bash works but symlinks require
-Developer Mode; native PowerShell / cmd is not supported. Contributors
-rebuilding `.augment/` locally also need [Task](https://taskfile.dev/).
+- **Bash** — `scripts/install` orchestrates payload sync (`install.sh`) and bridges (`install.py`).
+- **Python 3.10+** — bridge stage only; missing → orchestrator skips bridges.
+- **Composer or npm** — to pull the package.
+- **Platform:** macOS 12.3+, Linux, WSL2. Git Bash needs Developer Mode for symlinks; native PowerShell / cmd unsupported. Contributors rebuilding `.augment/` also need [Task](https://taskfile.dev/).
 
 ## License
 

package/config/agent-settings.template.yml

@@ -121,6 +121,24 @@ pipelines:
   # want a silent agent; `custom` profile ignores this default entirely.
   skill_improvement: true
 
+# --- Roadmap execution ---
+#
+# Controls when /roadmap execute runs the project's quality pipeline
+# (the `task ci` / `make test` / `npm run check` style command).
+# Steps are ALWAYS marked `[x]` and the dashboard is ALWAYS regenerated
+# in the same response — that cadence is governed by `roadmap-progress-sync`
+# and is non-negotiable. This setting only governs *quality tool runs*.
+roadmap:
+  # When to run quality tools during /roadmap execute.
+  #   end_of_roadmap = once, before archiving the completed roadmap (default — fastest, fewest tokens)
+  #   per_phase      = once after every completed phase
+  #   per_step       = after every completed step (legacy verbose; highest token cost)
+  # Trade-off: end_of_roadmap saves tokens and time but lets errors compound
+  # across phases. Pick per_phase if the work is risky or unfamiliar.
+  # Iron Law `verify-before-complete` still applies — fresh quality output
+  # is mandatory before any "roadmap complete" claim regardless of cadence.
+  quality_cadence: end_of_roadmap
+
 # --- Subagent orchestration ---
 #
 # Controls model selection and parallelism for subagent-based workflows
@@ -195,6 +213,11 @@ ai_council:
     max_calls: 10
     max_total_usd: 0.50
 
+  # Retention for `agents/council-sessions/` audit folders. Sessions
+  # older than this are pruned automatically on the next `save()`.
+  # `0` disables pruning (keep forever — disk grows unbounded).
+  session_retention_days: 14
+
 # --- Onboarding ---
 #
 # Tracks whether the initial setup flow (/onboard) has been completed

package/docs/catalog.md

@@ -1,6 +1,6 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **327 public artefacts** shipped by
+Consumer-facing catalog of all **330 public artefacts** shipped by
 this package. Internal package-maintenance rules and deprecation shims
 are excluded.
 
@@ -301,14 +301,16 @@ are excluded.
 | command | [`upstream-contribute`](../.agent-src/commands/upstream-contribute.md) |  | Contribute a learning, skill, rule, or fix from a consumer project back to the shared agent-config package |
 | command | [`work`](../.agent-src/commands/work.md) |  | Drive a free-form prompt end-to-end through refine → score → plan → implement → test → verify → report — Option-A loop over the `work_engine` Python engine, confidence-band gated, no auto-git. |
 
-## Guidelines (48)
+## Guidelines (51)
 
 | kind | name | category | description |
 |---|---|---|---|
 | guideline | [`agent-interaction-and-decision-quality`](../docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md) | agent-infra |  |
+| guideline | [`ask-when-uncertain-demos`](../docs/guidelines/agent-infra/ask-when-uncertain-demos.md) | agent-infra |  |
 | guideline | [`asking-and-brevity-examples`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md) | agent-infra |  |
 | guideline | [`break-glass-usage`](../docs/guidelines/agent-infra/break-glass-usage.md) | agent-infra |  |
 | guideline | [`developer-judgment`](../docs/guidelines/agent-infra/developer-judgment.md) | agent-infra |  |
+| guideline | [`direct-answers-demos`](../docs/guidelines/agent-infra/direct-answers-demos.md) | agent-infra |  |
 | guideline | [`engineering-memory-data-format`](../docs/guidelines/agent-infra/engineering-memory-data-format.md) | agent-infra |  |
 | guideline | [`language-and-tone-examples`](../docs/guidelines/agent-infra/language-and-tone-examples.md) | agent-infra |  |
 | guideline | [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md) | agent-infra |  |
@@ -322,6 +324,7 @@ are excluded.
 | guideline | [`self-improvement-pipeline`](../docs/guidelines/agent-infra/self-improvement-pipeline.md) | agent-infra |  |
 | guideline | [`size-and-scope`](../docs/guidelines/agent-infra/size-and-scope.md) | agent-infra |  |
 | guideline | [`tool-integration`](../docs/guidelines/agent-infra/tool-integration.md) | agent-infra |  |
+| guideline | [`verify-before-complete-demos`](../docs/guidelines/agent-infra/verify-before-complete-demos.md) | agent-infra |  |
 | guideline | [`readme-size-and-splitting`](../docs/guidelines/docs/readme-size-and-splitting.md) | docs |  |
 | guideline | [`playwright`](../docs/guidelines/e2e/playwright.md) | e2e |  |
 | guideline | [`api-design`](../docs/guidelines/php/api-design.md) | php |  |

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

@@ -0,0 +1,127 @@
+---
+stability: beta
+---
+
+# ADR — Settings sync engine: stdlib-only round-trip
+
+> **Status:** Decided · 2026-05-04
+> **Context:** Additive Settings Sync roadmap — review round 2
+> (Self-Review + AI Council, Anthropic + OpenAI) flagged the
+> 735-line `scripts/sync_yaml_rt.py` as potential NIH burden vs.
+> adopting `ruamel.yaml` as a third-party dependency.
+> **Builds on:** [`docs/guidelines/agent-infra/layered-settings.md`](../guidelines/agent-infra/layered-settings.md)
+> § Sync rules — defines the additive-merge-with-user-line-preservation
+> contract this engine implements.
+
+## Decision
+
+`.agent-settings.yml` synchronization uses a **custom, stdlib-only
+round-trip parser + emitter** in [`scripts/sync_yaml_rt.py`](../../scripts/sync_yaml_rt.py),
+not `ruamel.yaml` or any other third-party YAML library.
+
+The engine implements a narrow YAML subset (block-mappings, scalars,
+flow-list values, comments, CRLF/LF) that covers the full surface of
+`.agent-settings.yml` plus its template (`config/agent-settings.template.yml`).
+Out-of-subset YAML — anchors, aliases, multi-document streams, complex
+keys, nested flow mappings — is **not supported** and raises `ValueError`.
+
+The merge layer (additive walk, max-index insertion, scalar→section
+guard, healer for legacy `_user._user.foo` corruption, EOL
+normalization) sits on top of the parser and is custom regardless of
+the parser choice.
+
+## Why this was a real question
+
+Three options were on the table:
+
+1. **`ruamel.yaml` for parse + emit, custom merge on top.** Rejected.
+2. **`PyYAML` for parse, custom emitter for round-trip.** Rejected
+   earlier in the roadmap — PyYAML's parser drops comments and
+   formatting before the merger ever sees them.
+3. **Custom stdlib-only parser + emitter + merger.** Chosen.
+
+### Why ruamel.yaml does not match the contract
+
+The driving requirement from `layered-settings.md` is **verbatim
+user-line preservation** — every byte of every line in the user's
+file is preserved unless that line carries a key the merger is
+explicitly editing. Tests pin this contract by asserting byte-identity
+across two consecutive sync runs (`test_user_block_round_trip_is_idempotent`,
+`test_three_level_idempotent`).
+
+`ruamel.yaml` is a round-trip-aware library, not a verbatim one — it
+re-parses into an in-memory model and **re-emits** through its own
+emitter. This re-emit normalizes:
+
+| Behavior | ruamel.yaml | Custom engine |
+|---|---|---|
+| User-line bytes (whitespace, quoting, blanks) | re-emitted, may shift | preserved 1:1 |
+| Mixed CRLF/LF in user file | normalized to one EOL (typically platform default) | detected + normalized to the user's predominant EOL |
+| `personal: null` blocking template-section injection | requires custom merge logic regardless | scalar guard in `_merge_into` |
+| Legacy `_user._user.foo.bar` healer (one-off migration) | requires custom logic regardless | `heal_user_block` |
+| Synthetic header rendering for newly-inserted template keys | re-emits the entire file | only renders the new subtree |
+| Unknown user blocks at top level | preserved as data, but indent / quoting may shift on emit | preserved verbatim |
+| 3rd-party dependency in distribution package | +1 (`ruamel.yaml` + transitive `ruamel.yaml.clib`) | 0 |
+
+The rows where the libraries diverge are exactly the rows the test
+suite asserts on.
+
+### Cost analysis
+
+| Axis | Custom engine | ruamel.yaml |
+|---|---|---|
+| Lines of code | 735 (engine) + 335 (merge/heal) = 1070 | ~400 (parser+emitter saved) + 335 (merge/heal stays) + adapter glue = ~735 |
+| Net code saved | — | ~335 lines |
+| 3rd-party deps | 0 | +2 (`ruamel.yaml`, `ruamel.yaml.clib`) |
+| Runtime YAML surface | narrow (documented subset) | full YAML 1.2 |
+| Verbatim guarantee | yes | no |
+| Performance | irrelevant — cold-path, runs on profile change | irrelevant |
+
+The 335-line saving is real but offset by a stronger contract (verbatim)
+and a 0-dep posture. The package is a distribution-layer library
+(`composer.json` `type: library`, `package.json` thin manifest); it
+already restricts itself to stdlib for portability across consumer
+projects, several of which lock Python deps tightly.
+
+## Consequences
+
+- **Maintenance:** the engine must keep covering the YAML subset its
+  template + user files exercise. Any new template feature (e.g. a
+  block-style nested list) is a parser change, not a config change.
+- **Error surface:** YAML outside the subset (anchors, complex keys)
+  surfaces as a friendly `ValueError` from `_rt.sync()`, caught by
+  `sync_agent_settings.main` and turned into exit code 2 with a
+  user-readable message. Documented in
+  `tests/test_sync_agent_settings.py::test_malformed_user_yaml_exits_2_with_message`.
+- **Test debt:** `tests/test_sync_round_trip.py` (34 tests) and
+  `tests/test_sync_agent_settings.py` (15 tests) are the contract.
+  Any parser change must keep those green and is the entry point
+  for new fixtures under `tests/fixtures/sync_yaml_rt/`.
+
+## Revisit triggers
+
+This decision is revisited (new ADR with successor link) when **any**
+of the following holds:
+
+1. `.agent-settings.yml` schema gains a YAML feature outside the
+   supported subset (anchors, multi-doc, complex keys, nested flow
+   mappings) — the cost of extending the parser exceeds the cost of
+   adopting ruamel.
+2. The verbatim-preservation contract is relaxed (e.g. consumers
+   accept that sync can re-format) — the driver for the custom engine
+   is gone.
+3. The 0-dep posture for Python tooling is dropped at the package level
+   — the marginal cost of one more dep collapses.
+4. A maintenance bug surfaces in the engine that would have been
+   prevented by ruamel's mature spec coverage.
+
+## See also
+
+- [`docs/guidelines/agent-infra/layered-settings.md`](../guidelines/agent-infra/layered-settings.md)
+  § Sync rules — the contract this engine implements.
+- [`scripts/sync_yaml_rt.py`](../../scripts/sync_yaml_rt.py) module
+  docstring — the supported YAML subset, listed exhaustively.
+- `tests/test_sync_round_trip.py` — verbatim, scalar-guard, healer,
+  CRLF, and synthetic-header pinning.
+- `tests/test_sync_agent_settings.py` — CLI integration, profile
+  override, malformed-input exit code.

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

@@ -0,0 +1,146 @@
+---
+stability: beta
+---
+
+# Decision-trace v1
+
+**Purpose.** Pin the JSON shape that `/implement-ticket` and `/work`
+runs emit when the user opts into trace surfacing. The trace is the
+audit substrate for the rule-interaction matrix
+([`rule-interactions.md`](rule-interactions.md)) and feeds the
+showcase-session capture pipeline
+([`outcome-baseline.md`](../../agents/contexts/outcome-baseline.md)).
+
+**Scope.** Defines the JSON envelope written next to a `WorkState`
+file when `decision_engine.surface_traces: true`. Does **not**
+specify how individual rules detect their own activation — that is
+the rule's own responsibility — only the shape of the report.
+
+Last refreshed: 2026-05-04.
+
+## Opt-in
+
+Off by default. Toggled in `.agent-settings.yml`:
+
+```yaml
+decision_engine:
+  surface_traces: true
+```
+
+The `/work` and `/implement-ticket` engines check this flag at phase
+boundaries and emit one trace file per phase when set.
+
+## File location
+
+```
+agents/state/work/<work-id>/decision-trace-<phase>.json
+```
+
+`work-id` matches the `WorkState` directory; `phase` is one of
+`refine`, `memory`, `analyze`, `plan`, `implement`, `test`, `verify`,
+`report`. Files are gitignored.
+
+## Envelope shape
+
+```json
+{
+  "schema_version": 1,
+  "work_id": "ABCD-1234-2026-05-04T12-34-56Z",
+  "phase": "implement",
+  "started_at": "2026-05-04T12:35:01Z",
+  "ended_at": "2026-05-04T12:38:42Z",
+  "confidence_band": "high",
+  "risk_class": "low",
+  "rules": [
+    {
+      "rule_id": "verify-before-complete",
+      "applied": true,
+      "skipped": false,
+      "conflicted_with": [],
+      "evidence_refs": ["agents/state/work/.../verify.log"]
+    }
+  ],
+  "memory": {
+    "asks": 3,
+    "hits": 2,
+    "ids": ["mem_42", "mem_57"]
+  },
+  "verify": {
+    "claims": 1,
+    "first_try_passes": 1
+  }
+}
+```
+
+Concerns and engines MUST treat unknown top-level keys as forward-
+compat extensions and MUST NOT raise on them.
+
+## Field semantics
+
+| Field | Meaning |
+|---|---|
+| `schema_version` | Always `1` for this contract. Major bump on breaking changes. |
+| `work_id` | Stable id of the WorkState directory. Allows cross-trace correlation across phases. |
+| `phase` | Engine phase that produced the trace. One of the eight phases above. |
+| `confidence_band` | One of `low` / `medium` / `high`. Heuristic defined below — derived from memory hits + ambiguity flags + verify evidence count. |
+| `risk_class` | One of `low` / `medium` / `high`. Per [`rule-interactions.md`](rule-interactions.md) — drives reviewer routing. |
+| `rules[].rule_id` | Stable rule id, matches the filename under `.agent-src.uncompressed/rules/` minus `.md`. |
+| `rules[].applied` | True if the rule's Iron Law fired and changed engine behaviour this phase. |
+| `rules[].skipped` | True if the rule was checked but produced no effect (no trigger match). |
+| `rules[].conflicted_with` | List of rule_ids that fired against this one. Reduction handled per `rule-interactions.md`. |
+| `rules[].evidence_refs` | Optional list of paths under `agents/state/` or `tests/` that back the `applied` claim. |
+| `memory.asks` | Count of `memory_retrieve` calls during the phase. |
+| `memory.hits` | Count of calls that returned ≥ 1 result. |
+| `memory.ids` | Stable memory entry ids returned. Bounded to ≤ 32 ids per phase; remainder dropped silently. |
+| `verify.claims` | Count of "done"-class claims the engine attempted this phase. |
+| `verify.first_try_passes` | Count of those claims that passed the verify gate without a re-prompt. |
+
+## Confidence-band heuristic
+
+```
+high:    memory.hits ≥ 2  AND  verify.first_try_passes == verify.claims  AND  no ambiguity flag
+medium:  memory.hits ≥ 1  OR   verify.first_try_passes ≥ 1
+low:     otherwise
+```
+
+Edge case: `verify.claims == 0` is not "high" by default — it folds
+into "medium" if at least one memory hit landed, "low" otherwise.
+
+## Risk-class heuristic
+
+Mirrors [`file-ownership-matrix.json`](file-ownership-matrix.json):
+the trace inherits the **maximum** risk class across all files the
+phase touched. If no files were touched (pure planning phase), risk
+is `low`.
+
+## Privacy floor
+
+- `memory.ids` carries opaque ids only — no entry bodies, no secrets.
+- `evidence_refs` carries paths only — no file contents.
+- `rules[].rule_id` is stable id, not free-form text.
+
+The visibility line surfaced to the user (Phase 4) consumes this file
+under the same floor.
+
+## Stability
+
+Beta. Breaking changes between v1 and v2 are allowed in a minor
+release if the change appears in `CHANGELOG.md` under a `### Breaking`
+heading. Engines MUST gate on `schema_version` and refuse unknown
+majors.
+
+## Cross-references
+
+- Personas (Architect, Risk-Officer) live in the package's persona
+  library under [`.agent-src.uncompressed/personas/`](../../.agent-src.uncompressed/personas/).
+  This contract does not duplicate them — when a future trace consumer
+  attributes a decision to one of those personas, the persona file is
+  the source of truth, not this envelope.
+- Rule-interaction matrix:
+  [`rule-interactions.md`](rule-interactions.md) (machine-readable
+  source: [`rule-interactions.yml`](rule-interactions.yml)).
+- Confidence-band heuristic is implemented in
+  `work_engine/scoring/decision_trace.py` and exercised by
+  `tests/work_engine/scoring/test_decision_trace_scoring.py`.
+- Outcome metrics consume `verify.first_try_passes`:
+  [`outcome-baseline.md`](../../agents/contexts/outcome-baseline.md).

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

@@ -6249,6 +6249,13 @@
       "via": "body_link",
       "depth": 1
     },
+    {
+      "source": ".agent-src.uncompressed/skills/roadmap-management/SKILL.md",
+      "target": ".agent-src.uncompressed/commands/roadmap/create.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
     {
       "source": ".agent-src.uncompressed/skills/roadmap-management/SKILL.md",
       "target": ".agent-src.uncompressed/rules/roadmap-progress-sync.md",

package/docs/contracts/hook-architecture-v1.md

@@ -0,0 +1,213 @@
+---
+stability: beta
+---
+
+# Hook architecture v1
+
+**Purpose.** Pin the contract that the universal hook dispatcher
+implements, so concern scripts and per-platform trampolines can be
+written, tested, and refactored against a stable surface.
+
+**Scope.** Defines the dispatcher's stdin/stdout shape, exit-code
+semantics, the `hook_manifest.yaml` schema, the concurrency contract
+for `agents/state/` writes, and the Copilot fallback pattern. Does
+**not** specify per-platform install paths — those live in
+[`chat-history-platform-hooks.md`](../../agents/contexts/chat-history-platform-hooks.md).
+
+Last refreshed: 2026-05-04.
+
+## Vocabulary
+
+| Term | Meaning |
+|---|---|
+| **Platform** | Host agent surface — one of `augment`, `claude`, `cursor`, `cline`, `windsurf`, `gemini`, `copilot`. The `claude` value covers both Claude Code (CLI) and Claude.ai Web; the canonical platform identifier is `claude` (matches `chat_history.PLATFORM_EVENT_MAP`). |
+| **Concern** | A single agent-config behaviour wired to one or more lifecycle events — e.g. `chat-history`, `roadmap-progress`, `verify-before-complete`. Lives as a Python script under `scripts/hooks/concerns/<name>.py`. |
+| **Event** | The agent-config-internal event vocabulary the dispatcher exposes — `session_start`, `session_end`, `user_prompt_submit`, `pre_tool_use`, `post_tool_use`, `stop`, `pre_compact`, `agent_error`. Per-platform native names map to these. `agent_error` is synthetic — fired by the agent (or wrapper) when the host crashes outside a concern, so chat-history can checkpoint partial sessions on abnormal exit. (Added in Round 2 — 2026-05-04.) |
+| **Trampoline** | A 5–10 line per-platform shell script that reads the platform's native payload, calls the dispatcher with `--platform <name>`, and forwards the platform's exit-code semantics. |
+| **Dispatcher** | `scripts/hooks/dispatch_hook.py` — single Python entrypoint that reads the manifest, resolves which concerns fire on `(platform, event)`, runs each one with the contract envelope below, and reduces their exit codes. |
+
+## Dispatcher invocation
+
+```
+python3 scripts/hooks/dispatch_hook.py \
+    --platform <name> \
+    --event <agent-config-event> \
+    [--native-event <platform-event>] \
+    < platform-payload.json
+```
+
+`--native-event` is informational; the dispatcher does not branch on
+it. The trampoline is responsible for translating the platform's
+native event name to the agent-config vocabulary before invocation.
+
+## Stdin contract — concern envelope
+
+The dispatcher writes a single JSON object to each concern's stdin:
+
+```json
+{
+  "schema_version": 1,
+  "platform": "augment",
+  "event": "stop",
+  "native_event": "Stop",
+  "session_id": "…",
+  "workspace_root": "/abs/path",
+  "payload": { /* opaque, platform-native */ },
+  "settings": { /* materialized .agent-settings.yml subset */ }
+}
+```
+
+Concerns MUST treat unknown top-level keys as forward-compat extensions
+and MUST NOT raise on them. `payload` is passed through verbatim from
+the platform — concerns extract what they need via their own helpers
+(see `scripts/chat_history.py` `_extract_*` for the pattern).
+
+## Stdout contract — concern reply
+
+A concern MAY write a single JSON object to stdout. The dispatcher
+reads it; non-JSON or empty stdout is treated as no-op (decision
+inferred from exit code only).
+
+```json
+{
+  "decision": "allow" | "block" | "warn",
+  "reason": "human-readable, ≤ 200 chars",
+  "additional_context": "optional — surfaces back to the model on platforms that support it",
+  "state_writes": ["agents/state/chat-history.json", "…"]
+}
+```
+
+`state_writes` is advisory; concerns still write the files themselves
+under the concurrency rules below.
+
+## Exit-code semantics
+
+| Code | Meaning | Dispatcher action |
+|---|---|---|
+| `0` | allow | no-op; pass through |
+| `1` | block | dispatcher exits 1, surfaces `reason` to platform's deny channel |
+| `2` | warn | dispatcher exits 0, logs `reason` to stderr, sets `additionalContext` if platform supports it |
+| `≥ 3` | error | dispatcher logs full traceback, exits 0 (fail-open) unless `concerns.<name>.fail_closed: true` in settings |
+
+## Reduction across multiple concerns
+
+When a `(platform, event)` tuple maps to ≥ 2 concerns, the dispatcher
+runs them **sequentially** in manifest order and reduces:
+
+- Any `block` → final decision is `block` (most-restrictive merge).
+- Else any `warn` → final decision is `warn`.
+- Else `allow`.
+
+`additional_context` strings are concatenated with `\n\n` separators,
+in manifest order. Concerns are never run in parallel — concurrency
+guarantees rely on serial state writes.
+
+## Feedback channel — `agents/state/.dispatcher/<session_id>/`
+
+Exit-code reduction collapses the severity ladder to a single
+platform-native code, which can hide a `warn` behind a `block` or
+mask non-actioned reasons entirely. To preserve per-concern detail
+without re-routing control flow, the dispatcher writes a feedback
+directory per invocation:
+
+```
+agents/state/.dispatcher/<session_id>/
+  <concern>.json     — one file per concern that ran
+  summary.json       — rollup written after the last concern
+```
+
+Each `<concern>.json` carries:
+
+```json
+{
+  "concern": "chat-history",
+  "exit_code": 0,
+  "raw_exit_code": 0,
+  "severity": "allow",
+  "decision": "allow",
+  "reason": "appended turn 12",
+  "duration_ms": 47,
+  "started_at": "2026-05-04T12:34:56Z",
+  "completed_at": "2026-05-04T12:34:56Z",
+  "fail_closed": false
+}
+```
+
+`summary.json` carries the platform / event tuple, the reduced
+`final_exit_code` + `final_severity`, and a trimmed list of all
+concern entries. `session_id` falls back to
+`dispatch-<unix_ts>-<pid>` when the envelope omits one. Path
+traversal in `session_id` is collapsed (`/`, `\`, `..` → `_`).
+
+Feedback writes are non-fatal — IO errors log to stderr but never
+change the dispatcher's exit code. The directory is gitignored and
+consumed by `task hooks-status` (Phase 7.11). Added in Round 2
+(2026-05-04) per Q1 of `tmp/council_round2/q1_feedback_channel.md`.
+
+## Manifest schema — `scripts/hook_manifest.yaml`
+
+```yaml
+schema_version: 1
+concerns:
+  chat-history:
+    script: scripts/hooks/concerns/chat_history.py
+    fail_closed: false
+roadmap-progress:
+    script: scripts/hooks/concerns/roadmap_progress.py
+    fail_closed: false
+
+platforms:
+  augment:
+    session_start: [chat-history]
+    stop:          [chat-history, roadmap-progress]
+    post_tool_use: [chat-history]
+  claude:
+    session_start: [chat-history]
+    user_prompt_submit: [chat-history]
+    stop:          [chat-history, roadmap-progress]
+  copilot:
+    # No dispatcher — see "Copilot fallback" below.
+```
+
+Validated by `scripts/lint_hook_manifest.py` (Phase 7.10): every
+concern script must exist on disk, every platform key must be a known
+platform, every event key must be in the agent-config event vocabulary.
+
+## Concurrency — atomic state writes
+
+Concerns that write under `agents/state/` MUST use the pattern:
+
+1. Acquire `fcntl.flock(LOCK_EX)` on `agents/state/.dispatcher.lock`.
+2. Write to a sibling `<dest>.tmp.<pid>` file in the same directory.
+3. `os.replace(tmp, dest)` — POSIX-atomic on the same filesystem.
+4. Release the lock.
+
+The single `.dispatcher.lock` is intentional: serialising state
+writes across concerns is cheaper than per-file locks, and concerns
+already run sequentially within one dispatcher invocation. The lock
+file is gitignored.
+
+Phase 7.4 ships a regression test that spawns two concurrent
+dispatcher invocations against the same event and asserts no torn
+writes (file ends with valid JSON, last-writer-wins).
+
+## Copilot fallback pattern
+
+Copilot has no hook surface. Concerns whose source rule cites
+`agents/state/<concern>.json` MUST gain a "Copilot fallback" section
+that:
+
+- Names the state file the concern would have written.
+- Names a manual command or task that reproduces the side effect
+  (e.g. `task chat-history:append`).
+- Includes no Iron-Law-changing prose.
+
+The dispatcher silently no-ops when called with `--platform copilot`;
+the fallback is consumed by reading the rule, not by hook invocation.
+
+## Stability
+
+Beta. Breaking changes between v1 and v2 are allowed in a minor
+release if the change appears in `CHANGELOG.md` under a `### Breaking`
+heading. Concerns MUST gate on `schema_version` and refuse unknown
+majors.