@houseofwolvesllc/claude-scrum-skill 2.1.0 → 2.1.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-scrum-skill",
   "description": "Complete scrum pipeline — PRD to production release with Claude as scrum master. Includes project scaffolding, sprint planning, status tracking, sprint releases, and full-project emulation testing.",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "author": {
     "name": "House of Wolves LLC"
   },

package/lib/workflows/sprint_pipeline.js

@@ -1,8 +1,33 @@
-// sprint_pipeline.js — per-story sprint execution as a pipeline.
+// sprint_pipeline.js — per-story sprint execution.
 //
-// Invoked by /project-orchestrate Phase 1 Step 3. Replaces the v1.x
-// Task-spawning prose with per-stage barrier removal and concurrency up
-// to min(16, cpu_cores - 2) per the Workflow tool's cap.
+// Invoked by /project-orchestrate Phase 1 Step 3. Each story runs its own
+// independent chain — implement → review → verify → open PR — with no
+// per-stage barriers and concurrency up to min(16, cpu_cores - 2) per the
+// Workflow tool's cap.
+//
+// Concurrency safety. Stories run in parallel against one git repository, so
+// the model is built around a single invariant: the main working tree is
+// mutated only by the serialized local-mode merge step. Everything else stays
+// off it.
+//   - Implement and verify run in isolated worktrees (`isolation: 'worktree'`).
+//     They create/build the story branch in their own tree, so concurrent
+//     `git checkout -b` and commits never race in the shared tree. Branches and
+//     commits land in the shared object store and are visible afterward.
+//   - Review only diffs two refs (object-store comparison, no checkout), so it
+//     never touches the working tree.
+//   - Local-mode finalize merges each story branch into the shared release
+//     branch in the main tree; these merges are serialized behind a lock so
+//     concurrent fan-in merges cannot race. GitHub mode opens independent PRs
+//     and needs no lock.
+//
+// Dependency gating. A story does not start until every blocker that is also in
+// this batch has finished `done` (see `blocked_by`). Because a dependent only
+// branches after its in-batch blockers have merged into the release branch, it
+// builds on their work. Blockers outside this batch are the orchestrator's
+// concern — it passes only stories whose external blockers are already resolved
+// (SKILL.md "Independence check"). The in-batch graph is assumed acyclic; the
+// orchestrate skill validates the dependency DAG (cycle + missing-edge checks)
+// before any story reaches this workflow.
 //
 // args: {
 //   stories: Story[],              // StorySchema-shaped
@@ -151,7 +176,7 @@ ${(story.acceptance_criteria || []).map(c => `  - ${c}`).join('\n')}
 
 **Technical context:** ${story.technical_context || '(none provided)'}
 
-**Branch strategy:** Create branch \`story/${story.slug}\` from \`${releaseBranch}\`. Implement. Commit with a clear message. Return the branch name, the commit SHAs, and any notes.
+**Branch strategy:** You are in an isolated git worktree — work only here; do not touch other branches. Create branch \`story/${story.slug}\` from the latest \`${releaseBranch}\` (\`git checkout -b story/${story.slug} ${releaseBranch}\`); it already contains any in-sprint dependency this story builds on. Implement. Commit with a clear message. Return the branch name, the commit SHAs, and any notes.
 
 Do NOT open a PR yet. Do NOT merge. The next stage handles review.`
 }
@@ -159,7 +184,7 @@ Do NOT open a PR yet. Do NOT merge. The next stage handles review.`
 function buildReviewPrompt(impl, story) {
   return `You are reviewing the implementation of story ${story.slug} on branch ${impl.branch}.
 
-Read the diff between ${releaseBranch} and ${impl.branch}.
+Read the diff between ${releaseBranch} and ${impl.branch} with \`git diff ${releaseBranch}...${impl.branch}\` — do NOT check out either branch (other stories run concurrently in this repository; checking out would disturb the shared working tree).
 
 Story acceptance criteria:
 ${(story.acceptance_criteria || []).map(c => `  - ${c}`).join('\n')}
@@ -172,7 +197,7 @@ Return a ReviewVerdict: recommendation (accept | accept-with-followups | block),
 function buildVerifyPrompt(review, story) {
   return `You are running a lightweight verification on story ${story.slug}.
 
-If the project has a build/lint/test command, run it on the story branch. If not, perform a smoke read of the changed files to confirm no obvious runtime defects (broken imports, syntax errors, dangling references).
+You are in an isolated git worktree — check out \`story/${story.slug}\` here (\`git checkout story/${story.slug}\`) so any build artifacts stay off the shared working tree. If the project has a build/lint/test command, run it on the story branch. If not, perform a smoke read of the changed files to confirm no obvious runtime defects (broken imports, syntax errors, dangling references).
 
 Return verifyStatus (pass | warn | fail) and brief notes.`
 }
@@ -196,69 +221,140 @@ phase('Review')
 phase('Verify')
 phase('Open PR')
 
-const results = await pipeline(
-  stories,
-  // Stage 1: Implement
-  story =>
-    agent(buildImplementPrompt(story), {
-      label: `impl:${story.slug}`,
-      phase: 'Implement',
-      schema: IMPL_RETURN_SCHEMA,
-    }),
-  // Stage 2: Review
-  (impl, story) =>
-    impl
-      ? agent(buildReviewPrompt(impl, story), {
-          label: `review:${story.slug}`,
-          phase: 'Review',
-          schema: REVIEW_VERDICT_SCHEMA,
-        }).then(review => ({ impl, review }))
-      : null,
-  // Stage 3: Verify
-  (prev, story) =>
-    prev
-      ? agent(buildVerifyPrompt(prev.review, story), {
-          label: `verify:${story.slug}`,
-          phase: 'Verify',
-          schema: VERIFY_RETURN_SCHEMA,
-        }).then(verify => ({ ...prev, verify }))
-      : null,
-  // Stage 4: Open PR (or local merge)
-  (prev, story) => {
-    if (!prev) return null
-    const { impl, review, verify } = prev
-    // If the reviewer said block, short-circuit to blocked status without an openPR call.
-    if (review.recommendation === 'block') {
-      const blockers = [
-        ...review.findings.critical.map(f => f.title),
-        ...review.findings.warning.map(f => f.title),
-      ]
-      return makeSprintStoryReturn({
-        storySlug: story.slug,
-        status: 'blocked',
-        branch: impl.branch,
-        commits: impl.commits,
-        blockers,
-        reason: 'Review recommended block.',
-      })
-    }
-    // If verify failed, also short-circuit.
-    if (verify.verifyStatus === 'fail') {
-      return makeSprintStoryReturn({
-        storySlug: story.slug,
-        status: 'blocked',
-        branch: impl.branch,
-        commits: impl.commits,
-        blockers: [verify.notes || 'verification failed'],
-        reason: 'Verification failed.',
-      })
+const batchSlugs = new Set(stories.map(story => story.slug))
+
+/**
+ * Blockers of `story` that are also in this batch, by trailing slug.
+ * blocked_by entries may be bare slugs or "<epic>/<slug>" references. A story
+ * cannot block itself, and blockers outside the batch are the orchestrator's
+ * concern (it only passes stories whose external blockers are resolved).
+ */
+function inBatchBlockers(story) {
+  return (story.blocked_by || [])
+    .map(reference => reference.split('/').pop())
+    .filter(slug => slug !== story.slug && batchSlugs.has(slug))
+}
+
+// Serializes local-mode merges onto the shared release branch: each merge runs
+// only after the previous one settles, success or failure, so a failed merge
+// never stalls the rest. GitHub mode opens independent PRs and does not use it.
+let mergeChain = Promise.resolve()
+function serializeMerge(runMerge) {
+  const merged = mergeChain.then(runMerge, runMerge)
+  mergeChain = merged.then(() => {}, () => {})
+  return merged
+}
+
+function reviewBlocked(story, impl, review) {
+  return makeSprintStoryReturn({
+    storySlug: story.slug,
+    status: 'blocked',
+    branch: impl.branch,
+    commits: impl.commits,
+    blockers: [
+      ...review.findings.critical.map(finding => finding.title),
+      ...review.findings.warning.map(finding => finding.title),
+    ],
+    reason: 'Review recommended block.',
+  })
+}
+
+function verifyBlocked(story, impl, verify) {
+  return makeSprintStoryReturn({
+    storySlug: story.slug,
+    status: 'blocked',
+    branch: impl.branch,
+    commits: impl.commits,
+    blockers: [verify.notes || 'verification failed'],
+    reason: 'Verification failed.',
+  })
+}
+
+function dependencyBlocked(story, unmet) {
+  return makeSprintStoryReturn({
+    storySlug: story.slug,
+    status: 'blocked',
+    blockers: unmet.map(slug => `upstream story ${slug} did not complete`),
+    reason: 'Upstream in-sprint dependency did not complete.',
+  })
+}
+
+// Each story's terminal promise, registered before any chain runs so a
+// dependent can always await its blocker regardless of array order.
+const terminal = new Map()
+
+async function runStory(story) {
+  const blockers = inBatchBlockers(story)
+  if (blockers.length) {
+    const outcomes = await Promise.all(blockers.map(slug => terminal.get(slug)))
+    const unmet = blockers.filter((_, index) => outcomes[index]?.status !== 'done')
+    if (unmet.length) {
+      log(`Skipping ${story.slug}: upstream ${unmet.join(', ')} did not complete.`)
+      return dependencyBlocked(story, unmet)
     }
-    return agent(buildOpenPRPrompt(verify, story, impl), {
+  }
+
+  const impl = await agent(buildImplementPrompt(story), {
+    label: `impl:${story.slug}`,
+    phase: 'Implement',
+    schema: IMPL_RETURN_SCHEMA,
+    isolation: 'worktree',
+  })
+  if (!impl) return null
+
+  const review = await agent(buildReviewPrompt(impl, story), {
+    label: `review:${story.slug}`,
+    phase: 'Review',
+    schema: REVIEW_VERDICT_SCHEMA,
+  })
+  if (!review) return null
+  if (review.recommendation === 'block') return reviewBlocked(story, impl, review)
+
+  const verify = await agent(buildVerifyPrompt(review, story), {
+    label: `verify:${story.slug}`,
+    phase: 'Verify',
+    schema: VERIFY_RETURN_SCHEMA,
+    isolation: 'worktree',
+  })
+  if (!verify) return null
+  if (verify.verifyStatus === 'fail') return verifyBlocked(story, impl, verify)
+
+  const finalize = () =>
+    agent(buildOpenPRPrompt(verify, story, impl), {
       label: `pr:${story.slug}`,
       phase: 'Open PR',
       schema: SPRINT_STORY_RETURN_SCHEMA,
     })
-  }
-)
 
+  // Local mode mutates the shared release branch — serialize. GitHub mode opens
+  // an independent PR and can run concurrently.
+  return backendMode === 'github' ? finalize() : serializeMerge(finalize)
+}
+
+// Open the gate only after every terminal promise is registered, so a
+// dependent's blocker lookup never races an unregistered entry.
+let openGate
+const gate = new Promise(resolve => {
+  openGate = resolve
+})
+for (const story of stories) {
+  terminal.set(
+    story.slug,
+    // Isolate each chain: a thrown agent or stage becomes a 'failed' result
+    // rather than rejecting Promise.all and tearing down the whole batch. A
+    // failed (not 'done') outcome also correctly blocks any dependent.
+    gate.then(() => runStory(story)).catch(error => {
+      const detail = error?.message || String(error)
+      log(`Story ${story.slug} errored: ${detail}`)
+      return makeSprintStoryReturn({
+        storySlug: story.slug,
+        status: 'failed',
+        reason: `Unhandled error: ${detail}`,
+      })
+    })
+  )
+}
+openGate()
+
+const results = await Promise.all(stories.map(story => terminal.get(story.slug)))
 return results.filter(Boolean)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@houseofwolvesllc/claude-scrum-skill",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Claude Code skills for scrum project management — PRD to production release pipeline with project scaffolding, sprint planning, status tracking, sprint releases, full-project emulation testing, autonomous orchestration, and project cleanup.",
   "bin": {},
   "publishConfig": {

package/skills/project-orchestrate/SKILL.md

@@ -425,9 +425,11 @@ For each entry in the workflow's return:
 - `status: "blocked"` — Record `blockers[]` and `reason` in the state file. Add the `blocked` label to the story (or mark blocked locally). Continue.
 - `status: "failed"` — Same persistence as blocked, plus log the failure for sprint-release to roll over.
 
-#### Concurrency and barriers
+#### Concurrency, isolation, and barriers
 
-The workflow runs up to `min(16, cpu_cores - 2)` stories concurrently with no per-stage barriers — each story's pipeline is independent, so one slow review doesn't gate other stories' implementations. The barrier-removal benefit is unconditional; the concurrency lift is conditional on host cores (a 4-core host gets concurrency 2, an 8-core host gets 6, a 18+-core host gets the full 16). On all hosts this still beats v1.x's hardcoded 3 + barriers model on most sprint sizes.
+The workflow runs up to `min(16, cpu_cores - 2)` stories concurrently with no per-stage barriers — each story's chain is independent, so one slow review doesn't gate other stories' implementations. The barrier-removal benefit is unconditional; the concurrency lift is conditional on host cores (a 4-core host gets concurrency 2, an 8-core host gets 6, a 18+-core host gets the full 16). On all hosts this still beats v1.x's hardcoded 3 + barriers model on most sprint sizes.
+
+Concurrent stories share one git repository, so the workflow keeps them off each other's toes with a single invariant: **the main working tree is mutated only by the serialized local-mode merge step.** Implement and verify run in isolated git worktrees (each story branches, commits, and builds in its own tree); review only diffs refs without checking out; and in local mode the per-story merges into the shared release branch are serialized behind a lock. This is why the **Independence check** (above) need not be perfect: even if two file-overlapping stories run together, they cannot corrupt each other's branch or commits. The workflow also re-enforces dependencies internally — a story whose `blocked_by` names another story *in the same batch* waits for that story to finish `done` before it starts, and branches from the release branch only after the blocker has merged.
 
 #### Progress updates