feat: worktree-per-task wave execution by daniellam258 · Pull Request #1 · CommandOSSLabs/ai-devkit

daniellam258 · 2026-08-10T15:09:01Z

What the skills get wrong today

Phase 3's wave predicate treats disjoint File scope: as sufficient for co-scheduling two tasks in one worktree. It is only necessary: toolchains with a shared mutable build root — Cargo is the canonical case, one workspace-level target/ behind an exclusive file lock — serialize two "independent" tasks into lock-thrash. In an agent-executed pipeline this is worse than serialization: every worker turn blocks on Blocking waiting for file lock or times out, each turn yields near-zero progress, and a consuming repo observed one ticket spinning for more than 24 hours this way.

The change

Independent wave tasks each get their own git worktree and branch from a pinned wave base, making build state private by construction and giving each task a private branch — which also removes the commit-contamination reason SDD serialized implementers, so path-scoped review packaging collapses into plain per-task-branch ranges with a scope-overflow check.

delivery-pipeline/references/worktree-wave-execution.md (new) — the runtime-neutral protocol: parent-WIP wip: snapshot with untracked-file inspection and a no-push-while-wip rule; pinned wave base + ledger wave manifest for crash resume; per-task git worktree add; build-dir-isolation verification; CoW cache seeding (fresh-destination-only); join as rebase-in-task-worktree + git merge --ff-only from the ticket worktree (a checked-out branch cannot be force-moved); controller-mediated reconciliation; one-writer rule; progress-discriminating thrash detection; snapshot absorption; sequential fallback for runtimes without concurrent dispatch.
delivery-pipeline/references/phase-3-execution.md — the three path-scoped-package conditions are replaced by the worktree-per-task contract; wave eligibility gains Exclusive resources:; thrash detection added.
delivery-spec-plan — new optional Exclusive resources: task header (worktrees isolate paths, not daemons: Docker, a shared local chain); File scope: bullet reworded so disjointness reads as necessary, not sufficient.
delivery-ship — ship gate: no wip: commit may remain in the PR range, verified via git log --oneline <base>..HEAD.
delivery-handoff — mid-wave handoffs enumerate live task worktrees (path, branch, wave-base SHA, join state) from the wave manifest.
delivery-workflow — the vendor-bindings template now asks each binding to record which wave-protocol protections the runtime enforces versus leaves to the controller, whether a native worktree convenience satisfies the contract, and the sequential fallback for runtimes without concurrent dispatch.
Versions bumped to 0.2.0 on the five touched skills.

Upstreamed from a consuming repo per CONTRIBUTING (contribute mode): the protocol shipped there first, then survived a seven-lens adversarial review whose corrections (ff-only join mechanics, fail-closed overflow check, untracked-inspection before snapshot, fresh-destination seeding, progress-based thrash discrimination) are already folded into this text. Repo-specific tooling names were genericized.

Verification

bash scripts/skill-lint.sh → skill-lint: OK (frontmatter, size, references, citations, paths, eval.json across skills/). delivery-pipeline/SKILL.md and delivery-spec-plan/SKILL.md sit exactly at the 150-line budget.

File-scope disjointness alone co-schedules tasks that still contend on a shared mutable build root (Cargo's locked target/ is the canonical case), which in agent-executed pipelines degrades into hours of lock-thrash. Observed: two co-scheduled Rust tasks blocked on 'Blocking waiting for file lock' for 24+ hours with near-zero progress per turn. Phase 3 waves now dispatch each task into its own worktree and branch from a pinned wave base: build state becomes private by construction and each task gains a private branch, removing both reasons SDD serialized. The full dispatch/join/reconciliation/cleanup protocol lands in references/worktree-wave-execution.md; phase-3-execution.md's three path-scoped-package conditions collapse into per-task-branch packaging with a scope-overflow check. Spec-plan gains the Exclusive resources: task header (worktrees isolate paths, not daemons), ship gains the no-wip-commit ship gate, and handoff enumerates live task worktrees for mid-wave relays.

The vendor-bindings template tells a binding author what to record per section but said nothing about the wave protocol: which of its protections the runtime enforces versus leaves to the controller, whether a native worktree convenience satisfies the pinned-base/named-branch/ retention/seeding contract, and the sequential fallback for runtimes without concurrent dispatch. Consuming repos' bindings already need exactly this section; the template now asks for it.

…version roster The pipeline's mandatory read #1 had been narrowed to delivery-workflow's scope-band reference while still labelled "tracking contract", leaving no item that required the delivery-workflow body — so an agent never loaded the execution-ready / ship-ready definitions that phases 4 and 5 gate on. Split it back into two entries: the skill, then its scope-band reference. The version roster listed cmk:agent-instructions in two mutually exclusive bands at once and still claimed 0.1.x for delivery-family skills this branch had just bumped. Rewrite it so every skill appears in exactly one band. Drop the now-subjectless codebase-docs size-budget exemption (this branch took it from 160+ lines to 32) and make the array expansion safe under set -u on bash 3.2, so the 150-line gate covers it again. Qualify getObject by client in the sui-sdk migration table — it had been listed on both the stale and the current side of a table whose contract is "use the right column". Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

daniellam258 · 2026-08-10T15:09:01Z

What the skills get wrong today

Phase 3's wave predicate treats disjoint File scope: as sufficient for co-scheduling two tasks in one worktree. It is only necessary: toolchains with a shared mutable build root — Cargo is the canonical case, one workspace-level target/ behind an exclusive file lock — serialize two "independent" tasks into lock-thrash. In an agent-executed pipeline this is worse than serialization: every worker turn blocks on Blocking waiting for file lock or times out, each turn yields near-zero progress, and a consuming repo observed one ticket spinning for more than 24 hours this way.

The change

Independent wave tasks each get their own git worktree and branch from a pinned wave base, making build state private by construction and giving each task a private branch — which also removes the commit-contamination reason SDD serialized implementers, so path-scoped review packaging collapses into plain per-task-branch ranges with a scope-overflow check.

delivery-pipeline/references/worktree-wave-execution.md (new) — the runtime-neutral protocol: parent-WIP wip: snapshot with untracked-file inspection and a no-push-while-wip rule; pinned wave base + ledger wave manifest for crash resume; per-task git worktree add; build-dir-isolation verification; CoW cache seeding (fresh-destination-only); join as rebase-in-task-worktree + git merge --ff-only from the ticket worktree (a checked-out branch cannot be force-moved); controller-mediated reconciliation; one-writer rule; progress-discriminating thrash detection; snapshot absorption; sequential fallback for runtimes without concurrent dispatch.
delivery-pipeline/references/phase-3-execution.md — the three path-scoped-package conditions are replaced by the worktree-per-task contract; wave eligibility gains Exclusive resources:; thrash detection added.
delivery-spec-plan — new optional Exclusive resources: task header (worktrees isolate paths, not daemons: Docker, a shared local chain); File scope: bullet reworded so disjointness reads as necessary, not sufficient.
delivery-ship — ship gate: no wip: commit may remain in the PR range, verified via git log --oneline <base>..HEAD.
delivery-handoff — mid-wave handoffs enumerate live task worktrees (path, branch, wave-base SHA, join state) from the wave manifest.
delivery-workflow — the vendor-bindings template now asks each binding to record which wave-protocol protections the runtime enforces versus leaves to the controller, whether a native worktree convenience satisfies the contract, and the sequential fallback for runtimes without concurrent dispatch.
Versions bumped to 0.2.0 on the five touched skills.

Upstreamed from a consuming repo per CONTRIBUTING (contribute mode): the protocol shipped there first, then survived a seven-lens adversarial review whose corrections (ff-only join mechanics, fail-closed overflow check, untracked-inspection before snapshot, fresh-destination seeding, progress-based thrash discrimination) are already folded into this text. Repo-specific tooling names were genericized.

Verification

bash scripts/skill-lint.sh → skill-lint: OK (frontmatter, size, references, citations, paths, eval.json across skills/). delivery-pipeline/SKILL.md and delivery-spec-plan/SKILL.md sit exactly at the 150-line budget.

File-scope disjointness alone co-schedules tasks that still contend on a shared mutable build root (Cargo's locked target/ is the canonical case), which in agent-executed pipelines degrades into hours of lock-thrash. Observed: two co-scheduled Rust tasks blocked on 'Blocking waiting for file lock' for 24+ hours with near-zero progress per turn. Phase 3 waves now dispatch each task into its own worktree and branch from a pinned wave base: build state becomes private by construction and each task gains a private branch, removing both reasons SDD serialized. The full dispatch/join/reconciliation/cleanup protocol lands in references/worktree-wave-execution.md; phase-3-execution.md's three path-scoped-package conditions collapse into per-task-branch packaging with a scope-overflow check. Spec-plan gains the Exclusive resources: task header (worktrees isolate paths, not daemons), ship gains the no-wip-commit ship gate, and handoff enumerates live task worktrees for mid-wave relays.

The vendor-bindings template tells a binding author what to record per section but said nothing about the wave protocol: which of its protections the runtime enforces versus leaves to the controller, whether a native worktree convenience satisfies the pinned-base/named-branch/ retention/seeding contract, and the sequential fallback for runtimes without concurrent dispatch. Consuming repos' bindings already need exactly this section; the template now asks for it.

…version roster The pipeline's mandatory read #1 had been narrowed to delivery-workflow's scope-band reference while still labelled "tracking contract", leaving no item that required the delivery-workflow body — so an agent never loaded the execution-ready / ship-ready definitions that phases 4 and 5 gate on. Split it back into two entries: the skill, then its scope-band reference. The version roster listed cmk:agent-instructions in two mutually exclusive bands at once and still claimed 0.1.x for delivery-family skills this branch had just bumped. Rewrite it so every skill appears in exactly one band. Drop the now-subjectless codebase-docs size-budget exemption (this branch took it from 160+ lines to 32) and make the array expansion safe under set -u on bash 3.2, so the 150-line gate covers it again. Qualify getObject by client in the sui-sdk migration table — it had been listed on both the stale and the current side of a table whose contract is "use the right column". Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

daniellam258 · 2026-08-10T15:09:01Z

What the skills get wrong today

Phase 3's wave predicate treats disjoint File scope: as sufficient for co-scheduling two tasks in one worktree. It is only necessary: toolchains with a shared mutable build root — Cargo is the canonical case, one workspace-level target/ behind an exclusive file lock — serialize two "independent" tasks into lock-thrash. In an agent-executed pipeline this is worse than serialization: every worker turn blocks on Blocking waiting for file lock or times out, each turn yields near-zero progress, and a consuming repo observed one ticket spinning for more than 24 hours this way.

The change

Independent wave tasks each get their own git worktree and branch from a pinned wave base, making build state private by construction and giving each task a private branch — which also removes the commit-contamination reason SDD serialized implementers, so path-scoped review packaging collapses into plain per-task-branch ranges with a scope-overflow check.

delivery-pipeline/references/worktree-wave-execution.md (new) — the runtime-neutral protocol: parent-WIP wip: snapshot with untracked-file inspection and a no-push-while-wip rule; pinned wave base + ledger wave manifest for crash resume; per-task git worktree add; build-dir-isolation verification; CoW cache seeding (fresh-destination-only); join as rebase-in-task-worktree + git merge --ff-only from the ticket worktree (a checked-out branch cannot be force-moved); controller-mediated reconciliation; one-writer rule; progress-discriminating thrash detection; snapshot absorption; sequential fallback for runtimes without concurrent dispatch.
delivery-pipeline/references/phase-3-execution.md — the three path-scoped-package conditions are replaced by the worktree-per-task contract; wave eligibility gains Exclusive resources:; thrash detection added.
delivery-spec-plan — new optional Exclusive resources: task header (worktrees isolate paths, not daemons: Docker, a shared local chain); File scope: bullet reworded so disjointness reads as necessary, not sufficient.
delivery-ship — ship gate: no wip: commit may remain in the PR range, verified via git log --oneline <base>..HEAD.
delivery-handoff — mid-wave handoffs enumerate live task worktrees (path, branch, wave-base SHA, join state) from the wave manifest.
delivery-workflow — the vendor-bindings template now asks each binding to record which wave-protocol protections the runtime enforces versus leaves to the controller, whether a native worktree convenience satisfies the contract, and the sequential fallback for runtimes without concurrent dispatch.
Versions bumped to 0.2.0 on the five touched skills.

Upstreamed from a consuming repo per CONTRIBUTING (contribute mode): the protocol shipped there first, then survived a seven-lens adversarial review whose corrections (ff-only join mechanics, fail-closed overflow check, untracked-inspection before snapshot, fresh-destination seeding, progress-based thrash discrimination) are already folded into this text. Repo-specific tooling names were genericized.

Verification

bash scripts/skill-lint.sh → skill-lint: OK (frontmatter, size, references, citations, paths, eval.json across skills/). delivery-pipeline/SKILL.md and delivery-spec-plan/SKILL.md sit exactly at the 150-line budget.

File-scope disjointness alone co-schedules tasks that still contend on a shared mutable build root (Cargo's locked target/ is the canonical case), which in agent-executed pipelines degrades into hours of lock-thrash. Observed: two co-scheduled Rust tasks blocked on 'Blocking waiting for file lock' for 24+ hours with near-zero progress per turn. Phase 3 waves now dispatch each task into its own worktree and branch from a pinned wave base: build state becomes private by construction and each task gains a private branch, removing both reasons SDD serialized. The full dispatch/join/reconciliation/cleanup protocol lands in references/worktree-wave-execution.md; phase-3-execution.md's three path-scoped-package conditions collapse into per-task-branch packaging with a scope-overflow check. Spec-plan gains the Exclusive resources: task header (worktrees isolate paths, not daemons), ship gains the no-wip-commit ship gate, and handoff enumerates live task worktrees for mid-wave relays.

The vendor-bindings template tells a binding author what to record per section but said nothing about the wave protocol: which of its protections the runtime enforces versus leaves to the controller, whether a native worktree convenience satisfies the pinned-base/named-branch/ retention/seeding contract, and the sequential fallback for runtimes without concurrent dispatch. Consuming repos' bindings already need exactly this section; the template now asks for it.

…version roster The pipeline's mandatory read #1 had been narrowed to delivery-workflow's scope-band reference while still labelled "tracking contract", leaving no item that required the delivery-workflow body — so an agent never loaded the execution-ready / ship-ready definitions that phases 4 and 5 gate on. Split it back into two entries: the skill, then its scope-band reference. The version roster listed cmk:agent-instructions in two mutually exclusive bands at once and still claimed 0.1.x for delivery-family skills this branch had just bumped. Rewrite it so every skill appears in exactly one band. Drop the now-subjectless codebase-docs size-budget exemption (this branch took it from 160+ lines to 32) and make the array expansion safe under set -u on bash 3.2, so the 150-line gate covers it again. Qualify getObject by client in the sui-sdk migration table — it had been listed on both the stale and the current side of a table whose contract is "use the right column". Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

daniellam258 · 2026-08-10T15:09:01Z

What the skills get wrong today

Phase 3's wave predicate treats disjoint File scope: as sufficient for co-scheduling two tasks in one worktree. It is only necessary: toolchains with a shared mutable build root — Cargo is the canonical case, one workspace-level target/ behind an exclusive file lock — serialize two "independent" tasks into lock-thrash. In an agent-executed pipeline this is worse than serialization: every worker turn blocks on Blocking waiting for file lock or times out, each turn yields near-zero progress, and a consuming repo observed one ticket spinning for more than 24 hours this way.

The change

Independent wave tasks each get their own git worktree and branch from a pinned wave base, making build state private by construction and giving each task a private branch — which also removes the commit-contamination reason SDD serialized implementers, so path-scoped review packaging collapses into plain per-task-branch ranges with a scope-overflow check.

delivery-pipeline/references/worktree-wave-execution.md (new) — the runtime-neutral protocol: parent-WIP wip: snapshot with untracked-file inspection and a no-push-while-wip rule; pinned wave base + ledger wave manifest for crash resume; per-task git worktree add; build-dir-isolation verification; CoW cache seeding (fresh-destination-only); join as rebase-in-task-worktree + git merge --ff-only from the ticket worktree (a checked-out branch cannot be force-moved); controller-mediated reconciliation; one-writer rule; progress-discriminating thrash detection; snapshot absorption; sequential fallback for runtimes without concurrent dispatch.
delivery-pipeline/references/phase-3-execution.md — the three path-scoped-package conditions are replaced by the worktree-per-task contract; wave eligibility gains Exclusive resources:; thrash detection added.
delivery-spec-plan — new optional Exclusive resources: task header (worktrees isolate paths, not daemons: Docker, a shared local chain); File scope: bullet reworded so disjointness reads as necessary, not sufficient.
delivery-ship — ship gate: no wip: commit may remain in the PR range, verified via git log --oneline <base>..HEAD.
delivery-handoff — mid-wave handoffs enumerate live task worktrees (path, branch, wave-base SHA, join state) from the wave manifest.
delivery-workflow — the vendor-bindings template now asks each binding to record which wave-protocol protections the runtime enforces versus leaves to the controller, whether a native worktree convenience satisfies the contract, and the sequential fallback for runtimes without concurrent dispatch.
Versions bumped to 0.2.0 on the five touched skills.

Upstreamed from a consuming repo per CONTRIBUTING (contribute mode): the protocol shipped there first, then survived a seven-lens adversarial review whose corrections (ff-only join mechanics, fail-closed overflow check, untracked-inspection before snapshot, fresh-destination seeding, progress-based thrash discrimination) are already folded into this text. Repo-specific tooling names were genericized.

Verification

bash scripts/skill-lint.sh → skill-lint: OK (frontmatter, size, references, citations, paths, eval.json across skills/). delivery-pipeline/SKILL.md and delivery-spec-plan/SKILL.md sit exactly at the 150-line budget.

File-scope disjointness alone co-schedules tasks that still contend on a shared mutable build root (Cargo's locked target/ is the canonical case), which in agent-executed pipelines degrades into hours of lock-thrash. Observed: two co-scheduled Rust tasks blocked on 'Blocking waiting for file lock' for 24+ hours with near-zero progress per turn. Phase 3 waves now dispatch each task into its own worktree and branch from a pinned wave base: build state becomes private by construction and each task gains a private branch, removing both reasons SDD serialized. The full dispatch/join/reconciliation/cleanup protocol lands in references/worktree-wave-execution.md; phase-3-execution.md's three path-scoped-package conditions collapse into per-task-branch packaging with a scope-overflow check. Spec-plan gains the Exclusive resources: task header (worktrees isolate paths, not daemons), ship gains the no-wip-commit ship gate, and handoff enumerates live task worktrees for mid-wave relays.

The vendor-bindings template tells a binding author what to record per section but said nothing about the wave protocol: which of its protections the runtime enforces versus leaves to the controller, whether a native worktree convenience satisfies the pinned-base/named-branch/ retention/seeding contract, and the sequential fallback for runtimes without concurrent dispatch. Consuming repos' bindings already need exactly this section; the template now asks for it.

…version roster The pipeline's mandatory read #1 had been narrowed to delivery-workflow's scope-band reference while still labelled "tracking contract", leaving no item that required the delivery-workflow body — so an agent never loaded the execution-ready / ship-ready definitions that phases 4 and 5 gate on. Split it back into two entries: the skill, then its scope-band reference. The version roster listed cmk:agent-instructions in two mutually exclusive bands at once and still claimed 0.1.x for delivery-family skills this branch had just bumped. Rewrite it so every skill appears in exactly one band. Drop the now-subjectless codebase-docs size-budget exemption (this branch took it from 160+ lines to 32) and make the array expansion safe under set -u on bash 3.2, so the 150-line gate covers it again. Qualify getObject by client in the sui-sdk migration table — it had been listed on both the stale and the current side of a table whose contract is "use the right column". Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

daniellam258 · 2026-08-10T15:09:01Z

What the skills get wrong today

Phase 3's wave predicate treats disjoint File scope: as sufficient for co-scheduling two tasks in one worktree. It is only necessary: toolchains with a shared mutable build root — Cargo is the canonical case, one workspace-level target/ behind an exclusive file lock — serialize two "independent" tasks into lock-thrash. In an agent-executed pipeline this is worse than serialization: every worker turn blocks on Blocking waiting for file lock or times out, each turn yields near-zero progress, and a consuming repo observed one ticket spinning for more than 24 hours this way.

The change

Independent wave tasks each get their own git worktree and branch from a pinned wave base, making build state private by construction and giving each task a private branch — which also removes the commit-contamination reason SDD serialized implementers, so path-scoped review packaging collapses into plain per-task-branch ranges with a scope-overflow check.

delivery-pipeline/references/worktree-wave-execution.md (new) — the runtime-neutral protocol: parent-WIP wip: snapshot with untracked-file inspection and a no-push-while-wip rule; pinned wave base + ledger wave manifest for crash resume; per-task git worktree add; build-dir-isolation verification; CoW cache seeding (fresh-destination-only); join as rebase-in-task-worktree + git merge --ff-only from the ticket worktree (a checked-out branch cannot be force-moved); controller-mediated reconciliation; one-writer rule; progress-discriminating thrash detection; snapshot absorption; sequential fallback for runtimes without concurrent dispatch.
delivery-pipeline/references/phase-3-execution.md — the three path-scoped-package conditions are replaced by the worktree-per-task contract; wave eligibility gains Exclusive resources:; thrash detection added.
delivery-spec-plan — new optional Exclusive resources: task header (worktrees isolate paths, not daemons: Docker, a shared local chain); File scope: bullet reworded so disjointness reads as necessary, not sufficient.
delivery-ship — ship gate: no wip: commit may remain in the PR range, verified via git log --oneline <base>..HEAD.
delivery-handoff — mid-wave handoffs enumerate live task worktrees (path, branch, wave-base SHA, join state) from the wave manifest.
delivery-workflow — the vendor-bindings template now asks each binding to record which wave-protocol protections the runtime enforces versus leaves to the controller, whether a native worktree convenience satisfies the contract, and the sequential fallback for runtimes without concurrent dispatch.
Versions bumped to 0.2.0 on the five touched skills.

Upstreamed from a consuming repo per CONTRIBUTING (contribute mode): the protocol shipped there first, then survived a seven-lens adversarial review whose corrections (ff-only join mechanics, fail-closed overflow check, untracked-inspection before snapshot, fresh-destination seeding, progress-based thrash discrimination) are already folded into this text. Repo-specific tooling names were genericized.

Verification

bash scripts/skill-lint.sh → skill-lint: OK (frontmatter, size, references, citations, paths, eval.json across skills/). delivery-pipeline/SKILL.md and delivery-spec-plan/SKILL.md sit exactly at the 150-line budget.

File-scope disjointness alone co-schedules tasks that still contend on a shared mutable build root (Cargo's locked target/ is the canonical case), which in agent-executed pipelines degrades into hours of lock-thrash. Observed: two co-scheduled Rust tasks blocked on 'Blocking waiting for file lock' for 24+ hours with near-zero progress per turn. Phase 3 waves now dispatch each task into its own worktree and branch from a pinned wave base: build state becomes private by construction and each task gains a private branch, removing both reasons SDD serialized. The full dispatch/join/reconciliation/cleanup protocol lands in references/worktree-wave-execution.md; phase-3-execution.md's three path-scoped-package conditions collapse into per-task-branch packaging with a scope-overflow check. Spec-plan gains the Exclusive resources: task header (worktrees isolate paths, not daemons), ship gains the no-wip-commit ship gate, and handoff enumerates live task worktrees for mid-wave relays.

The vendor-bindings template tells a binding author what to record per section but said nothing about the wave protocol: which of its protections the runtime enforces versus leaves to the controller, whether a native worktree convenience satisfies the pinned-base/named-branch/ retention/seeding contract, and the sequential fallback for runtimes without concurrent dispatch. Consuming repos' bindings already need exactly this section; the template now asks for it.

…version roster The pipeline's mandatory read #1 had been narrowed to delivery-workflow's scope-band reference while still labelled "tracking contract", leaving no item that required the delivery-workflow body — so an agent never loaded the execution-ready / ship-ready definitions that phases 4 and 5 gate on. Split it back into two entries: the skill, then its scope-band reference. The version roster listed cmk:agent-instructions in two mutually exclusive bands at once and still claimed 0.1.x for delivery-family skills this branch had just bumped. Rewrite it so every skill appears in exactly one band. Drop the now-subjectless codebase-docs size-budget exemption (this branch took it from 160+ lines to 32) and make the array expansion safe under set -u on bash 3.2, so the 150-line gate covers it again. Qualify getObject by client in the sui-sdk migration table — it had been listed on both the stale and the current side of a table whose contract is "use the right column". Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

daniellam258 · 2026-08-10T15:09:01Z

What the skills get wrong today

Phase 3's wave predicate treats disjoint File scope: as sufficient for co-scheduling two tasks in one worktree. It is only necessary: toolchains with a shared mutable build root — Cargo is the canonical case, one workspace-level target/ behind an exclusive file lock — serialize two "independent" tasks into lock-thrash. In an agent-executed pipeline this is worse than serialization: every worker turn blocks on Blocking waiting for file lock or times out, each turn yields near-zero progress, and a consuming repo observed one ticket spinning for more than 24 hours this way.

The change

Independent wave tasks each get their own git worktree and branch from a pinned wave base, making build state private by construction and giving each task a private branch — which also removes the commit-contamination reason SDD serialized implementers, so path-scoped review packaging collapses into plain per-task-branch ranges with a scope-overflow check.

delivery-pipeline/references/worktree-wave-execution.md (new) — the runtime-neutral protocol: parent-WIP wip: snapshot with untracked-file inspection and a no-push-while-wip rule; pinned wave base + ledger wave manifest for crash resume; per-task git worktree add; build-dir-isolation verification; CoW cache seeding (fresh-destination-only); join as rebase-in-task-worktree + git merge --ff-only from the ticket worktree (a checked-out branch cannot be force-moved); controller-mediated reconciliation; one-writer rule; progress-discriminating thrash detection; snapshot absorption; sequential fallback for runtimes without concurrent dispatch.
delivery-pipeline/references/phase-3-execution.md — the three path-scoped-package conditions are replaced by the worktree-per-task contract; wave eligibility gains Exclusive resources:; thrash detection added.
delivery-spec-plan — new optional Exclusive resources: task header (worktrees isolate paths, not daemons: Docker, a shared local chain); File scope: bullet reworded so disjointness reads as necessary, not sufficient.
delivery-ship — ship gate: no wip: commit may remain in the PR range, verified via git log --oneline <base>..HEAD.
delivery-handoff — mid-wave handoffs enumerate live task worktrees (path, branch, wave-base SHA, join state) from the wave manifest.
delivery-workflow — the vendor-bindings template now asks each binding to record which wave-protocol protections the runtime enforces versus leaves to the controller, whether a native worktree convenience satisfies the contract, and the sequential fallback for runtimes without concurrent dispatch.
Versions bumped to 0.2.0 on the five touched skills.

Upstreamed from a consuming repo per CONTRIBUTING (contribute mode): the protocol shipped there first, then survived a seven-lens adversarial review whose corrections (ff-only join mechanics, fail-closed overflow check, untracked-inspection before snapshot, fresh-destination seeding, progress-based thrash discrimination) are already folded into this text. Repo-specific tooling names were genericized.

Verification

bash scripts/skill-lint.sh → skill-lint: OK (frontmatter, size, references, citations, paths, eval.json across skills/). delivery-pipeline/SKILL.md and delivery-spec-plan/SKILL.md sit exactly at the 150-line budget.

File-scope disjointness alone co-schedules tasks that still contend on a shared mutable build root (Cargo's locked target/ is the canonical case), which in agent-executed pipelines degrades into hours of lock-thrash. Observed: two co-scheduled Rust tasks blocked on 'Blocking waiting for file lock' for 24+ hours with near-zero progress per turn. Phase 3 waves now dispatch each task into its own worktree and branch from a pinned wave base: build state becomes private by construction and each task gains a private branch, removing both reasons SDD serialized. The full dispatch/join/reconciliation/cleanup protocol lands in references/worktree-wave-execution.md; phase-3-execution.md's three path-scoped-package conditions collapse into per-task-branch packaging with a scope-overflow check. Spec-plan gains the Exclusive resources: task header (worktrees isolate paths, not daemons), ship gains the no-wip-commit ship gate, and handoff enumerates live task worktrees for mid-wave relays.

The vendor-bindings template tells a binding author what to record per section but said nothing about the wave protocol: which of its protections the runtime enforces versus leaves to the controller, whether a native worktree convenience satisfies the pinned-base/named-branch/ retention/seeding contract, and the sequential fallback for runtimes without concurrent dispatch. Consuming repos' bindings already need exactly this section; the template now asks for it.

…version roster The pipeline's mandatory read #1 had been narrowed to delivery-workflow's scope-band reference while still labelled "tracking contract", leaving no item that required the delivery-workflow body — so an agent never loaded the execution-ready / ship-ready definitions that phases 4 and 5 gate on. Split it back into two entries: the skill, then its scope-band reference. The version roster listed cmk:agent-instructions in two mutually exclusive bands at once and still claimed 0.1.x for delivery-family skills this branch had just bumped. Rewrite it so every skill appears in exactly one band. Drop the now-subjectless codebase-docs size-budget exemption (this branch took it from 160+ lines to 32) and make the array expansion safe under set -u on bash 3.2, so the 150-line gate covers it again. Qualify getObject by client in the sui-sdk migration table — it had been listed on both the stale and the current side of a table whose contract is "use the right column". Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

daniellam258 · 2026-08-10T15:09:01Z

What the skills get wrong today

Phase 3's wave predicate treats disjoint File scope: as sufficient for co-scheduling two tasks in one worktree. It is only necessary: toolchains with a shared mutable build root — Cargo is the canonical case, one workspace-level target/ behind an exclusive file lock — serialize two "independent" tasks into lock-thrash. In an agent-executed pipeline this is worse than serialization: every worker turn blocks on Blocking waiting for file lock or times out, each turn yields near-zero progress, and a consuming repo observed one ticket spinning for more than 24 hours this way.

The change

Independent wave tasks each get their own git worktree and branch from a pinned wave base, making build state private by construction and giving each task a private branch — which also removes the commit-contamination reason SDD serialized implementers, so path-scoped review packaging collapses into plain per-task-branch ranges with a scope-overflow check.

delivery-pipeline/references/worktree-wave-execution.md (new) — the runtime-neutral protocol: parent-WIP wip: snapshot with untracked-file inspection and a no-push-while-wip rule; pinned wave base + ledger wave manifest for crash resume; per-task git worktree add; build-dir-isolation verification; CoW cache seeding (fresh-destination-only); join as rebase-in-task-worktree + git merge --ff-only from the ticket worktree (a checked-out branch cannot be force-moved); controller-mediated reconciliation; one-writer rule; progress-discriminating thrash detection; snapshot absorption; sequential fallback for runtimes without concurrent dispatch.
delivery-pipeline/references/phase-3-execution.md — the three path-scoped-package conditions are replaced by the worktree-per-task contract; wave eligibility gains Exclusive resources:; thrash detection added.
delivery-spec-plan — new optional Exclusive resources: task header (worktrees isolate paths, not daemons: Docker, a shared local chain); File scope: bullet reworded so disjointness reads as necessary, not sufficient.
delivery-ship — ship gate: no wip: commit may remain in the PR range, verified via git log --oneline <base>..HEAD.
delivery-handoff — mid-wave handoffs enumerate live task worktrees (path, branch, wave-base SHA, join state) from the wave manifest.
delivery-workflow — the vendor-bindings template now asks each binding to record which wave-protocol protections the runtime enforces versus leaves to the controller, whether a native worktree convenience satisfies the contract, and the sequential fallback for runtimes without concurrent dispatch.
Versions bumped to 0.2.0 on the five touched skills.

Upstreamed from a consuming repo per CONTRIBUTING (contribute mode): the protocol shipped there first, then survived a seven-lens adversarial review whose corrections (ff-only join mechanics, fail-closed overflow check, untracked-inspection before snapshot, fresh-destination seeding, progress-based thrash discrimination) are already folded into this text. Repo-specific tooling names were genericized.

Verification

bash scripts/skill-lint.sh → skill-lint: OK (frontmatter, size, references, citations, paths, eval.json across skills/). delivery-pipeline/SKILL.md and delivery-spec-plan/SKILL.md sit exactly at the 150-line budget.

File-scope disjointness alone co-schedules tasks that still contend on a shared mutable build root (Cargo's locked target/ is the canonical case), which in agent-executed pipelines degrades into hours of lock-thrash. Observed: two co-scheduled Rust tasks blocked on 'Blocking waiting for file lock' for 24+ hours with near-zero progress per turn. Phase 3 waves now dispatch each task into its own worktree and branch from a pinned wave base: build state becomes private by construction and each task gains a private branch, removing both reasons SDD serialized. The full dispatch/join/reconciliation/cleanup protocol lands in references/worktree-wave-execution.md; phase-3-execution.md's three path-scoped-package conditions collapse into per-task-branch packaging with a scope-overflow check. Spec-plan gains the Exclusive resources: task header (worktrees isolate paths, not daemons), ship gains the no-wip-commit ship gate, and handoff enumerates live task worktrees for mid-wave relays.

The vendor-bindings template tells a binding author what to record per section but said nothing about the wave protocol: which of its protections the runtime enforces versus leaves to the controller, whether a native worktree convenience satisfies the pinned-base/named-branch/ retention/seeding contract, and the sequential fallback for runtimes without concurrent dispatch. Consuming repos' bindings already need exactly this section; the template now asks for it.

…version roster The pipeline's mandatory read #1 had been narrowed to delivery-workflow's scope-band reference while still labelled "tracking contract", leaving no item that required the delivery-workflow body — so an agent never loaded the execution-ready / ship-ready definitions that phases 4 and 5 gate on. Split it back into two entries: the skill, then its scope-band reference. The version roster listed cmk:agent-instructions in two mutually exclusive bands at once and still claimed 0.1.x for delivery-family skills this branch had just bumped. Rewrite it so every skill appears in exactly one band. Drop the now-subjectless codebase-docs size-budget exemption (this branch took it from 160+ lines to 32) and make the array expansion safe under set -u on bash 3.2, so the 150-line gate covers it again. Qualify getObject by client in the sui-sdk migration table — it had been listed on both the stale and the current side of a table whose contract is "use the right column". Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

daniellam258 · 2026-08-10T15:09:01Z

What the skills get wrong today

Phase 3's wave predicate treats disjoint File scope: as sufficient for co-scheduling two tasks in one worktree. It is only necessary: toolchains with a shared mutable build root — Cargo is the canonical case, one workspace-level target/ behind an exclusive file lock — serialize two "independent" tasks into lock-thrash. In an agent-executed pipeline this is worse than serialization: every worker turn blocks on Blocking waiting for file lock or times out, each turn yields near-zero progress, and a consuming repo observed one ticket spinning for more than 24 hours this way.

The change

Independent wave tasks each get their own git worktree and branch from a pinned wave base, making build state private by construction and giving each task a private branch — which also removes the commit-contamination reason SDD serialized implementers, so path-scoped review packaging collapses into plain per-task-branch ranges with a scope-overflow check.

delivery-pipeline/references/worktree-wave-execution.md (new) — the runtime-neutral protocol: parent-WIP wip: snapshot with untracked-file inspection and a no-push-while-wip rule; pinned wave base + ledger wave manifest for crash resume; per-task git worktree add; build-dir-isolation verification; CoW cache seeding (fresh-destination-only); join as rebase-in-task-worktree + git merge --ff-only from the ticket worktree (a checked-out branch cannot be force-moved); controller-mediated reconciliation; one-writer rule; progress-discriminating thrash detection; snapshot absorption; sequential fallback for runtimes without concurrent dispatch.
delivery-pipeline/references/phase-3-execution.md — the three path-scoped-package conditions are replaced by the worktree-per-task contract; wave eligibility gains Exclusive resources:; thrash detection added.
delivery-spec-plan — new optional Exclusive resources: task header (worktrees isolate paths, not daemons: Docker, a shared local chain); File scope: bullet reworded so disjointness reads as necessary, not sufficient.
delivery-ship — ship gate: no wip: commit may remain in the PR range, verified via git log --oneline <base>..HEAD.
delivery-handoff — mid-wave handoffs enumerate live task worktrees (path, branch, wave-base SHA, join state) from the wave manifest.
delivery-workflow — the vendor-bindings template now asks each binding to record which wave-protocol protections the runtime enforces versus leaves to the controller, whether a native worktree convenience satisfies the contract, and the sequential fallback for runtimes without concurrent dispatch.
Versions bumped to 0.2.0 on the five touched skills.

Upstreamed from a consuming repo per CONTRIBUTING (contribute mode): the protocol shipped there first, then survived a seven-lens adversarial review whose corrections (ff-only join mechanics, fail-closed overflow check, untracked-inspection before snapshot, fresh-destination seeding, progress-based thrash discrimination) are already folded into this text. Repo-specific tooling names were genericized.

Verification

bash scripts/skill-lint.sh → skill-lint: OK (frontmatter, size, references, citations, paths, eval.json across skills/). delivery-pipeline/SKILL.md and delivery-spec-plan/SKILL.md sit exactly at the 150-line budget.

File-scope disjointness alone co-schedules tasks that still contend on a shared mutable build root (Cargo's locked target/ is the canonical case), which in agent-executed pipelines degrades into hours of lock-thrash. Observed: two co-scheduled Rust tasks blocked on 'Blocking waiting for file lock' for 24+ hours with near-zero progress per turn. Phase 3 waves now dispatch each task into its own worktree and branch from a pinned wave base: build state becomes private by construction and each task gains a private branch, removing both reasons SDD serialized. The full dispatch/join/reconciliation/cleanup protocol lands in references/worktree-wave-execution.md; phase-3-execution.md's three path-scoped-package conditions collapse into per-task-branch packaging with a scope-overflow check. Spec-plan gains the Exclusive resources: task header (worktrees isolate paths, not daemons), ship gains the no-wip-commit ship gate, and handoff enumerates live task worktrees for mid-wave relays.

The vendor-bindings template tells a binding author what to record per section but said nothing about the wave protocol: which of its protections the runtime enforces versus leaves to the controller, whether a native worktree convenience satisfies the pinned-base/named-branch/ retention/seeding contract, and the sequential fallback for runtimes without concurrent dispatch. Consuming repos' bindings already need exactly this section; the template now asks for it.

…version roster The pipeline's mandatory read #1 had been narrowed to delivery-workflow's scope-band reference while still labelled "tracking contract", leaving no item that required the delivery-workflow body — so an agent never loaded the execution-ready / ship-ready definitions that phases 4 and 5 gate on. Split it back into two entries: the skill, then its scope-band reference. The version roster listed cmk:agent-instructions in two mutually exclusive bands at once and still claimed 0.1.x for delivery-family skills this branch had just bumped. Rewrite it so every skill appears in exactly one band. Drop the now-subjectless codebase-docs size-budget exemption (this branch took it from 160+ lines to 32) and make the array expansion safe under set -u on bash 3.2, so the 150-line gate covers it again. Qualify getObject by client in the sui-sdk migration table — it had been listed on both the stale and the current side of a table whose contract is "use the right column". Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

daniellam258 added 2 commits August 10, 2026 22:08