Add runtime isolation discipline for Pattern C cluster parallelism

CHANGELOG.json

@@ -1,5 +1,47 @@
 {
   "releases": [
+    {
+      "version": "Unreleased",
+      "date": null,
+      "sections": {
+        "added": [
+          {
+            "title": "`docs/multi-agent-handoff.md` — new `§Where inter-agent communication is recorded` section (routing table).",
+            "body": "Inserted between `§Field read/write ownership matrix` and `§Tool-permission matrix`. The field-ownership matrix declares **who may write each field**; the new routing table declares **which field carries each shape of inter-agent communication** — Implementer → Planner deltas (`implementation_notes[*]` with `type: planner_disagreement`), Reviewer → Implementer send-backs (`review_notes[*]` + phase reversion), Reviewer's reference-existence challenges (`review_notes[*]` + Implementer's reproduction in `implementation_notes[*]`), specialist audit findings (`parallel_groups[*].synthesis` for Reviewer parent), cluster-scoped returns (`implementation_clusters[*].status` + `cluster_id`-tagged `implementation_notes[*]`), supersede acts (new manifest with `supersedes`), escalations to humans (`escalations[*]`, `waivers[*]`), outbound briefings (`handoff_narrative` / `residual_risk` / `next_action`), long-running sub-agent mid-flight progress (D2 working-space path), supervision keep/discard/stop records (Tier-2 project memory), and sign-offs (`approvals[*]`). Cites only existing fields and rules; introduces no new artifact type, no new schema field, no new evidence enum. Closes the consolidation gap where a reader following a send-back, a discovery return, or an escalation had to reconstruct the routing per change. Includes an explicit `§What this table is not` callout: the table is not a license to introduce a free-form conversation log; every channel listed has a structured field, an owner, and a binding rule, and bundling them into a single flat artifact would erase the field decomposition the schema is built on."
+          },
+          {
+            "title": "`docs/glossary.md` — new term `Agent loop` in `§Process terms`.",
+            "body": "The phrase \"agent loop\" appeared in four canonical files (`docs/runtime-hook-contract.md`, `docs/ci-cd-integration-hooks.md`, `docs/throughput-first-merge-philosophy.md`, `docs/diagrams.md`) as if defined, but no glossary entry pinned the term. The new entry defines it as the runtime cycle in which a tool-using agent reads context → emits action → observes result → repeats, names what binds on the loop normatively (phase progression, evidence emission, hook firing, role boundaries) versus what is bridge-layer (event-driven vs polling, single-threaded vs concurrent, sync vs async tool dispatch), enumerates termination triggers (stop conditions, iteration caps, Tree D escalation, runtime-imposed boundaries), and explicitly classifies the **loop-as-clock failure mode** (fire delegation → end turn → wait for tick → fire again, without canonical-role concurrent work) as the central pattern long-running-delegation D3 and `docs/anti-entropy-discipline.md` Rule \"Sweep agent runs 24/7\" reject from opposite directions. Pinning the definition in the glossary prevents the term from drifting independently across consumers and gives the four consuming files a single citation target rather than each implying its own definition."
+          },
+          {
+            "title": "`skills/engineering-workflow/references/long-running-delegation.md` — new `§Mapping the runtime loop to phase boundaries` section.",
+            "body": "Added between `§Capability-category mapping` and `§Anti-patterns`. Maps the abstract D1 (checkpoint-bounded scope) / D2 (artifact-grounded progress) / D3 (canonical-role non-idle) disciplines onto a concrete agent loop without endorsing the failure modes the methodology rejects. Four sub-points: (a) where loop iterations meet phase boundaries (a phase advance is a single iteration; intra-phase iterations may fire Category B/C hooks but do not change `phase`); (b) where D2 writes happen on a loop tick (per useful-work iteration; canonical role's separate loop may tail the D2 path on its own iterations as part of its defined polling plan — two loops, one shared artifact path, never one loop polling the other agent); (c) termination triggers in priority order (stop conditions per `AGENTS.md §Stop conditions` → iteration caps per `application-driven-loop.md` and `fix-retest-loop.md` framed as **diagnostic budgets, not compute budgets** → Tree D escalation per `docs/decision-trees.md` → runtime-imposed boundaries); (d) explicit anti-pattern call-out classifying loop-as-clock as symmetric with `anti-entropy-discipline.md` \"Sweep agent runs 24/7\" and with `ai-operating-contract.md §11` fabrication-by-silence. Closes the dangling-term gap where multiple files used \"agent loop\" as a runtime primitive without normative content explaining how the methodology binds to it."
+          },
+          {
+            "title": "`docs/runtime-hook-contract.md`, `docs/ci-cd-integration-hooks.md`, `docs/throughput-first-merge-philosophy.md`, `docs/diagrams.md` — back-pointers from each \"agent loop\" mention to the new glossary entry.",
+            "body": "One inline parenthetical link per file, on the first significant mention. `runtime-hook-contract.md:120` (prose-only refuse fallback, \"outside the agent loop\"); `ci-cd-integration-hooks.md:208` (runtime-vs-CI hook contrast, \"inside the agent loop\"); `throughput-first-merge-philosophy.md:14` (agent-velocity rationale, \"every block costs an agent loop iteration\"); `diagrams.md:227` (`See also` line on Stack Map diagram §6, where the `RUNTIME` node label uses the term). No substantive prose changed; only the dangling-term references resolved. Per `CLAUDE.md §5`, term changes propagate to all consumers in the same change."
+          },
+          {
+            "title": "`skills/engineering-workflow/references/cluster-parallelism.md` — new `§Runtime isolation` section (Pattern C runtime enforcement layer).",
+            "body": "Existing §The core rule §1 declares file-disjoint scope at the schema level; the runtime mechanism that enforces the declaration was undefined, leaving three failure modes the schema cannot detect: races on files outside `scope_files` (lockfiles, build caches, `.git/index`), concurrent appends to shared manifest array fields, and merge-back ambiguity at fan-in. The new section names the discipline in three sub-sections: **Per-cluster exclusive write region** (each cluster's Implementer runs in an isolated working copy where only that cluster holds write capability; the methodology binds on the property — mutual write exclusion covering files outside `scope_files` as well as inside — not on the runtime mechanism, which is a bridge-layer choice per `docs/file-role-map.md`); **Manifest field collision rule** (each cluster's Implementer appends only entries tagged with its own `cluster_id` to shared array fields like `implementation_notes[]`; cross-cluster aggregation is the Planner's responsibility at §5 fan-in); **Merge-back ordering at fan-in** (three-rule priority: halt overrides → cluster_id-sorted assembly → cross-cluster gap-check first; determinism is the property so two Reviewers replaying the same fan-in produce byte-identical merged output). Includes a six-row failure-mode catalog enumerating concrete races (lockfile conflicts, build-cache poisoning, ambiguous notes attribution, git-commit collisions, shared `/tmp` contamination, parallel write-locks erasing the parallelism benefit). Closes the gap where `cluster-parallelism.md` had a declared invariant 1 (file-disjoint) but no operational discipline binding the declaration to runtime enforcement, leaving Pattern C's runtime safety implicit. Cross-cutting: §The core rule §1 explanation extended to point at the new section; §Why each invariant is needed gains a row distinguishing declared vs runtime-enforced disjointness; §Anti-patterns gains four rows (shared write region, untagged shared-array appends, premature merge before gap check, verification writes to shared OS path); §Relation to other documents updated to cite the new schema field."
+          },
+          {
+            "title": null,
+            "body": "**`schemas/change-manifest.schema.yaml` (and generated `.json`) — new optional `implementation_clusters[*].isolation_root` field.** Declarative companion to the new §Runtime isolation section: a string field naming the cluster's exclusive write region (worktree path, container mount, scoped filesystem view). **Optional**, additive (existing manifests without the field validate unchanged); not part of the cluster's `required` list because not every runtime can produce a stable identifier (ephemeral container mounts, in-memory filesystems). When declared, gives the Reviewer a verifiable target (\"did this cluster's Implementer in fact write only within `isolation_root`?\"); when absent, the runtime-isolation property still binds but cannot be audited from the manifest alone. Field description cross-references `cluster-parallelism.md §Runtime isolation §Per-cluster exclusive write region` so a runtime bridge author landing in the schema can navigate to the binding rule. Backwards compatibility: existing 1.x manifests using `implementation_clusters` without `isolation_root` continue to validate; pre-1.30 manifests (without `implementation_clusters` at all) continue to validate."
+          }
+        ],
+        "changed": [
+          {
+            "title": "`skills/engineering-workflow/references/cluster-parallelism.md §The core rule §1` — extended to name runtime-enforcement scope.",
+            "body": "Previously only declared \"no two clusters declare `scope_files` patterns that could resolve to the same file.\" Now adds: \"Declaration alone does not prevent races on files outside `scope_files` (lockfiles, build caches, `.git/index`) or on shared manifest array fields; runtime enforcement of the declaration lives in §Runtime isolation below.\" This is a normative scope expansion — invariant 1 now binds on both declaration and runtime enforcement, surfacing the operational gap the new section closes. The §Why each invariant is needed table also gains a row distinguishing the two enforcement layers."
+          },
+          {
+            "title": "`skills/engineering-workflow/references/parallelization-patterns.md` §Phase applicability summary footnote — Pattern C disciplines list updated.",
+            "body": "The footnote naming Pattern C's disciplines previously listed \"file-disjoint clusters, discovery-halt-all-clusters, Reviewer cross-cluster gap check, `implementation_clusters` manifest field.\" Now also names \"runtime isolation per `cluster-parallelism.md §Runtime isolation`.\" This is a one-clause cross-reference addition — substantive Pattern C content remains in `cluster-parallelism.md` per `CLAUDE.md §5` (do not split SoT across multiple files)."
+          }
+        ]
+      }
+    },
     {
       "version": "1.34.0",
       "date": "2026-04-29",