valent-pipeline 0.19.57 → 0.19.59

package/package.json

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

package/pipeline/steps/qa-a/write-spec.md

@@ -87,6 +87,8 @@ For each NFR-sensitive path: `[NFR-PERF]` response time + load patterns; `[NFR-S
 
 **Sanctioning a checkpoint `N/A (sanction)` — the visual gate covers browser-testable *static renders* only.** The PMCP visual gate drives a **stateless** browser-automation MCP: it can navigate, snapshot, and assert rendered DOM, but it CANNOT drive a persistent WebSocket event (`career.created`, `career.resumed`), sever a connection mid-session, or catch an in-flight transient. A checkpoint whose pass criteria *require* such a flow will false-FAIL the visual gate even when the feature works. For exactly those checkpoints, set the checklist's **`N/A (sanction)`** field to `yes — <rationale>`, where the rationale (a) states why the browser MCP cannot drive it and (b) **names the acceptance/integration test that DOES validate it** — that test MUST exist; an `na` with no validating test is a coverage hole, not a sanction. PMCP then records the checkpoint N/A (not FAIL) and JUDGE treats it as non-blocking. Keep every browser-testable static render (default/empty/error/success states, element presence, layout) as a normal PASS/FAIL checkpoint — only WS-event-driven / non-render flows are eligible. When in doubt, do NOT sanction: a real render that fails must stay a FAIL.
 
+**The validating test a WS-driven sanction names MUST be a true end-to-end reachability case — never a service-layer test that bypasses the live event path.** When the UXA spec carries a Step 6b reachability contract for a WS-driven screen, author a REQUIRED `e2e` acceptance case that **drives the real triggering event over the actual connection** (register/login → issue the WS command → assert the screen leaves loading and renders), then sanction the matching visual checkpoint to it. A test that calls the service/handler layer directly (e.g. asserts `POST /api/careers` or the service method) can pass green while the **live WS command path is structurally broken** — a missing initial-state push, or a bootstrap command that violates a pre-event invariant (writing an FK row keyed on an id that does not exist until the event lands). That gap stays invisible until the visual gate a full attempt later. The reachability case is what forces the live path; the service-layer test is necessary but NOT sufficient to back a sanction.
+
 ## Step 9b: Test Quality Bar — make every case implementable AND falsifiable
 
 The dev agents implement exactly what you specify, and CRITIC rejects tests that are weak, unfalsifiable, or bound to the wrong artifact. Spec the bar IN so it is built right the first time (each rule below traces to a real rework cycle):

package/pipeline/steps/uxa/translate-spec.md

@@ -37,6 +37,21 @@ For every page, document all five states. No exceptions.
 
 Each state: condition (when), behavior (what user sees/can do).
 
+## Step 6b: WS-Driven Screen Reachability Contract (Conditional — real-time / WebSocket / SSE UIs)
+
+A screen whose data arrives over a **persistent connection** (WebSocket/SSE) — not an HTTP page load — is NOT reachable just because its component renders. It becomes reachable only once its **triggering event fires AND pushes the initial state** the screen needs to leave its loading state. Miss that push and the screen hangs in Loading forever: the component is correct, the screen is unreachable. This is the single most common late-caught UI defect on real-time apps — the acceptance/visual gate catches it at green, a full attempt late. Spec it HERE so the dev wires the push first-try.
+
+For EACH WS-driven screen, document its **reachability contract**:
+
+| Field | What to specify |
+|-------|-----------------|
+| **Triggering event** | The server→client event that makes this screen reachable (e.g. `career.created`, `career.resumed`) |
+| **Initial-state-push payload** | The exact state fields the event MUST push so the screen's loading state resolves to active — name them (e.g. `school_name`, `season`, `current_phase`); "sends state" is not enough |
+| **Pre-event session state** | What exists BEFORE the event (e.g. session keyed on a player/user id, no record yet) — flags bootstrap commands that must NOT assume post-event invariants (FK rows, ids that do not exist until the event lands) |
+| **Unreachable-if** | The concrete failure: which screen hangs in which state if the push (or the bootstrap command) is missing/broken |
+
+Each contract becomes a REQUIRED end-to-end reachability acceptance case in QA-A (drive the real event → assert the screen renders), and the matching PMCP visual checkpoint is sanctioned `N/A` (the stateless browser MCP cannot drive a persistent WS event — see QA-A Step 9). A screen reachable via a plain HTTP load only is out of scope — this is for event-driven reachability.
+
 ## Step 7: Accessibility Checklist (WCAG AA)
 
 - [ ] ARIA labels for interactive components
@@ -71,6 +86,7 @@ A developer with zero project context must build every page from this spec alone
 | Components have explicit dimensions/spacing/layout | | |
 | Interactive elements have behavior for all actions | | |
 | All five states documented per page | | |
+| WS-driven screens carry a reachability contract (triggering event + named initial-state-push payload) — Step 6b | | |
 | Area labels consistent and follow convention | | |
 | No ambiguous language ("appropriate", "as needed") | | |
 | Multi-language considerations documented | | |

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 };
   }