valent-pipeline 0.19.53 → 0.19.55

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "valent-pipeline",
-  "version": "0.19.53",
+  "version": "0.19.55",
   "description": "v3 multi-agent AI pipeline for software development lifecycle",
   "type": "module",
   "bin": {

package/pipeline/orchestrators/claude-code/sprint.workflow.js

@@ -885,16 +885,27 @@ const parCfg = (() => {
 const parallelEnabled = gitFlowEnabled && parCfg.enabled === true
 const maxParallelStories = Math.max(1, Number.isInteger(parCfg.maxStories) ? parCfg.maxStories
   : Number.isInteger(parCfg.max_stories) ? parCfg.max_stories : 2)
+// Worktree ISOLATION (review 2026-06-24, M-152): each story builds in its OWN worktree under
+// worktreeDir/<id> instead of the shared main checkout. Parallel mode REQUIRES it (concurrent
+// stories cannot share one checkout); serial mode can opt in via `git.worktree_isolation: true` to
+// stop cross-story working-tree residue from bleeding into a story's review-pin `git add -A` sweep
+// (the contamination that swept 3.10 files into story/3.1). Isolation is DECOUPLED from CONCURRENCY:
+// the ship-lock, work queue, and post-merge re-verify stay keyed on `parallelEnabled` (concurrency),
+// while the worktree create/cd/workdir paths + --require-evidence-on-assert (evidence must be
+// self-contained in the worktree) key on THIS. Parallel implies isolation. Default off => no
+// behavior change until a project opts in at a clean boundary.
+const worktreeIsolation = gitFlowEnabled
+  && (gitCfg.worktree_isolation === true || gitCfg.worktreeIsolation === true || parallelEnabled)
 const worktreeDir = (typeof (parCfg.worktreeDir ?? parCfg.worktree_dir) === 'string'
   && (parCfg.worktreeDir ?? parCfg.worktree_dir).trim()) || '.valent-worktrees'
-const wtFlag = parallelEnabled
+const wtFlag = worktreeIsolation
   ? ` --worktree${worktreeDir !== '.valent-worktrees' ? ` --worktree-dir ${worktreeDir}` : ''}`
   : ''
 const storyWorkDir = (sid) => `${worktreeDir}/${sid}`
-// Where a story's commands run: its worktree in parallel mode, the project root otherwise.
+// Where a story's commands run: its own worktree when isolation is on, the project root otherwise.
 // `inWorktree` is false for sprint-level runners (backlog/integration) and the revalidation path.
 const runDirPhrase = (sid, inWorktree = true) =>
-  parallelEnabled && inWorktree ? `the story worktree at \`${storyWorkDir(sid)}\` (cd into it FIRST)` : 'the project root'
+  worktreeIsolation && inWorktree ? `the story worktree at \`${storyWorkDir(sid)}\` (cd into it FIRST)` : 'the project root'
 
 // Ship/leave mutex + ORDERED ship queue (review 2026-06-10 #9): merges mutate the shared target
 // ref + main working tree — strictly one at a time, and in QUEUE ORDER, not completion order, so
@@ -1762,10 +1773,10 @@ async function runStory(story) {
     }
   }
 
-  // In parallel mode every per-story agent works inside the story's worktree (the revalidation
+  // When isolation is on, every per-story agent works inside the story's worktree (the revalidation
   // and re-ship paths are the exceptions — they work the MAIN tree: the fix already merged there /
   // sync-story checks the retained branch out there).
-  const storyWorkCopy = parallelEnabled && !revalidate && !reshipOnly ? storyWorkDir(storyId) : null
+  const storyWorkCopy = worktreeIsolation && !revalidate && !reshipOnly ? storyWorkDir(storyId) : null
   const spawn = (role, promptFile, taskSubject, opts = {}) =>
     agent(buildPrompt({ role, promptFile, storyId, taskSubject, workDir: storyWorkCopy, ...opts }), {
       label: opts.label || `${role.toLowerCase()}:${storyId}`,
@@ -2076,6 +2087,25 @@ async function runStory(story) {
     if (has('uxa')) {
       await spawn('UXA', 'uxa.md', 'Translate the brief into uxa-spec.md.', { phase: 'Spec' })
     }
+    // Fix D (rework-reduction, 2026-06-24): QA-A proves its acceptance suite is honestly RED BEFORE
+    // handoff, instead of the RED gate discovering a premature-pass a cycle later — after the dev
+    // fan-out is already staged (the 2.29 class: 10 cycles, an escalation, a build break, zero
+    // implementation burned). The lever mirrors the dev pre-handoff self-gate (Fix #3): thread the
+    // SAME acceptance command the RED gate will run into QA-A's authoring turn so it self-checks in
+    // context. Deliberately the RAW command (not the `evidence run` wrapper) — QA-A only needs to
+    // OBSERVE pass/fail, and minting a labeled `acceptance` assert here would shadow the baseline the
+    // RED/green/evidence gates freeze against. The RED gate stays the mechanical backstop. atddEnabled
+    // + args only => journal-replay safe.
+    const qaaRedSelfCheck = atddEnabled
+      ? ` Then prove the suite is honestly RED before handoff (Fix D — shift-left the RED gate): run ` +
+        `\`${subCmd(atddCommandTpl, storyId, effectiveWorkspaces)}\` against the current (unimplemented) tree. ` +
+        `Every \`required: true\` case MUST run and FAIL for a behavioral reason (404 / empty / missing element) — ` +
+        `exactly what the RED gate will demand. A required case that PASSES now is a premature-pass spec bug: ` +
+        `re-target it to assert a NEW endpoint/element this story has not built yet, or — if it only guards an ` +
+        `already-established infrastructure invariant — mark it \`required: false\` ` +
+        `(steps/qa-a/write-acceptance-tests.md Step C), never weakening or deleting the guard. Fix every ` +
+        `premature-pass before handoff so the RED gate passes first-try.`
+      : ''
     await spawn('QA-A', 'qa-a.md',
       'Produce qa-test-spec.md before any code is written.' +
         (atddEnabled
@@ -2083,7 +2113,7 @@ async function runStory(story) {
             `under ${atddDir}/${storyId}/ — one+ per AC, TC id in the test title, black-box against the running system, ` +
             `no mocks — plus the manifest kind:"acceptance"/testFile/files[] fields. The prose spec is companion notes. ` +
             `Then self-attack your tests (steps/qa-a/self-attack.md) and fix what you find before handoff.`
-          : ''),
+          : '') + qaaRedSelfCheck,
       { phase: 'Spec' })
 
     phase('SpecCheck')
@@ -2721,10 +2751,10 @@ async function runStory(story) {
     const commands = [
       `node .valent-pipeline/bin/cli.js evidence pin --story ${sid} --gate evidence`,
       `node .valent-pipeline/bin/cli.js trace check --story ${sid} --label ${evidenceLabel}`,
-      // --require-evidence in parallel mode (review #37): evidence lives in the WORKTREE — a gate
-      // accidentally run at the main root would otherwise find nothing and no-op PASS. Serial mode
-      // keeps the graceful no-op (the legacy/pre-evidence story path).
-      `node .valent-pipeline/bin/cli.js evidence assert --story ${sid} --label ${evidenceLabel}${pinsFlag}${parallelEnabled ? ' --require-evidence' : ''}`,
+      // --require-evidence when isolation is on (review #37): evidence lives in the WORKTREE — a gate
+      // accidentally run at the main root would otherwise find nothing and no-op PASS. Serial WITHOUT
+      // isolation keeps the graceful no-op (the legacy/pre-evidence story path).
+      `node .valent-pipeline/bin/cli.js evidence assert --story ${sid} --label ${evidenceLabel}${pinsFlag}${worktreeIsolation ? ' --require-evidence' : ''}`,
     ]
     let rejections = 0
     let reverify = null // last rework re-review (pin coherence v2) — open Highs ride to JUDGE

package/pipeline/steps/qa-a/self-attack.md

@@ -12,3 +12,15 @@ Probe each acceptance case as the laziest implementer who wants green with minim
 - **Implementation sniffing (ATDD):** the dev can read your tests. Avoid magic fixture values an implementation could special-case; randomize or parameterize identifying data where cheap. (CRITIC's acceptance pass audits the implementation side of this.)
 
 Rate residual gameability **low | medium | high** per AC. HIGH means you have not finished — strengthen the test and re-rate. Record the final ratings + what you hardened in `qa-test-spec.md#self-attack` so CRITIC and JUDGE see what was already attacked.
+
+## Prove the suite is RED before handoff (ATDD)
+
+This is the mechanical close-out, run AFTER the gameability pass above. The orchestrator hands you the exact acceptance command to run — execute it against the current, **unimplemented** tree and read the result:
+
+- **Every `required: true` case MUST run and FAIL for a behavioral reason** — a 404, an empty/absent response, a missing element. That is precisely what the RED gate checks a cycle later; proving it here means the gate passes first-try instead of bouncing your spec back after the dev fan-out is already staged.
+- **A `required: true` case that PASSES now is a premature-pass spec bug.** It does not assert anything this story builds — it asserts behavior that already exists. Two fixes, both before handoff:
+  - **Re-target it** so it asserts a NEW endpoint/element/field this story has not built yet (e.g. route the assertion through a new path that 404s until implemented). This is the right fix when the case is meant to prove new behavior.
+  - **Or mark it `required: false`** (write-acceptance-tests.md Step C) when it only guards an already-established infrastructure invariant — still executed and asserted at the GREEN gate, but exempt from the red-required set. **Never weaken or delete the guard** — just make red honest.
+- A required case that **errors for a non-behavioral reason** (import failure, harness misconfig, syntax) is not honest red either — fix the test so it fails *because the feature is absent*, not because it cannot run.
+
+Do not hand off while any `required: true` case passes against the unimplemented tree. The RED gate will dead-end the story if you do; catching it here costs one self-run instead of a full round-trip.

package/skills/valent-configure/SKILL.md

@@ -82,7 +82,19 @@ Present defaults and let the user adjust:
 | `retrospective_every_n_stories` | `5` | How often the Retrospective Agent runs (range: 3-10) |
 | `stall_threshold_minutes` | `15` | Minutes before a stalled agent gets a check-in (range: 5-30) |
 
-### Step 4b: Parallel story execution (`git.parallelism`)
+### Step 4b: Worktree isolation (`git.worktree_isolation`)
+
+Off by default. When on, each story builds in its OWN git worktree (under
+`git.parallelism.worktree_dir/<id>`) even in serial mode — so cross-story working-tree residue
+can't bleed into a story's review-pin `git add -A` sweep and ship under the wrong story. It is the
+precondition parallelism builds on (parallel mode forces it on); enabling it serially is the safe
+first step toward parallel execution.
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `git.worktree_isolation` | `false` | Build each story in its own worktree even when serial (parallel forces on) |
+
+### Step 4c: Parallel story execution (`git.parallelism`)
 
 Off by default (`enabled: false` = strictly sequential). Turning it on runs up to `max_stories`
 stories concurrently, each in its own git worktree under `worktree_dir` (default

package/skills/valent-run-epic-workflow/SKILL.md

@@ -170,7 +170,7 @@ Feed the planned batch straight into `sprint.workflow.js`:
 ```js
 Workflow({
   scriptPath: '.valent-pipeline/orchestrators/claude-code/sprint.workflow.js',
-  args: { stories: <plan output .stories>, backlogPath: '{backlog_path}', maxRejectionCycles: {quality.max_rejection_cycles or 3}, maxJudgeRejects: {quality.max_judge_rejects or 2}, targetedReverify: {quality.targeted_reverify or false}, models: <config.models or omit>, reasoning: <config.reasoning or omit>, preCriticGate: <config.pre_critic_gate or omit>, packGate: <config.pack_gate or omit>, evidenceGate: <config.evidence_gate or omit>, atdd: <config.atdd or omit>, monorepo: <config.monorepo or omit>, git: { enabled: <config.git.enabled ?? true>, targetBranch: <config.git.target_branch or ''>, storyBranchPrefix: <config.git.story_branch_prefix or 'story/'>, parallelism: <config.git.parallelism or omit> }, ref: <config.ref or omit>, knowledge: { mode: <config.knowledge.mode or 'sqlite'>, curatedPath: <config.knowledge.curated_files_path or 'knowledge/curated'> }, visual: { onMissingMcp: <config.visual.on_missing_mcp or 'block'>, browserMcp: <tech_stack.browser_automation_mcp or 'playwright-mcp'> } }
+  args: { stories: <plan output .stories>, backlogPath: '{backlog_path}', maxRejectionCycles: {quality.max_rejection_cycles or 3}, maxJudgeRejects: {quality.max_judge_rejects or 2}, targetedReverify: {quality.targeted_reverify or false}, models: <config.models or omit>, reasoning: <config.reasoning or omit>, preCriticGate: <config.pre_critic_gate or omit>, packGate: <config.pack_gate or omit>, evidenceGate: <config.evidence_gate or omit>, atdd: <config.atdd or omit>, monorepo: <config.monorepo or omit>, git: { enabled: <config.git.enabled ?? true>, targetBranch: <config.git.target_branch or ''>, storyBranchPrefix: <config.git.story_branch_prefix or 'story/'>, worktreeIsolation: <config.git.worktree_isolation ?? false>, parallelism: <config.git.parallelism or omit> }, ref: <config.ref or omit>, knowledge: { mode: <config.knowledge.mode or 'sqlite'>, curatedPath: <config.knowledge.curated_files_path or 'knowledge/curated'> }, visual: { onMissingMcp: <config.visual.on_missing_mcp or 'block'>, browserMcp: <tech_stack.browser_automation_mcp or 'playwright-mcp'> } }
 })
 ```
 

package/skills/valent-run-project-workflow/SKILL.md

@@ -178,7 +178,7 @@ Feed the planned batch straight into `sprint.workflow.js`:
 ```js
 Workflow({
   scriptPath: '.valent-pipeline/orchestrators/claude-code/sprint.workflow.js',
-  args: { stories: <plan output .stories>, backlogPath: '{backlog_path}', maxRejectionCycles: {quality.max_rejection_cycles or 3}, maxJudgeRejects: {quality.max_judge_rejects or 2}, targetedReverify: {quality.targeted_reverify or false}, models: <config.models or omit>, reasoning: <config.reasoning or omit>, preCriticGate: <config.pre_critic_gate or omit>, packGate: <config.pack_gate or omit>, evidenceGate: <config.evidence_gate or omit>, atdd: <config.atdd or omit>, monorepo: <config.monorepo or omit>, git: { enabled: <config.git.enabled ?? true>, targetBranch: <config.git.target_branch or ''>, storyBranchPrefix: <config.git.story_branch_prefix or 'story/'>, parallelism: <config.git.parallelism or omit> }, ref: <config.ref or omit>, knowledge: { mode: <config.knowledge.mode or 'sqlite'>, curatedPath: <config.knowledge.curated_files_path or 'knowledge/curated'> }, visual: { onMissingMcp: <config.visual.on_missing_mcp or 'block'>, browserMcp: <tech_stack.browser_automation_mcp or 'playwright-mcp'> } }
+  args: { stories: <plan output .stories>, backlogPath: '{backlog_path}', maxRejectionCycles: {quality.max_rejection_cycles or 3}, maxJudgeRejects: {quality.max_judge_rejects or 2}, targetedReverify: {quality.targeted_reverify or false}, models: <config.models or omit>, reasoning: <config.reasoning or omit>, preCriticGate: <config.pre_critic_gate or omit>, packGate: <config.pack_gate or omit>, evidenceGate: <config.evidence_gate or omit>, atdd: <config.atdd or omit>, monorepo: <config.monorepo or omit>, git: { enabled: <config.git.enabled ?? true>, targetBranch: <config.git.target_branch or ''>, storyBranchPrefix: <config.git.story_branch_prefix or 'story/'>, worktreeIsolation: <config.git.worktree_isolation ?? false>, parallelism: <config.git.parallelism or omit> }, ref: <config.ref or omit>, knowledge: { mode: <config.knowledge.mode or 'sqlite'>, curatedPath: <config.knowledge.curated_files_path or 'knowledge/curated'> }, visual: { onMissingMcp: <config.visual.on_missing_mcp or 'block'>, browserMcp: <tech_stack.browser_automation_mcp or 'playwright-mcp'> } }
 })
 ```
 

package/skills/valent-run-story-workflow/SKILL.md

@@ -29,7 +29,7 @@ If no argument is provided, resolve the next work item from the backlog (see Ste
 
 ### Step 1: Load Pipeline Config
 
-Read `.valent-pipeline/pipeline-config.yaml` and resolve the variables you need below (project type, paths, quality caps, `tech_stack`, `knowledge`). Capture `project.type` — it feeds `--project-type` in Step 1b, and the resolved candidate object then carries `projectType`, `profiles`, and the execution-mode flags for Step 4 (when the user gave an explicit story argument instead, run the Step 1b resolver command anyway and select that story's candidate object from its buckets). Also capture the entire `models` section (the `{ opus:[...], sonnet:[...], haiku:[...] }` tier→roles map) — pass it as the `models` arg so per-agent model tiers stay config-driven (editable via `/valent-configure`). If the config has no `models` section, omit the arg and the workflow uses its baked-in default assignment. Likewise capture the `reasoning` section (the `{ ultrathink:[...], 'think-harder':[...], 'think-hard':[...], think:[...] }` level→roles map) and pass it as the `reasoning` arg; it is blank by default (injects nothing). Omit the arg if the section is absent or all levels are empty. Also capture the `pre_critic_gate` section (deterministic lint/type/static checks) and pass it as the `preCriticGate` arg; omit it if absent or its `commands` list is empty (the gate is then a no-op). Likewise capture the `pack_gate` section (run-level pack-time freshness checks — they run ONCE at sprint intake, before the story spends tokens) and pass it as the `packGate` arg; omit it if absent or its `commands` list is empty. Capture the `atdd` section and pass it as the `atdd` arg — it drives the RED gate (pre-implementation acceptance-suite run that must fail) and the GREEN gate (post-CRITIC re-run that must pass with the acceptance sources unchanged); omit it if absent or its `command` is blank (both gates are then a loud no-op). Capture the `git` section and pass it as the `git` arg `{ enabled: <git.enabled ?? true>, targetBranch: <git.target_branch or ''>, storyBranchPrefix: <git.story_branch_prefix or 'story/'>, parallelism: <git.parallelism or omit> }` — it drives the story git flow (branch off the target, full commit trail, merge --no-ff on SHIP); `parallelism` ({ enabled, max_stories, worktree_dir, setup_commands }) additionally enables concurrent stories in worktrees (off by default). Omit the whole arg only to accept the defaults (flow ON, parallelism OFF, graceful no-op outside a git repo). Capture the `visual` section together with `tech_stack.browser_automation_mcp` and pass them as the `visual` arg `{ onMissingMcp: <visual.on_missing_mcp or 'block'>, browserMcp: <tech_stack.browser_automation_mcp or 'playwright-mcp'> }` — this drives the Visual (PMCP) phase for `ui`-profile stories.
+Read `.valent-pipeline/pipeline-config.yaml` and resolve the variables you need below (project type, paths, quality caps, `tech_stack`, `knowledge`). Capture `project.type` — it feeds `--project-type` in Step 1b, and the resolved candidate object then carries `projectType`, `profiles`, and the execution-mode flags for Step 4 (when the user gave an explicit story argument instead, run the Step 1b resolver command anyway and select that story's candidate object from its buckets). Also capture the entire `models` section (the `{ opus:[...], sonnet:[...], haiku:[...] }` tier→roles map) — pass it as the `models` arg so per-agent model tiers stay config-driven (editable via `/valent-configure`). If the config has no `models` section, omit the arg and the workflow uses its baked-in default assignment. Likewise capture the `reasoning` section (the `{ ultrathink:[...], 'think-harder':[...], 'think-hard':[...], think:[...] }` level→roles map) and pass it as the `reasoning` arg; it is blank by default (injects nothing). Omit the arg if the section is absent or all levels are empty. Also capture the `pre_critic_gate` section (deterministic lint/type/static checks) and pass it as the `preCriticGate` arg; omit it if absent or its `commands` list is empty (the gate is then a no-op). Likewise capture the `pack_gate` section (run-level pack-time freshness checks — they run ONCE at sprint intake, before the story spends tokens) and pass it as the `packGate` arg; omit it if absent or its `commands` list is empty. Capture the `atdd` section and pass it as the `atdd` arg — it drives the RED gate (pre-implementation acceptance-suite run that must fail) and the GREEN gate (post-CRITIC re-run that must pass with the acceptance sources unchanged); omit it if absent or its `command` is blank (both gates are then a loud no-op). Capture the `git` section and pass it as the `git` arg `{ enabled: <git.enabled ?? true>, targetBranch: <git.target_branch or ''>, storyBranchPrefix: <git.story_branch_prefix or 'story/'>, worktreeIsolation: <git.worktree_isolation ?? false>, parallelism: <git.parallelism or omit> }` — it drives the story git flow (branch off the target, full commit trail, merge --no-ff on SHIP); `worktreeIsolation` builds each story in its own worktree even when serial (parallel mode forces it on); `parallelism` ({ enabled, max_stories, worktree_dir, setup_commands }) additionally enables concurrent stories in worktrees (off by default). Omit the whole arg only to accept the defaults (flow ON, parallelism OFF, graceful no-op outside a git repo). Capture the `visual` section together with `tech_stack.browser_automation_mcp` and pass them as the `visual` arg `{ onMissingMcp: <visual.on_missing_mcp or 'block'>, browserMcp: <tech_stack.browser_automation_mcp or 'playwright-mcp'> }` — this drives the Visual (PMCP) phase for `ui`-profile stories.
 
 ### Step 1b: Resolve Next Work Item (when no argument provided)
 

package/src/commands/init.js

@@ -546,6 +546,10 @@ git:
   # Blank = whatever branch the sprint starts on (recorded per story by git start-story).
   target_branch: "${config.git.target_branch}"
   story_branch_prefix: "${config.git.story_branch_prefix}"
+  # Worktree isolation: build each story in its own worktree (under parallelism.worktree_dir/<id>)
+  # even when serial, so cross-story working-tree residue can't ship under the wrong story. Parallel
+  # mode forces this ON. OFF by default for serial runs — opt in at a clean boundary.
+  worktree_isolation: ${config.git.worktree_isolation ?? false}
   # Parallel story execution (worktrees): up to max_stories run concurrently, each in its own git
   # worktree under worktree_dir; the main checkout stays on the target, merges are serialized, and
   # each ship gets a post-merge acceptance verify (ATDD armed). OFF by default — sequential sprint.

package/src/lib/config-schema.js

@@ -528,6 +528,12 @@ export const defaults = {
     // (recorded per story by `git start-story`, so ship-story returns to the same place).
     target_branch: '',
     story_branch_prefix: 'story/',
+    // Worktree isolation: build each story in its OWN worktree (under parallelism.worktree_dir/<id>)
+    // even when running serially, so cross-story working-tree residue can't bleed into a story's
+    // review-pin `git add -A` sweep and ship under the wrong story. Parallel mode forces this ON
+    // (concurrent stories cannot share a checkout). OFF by default for serial runs — opt in at a
+    // clean boundary; it's the precondition the parallelism rollout builds on.
+    worktree_isolation: false,
     // Parallel story execution: up to max_stories run concurrently, each in its own git worktree
     // (main checkout stays on the target; merges are serialized; each ship gets a post-merge
     // acceptance verify when ATDD is armed). OFF by default — the sprint is strictly sequential.