@event4u/agent-config 2.9.0 → 2.10.0

package/.agent-src/rules/no-roadmap-references.md

@@ -83,6 +83,25 @@ fail the build on any new violation.
   descriptions — transient by construction, not part of the package
   surface
 
+## Structural carve-outs (immutable inputs / decision provenance)
+
+Two source/target shapes are exempt from the council-link ban
+because the target is **immutable input** or **decision provenance**,
+not transient drafting state. The linter implements these directly
+(`STRUCTURAL_CARVEOUTS` in `scripts/check_council_references.py`);
+they do **not** need an inline `<!-- council-ref-allowed: ... -->`
+pragma.
+
+| Source                                         | Target                                           | Why                                                                                  |
+| ---------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| `agents/contexts/evaluation-*.md`              | `agents/council-questions/*.md`                  | Question file is a frozen function-parameter / spend-gate input, not documentation. |
+| `docs/contracts/*.md`                          | `agents/council-sessions/*/synthesis.md`         | Synthesis is the audit-trail receipt; contract inlines the decision body itself.    |
+
+Driven by the 2026-05-14 P3.4 council round (claude-sonnet-4-5 +
+gpt-4o, converged on rule refactor over escape-hatch overuse). Any
+other source/target combination still needs an inline pragma or
+inline-summary rewrite.
+
 ## What to do instead
 
 When a stable artifact needs to cite a transient finding:

package/.agent-src/templates/scripts/work_engine/hooks/builtin/memory_visibility.py

@@ -23,8 +23,11 @@ from __future__ import annotations
 
 from typing import Any, Iterable
 
+from ...scoring.decision_trace import summarise_memory, summarise_verify
 from ...scoring.memory_visibility import (
     DEFAULT_ASKED_TYPES,
+    compute_affected,
+    format_changed_decisions_block,
     format_line,
     should_emit,
     summarise_visibility,
@@ -82,20 +85,46 @@ class MemoryVisibilityHook:
             visibility_off=self._visibility_off,
         ):
             return
-        line = format_line(summary)
+        affected = self._derive_affected(work, memory)
+        line = format_line(summary, affected=affected)
         if not line:
             return
+        block = format_changed_decisions_block(
+            summary.get("ids") or [], affected,
+        )
         existing = getattr(work, "report", "") or ""
-        if line in existing:
+        rendered = line if block is None else f"{line}\n\n{block}"
+        if line in existing and (block is None or block in existing):
             return
         sep = "\n\n" if existing else ""
         try:
-            work.report = f"{existing}{sep}{line}"
+            work.report = f"{existing}{sep}{rendered}"
         except AttributeError as exc:
             raise HookError(
                 "memory-visibility: state.report not writable",
             ) from exc
 
+    def _derive_affected(self, work: Any, memory: Any) -> list[str] | None:
+        """Compute the closed-list ``affected`` keys for this work step.
+
+        Reuses the decision-trace summarisers so the counterfactual
+        matches the trace hook's view of the same WorkState. Returns
+        ``None`` when memory was not consulted (hits == 0); callers
+        then omit the ``· affected: …`` segment per the contract.
+        """
+        memory_summary = summarise_memory(memory)
+        verify_summary = summarise_verify(getattr(work, "verify", None))
+        ambiguity = bool(getattr(work, "questions", None))
+        return compute_affected(
+            memory_hits=memory_summary["hits"],
+            verify_claims=verify_summary["claims"],
+            verify_first_try_passes=verify_summary["first_try_passes"],
+            ambiguity_flag=ambiguity,
+            changes=getattr(work, "changes", None),
+            applied_rules=getattr(work, "applied_rules", None),
+            test_plan=getattr(work, "test_plan", None),
+        )
+
 
 def derive_visibility(memory: Any) -> str | None:
     """Convenience helper: render the line directly from a memory list.

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.10.0",
     "keywords": [
       "agent-config",
       "skills",

package/CHANGELOG.md

@@ -429,6 +429,34 @@ 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.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

@@ -12,17 +12,37 @@ Give your AI agents an audit-disciplined orchestration contract — testing, Git
 
 ---
 
-## Start here
-
-Three ways in, depending on what you're doing today:
-
-| 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.
+## 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/`.
 
 ## Quickstart
 

package/config/agent-settings.template.yml

@@ -390,6 +390,34 @@ 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
+
 # --- Update check ---
 #
 # Daily background check against the npm registry for a newer

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

@@ -113,6 +113,36 @@ the trace inherits the **maximum** risk class across all files the
 phase touched. If no files were touched (pure planning phase), risk
 is `low`.
 
+## Memory consequence keys
+
+**Purpose.** Bound the surface area where a memory hit can be said
+to have *changed* an outcome. Closed list, not open — without this
+bound, every memory call risks the "memory affected everything"
+failure mode (Risk register row 2 of
+[`agents/roadmaps/road-to-proof-not-features.md`](../../agents/roadmaps/road-to-proof-not-features.md)).
+
+**Closed list (v1).** Exactly four keys. Adding a fifth requires a
+schema bump + entry under `### Breaking` in `CHANGELOG.md`.
+
+| Key | Source | Diff semantics |
+|---|---|---|
+| `confidence_band` | Top-level envelope field. | String inequality (`high` ≠ `medium` ≠ `low`). |
+| `risk_class` | Top-level envelope field. | String inequality. |
+| `applied_rules` | Derived: sorted list of `rules[].rule_id` where `applied == true`. | Set inequality. |
+| `test_plan` | Derived: sorted list of test paths captured in the Plan-phase `state.plan.tests` slice. May be `null` when the phase is not `plan` or no Plan-phase tests were captured. | Set inequality; `null` on either side suppresses the key from the diff. |
+
+**Diff semantics.** The producer renders two traces for the same
+phase: one **with** the memory entry consulted, one **without**
+(re-running the heuristic against `memory.hits` decremented by the
+entry's contribution). The `affected` field is the sorted list of
+keys above whose values differ between the two traces. Empty list
+means "consulted but no key diverged" — the call was informational,
+not load-bearing.
+
+**Out of scope for v1.** Gradations beyond binary key-diverged /
+not-diverged (overridden, combined, filtered). Tracked as a Phase-1-
+gated revisit in the same Risk register.
+
 ## Privacy floor
 
 - `memory.ids` carries opaque ids only — no entry bodies, no secrets.

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

@@ -205,6 +205,50 @@ that:
 The dispatcher silently no-ops when called with `--platform copilot`;
 the fallback is consumed by reading the rule, not by hook invocation.
 
+## Fixture corpus — `tests/fixtures/hooks/`
+
+Replay-safe, platform-native payloads. One JSON file per event in the
+agent-config event vocabulary. Consumed by `./agent-config hooks:replay`
+and by the dispatcher replay tests
+(`tests/hooks/test_hooks_replay.py` — Phase 2.4c).
+
+```
+tests/fixtures/hooks/
+  session_start.json · session_end.json · user_prompt_submit.json
+  pre_tool_use.json  · post_tool_use.json · stop.json
+  pre_compact.json   · agent_error.json
+  README.md          — corpus contract + platform-shape table
+```
+
+Each fixture is a **stdin payload** — the dispatcher wraps it via
+`_build_envelope` before handing it to a concern. Required keys:
+
+- Valid JSON object at the top level.
+- `session_id` — string, non-empty (drives feedback dir naming).
+- Event-specific fields realistic enough that the bound concerns
+  (`chat-history`, `roadmap-progress`, `context-hygiene`,
+  `verify-before-complete`, `minimal-safe-diff`) run without raising
+  — primarily `tool_name` (for `*_tool_use`), `prompt` (for
+  `user_prompt_submit`).
+- No real user content. Committed alongside source; the redaction
+  workflow in [`hook-payload-capture`](../hook-payload-capture.md)
+  applies to **captured** payloads, not committed fixtures.
+
+The corpus is platform-shape-representative, not platform-exhaustive
+— multi-platform shape coverage lives in
+`tests/hooks/test_event_shape_contract.py`. The replay test asserts
+1:1 mapping between `EVENT_VOCABULARY` and this directory.
+
+## Replay mode — `AGENT_CONFIG_REPLAY=1`
+
+Concerns that write under `agents/state/` MUST honor the
+`AGENT_CONFIG_REPLAY` env var: when set to `1`, skip all state
+mutations and run as read-only. The dispatcher passes the env var
+through to subprocess concerns unchanged. Concerns that do not honor
+the flag are listed by `./agent-config hooks:doctor` as not
+replay-safe; replay tests assert no `agents/state/` mutation
+post-invocation.
+
 ## Stability
 
 Beta. Breaking changes between v1 and v2 are allowed in a minor
@@ -218,3 +262,5 @@ majors.
   operational how-to for capturing redacted live payloads to upgrade
   a platform's chat-history extractor from `docs-verified` to
   `payload-verified`.
+- [`tests/fixtures/hooks/README.md`](../../tests/fixtures/hooks/README.md)
+  — fixture corpus contract.

package/docs/contracts/memory-visibility-v1.md

@@ -24,6 +24,7 @@ and a single space:
 
 ```
 🧠 Memory: <hits>/<asks> · ids=[<comma-separated-ids>]
+🧠 Memory: <hits>/<asks> · ids=[<comma-separated-ids>] · affected: <keys>
 ```
 
 Examples:
@@ -32,6 +33,8 @@ Examples:
 🧠 Memory: 3/4 · ids=[mem_42, mem_57, mem_91]
 🧠 Memory: 0/2 · ids=[]
 🧠 Memory: 5/5 · ids=[mem_a01, mem_a02, mem_a03, …+2]
+🧠 Memory: 3/4 · ids=[mem_42, mem_57] · affected: confidence_band,applied_rules
+🧠 Memory: 2/4 · ids=[mem_42] · affected: none
 ```
 
 Cap at 5 ids inline; remainder rendered as `…+N`. The full id list
@@ -45,10 +48,15 @@ lives in the decision-trace JSON
 | `hits` | Count of `memory_retrieve_*` calls during this turn that returned ≥ 1 entry. |
 | `asks` | Count of `memory_retrieve_*` calls during this turn — both successful and empty. |
 | `ids` | Stable memory entry ids returned across all calls, deduped, ordered by retrieval timestamp. |
+| `affected` | Optional trailing segment. Comma-separated list of decision-trace keys that diverged when this memory was consulted vs not consulted. Closed key list defined in [`decision-trace-v1.md § Memory consequence keys`](decision-trace-v1.md#memory-consequence-keys). Rendered as `none` when `hits ≥ 1` but no key diverged. Omitted entirely when `hits == 0` or when the producer cannot compute a counterfactual trace. |
 
 `hits ≤ asks` is invariant. If `asks == 0`, the engine MUST suppress
 the line entirely — no `0/0` noise.
 
+The `affected` segment is a forward-compat trailing extension per
+the Stability clause below — clients pinned to the segment-free
+shape MUST still parse the line.
+
 ## Privacy floor
 
 The visibility line and the JSON it derives from MUST NOT contain:
@@ -88,6 +96,31 @@ counts and ids for downstream metrics.
 Cost-profile lookup respects `.agent-settings.yml`'s `cost_profile`
 key. Default is `standard`.
 
+## End-of-run "Memory changed decisions" block
+
+When the visibility line carries a non-empty `affected` segment, the
+engine MUST also append a structured block at the end of the run's
+report surface so reviewers can audit attribution without parsing
+the inline segment:
+
+```
+Memory changed decisions:
+- mem_42 → confidence_band
+- mem_57 → confidence_band
+```
+
+Rules:
+
+- Suppressed entirely when `affected` is empty or absent (no key
+  diverged, or memory was not consulted).
+- Each consulted id from the visibility line's `ids` is paired with
+  each affected key. v1 attribution is aggregate; per-id attribution
+  is a follow-up risk tracked in the roadmap Risk register.
+- Block heading is the literal string `Memory changed decisions:`
+  followed by `-` bullet lines in `<id> → <key>` shape.
+- Implementation: `format_changed_decisions_block` in
+  `work_engine/scoring/memory_visibility.py`.
+
 ## Audit-as-memory feed
 
 The visibility output produced by the engine is the input to the