valent-pipeline 0.19.57 → 0.19.58

package/package.json

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

package/skills/valent-configure/SKILL.md

@@ -107,6 +107,7 @@ the config — surface it explicitly:
 | `git.parallelism.max_stories` | `2` | Concurrent story cap |
 | `git.parallelism.worktree_dir` | `.valent-worktrees` | Worktree container (ignored via `.git/info/exclude`) |
 | `git.parallelism.setup_commands` | `[]` | Commands run in each fresh worktree (env files, per-story ports, non-node installs) — MUST be idempotent (setup re-runs on resume) |
+| `git.parallelism.teardown_commands` | `[]` | Commands run IN the worktree just before removal (on ship or rollover) — symmetric cleanup (e.g. `docker compose down` on a per-story stack) so a stale stack can't leak into the next story. Best-effort: a failure is logged but never blocks the ship/rollover |
 
 ### Step 4a: Evidence Gate (machine-evidence layer)
 

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/'>, 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.
+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, teardown_commands }) additionally enables concurrent stories in worktrees (off by default); `setup_commands`/`teardown_commands` run in each worktree on create/remove (the git CLI reads them from config on disk). 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/git-flow.js

@@ -36,6 +36,7 @@ function resolveOpts(options) {
     worktree: options.worktree === true,
     worktreeDir: options.worktreeDir || par.worktree_dir || DEFAULT_WORKTREE_DIR,
     setupCommands: Array.isArray(par.setup_commands) ? par.setup_commands : [],
+    teardownCommands: Array.isArray(par.teardown_commands) ? par.teardown_commands : [],
   };
 }
 
@@ -78,7 +79,7 @@ export async function gitCommitPhaseCmd(options) {
 
 export async function gitShipStoryCmd(options) {
   try {
-    const { root, targetBranch, prefix, worktree } = resolveOpts(options);
+    const { root, targetBranch, prefix, worktree, teardownCommands } = resolveOpts(options);
     // Ship-time evidence binding (review pass-3 #7): the clamp config rides pipeline-config.yaml
     // (evidence_gate.ship_clamp) — no CLI bypass flag exists by design.
     const { evidenceShipConfig } = await import('./evidence.js');
@@ -87,6 +88,7 @@ export async function gitShipStoryCmd(options) {
       root, story: options.story, verdict: options.verdict || 'ship', targetBranch, prefix, worktree,
       into: options.into || null,
       shipClamp: shipCfg.mode === 'off' ? null : { mode: shipCfg.mode, label: shipCfg.label },
+      teardownCommands,
     });
     if (result.shipClampWarning) {
       console.error(`git-flow WARNING: ship-time evidence binding failed (${result.shipClampWarning}) — proceeding (evidence_gate.ship_clamp: warn)`);
@@ -135,8 +137,8 @@ export async function gitStoryStatusCmd(options) {
 
 export async function gitLeaveStoryCmd(options) {
   try {
-    const { root, targetBranch, prefix, worktree } = resolveOpts(options);
-    finish(leaveStory({ root, story: options.story, reason: options.reason || 'rejected', targetBranch, prefix, worktree }));
+    const { root, targetBranch, prefix, worktree, teardownCommands } = resolveOpts(options);
+    finish(leaveStory({ root, story: options.story, reason: options.reason || 'rejected', targetBranch, prefix, worktree, teardownCommands }));
   } catch (e) {
     fail(e);
   }

package/src/commands/init.js

@@ -554,12 +554,16 @@ 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.
   # setup_commands run in each fresh worktree (node_modules is linked + pipeline.db copied for you;
-  # add project-specific needs here, e.g. env files or per-story ports).
+  # add project-specific needs here, e.g. env files or per-story ports). teardown_commands run in
+  # the worktree just before it is removed (on ship or rollover) — the symmetric cleanup (e.g.
+  # "docker compose down" on a per-story stack) so a stale stack can't leak into the next story.
+  # Best-effort: a teardown failure is logged but never blocks the ship/rollover.
   parallelism:
     enabled: ${config.git.parallelism?.enabled ?? false}
     max_stories: ${config.git.parallelism?.max_stories ?? 2}
     worktree_dir: "${config.git.parallelism?.worktree_dir ?? '.valent-worktrees'}"
     setup_commands: [${(config.git.parallelism?.setup_commands ?? []).map((c) => JSON.stringify(c)).join(', ')}]
+    teardown_commands: [${(config.git.parallelism?.teardown_commands ?? []).map((c) => JSON.stringify(c)).join(', ')}]
 
 communication:
   handoff_format: "${config.communication.handoff_format}"

package/src/lib/config-schema.js

@@ -545,6 +545,12 @@ export const defaults = {
       // Commands run in each fresh worktree after node_modules linking + pipeline.db copy —
       // project-specific setup (env files, per-story ports, non-node package installs).
       setup_commands: [],
+      // Commands run IN the worktree just before it is removed (on ship or rollover) — the
+      // symmetric complement to setup_commands. Use to tear down per-worktree side effects a setup
+      // command created (e.g. `docker compose down` on a per-story stack) so a stale stack can't
+      // leak into the next story and pin a shared host port. Best-effort: a failure is logged but
+      // never blocks the ship/rollover.
+      teardown_commands: [],
     },
   },
   communication: {

package/src/lib/git-flow.js

@@ -276,12 +276,41 @@ function worktreeForBranch(root, branch) {
   return null;
 }
 
+/**
+ * Best-effort teardown (config git.parallelism.teardown_commands), run IN the worktree just before
+ * it is removed — the symmetric complement to setupWorktree's setup_commands. Use it to tear down
+ * per-worktree side effects a setup command created (e.g. `docker compose down` on a per-story
+ * stack) so a stale stack can't leak into the next story and pin a shared host port. UNLIKE setup,
+ * a teardown failure NEVER throws: the worktree is being discarded regardless, and a failed cleanup
+ * must not strand a shipped/rolled-over story — it is reported loudly on stderr and removal still
+ * proceeds. Runs in the worktree's cwd so a command can read its compose project name / .env.test.
+ */
+function runWorktreeTeardown(wtPath, teardownCommands = []) {
+  if (!Array.isArray(teardownCommands) || !existsSync(wtPath)) return { ran: [], failed: [] };
+  const ran = [], failed = [];
+  for (const cmd of teardownCommands) {
+    if (typeof cmd !== 'string' || !cmd.trim()) continue;
+    try {
+      execSync(cmd, { cwd: wtPath, stdio: ['ignore', 'pipe', 'pipe'], timeout: 300000 });
+      ran.push(cmd);
+    } catch (e) {
+      const stderr = e.stderr ? e.stderr.toString().slice(-2000) : '';
+      const why = e.killed ? ' (timed out after 300s)' : '';
+      failed.push(cmd);
+      console.error(`git-flow WARNING: worktree teardown command failed${why} (best-effort, removal proceeds): ${cmd}${stderr ? `\n${stderr}` : ''}`);
+    }
+  }
+  return { ran, failed };
+}
+
 /**
  * Remove a worktree AFTER its sweep commit. Plain remove refuses while untracked/ignored files
  * remain — post-sweep the only leftovers are ignored setup artifacts (the node_modules link, the
- * pipeline.db copy), so the --force fallback discards nothing of value.
+ * pipeline.db copy), so the --force fallback discards nothing of value. Teardown commands run FIRST
+ * (in the worktree, while its files still exist), best-effort.
  */
-function removeWorktreeDir(root, wtPath) {
+function removeWorktreeDir(root, wtPath, teardownCommands = []) {
+  runWorktreeTeardown(wtPath, teardownCommands);
   try {
     git(root, ['worktree', 'remove', wtPath]);
     return true;
@@ -691,7 +720,7 @@ export function commitPhase({ root, story, phase, summary = null, gate = null })
  * shipped; the branch retains every commit. Idempotent: an already-merged branch reports
  * { merged:true, already:true }.
  */
-export function shipStory({ root, story, verdict = 'ship', targetBranch = '', prefix = 'story/', worktree = false, into = null, shipClamp = null }) {
+export function shipStory({ root, story, verdict = 'ship', targetBranch = '', prefix = 'story/', worktree = false, into = null, shipClamp = null, teardownCommands = [] }) {
   if (!isRepoWithCommits(root)) return NOT_REPO;
   const branch = storyBranchName(prefix, story);
   if (!branchExists(root, branch)) throw new Error(`story branch "${branch}" does not exist — was start-story run?`);
@@ -735,7 +764,7 @@ export function shipStory({ root, story, verdict = 'ship', targetBranch = '', pr
     sweep = commitAll(root, buildCommitMessage({ storyId: story, phase: 'ship', trailers: { Verdict: verdict } }));
   }
 
-  const removeWorktree = () => (wt ? removeWorktreeDir(root, wt) : false);
+  const removeWorktree = () => (wt ? removeWorktreeDir(root, wt, teardownCommands) : false);
 
   if (isMergedInto(root, branch, target)) {
     if (currentBranch(root) !== target) git(root, ['checkout', target]);
@@ -898,7 +927,7 @@ export function syncStory({ root, story, targetBranch = '', prefix = 'story/', c
  * must survive for the inline fix or next-sprint retry), checkout the target, branch retained.
  * Safe to call from any branch state; idempotent.
  */
-export function leaveStory({ root, story, reason = 'rejected', targetBranch = '', prefix = 'story/', worktree = false }) {
+export function leaveStory({ root, story, reason = 'rejected', targetBranch = '', prefix = 'story/', worktree = false, teardownCommands = [] }) {
   if (!isRepoWithCommits(root)) return NOT_REPO;
   const branch = storyBranchName(prefix, story);
 
@@ -910,7 +939,7 @@ export function leaveStory({ root, story, reason = 'rejected', targetBranch = ''
     let removed = false;
     if (wt) {
       sweep = commitAll(wt, buildCommitMessage({ storyId: story, phase: 'rollover', summary: `roll over (${reason})` }));
-      removed = removeWorktreeDir(root, wt);
+      removed = removeWorktreeDir(root, wt, teardownCommands);
     }
     return { left: true, branch, target: targetBranch || currentBranch(root), sweepSha: sweep.sha || null, reason, worktreeRemoved: removed };
   }