@event4u/agent-config 2.9.0 → 2.10.0

package/docs/contracts/settings-sync-yaml-subset.md

@@ -0,0 +1,138 @@
+---
+stability: beta
+---
+
+# Settings-sync YAML subset
+
+**Purpose.** Pin the YAML feature set that `.agent-settings.yml` and
+`config/agent-settings.template.yml` may use, so contributors can cite a
+contract instead of inferring it from
+[`scripts/sync_yaml_rt.py`](../../scripts/sync_yaml_rt.py) source. The
+sync engine ([ADR](adr-settings-sync-engine.md)) is a custom stdlib-only
+round-trip parser/emitter; staying inside the subset below is what
+keeps user-line preservation (every byte of every user line round-trips
+unchanged unless the merger explicitly edits the key).
+
+Authoritative source: this document. The module docstring of
+`sync_yaml_rt.py` mirrors it; on drift, this file wins and the docstring
+is corrected to match.
+
+## Supported
+
+### Document shape
+
+- One YAML document per file. No `---` or `...` document separators.
+- UTF-8. CRLF and LF line endings — both accepted, preserved per-line.
+
+### Mappings (sections)
+
+- Block-style mappings only (`key: value` on its own line).
+- Indent: 2- or 4-space, **no tabs** in indent.
+- Nested mappings unlimited in depth (the template uses 3 levels —
+  e.g. `chat_history.archive.cleanup_after_days`).
+- Duplicate keys at the same level: **last wins** (the later line
+  carries the value; the earlier entry is replaced).
+
+### Scalars (values)
+
+- Bare scalars: `enabled`, `42`, `true`, `~`, `null`, `None`.
+- Single-quoted strings: `'literal text'`.
+- Double-quoted strings: `"literal text"`.
+- Bools, ints, `~` / `null` / `None` are kept **verbatim** — the
+  parser does not normalise `True` → `true` or `null` → `~`.
+
+### Lists (sequences of scalars)
+
+- Block-style lists:
+  ```yaml
+  allowlist:
+    - foo
+    - bar
+  ```
+  Indent inside the list must be consistent.
+- Inline-flow lists, **flat only**: `[a, b, c]`.
+- List items are scalars only. Nested mappings inside a list item are
+  **not** supported (see below).
+
+### Comments and blank lines
+
+- `#`-comments — full-line and inline (`key: value  # comment`). Both
+  preserved verbatim, including leading whitespace and the gap before
+  `#`.
+- Blank lines preserved verbatim — the engine never collapses them.
+
+## Not supported (parser raises `ValueError` with a line number)
+
+The following YAML features are out of contract. A user file that uses
+any of them surfaces as `ValueError` from `scripts/sync_yaml_rt.py:sync`,
+which `scripts/sync_agent_settings.py` catches and reports as **exit
+code 2** with a line-numbered message.
+
+- **Anchors and aliases** — `&name`, `*name`.
+- **Multi-document streams** — `---` / `...` separators.
+- **Nested flow mappings** — `key: {nested: value}` inline. Block-style
+  nested mappings are fine; flow-style nested mappings are not.
+- **Nested mappings inside list items** — `- name: foo` followed by
+  indented children. Lists hold scalars only.
+- **Complex keys** — `? [composite, key]: value`.
+- **Tagged scalars** — `!!str 42`, `!Custom value`.
+- **Multiline scalar styles** — `|` (literal) and `>` (folded) block
+  scalars.
+- **Tabs in indent** — even one tab character in indent.
+- **Mixed indent inside a block** — every child of a parent must share
+  the same indent.
+
+Pinned by `tests/test_sync_round_trip.py` (34 tests) — every
+not-supported feature has at least one fixture that asserts the
+`ValueError` message.
+
+## Test pinning
+
+- Verbatim round-trip: `tests/test_sync_round_trip.py::test_user_block_round_trip_is_idempotent`, `::test_three_level_idempotent`.
+- Out-of-subset rejection: same file, fixtures under
+  `tests/fixtures/sync_yaml_rt/` named `bad_*.yml`.
+- CLI exit code on malformed input:
+  `tests/test_sync_agent_settings.py::test_malformed_user_yaml_exits_2_with_message`.
+
+Any parser change is gated on those tests staying green. New fixtures
+for new features land under `tests/fixtures/sync_yaml_rt/`.
+
+## Why this subset (and why it is fixed)
+
+The driving requirement from
+[`layered-settings`](../guidelines/agent-infra/layered-settings.md) is
+**verbatim user-line preservation**. `ruamel.yaml` and PyYAML both
+re-emit through their own emitters, which normalises whitespace,
+quoting, and blank-line placement. A stdlib parser limited to this
+subset gives byte-identity across two consecutive syncs — the property
+the merger relies on for additive insertion.
+
+Out-of-subset YAML therefore is not a parser bug; it is a contract
+violation by the user file. The friendly `ValueError` and exit code 2
+are the contract's failure surface.
+
+## Revisit triggers
+
+This subset is **fixed** until one of the
+[ADR revisit triggers](adr-settings-sync-engine.md#revisit-triggers)
+fires — namely:
+
+1. `.agent-settings.yml` schema gains a YAML feature outside the subset
+   (anchors, multi-doc, complex keys, nested flow mappings) — the cost
+   of extending the parser exceeds the cost of adopting `ruamel.yaml`.
+2. The verbatim-preservation contract is relaxed — the driver for the
+   custom parser 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 ruamel's mature spec
+   coverage would have prevented.
+
+A new ADR (with successor link) is required to change the subset; this
+document is updated in the same commit.
+
+## See also
+
+- [`docs/contracts/adr-settings-sync-engine.md`](adr-settings-sync-engine.md) — decision record for the stdlib-only engine.
+- [`docs/guidelines/agent-infra/layered-settings.md`](../guidelines/agent-infra/layered-settings.md) § Sync rules — the additive-merge-with-user-line-preservation contract this subset implements.
+- [`scripts/sync_yaml_rt.py`](../../scripts/sync_yaml_rt.py) — implementation; module docstring mirrors this file.
+- [`scripts/sync_agent_settings.py`](../../scripts/sync_agent_settings.py) — CLI driver and exit-code contract.

package/docs/readme-split-plan.md

@@ -0,0 +1,102 @@
+# README three-audience split — plan
+
+Annotated outline for `P2.2a` in
+[`road-to-proof-not-features.md`](../agents/roadmaps/road-to-proof-not-features.md).
+Decides the **information architecture**, not the prose. No content
+rewrite happens in this step; `P2.2b` applies the mapping.
+
+## Target headings (top of README, in order)
+
+1. **Use it in your project** — anchor `#use-it`
+2. **Prove it** — anchor `#prove-it`
+3. **Contribute** — anchor `#contribute`
+
+Each branch opens with one paragraph + one primary CTA. AI Council is
+not mentioned in any branch (verified by `P3.4`).
+
+### Anchor-stability promise
+
+`P2.2b` must keep these existing anchors intact so external inbound
+links survive:
+
+| Anchor today | Lives under (new) | Why |
+|---|---|---|
+| `#quickstart` | `#use-it` | npm/composer search results, social links |
+| `#supported-tools` | `#use-it` | most-cited section on the web |
+| `#what-your-agent-is-asked-to-do` | `#prove-it` | linked from blog posts |
+| `#documentation` | `#use-it` | docs portal entry |
+| `#development` | `#contribute` | contributor guides |
+
+Other section anchors may be renamed; `lint-readme` checks the table
+above and the three new audience anchors only.
+
+## Block-by-block mapping
+
+Every existing top-of-README block, in source order, mapped to
+exactly one branch. "Drop" = block is retired; "Move" = relocated as-
+is; "Reframe" = block stays but its lead-in / CTA changes (still no
+copy rewrite in this step — the reframe direction is decided here,
+applied in `P2.2b`).
+
+| # | Block (current heading) | Lines | Branch | Action | Notes |
+|---|---|---|---|---|---|
+| 1 | Title + tagline + stats badge | 1–13 | — | Keep above branches | Survives unchanged; counts updated by `update_readme_counts`. |
+| 2 | `## Start here` (three-paths table) | 15–25 | — | **Drop** | Replaced by the three branch sections themselves; rows map cleanly: `/onboard` → Use, `task ci` → Contribute, `task generate-tools` → Use. |
+| 3 | `## Quickstart` lead-in | 27–39 | Use it | Move | Becomes the opening paragraph under `#use-it`. |
+| 4 | `### For teams (recommended)` | 40–79 | Use it | Move | Primary CTA for `#use-it`. |
+| 5 | `### Pick specific AIs` | 81–101 | Use it | Move | Stays under Quickstart subtree. |
+| 6 | `#### Global install` | 103–124 | Use it | Move | Subsection of Pick specific AIs. |
+| 7 | `### For individual use (optional)` | 126–144 | Use it | Move | Alternate install path. |
+| 8 | `### Self-hosted MCP on Cloudflare` | 146–226 | Use it | Move | Operator install path; deep but consumer-facing. |
+| 9 | `#### Lock your Worker behind Bearer` | 196–213 | Use it | Move | Subsection of MCP block; stays nested. |
+| 10 | `### Optional: persistent agent memory` | 228–247 | Use it | Move | Companion package install. |
+| 11 | `## 2-minute demo: /implement-ticket` | 251–285 | Prove it | Move | Flagship evidence surface. Primary CTA for `#prove-it`. |
+| 12 | `### Sibling entrypoint: /work` | 287–316 | Prove it | Move | Same engine, second envelope. |
+| 13 | `### Product UI track` | 318–347 | Prove it | Move | Third evidence surface. |
+| 14 | `## What your agent is asked to do` | 351–365 | Prove it | Move | Intent table — proof of behaviour, not features. |
+| 15 | `## What this package is — and what it isn't` | 369–398 | Prove it | Move | Scope-honesty surface; loadbearing for the "proof" framing. |
+| 16 | `## You don't need everything` (cost profiles) | 402–423 | Prove it | Reframe | Currently sits as "feature" prose; the new framing is "proof that the package shrinks to fit". |
+| 17 | `## Who this is for` (stack coverage) | 427–439 | Prove it | Move | Honest depth claim — also evidence-side. |
+| 18 | `## Featured Skills` | 443–462 | Use it | Move | Catalog teaser → consumer surface. |
+| 19 | `## Featured Commands` | 466–481 | Use it | Move | Catalog teaser → consumer surface. |
+| 20 | `## Supported Tools / Project-installed` | 487–527 | Use it | Move | Per-tool install matrix. |
+| 21 | `## Supported Tools / Plugin-installed` | 529–541 | Use it | Move | Subsection. |
+| 22 | `## Supported Tools / Cloud / Hosted-agent` | 543–558 | Use it | Move | Subsection. |
+| 23 | `## Core Principles` | 562–570 | Prove it | Move | Behavioural floor — proof-side. |
+| 24 | `## Documentation` (index table) | 574–589 | Use it | Move | Doc portal entry. |
+| 25 | `### Maintainer telemetry (opt-in)` | 591–608 | Contribute | Move | Engagement measurement — maintainer / contributor surface. |
+| 26 | `### Context-aware command suggestion` | 610–629 | Use it | Move | Consumer-facing feature toggle. |
+| 27 | `## Development` | 633–642 | Contribute | Move | Primary CTA for `#contribute`. |
+| 28 | `## Requirements` | 644–649 | Use it | Move | Install gate — Use-side, not Contribute. |
+| 29 | `## License` | 651–653 | — | Keep at bottom | Footer; outside the three branches. |
+
+## Branch outlines (post-migration shape)
+
+### `## Use it in your project`
+
+Opening paragraph: one-line "Two minutes from npx to a better-behaved
+agent." Primary CTA: `npx @event4u/agent-config init`. Children:
+Quickstart subtree (#3–#7), MCP operator path (#8–#9), optional memory
+(#10), Featured Skills + Commands (#18–#19), Supported Tools (#20–#22),
+Documentation (#24), Command suggestion (#26), Requirements (#28).
+
+### `## Prove it`
+
+Opening paragraph: one-line "What the agent actually does, with
+evidence." Primary CTA: `/implement-ticket` demo (#11). Children:
+`/work` (#12), Product UI track (#13), Intent table (#14), Scope
+statement (#15), Cost profiles reframed (#16), Stack coverage (#17),
+Core Principles (#23).
+
+### `## Contribute`
+
+Opening paragraph: one-line "Editing rules, skills, commands — the
+contributor loop." Primary CTA: `task ci` (#27). Children: Maintainer
+telemetry (#25). External links: `CONTRIBUTING.md`, `AGENTS.md`,
+`docs/development.md`.
+
+## Verification (P2.2c preview)
+
+Grep-based test asserts `## Use it in your project`, `## Prove it`,
+`## Contribute` appear in that order. `lint-readme` keeps anchor
+stability for the rows in the Anchor-stability promise table.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "2.9.0",
+    "version": "2.10.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/_cli/cmd_settings_check.py

@@ -0,0 +1,171 @@
+"""``agent-config settings:check`` — validate ``.agent-settings.yml`` against the supported YAML subset.
+
+Read-only. Implements P3.2 of road-to-proof-not-features.md. The contract
+this checks against is pinned in
+``docs/contracts/settings-sync-yaml-subset.md``; out-of-subset constructs
+cause :class:`sync_yaml_rt` to raise ``ValueError`` during a sync. This
+CLI surfaces the same findings *before* a sync runs, so users can fix
+their file without watching the merge fail.
+
+Output line format::
+
+    line:N  <kind>  <verdict>  <fix hint>
+
+Exit codes:
+
+* ``0`` — file is inside the supported subset (or absent and ``--allow-missing``).
+* ``1`` — one or more findings (verdict ``not supported``).
+* ``2`` — file absent (without ``--allow-missing``) or unreadable.
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+# Imported lazily inside ``main`` so a missing engine cannot break ``--help``.
+
+DEFAULT_PATH = ".agent-settings.yml"
+
+# Out-of-subset patterns detected by a line-level pre-scan. Each rule is
+# (label, regex, fix hint). The regex is applied to the *stripped* body
+# of each non-comment line so leading indent does not affect matching.
+_PRESCAN_RULES: tuple[tuple[str, re.Pattern[str], str], ...] = (
+    (
+        "multi-doc separator",
+        re.compile(r"^(---|\.\.\.)\s*(#.*)?$"),
+        "remove the separator — one YAML document per file only.",
+    ),
+    (
+        "complex key",
+        re.compile(r"^\?\s"),
+        "rewrite as a plain ``key: value`` mapping line.",
+    ),
+    (
+        "block-scalar indicator",
+        re.compile(r":\s*[|>][+-]?\s*(#.*)?$"),
+        "inline the value as a single-line quoted scalar.",
+    ),
+    (
+        "tagged scalar",
+        re.compile(r":\s*!!?[A-Za-z_]"),
+        "remove the ``!tag``; the parser does not honour it.",
+    ),
+    (
+        "anchor / alias",
+        re.compile(r":\s*[&*][A-Za-z_]"),
+        "expand the anchor inline — anchors / aliases are not supported.",
+    ),
+    (
+        "nested flow-mapping",
+        re.compile(r":\s*\{[^}]*:[^}]*\}"),
+        "rewrite as a block-style nested mapping (indented child keys).",
+    ),
+)
+
+
+def _scan_line(stripped: str) -> tuple[str, str] | None:
+    if not stripped or stripped.startswith("#"):
+        return None
+    for label, pattern, hint in _PRESCAN_RULES:
+        if pattern.search(stripped):
+            return label, hint
+    return None
+
+
+def _scan_text(text: str) -> list[dict]:
+    findings: list[dict] = []
+    for lineno, raw in enumerate(text.splitlines(), 1):
+        stripped = raw.strip()
+        if "\t" in raw[: len(raw) - len(raw.lstrip(" \t"))]:
+            findings.append({
+                "line": lineno,
+                "kind": "tab in indent",
+                "verdict": "not supported",
+                "hint": "replace leading tabs with 2 or 4 spaces.",
+            })
+            continue
+        hit = _scan_line(stripped)
+        if hit is not None:
+            label, hint = hit
+            findings.append({
+                "line": lineno,
+                "kind": label,
+                "verdict": "not supported",
+                "hint": hint,
+            })
+    return findings
+
+
+def _format(finding: dict) -> str:
+    return (
+        f"  ❌  line:{finding['line']:<4}  "
+        f"{finding['kind']:<22}  {finding['verdict']:<14}  {finding['hint']}"
+    )
+
+
+def _parse(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="agent-config settings:check",
+        description=(
+            "Validate .agent-settings.yml against the supported YAML subset "
+            "(docs/contracts/settings-sync-yaml-subset.md). Read-only."
+        ),
+    )
+    parser.add_argument("--path", default=DEFAULT_PATH,
+                        help=f"target settings file (default: ./{DEFAULT_PATH})")
+    parser.add_argument("--allow-missing", action="store_true",
+                        help="exit 0 when the file is absent (CI-friendly)")
+    parser.add_argument("--quiet", action="store_true",
+                        help="suppress non-essential output")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str]) -> int:
+    opts = _parse(argv)
+    target = Path(opts.path)
+    if not target.is_file():
+        if opts.allow_missing:
+            if not opts.quiet:
+                print(f"✅  {target}: file absent (allow-missing).")
+            return 0
+        print(f"❌  {target}: file not found.", file=sys.stderr)
+        print("    Run `./agent-config sync-agent-settings` to create it.", file=sys.stderr)
+        return 2
+    try:
+        text = target.read_text(encoding="utf-8")
+    except OSError as exc:
+        print(f"❌  {target}: cannot read: {exc}", file=sys.stderr)
+        return 2
+
+    findings = _scan_text(text)
+    if not findings:
+        # Final gate: run the round-trip parser to catch anything the
+        # pre-scan missed (mismatched indent, malformed mapping lines).
+        from scripts import sync_yaml_rt as _rt  # noqa: PLC0415
+        try:
+            _rt.parse(text)
+        except ValueError as exc:
+            findings.append({
+                "line": 0, "kind": "parser",
+                "verdict": "not supported", "hint": str(exc),
+            })
+
+    if not findings:
+        if not opts.quiet:
+            print(f"✅  {target}: inside the supported subset "
+                  "(docs/contracts/settings-sync-yaml-subset.md).")
+        return 0
+    print(f"❌  {target}: {len(findings)} finding(s) outside the supported subset.",
+          file=sys.stderr)
+    for finding in findings:
+        print(_format(finding), file=sys.stderr)
+    print("", file=sys.stderr)
+    print("    Contract: docs/contracts/settings-sync-yaml-subset.md",
+          file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/agent-config

@@ -127,10 +127,22 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              (experimental — beta gates: docs/contracts/mcp-beta-criteria.md)
   roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
   roadmap:progress-check     Fail if agents/roadmaps-progress.md is stale (for CI)
+  settings:check             Validate .agent-settings.yml against the YAML-subset contract
+                             (docs/contracts/settings-sync-yaml-subset.md). Read-only.
+                             Exit 0 clean, 1 finding(s), 2 file absent / unreadable.
   hooks:install              Install the pre-commit roadmap-progress hook
                              (use --print to dump it, --force to overwrite an existing hook)
   hooks:status               Print the runtime hook matrix (per-platform install + bindings)
                              Flags: --format json|table, --strict (CI), --project-root <path>
+  hooks:doctor               Diagnose hook health: concerns + fail-open/closed posture,
+                             last dispatcher feedback per concern, missing trampolines.
+                             Wraps hooks:status. Read-only.
+                             Flags: --format json|table, --strict (CI), --project-root <path>
+  hooks:replay               Replay a fixture through the universal dispatcher with
+                             AGENT_CONFIG_REPLAY=1 (no writes under agents/state/).
+                             Usage: hooks:replay --platform <name> --event <event>
+                                    --payload <path|event-name> [--native-event <native>]
+                                    [--manifest <path>] [--json] [--dry-run]
   migrate-state              Migrate a legacy .implement-ticket-state.json file
                              to the v1 .work-state.json schema (preserves .bak)
   memory:lookup              Retrieve memory entries (text or JSON envelope)
@@ -217,7 +229,9 @@ Examples (Tier 2):
   ./agent-config mcp:setup
   ./agent-config mcp:run
   ./agent-config roadmap:progress
+  ./agent-config settings:check
   ./agent-config hooks:install
+  ./agent-config hooks:replay --platform augment --event post_tool_use --payload post_tool_use --json
   ./agent-config migrate-state
   ./agent-config memory:lookup --types domain-invariants --key billing
   ./agent-config memory:signal --type architecture-decision --path src/Foo.php --body "…"
@@ -507,6 +521,20 @@ cmd_hooks_status() {
   exec python3 "$script" "$@"
 }
 
+cmd_hooks_doctor() {
+  require_python3
+  local script
+  script="$(resolve_script "scripts/hooks_doctor.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
+cmd_hooks_replay() {
+  require_python3
+  local script
+  script="$(resolve_script "scripts/hooks/replay_hook.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
 cmd_chat_history_checkpoint() {
   require_python3
   local script
@@ -676,6 +704,15 @@ cmd_validate() {
   exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_validate "$@"
 }
 
+# `agent-config settings:check` — read-only YAML-subset validator for
+# `.agent-settings.yml` (P3.2 of road-to-proof-not-features.md). Contract
+# pinned in docs/contracts/settings-sync-yaml-subset.md. Exit 0 clean,
+# 1 finding(s), 2 file absent / unreadable.
+cmd_settings_check() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_settings_check "$@"
+}
+
 # `agent-config uninstall` — remove bridge markers (project) or lockfile
 # entries (global). Idempotent. Pass `--purge` to also delete deployed
 # content directories under user-scope anchors (destructive). See
@@ -744,6 +781,8 @@ main() {
     context-hygiene:hook)    cmd_context_hygiene_hook "$@" ;;
     dispatch:hook)           cmd_dispatch_hook "$@" ;;
     hooks:status)            cmd_hooks_status "$@" ;;
+    hooks:doctor)            cmd_hooks_doctor "$@" ;;
+    hooks:replay)            cmd_hooks_replay "$@" ;;
     telemetry:record)        cmd_telemetry_record "$@" ;;
     telemetry:status)        cmd_telemetry_status "$@" ;;
     telemetry:report)        cmd_telemetry_report "$@" ;;
@@ -757,6 +796,7 @@ main() {
     export)                  cmd_export "$@" ;;
     sync)                    cmd_sync "$@" ;;
     validate)                cmd_validate "$@" ;;
+    settings:check)          cmd_settings_check "$@" ;;
     uninstall)               cmd_uninstall "$@" ;;
     prune)                   cmd_prune "$@" ;;
     doctor)                  cmd_doctor "$@" ;;

package/scripts/chat_history.py

@@ -48,6 +48,15 @@ SCHEMA_VERSION = 4
 DEFAULT_MAX_SESSIONS = 5
 VALID_FREQS = {"per_turn", "per_phase", "per_tool"}
 VALID_OVERFLOW = {"rotate", "compress"}
+
+# Replay-mode signal — when set, every write to the on-disk transcript
+# is a no-op. Honoured per `docs/contracts/hook-architecture-v1.md`
+# § Replay mode so fixture dispatches never mutate real session state.
+REPLAY_ENV_VAR = "AGENT_CONFIG_REPLAY"
+
+
+def _is_replay_mode() -> bool:
+    return os.environ.get(REPLAY_ENV_VAR, "").strip() == "1"
 _WS_RE = re.compile(r"\s+")
 SESSION_ID_LEN = 16
 SESSION_ID_UNKNOWN = "<unknown>"
@@ -247,6 +256,8 @@ def init(freq: str = "per_phase", *,
         raise ValueError(f"freq must be one of {sorted(VALID_FREQS)}")
     p = path or file_path()
     header = _build_header(freq)
+    if _is_replay_mode():
+        return header
     p.parent.mkdir(parents=True, exist_ok=True)
     with p.open("w", encoding="utf-8") as fh:
         fh.write(json.dumps(header, ensure_ascii=False) + "\n")
@@ -318,6 +329,8 @@ def append(entry: dict[str, Any], *, path: Path | None = None,
         entry["s"] = session
     elif "s" not in entry and _session_tag_enabled():
         entry["s"] = _last_body_session_id(p)
+    if _is_replay_mode():
+        return
     with p.open("a", encoding="utf-8") as fh:
         fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
 
@@ -328,7 +341,11 @@ def _atomic_write_text(p: Path, text: str) -> None:
     Multiple processes writing to the same target use disjoint tmp paths
     (PID + uuid), so concurrent writes no longer collide on a shared
     ``.tmp`` file. The final ``replace`` is atomic on POSIX.
+
+    Under `AGENT_CONFIG_REPLAY=1` the call is a no-op.
     """
+    if _is_replay_mode():
+        return
     tmp = p.with_suffix(
         f"{p.suffix}.{os.getpid()}.{uuid.uuid4().hex[:8]}.tmp",
     )
@@ -405,6 +422,8 @@ def prepend_entries(entries: list[dict[str, Any]], *,
 
 
 def clear(*, path: Path | None = None) -> None:
+    if _is_replay_mode():
+        return
     p = path or file_path()
     if p.exists():
         p.unlink()

package/scripts/check_council_references.py

@@ -14,8 +14,10 @@ council files. Directory mentions and placeholder paths
 output-path convention, not a live reference.
 
 Forbidden hits in this codebase exist today (kernel-membership ADRs
-cite real session JSONs as decision traces). Suppress them with an
-inline pragma at the end of the line:
+cite real session JSONs as decision traces). Two source/target shapes
+are exempt structurally — see STRUCTURAL_CARVEOUTS below — because
+they encode immutable decision provenance, not transient drafting
+state. Anything else needs an inline pragma at the end of the line:
 
     `agents/council-sessions/...json` <!-- council-ref-allowed: <reason> -->
 
@@ -82,6 +84,31 @@ ALLOWLIST_FILES: frozenset[str] = frozenset({
 
 INLINE_PRAGMA = re.compile(r"<!--\s*council-ref-allowed:[^>]*-->")
 
+# Structural carve-outs — (source_pattern, target_pattern) pairs where
+# the reference is immutable decision provenance rather than transient
+# drafting state. Driven by the 2026-05-14 P3.4 council round
+# (agents/council-sessions/2026-05-14-p3-4-references/synthesis.md).
+#
+# Each entry: source file matches `source` regex AND the captured
+# reference path matches `target` regex → reference is allowed without
+# an inline pragma.
+STRUCTURAL_CARVEOUTS: tuple[tuple[re.Pattern[str], re.Pattern[str]], ...] = (
+    # (a) evaluation-context → council-question:
+    # the question file is a frozen function-parameter / spend-gate
+    # input, not a documentation link.
+    (
+        re.compile(r"^agents/contexts/evaluation-[^/]+\.md$"),
+        re.compile(r"^agents/council-questions/[^/]+\.md$"),
+    ),
+    # (b) contract → council-session-synthesis:
+    # the synthesis file is the audit-trail receipt the contract cites
+    # as decision provenance; the contract inlines the decision body.
+    (
+        re.compile(r"^docs/contracts/[^/]+\.md$"),
+        re.compile(r"^agents/council-sessions/[^/]+/synthesis\.md$"),
+    ),
+)
+
 
 def _is_allowlisted(rel: str) -> bool:
     if rel in ALLOWLIST_FILES:
@@ -89,8 +116,17 @@ def _is_allowlisted(rel: str) -> bool:
     return any(rel.startswith(prefix) for prefix in ALLOWLIST_PREFIXES)
 
 
+def _is_structurally_allowed(source_rel: str, target_capture: str) -> bool:
+    """True when (source, target) matches a structural carve-out pair."""
+    for src_re, tgt_re in STRUCTURAL_CARVEOUTS:
+        if src_re.match(source_rel) and tgt_re.match(target_capture):
+            return True
+    return False
+
+
 def _scan_file(path: Path) -> list[tuple[int, str]]:
     findings: list[tuple[int, str]] = []
+    rel = path.as_posix()
     try:
         text = path.read_text(encoding="utf-8")
     except (OSError, UnicodeDecodeError):
@@ -99,6 +135,8 @@ def _scan_file(path: Path) -> list[tuple[int, str]]:
         if INLINE_PRAGMA.search(line):
             continue
         for m in PATTERN.finditer(line):
+            if _is_structurally_allowed(rel, m.group(0)):
+                continue
             findings.append((ln, m.group(0)))
     return findings
 
@@ -136,10 +174,13 @@ def main() -> int:
     print(
         "\nRule: .agent-src/rules/no-roadmap-references.md (council clause)\n"
         "Fix: inline the convergence summary (members + date) instead of\n"
-        "linking the file. Append "
+        "linking the file. Two source/target shapes are exempt structurally\n"
+        "(evaluation-context → council-question, contract →\n"
+        "council-session-synthesis) — see STRUCTURAL_CARVEOUTS in this\n"
+        "script. Otherwise append "
         "<!-- council-ref-allowed: <reason> --> on the same line to\n"
-        "suppress when the reference is genuinely required (ADR / contract\n"
-        "decision trace)."
+        "suppress when the reference is genuinely required (ADR decision\n"
+        "trace)."
     )
     return 1
 

package/scripts/hooks/dispatch_hook.py

@@ -37,7 +37,7 @@ MANIFEST_PATH = REPO_ROOT / "scripts" / "hook_manifest.yaml"
 # Lazy import — we want this module to be importable even if the
 # hooks package state_io has changed (test isolation).
 sys.path.insert(0, str(Path(__file__).resolve().parent))
-from state_io import atomic_write_json, feedback_dir  # noqa: E402
+from state_io import atomic_write_json, feedback_dir, is_replay_mode  # noqa: E402
 
 EXIT_ALLOW = 0
 EXIT_BLOCK = 1
@@ -272,6 +272,10 @@ def _write_feedback(envelope: dict, session_id: str, entries: list[dict],
     not control flow. We only swallow IO errors here; fail-open
     matches the dispatcher's overall posture.
     """
+    # Replay mode skips feedback emission entirely so fixture replays
+    # never create per-session dirs under agents/state/.dispatcher/.
+    if is_replay_mode():
+        return
     workspace = envelope.get("workspace_root") or str(Path.cwd())
     state_root = Path(workspace) / "agents" / "state"
     fb_dir = feedback_dir(state_root, session_id)