@event4u/agent-config 1.17.0 → 1.19.0

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.

package/docs/contracts/load-context-budget-model.md

@@ -65,6 +65,86 @@ extraction pattern (Q1) and the **one-rule + three-contexts** consolidation
 (Q2); model (b) literal is the accounting that makes both patterns
 honest about their cost.
 
+## Load order (Q1) — file order in frontmatter
+
+Locked by Phase 1.2 of `road-to-context-layer-maturity` (council
+session `2026-05-03T17-56-21Z`, v2 lock).
+
+When a rule declares multiple `load_context:` and / or
+`load_context_eager:` entries, the agent processes them in the order
+they appear in the YAML list, top to bottom. `load_context_eager:`
+entries are concatenated into the active context in declaration
+order; `load_context:` entries are available for lazy retrieval in
+the same order, surfaced first-listed-first when the rule body cites
+them in prose.
+
+**Rejected alternatives:**
+
+- *Citation order in prose* — non-machine-readable; would force every
+  rule to embed a sort hint and the linter to parse rule body text.
+- *Priority field per entry* — adds frontmatter surface area without
+  observable benefit. The current rule with the most contexts
+  (`autonomous-execution`, 3 contexts) reads each in declaration
+  order without ambiguity.
+
+This contract treats list order as the canonical signal. Authors
+must order their `load_context:` entries from "load this first" to
+"load this last" so prose citations and frontmatter agree.
+
+## Per-rule context-count cap (Q2) — ≤ 3 contexts per rule
+
+Locked by Phase 1.3 of `road-to-context-layer-maturity` (council
+session `2026-05-03T17-56-21Z`, v2 lock). Enforced by
+`scripts/check_always_budget.py` as `MAX_CONTEXTS_PER_RULE = 3`.
+
+A rule's combined count of `load_context:` + `load_context_eager:`
+top-level entries must not exceed **3**. The cap is on *declared*
+entries (depth 1 from the rule), not transitive closure — depth-2
+context citations are governed by the depth-2 nesting cap below.
+
+**Rationale:**
+
+- Empirical max in the current rule set is 3
+  (`autonomous-execution`); the cap locks the ceiling without forcing
+  any rewrite.
+- A 4th declared context is the structural signal that the rule
+  should split (one rule, one obligation surface), not load more.
+- Cross-platform mechanical: a count check is O(N), no semantic
+  analysis, identical observable on Augment and Claude Code.
+
+The cap applies to **all rule types** (`always` and `auto`) — Q2 is
+a structural constraint on rule shape, not a budget concern.
+
+## Cross-rule sharing (Q3) — Model (b) literal locked
+
+Locked by Phase 1.4 of `road-to-context-layer-maturity` (decision
+3a). The accounting model in § The locked model above stands without
+shared-context discount.
+
+**Decision:** when context X is loaded by N rules, each rule pays
+the full `RawSize(X)` under Model (b). No `chars(X) / N` discount.
+
+**Rationale (3a over 3b):**
+
+- The linter is correct as-is — `RECOVERY_BAND_ENABLED` plus the
+  per-rule allowlist is already a working ratchet to drive total
+  utilization below 100 %.
+- 3b would require a linter rewrite plus a new failure-mode test
+  family (cross-rule attribution, divisor-stability invariants).
+  Phase 1.4a's 4-hour / 200-LOC feasibility cap was structured to
+  reject 3b on cost; with no current shared-context patterns
+  exceeding 1 loader per context (verified Phase 1.1 inventory), 3b
+  has no measurable upside.
+- Phase 4c (shared-context discount) becomes a no-op under 3a.
+  Phase 4 leverage shifts to 4a (demote), 4b (merge), and 4d
+  (hard-compress) — see `road-to-context-layer-maturity` Phase 4
+  inputs gate.
+
+**Reopener:** if a future inventory shows ≥ 3 shared-context loaders
+and total utilization re-enters the 95–100 % zone after Phase 4
+completes, run the Phase 1.4a feasibility spike and propose 3b via
+contract version bump.
+
 ## Nesting cap — depth 2
 
 A rule's `load_context:` may cite a context (depth 1). A context may

package/docs/contracts/load-context-schema.md

@@ -85,6 +85,26 @@ Single-rule contexts that don't fit one of the canonical topics live
 directly under `contexts/` (see `contexts/model-recommendations.md`,
 `contexts/skills-and-commands.md`).
 
+## Per-rule context-count cap (Q2)
+
+A rule's combined count of `load_context:` + `load_context_eager:`
+top-level entries MUST be ≤ **3**. Enforced by
+`scripts/check_always_budget.py` (`MAX_CONTEXTS_PER_RULE`); see
+[`load-context-budget-model.md § Per-rule context-count cap (Q2)`](load-context-budget-model.md#per-rule-context-count-cap-q2--3-contexts-per-rule)
+for the locking contract.
+
+A 4th context is the structural signal that the rule should split,
+not load more. Authors hitting the cap should extract a sibling rule
+with its own obligation surface, not stretch the existing one.
+
+## Load order
+
+Entries load in **frontmatter list order**, top-to-bottom. Author
+your list in "first read" order so prose citations and frontmatter
+agree. See
+[`load-context-budget-model.md § Load order (Q1)`](load-context-budget-model.md#load-order-q1--file-order-in-frontmatter)
+for the locking rationale.
+
 ## Combined char-budget guard
 
 `load_context_eager:` triggers a budget check:

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

@@ -0,0 +1,138 @@
+---
+stability: beta
+---
+
+# Memory-visibility v1
+
+**Purpose.** Pin the format of the user-facing visibility line that
+every memory-using `/work` and `/implement-ticket` run prints, so the
+user can tell what the agent retrieved and what it ignored.
+Complements [`agent-memory-contract.md`](agent-memory-contract.md):
+that doc describes the **CLI surface and backend states**; this doc
+describes the **operator-facing surface** the engine emits per turn.
+
+**Scope.** Defines the line shape, the privacy floor, the opt-out
+toggle, and the interaction with the chat-history heartbeat. Does
+**not** define how memory entries are scored or routed — that is the
+sibling agent-memory package.
+
+Last refreshed: 2026-05-04.
+
+## Line shape
+
+A single one-line ASCII record, prefixed with the memory icon `🧠`
+and a single space:
+
+```
+🧠 Memory: <hits>/<asks> · ids=[<comma-separated-ids>]
+```
+
+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]
+```
+
+Cap at 5 ids inline; remainder rendered as `…+N`. The full id list
+lives in the decision-trace JSON
+([`decision-trace-v1.md`](decision-trace-v1.md)).
+
+## Field semantics
+
+| Field | Meaning |
+|---|---|
+| `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. |
+
+`hits ≤ asks` is invariant. If `asks == 0`, the engine MUST suppress
+the line entirely — no `0/0` noise.
+
+## Privacy floor
+
+The visibility line and the JSON it derives from MUST NOT contain:
+
+- Entry **bodies**, summaries, or quoted snippets.
+- Secrets, tokens, environment values, or paths outside the
+  package's `agents/state/` and `tests/` allowlist.
+- User identifiers beyond what is already public in the working
+  directory's `.agent-settings.yml` (e.g. developer name).
+
+The privacy floor is enforced by
+`tests/contracts/test_memory_visibility_redaction.py` — any new
+content path that ships memory output adds a fixture there.
+
+## Opt-out
+
+On by default whenever memory is asked at all in a turn. Users can
+suppress the visibility line via:
+
+```yaml
+memory:
+  visibility: off
+```
+
+Off-mode does not silence the underlying memory calls; it only stops
+the line from rendering. The decision-trace JSON still records the
+counts and ids for downstream metrics.
+
+## Interaction with chat-history heartbeat
+
+The chat-history heartbeat (`📒` marker) and the memory-visibility
+line are **independent**:
+
+- Heartbeat fires on cadence boundaries
+  (`per_turn` / `per_phase` / `per_tool`).
+- Visibility line fires whenever `asks ≥ 1` for the current turn,
+  regardless of cadence.
+- Both render on the same reply when both fire — heartbeat first,
+  visibility line second, separated by a single newline.
+
+The visibility line is **not** part of the heartbeat payload — that
+keeps the heartbeat contract bytes-stable.
+
+## Cadence interaction
+
+| Cost profile | Visibility line | Heartbeat |
+|---|---|---|
+| `lean` | suppress unless `asks ≥ 3` | per-phase |
+| `standard` | always when `asks ≥ 1` | per-turn |
+| `verbose` | always when `asks ≥ 1` | per-tool |
+
+Cost-profile lookup respects `.agent-settings.yml`'s `cost_profile`
+key. Default is `standard`.
+
+## Audit-as-memory feed
+
+The visibility output produced by the engine is the input to the
+audit-as-memory pipeline (consumed by the sibling distribution +
+adoption work). Concretely:
+
+- The engine emits the line + the underlying counts to the
+  decision-trace JSON.
+- A consumer hook reads `agents/state/work/<work-id>/decision-trace-*.json`,
+  rolls counts up to the session level, and feeds the result back
+  into the agent-memory store as an audit entry.
+
+This contract pins the **producer** side. The audit-feed consumer
+lives outside the package's stable surface and must read this
+contract before parsing.
+
+## 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 the visibility line shape — clients
+parsing the stream MUST treat unknown trailing fields as forward-
+compat extensions.
+
+## Cross-references
+
+- CLI surface and backend states:
+  [`agent-memory-contract.md`](agent-memory-contract.md).
+- Decision-trace JSON consumes the same counts:
+  [`decision-trace-v1.md`](decision-trace-v1.md).
+- Privacy regression test path:
+  `tests/contracts/test_memory_visibility_redaction.py`.