sdcorejs-parallel-dispatch

name

sdcorejs-parallel-dispatch

description

Parallel execution gate and subagent fan-out discipline. Use after execute-plan asks sequential vs parallel and user chooses parallel, when an approved plan is explicitly split across agents, or for read-only parallel audits. Validates protocol-v2 contracts, runtime capabilities, path/resource ownership, per-unit isolation, DAG waves, deterministic fan-in, repair ownership, and evidence freshness. Applies to all tracks and generic work. Runtime-localized.

Codex path resolution: Resolve ../_refs/... relative to this SKILL.md. Resolve another SDCoreJS skill by opening the sibling folder ../<skill-name>/SKILL.md.

Parallel Dispatch

Shared Protocols

Before executing this skill:

1. Read and apply ../_refs/shared/tasklist.md for non-trivial execution tasks.
2. Read and apply ../_refs/shared/persona.md if a project persona exists.
3. Read and apply ../_refs/shared/project-context.md for project memory, resume checkpoints, summaries, specs/plans, tasks, and relevant memories.
4. Read ../_refs/orchestration/parallel-protocol.md completely and validate every dispatch against it.
5. Import the deterministic validators from ../_refs/orchestration/parallel-protocol.mjs; do not reimplement their contract, path, workspace, topology, fan-in, repair, evidence, or state checks in prompts.
6. For write-capable work, read ../_refs/orchestration/workspace-isolation.md before creating or selecting unit workspaces.
7. Current user request, current files, diffs, logs, failing tests, and command output override stored context.
8. Before a user-facing choice, apply ../_refs/shared/user-choice-prompt.md.

Purpose

This skill is the fail-closed gate for parallel work. It validates a protocol-v2 contract, classifies the dependency topology, dispatches only mechanically safe units, integrates immutable or exact-diff results deterministically, and runs global verification plus the final read-only branch-ready gate.

The public compatibility verdicts remain:

• SEQUENTIAL
• PARALLEL-CANDIDATE
• ROLE-SPLIT

The underlying topology is one of READ_ONLY_FANOUT, INDEPENDENT_WRITE_UNITS, CONTRACT_BOUND_ROLES, or SEQUENTIAL_DAG.

Parent write permission is narrow: it may write an approved protocol/brief artifact under the target .sdcorejs/ area and may apply validated unit results in the integration workspace. It does not own implementation files. Shared implementation paths belong to a concrete unit or integration-unit; parent-contract-only owns contract metadata only. In the read-only contract, the parent and units make no writes.

Entry Contracts

Accept exactly one discriminated contract branch:

1. approved-plan for every write-capable unit. It requires a contract ID, immutable approved-plan path and hash, frozen-contract identity, working-tree preflight, per-unit workspace/result protocol, and mandatory final tail.
2. read-only-request for report/evidence-only fan-out. It requires request and scope hashes plus write_policy: deny. It must not invent approved-plan fields. Every unit uses shared-readonly, has no writable paths, returns a report, and fails if the before/after changed-path snapshot is non-empty.

Unapproved implementation returns to sdcorejs-plan. A direct write-capable invocation must run the same working-tree preflight as sdcorejs-execute-plan; direct invocation is not a bypass.

Workflow

1. Precheck

1. Run sdcorejs-explore (summary-read) through project-context. Do not refresh the summary merely because execution is write-approved.
2. Validate the contract union and its hashes.
3. Capture current branch, HEAD, staged, unstaged, untracked, dirty-diff hash, unrelated dirty paths, and intended-output overlap.
4. Negotiate runtime capabilities. Unknown write-heavy capability is blocking.
5. Derive paths, stacks, executors, commands, roles, and resources from the approved plan and target evidence. Do not assume a framework or directory layout.
6. Emit the complete parallel_context from the protocol reference.

The emitted context begins with:

parallel_context:
  schema_version: 2
  contract: <approved-plan or read-only-request>
  target:
    stack_profile: <detected or plan-provided profile>
  units: []
  global_verification: {}

For consumers that still read allowed_paths_by_unit, provide it only as a derived compatibility projection of units[].ownership.allowed_paths. The protocol-v2 unit records, prohibited_paths, and shared_files ownership are authoritative; the projection cannot grant write permission.

If the working tree, contract, runtime, or target boundary cannot be proven safe, return SEQUENTIAL, return to the appropriate plan/execution decision, or mark the run BLOCKED; do not dispatch optimistically.

2. Classify And Wave

Build a dependency/resource graph from each unit's depends_on, produces, consumes, path ownership, exclusive resources, shared read-only resources, ports, database namespace, temp/cache/coverage roots, and expected cost.

• Read-only audits may share one checkout.
• Two expensive independent write units are enough to justify parallelism.
• Heterogeneous independent units may run together when ownership is disjoint.
• Contract-bound roles run as plan-derived DAG waves, not as an unconditional Product/Design/Backend/Frontend/QC flat wave.
• Resource or path conflicts force separate waves or sequential execution.
• Cross-stack test authoring may run early; execution waits for required integrated implementation results.

Do not dispatch approval gates, contract drafting, shared-file mutation, or a single cheap task.

3. Isolate And Brief

Each write unit must have a known workspace strategy, path, branch when applicable, common base HEAD, ownership scope, resource allocation, verification command/cwd, result type, failure policy, and current contract hash. Supported strategies are:

• shared-readonly
• disjoint-same-tree, only after mechanical path and resource checks
• worktree, with a distinct unit worktree/result and separate integration workspace

Briefs are self-contained and include contract identity, approved-plan slice, dependencies, exact scope, allowed/prohibited paths, resources, verification, result protocol, redaction rules, and out-of-scope behavior. A unit may not self-certify path compliance and may not spawn subagents.

4. Dispatch And Collect

Dispatch only units whose dependencies are satisfied. Respect the runtime's effective concurrency. If calls serialize, run explicit sequential waves and report that real concurrency was unavailable.

Each result must identify its commit, patch, exact working-tree diff, or report; the expected base; actual changed paths computed by the parent; exit code; blockers; and evidence digest. A missing result, non-zero claimed success, wrong cwd/base, timeout, deterministic path/contract violation, or unexpected write fails or blocks the unit under the protocol state machine.

5. Review, Repair, And Fan In

For each result:

1. Recompute changed paths from Git/filesystem evidence.
2. Run the mandatory path-boundary validator from the protocol reference.
3. Validate base ancestry/result identity and Stage A scope compliance.
4. Run Stage B sdcorejs-review for changed code.
5. Route valid findings through sdcorejs-repair-loop using an explicit repair_assignment bound to the original owner, workspace, base result, current contract hash, and allowlist.
6. Re-run Stage A, Stage B, path validation, and unit verification after writes.
7. Fan in only a PASSED unit, one at a time, in declared merge order using the declared cherry-pick, patch, or disjoint-same-tree strategy.
8. Run required integration probes after each accepted result.

Deferred blocking findings produce BLOCKED, never PASSED. A cross-unit repair requires recorded integration ownership transfer and invalidates all affected evidence.

6. Contract Change Control

Never mutate an approved plan or frozen contract in place.

• A non-semantic erratum creates a new revision/hash record and re-evaluates affected evidence.
• A material change transitions to PLAN_REVISION_REQUIRED, stops affected dispatch/fan-in, returns to sdcorejs-plan, obtains approval for a new immutable plan revision, marks dependent old results/evidence STALE, and re-briefs affected units.

7. Global Verification And Final Tail

After deterministic fan-in, run every discovered global command against the exact integrated HEAD/diff. Each evidence record contains command, cwd, timestamps, exit code, associated result identity, output digest, and environment fingerprint.

For write-capable work, verify_before_done, branch_ready_final_gate, and no_writes_after_branch_ready are always true. Run all write-producing tail steps before sdcorejs-ship (verify-before-done mode), then run sdcorejs-ship (branch-ready mode) as the last read-only gate. Any later write invalidates the corresponding evidence and requires rerunning the gate. No writes after branch-ready are permitted without that invalidation and rerun.

Reporting

Report the topology, compatibility verdict, runtime capability/fallback, per-unit status/result/evidence, integration order and atomicity outcome, global checks, final gate, and genuine blockers. Distinguish deterministic local simulation from real runtime concurrency evidence.

Rules

Must do

• Validate protocol v2 before dispatch.
• Fail closed on unknown write-heavy capability, ownership, base, workspace, or result identity.
• Mechanically compute actual changed paths and store the normalized list.
• Use plan-derived DAG waves and deterministic integration.
• Keep approved snapshots immutable and stale old evidence after revision.
• Route repairs to an explicit owner/workspace.
• Surface partial failures and unsupported cancellation honestly.
• Run global verification and final branch-ready on the final state.

Must not

• Require fake approved-plan fields for read-only requests.
• Treat disjoint application files as sufficient isolation proof.
• Let a prompt allowlist replace mechanical path validation.
• Use parent as an implementation-file owner; use a concrete unit, integration-unit, or parent-contract-only.
• Retry deterministic path or contract violations automatically.
• Fan in failed, blocked, cancelled, or stale units.
• Hard-code one framework, package manager, directory layout, or five-role wave.
• Promise timeout/cancellation/concurrency a runtime cannot provide.
• Write after final branch-ready without invalidating and rerunning it.

Cross-references

• ../_refs/orchestration/parallel-protocol.md - normative schema, validators, state machine, fan-in, failure, repair, and evidence semantics.
• ../_refs/orchestration/parallel-protocol.mjs - distributed deterministic validator implementation used by runtime automation and tests.
• ../_refs/orchestration/workspace-isolation.md - safe unit/integration workspace creation and cleanup ownership.
• sdcorejs-execute-plan - approved-plan execution entrypoint.
• sdcorejs-plan - immutable plan creation and revision approval.
• sdcorejs-review, sdcorejs-repair-loop, and sdcorejs-ship - per-unit review/repair and final verification gates.