Add runtime isolation discipline for Pattern C cluster parallelism#15
Merged
Add runtime isolation discipline for Pattern C cluster parallelism#15
Conversation
Closes the gap where cluster-parallelism.md §The core rule §1
declared file-disjoint scope at the schema layer but left runtime
enforcement undefined. Three failure modes the schema cannot detect
were not addressed normatively:
- races on files outside scope_files (lockfiles, build caches,
.git/index)
- concurrent appends to shared manifest array fields
- merge-back ambiguity at fan-in
Adds:
1. cluster-parallelism.md §Runtime isolation — substantive new
section binding the runtime enforcement layer of invariant 1.
Three sub-sections:
- Per-cluster exclusive write region (mutual write exclusion
across clusters, covering files outside scope_files; methodology
binds on the property, runtime mechanism is bridge-layer
per docs/file-role-map.md §Where a new rule belongs)
- Manifest field collision rule (cluster_id-tagged appends only
to shared arrays; cross-cluster aggregation is the Planner's
fan-in responsibility)
- Merge-back ordering at fan-in (halt overrides → cluster_id-
sorted → cross-cluster gap-check first; determinism property
so two Reviewers replay byte-identical merged output)
Plus a six-row failure-mode catalog enumerating concrete races.
2. schemas/change-manifest.schema.yaml — optional
implementation_clusters[*].isolation_root field (additive,
backwards-compatible). String type; declared = Reviewer has a
verifiable target; absent = property still binds but cannot be
audited from manifest alone. Pre-existing manifests without the
field validate unchanged.
3. cluster-parallelism.md §The core rule §1 extended with a clause
pointing 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 isolation_root.
4. parallelization-patterns.md — one-clause cross-reference added
to the §Phase applicability summary footnote. Substantive
Pattern C content stays in cluster-parallelism.md per
CLAUDE.md §5 (do not split SoT across multiple files); the plan
originally proposed the substantive edit in parallelization-
patterns.md, but on read of the existing cross-reference
structure (parallelization-patterns.md L124-L131 explicitly
delegates Pattern C discipline to cluster-parallelism.md), that
placement would have created the SoT drift CLAUDE.md §5 warns
against. Substantive edit relocated to the canonical SoT.
CHANGELOG.md and CHANGELOG.json updated under [Unreleased].
Tool-agnostic check: no vendor / model / framework / product names
introduced. Worktree / container / scoped filesystem view named as
capability categories with bridge-layer implementation deferred.
https://claude.ai/code/session_01LfypX8MN6jAZdtaYwUUdpr
The phrase "agent loop" appeared in four canonical files
(runtime-hook-contract.md, ci-cd-integration-hooks.md,
throughput-first-merge-philosophy.md, diagrams.md) as if defined,
but no glossary entry pinned the term. Closes the dangling-term
gap so consumers cite a single canonical definition rather than
implying their own.
Adds:
1. docs/glossary.md §Process terms — new term "Agent loop" inserted
before "Sub-agent invocation". Defines the runtime cycle (read
context → emit action → observe result → repeat); names what
binds 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);
classifies the loop-as-clock failure mode (fire delegation →
end turn → wait for tick → fire again) as the central pattern
D3 and anti-entropy-discipline.md "Sweep agent runs 24/7" reject
from opposite directions.
2. skills/engineering-workflow/references/long-running-delegation.md
— new §Mapping the runtime loop to phase boundaries section
between §Capability-category mapping and §Anti-patterns. Four
sub-points:
- where loop iterations meet phase boundaries (phase advance
= one iteration; intra-phase iterations fire Category B/C
hooks but do not change phase)
- where D2 writes happen on a loop tick (two loops, one shared
artifact path; never one loop polling the other agent)
- termination triggers in priority order (stop conditions →
iteration caps as DIAGNOSTIC budgets not compute budgets →
Tree D → runtime-imposed boundaries)
- explicit loop-as-clock anti-pattern callout, symmetric with
anti-entropy-discipline.md and ai-operating-contract.md §11
3. Back-pointers added to each of the four consuming files, one
inline parenthetical link per file on the first significant
mention. Per CLAUDE.md §5, term changes propagate to all
consumers in the same change. No substantive prose changed in
the consuming files; only the dangling-term references resolved.
Tool-agnostic check: no vendor / model / framework / product names
introduced. Loop semantics named as capability categories
(event-driven vs polling, sync vs async dispatch).
CHANGELOG.md and CHANGELOG.json updated under [Unreleased].
https://claude.ai/code/session_01LfypX8MN6jAZdtaYwUUdpr
Adds docs/multi-agent-handoff.md §Where inter-agent communication
is recorded — a routing table inserted between §Field read/write
ownership matrix and §Tool-permission matrix.
The field-ownership matrix already declares WHO may write each
field. The new routing table declares WHICH field carries each
shape of inter-agent communication, so a reader following a
send-back, a discovery return, or an escalation can locate the
binding artifact without reconstructing the routing per change.
Channels indexed (existing fields and rules only):
- Working brief at spawn time → Task Prompt (six columns)
- Implementation delta from plan → implementation_notes[*]
with type: planner_disagreement (Tier 1 annotate)
- Implementation discovery return → phase reversion +
implementation_notes[*] with type: discovery (Tier 2)
- Phase 4 record + evidence → manifest as state snapshot
- Review send-back → review_notes[*] + phase reversion
- Reviewer's reference-existence challenge → review_notes[*]
cite + Implementer's reproduction in implementation_notes[*]
- Specialist audit finding → parallel_groups[*].synthesis
- Cluster-scoped completion / discovery → implementation_clusters
[*].status transition + cluster_id-tagged implementation_notes
- Supersede act → new manifest with supersedes (Tier 3)
- Escalation requiring human → escalations[*], waivers[*]
- Outbound briefing → handoff_narrative + residual_risk +
next_action
- Long-running sub-agent mid-flight progress → D2 working-space
path (not a manifest field until promoted)
- Supervision keep/discard/stop → Tier-2 project-memory
supervision log (referenced via parallel_groups[*]
.supervision_log_ref when declared)
- Sign-off → approvals[*]
No new artifact type, no new schema field, no new evidence enum
introduced — the channels exist; only the index was missing. Each
row's "binding rule" column points back to the canonical source
per CLAUDE.md §5 (do not redefine in another file).
Includes 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 with an owner and a binding
rule that defines its lifecycle; bundling them into a single flat
artifact would erase the field decomposition the schema is built
on. The entry deliberately closes the door on the "agent dialog
log" proposal that the routing table consolidation might otherwise
appear to invite.
Tool-agnostic check: no vendor / model / framework / product names
introduced. All cited fields are existing schema entries and all
cited rules are existing canonical sections.
CHANGELOG.md and CHANGELOG.json updated under [Unreleased].
https://claude.ai/code/session_01LfypX8MN6jAZdtaYwUUdpr
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds the runtime enforcement layer for Pattern C cluster parallelism, closing the gap where file-disjoint scope was declared at the schema level but the operational discipline binding that declaration to runtime safety was undefined. The change introduces three new sections to
cluster-parallelism.mddefining exclusive write regions, manifest field collision rules, and merge-back ordering, plus a new optional schema fieldisolation_rootto declare cluster write boundaries. It also adds supporting documentation on agent loops and inter-agent communication routing.Scope classification
Surfaces touched
isolation_root, new binding rules for cluster-scoped execution)Rationale:
isolation_rootis a new optional manifest field that declares the cluster's exclusive write region; the runtime isolation rules are binding contracts for Pattern C implementers.§Runtime isolationsection defines operational discipline (exclusive write regions, manifest field collision, merge-back ordering) that was previously implicit; anti-patterns section gains four new rows covering runtime isolation violations.Source of Truth impact
skills/engineering-workflow/references/cluster-parallelism.md(primary),schemas/change-manifest.schema.yaml(schema),docs/multi-agent-handoff.md(inter-agent routing),docs/glossary.md(agent loop term),skills/engineering-workflow/references/long-running-delegation.md(loop-to-phase mapping)cluster-parallelism.md§The core rule §1 extended to point at runtime isolation sectioncluster-parallelism.md§Why each invariant is needed updated to distinguish declared vs runtime-enforced disjointnesscluster-parallelism.md§Anti-patterns gains four new rowscluster-parallelism.md§Relation to other documents updated to citeisolation_rootfieldschemas/change-manifest.schema.yamlnewimplementation_clusters[*].isolation_rootfielddocs/multi-agent-handoff.mdnew routing table for inter-agent communication (consolidates existing rules)docs/glossary.mdnew "Agent loop" term definitionskills/engineering-workflow/references/long-running-delegation.mdnew §Mapping the runtime loop to phase boundariesCHANGELOG.mdandCHANGELOG.jsonupdated with all additionsEvidence
python3 .github/scripts/validate-schema-syntax.py— schema validatessh .github/scripts/check-version-consistency.sh— version consistency maintainedSchema validation output:
Breaking-change level
The new
isolation_rootfield is optional and does not affect existing manifests. Existing Pattern C manifests without the field continue to validate. The new operational discipline (exclusive write regions, manifest field collision rules, merge-back ordering) is binding for new Pattern C invocations but does not retroactively break existing ones — it formalizes what was already required implicitly.Rollback mode
All changes are additive documentation and schema extensions. Reverting this PR removes the runtime isolation section and the optional
isolation_rootfield; existing manifests remain valid.https://claude.ai/code/session_01LfypX8MN6jAZdtaYwUUdpr