valent-pipeline 0.19.64 → 0.19.66

package/package.json

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

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

@@ -85,6 +85,8 @@ For each NFR-sensitive path: `[NFR-PERF]` response time + load patterns; `[NFR-S
 - If `ui` in `{testing_profiles}` → **MANDATORY.** Read `uxa-spec.md`. If `uxa-spec.md` is missing, write `status: blocked` to your frontmatter — do NOT proceed without it. For each page state define: Checkpoint ID (VV-{NNN}), Page/Route, State (Default/Loading/Empty/Error/Success or custom), AC Reference, Area labels in scope, Screenshot filename (`{story_id}_VV-{NNN}_{page}_{state}.png`), Expected visual elements, Setup instructions, Pass criteria. Write to `{story_output_dir}/visual-validation-checklist.md`.
 - If `ui` NOT in `{testing_profiles}` → skip, note "N/A — no UI profile."
 
+**The reach step must use the app's ACTUAL navigation mechanism — never assume a URL route exists.** Read `uxa-spec.md` for HOW each screen is reached, then match the checklist to it. A **URL-routed** screen (a server route or a real client router maps a path → screen) takes a URL-nav reach step. A **store-driven / client-side-nav** screen does NOT: a single-page app mounts views from application state (e.g. app-root renders the in-career screen at `loadingState === 'active'`) with NO URL router, so a URL-nav to a path like `/game` SILENTLY drops to the default view (login) → the screen never mounts → the gate records 0/N checkpoints → a **false visual:fail that reads as a code defect** (and costs a full reject + re-run — Epic-3 3.4). For a store-driven screen the reach step MUST drive the real nav: run the user flow that produces the state (register → login → Start Career → `active`) OR inject the documented store state (`window.__<store>__`) at the verified DPR — never a URL-nav. Confirm the app's nav model BEFORE writing any `Page / Route` + `Setup Instructions`; if the app has no URL router, author NO URL-route reach steps. This is the reach-step analogue of the Step 6b reachability contract: the screen must be genuinely reachable by the mechanism the checklist drives, or the gate measures nothing.
+
 **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.

package/pipeline/templates/visual-validation-checklist.template.md

@@ -39,7 +39,7 @@ blockers: []
 | Field | Value |
 |-------|-------|
 | **Checkpoint ID** | VV-{NNN} |
-| **Page / Route** | {page name and URL path, e.g. Registration / /register} |
+| **Page / Route** | {page name + how it is REACHED. A URL path ONLY if the app is genuinely URL-routed, e.g. Registration / /register. For a store-driven / client-side-nav SPA with no URL router, name the nav mechanism instead — e.g. "Office / reached via in-career flow (Start Career → active), NO URL route" — never a path that 404s to the default view} |
 | **State** | {Default \| Loading \| Empty \| Error \| Success \| custom state description} |
 | **AC Reference** | {AC-ID from qa-test-spec.md, e.g. AC-1} |
 | **Area Labels in Scope** | {list of area labels from uxa-spec.md that should be visible in this state} |
@@ -51,7 +51,7 @@ blockers: []
 - {element}: {expected appearance, position, or content}
 
 **Setup Instructions:**
-- {preconditions PMCP must establish before capturing -- e.g. seed data, auth state, form values}
+- {preconditions PMCP must establish before capturing -- e.g. seed data, auth state, form values; for a store-driven-nav screen, the EXACT steps to REACH it (drive the user flow or inject the documented store) — never assume a URL-nav lands on it}
 
 **Pass Criteria:**
 - {what PMCP must verify in the screenshot to mark this checkpoint as pass}

package/src/lib/git-flow.js

@@ -167,6 +167,42 @@ function isMergedInto(root, branch, target) {
   }
 }
 
+// RESUME-path backlog refresh (M-208). The create-path sync (startStory, the `merge --no-ff target`
+// below) fires ONLY on create — never on a RESUME, because a full merge there would move HEAD past the
+// critic pin (the documented constraint at the create-path guard). But a --from-story bug-fix branch
+// can still END UP missing the target-filed bug entry across a resume: if the entry is filed to the
+// target AFTER the branch is cut (the rejecting sprint's rollover-persist lands ~seconds after the
+// branch base, or the create launch dies before the entry exists) and the run then RESUMES the branch,
+// the create refresh never re-runs → `backlog ship --story <bug>` errors "backlog item not found"
+// (3.5-BUG-001, the M-36/M-65 class on the resume surface). Bring ONLY the target-canonical backlog
+// forward — a single path-scoped chore commit, NOT a merge — so the entry arrives while the pin and all
+// code stay exactly put (the backlog is already target-wins on every merge, REFRESH_TARGET_WINS). A
+// no-op when the branch backlog already matches the target (the create refresh delivered it, or nothing
+// was filed) so a resume never churns an empty commit; gated to inline --from-story fixes (basedOnStory)
+// whose target genuinely advanced, mirroring the create-path guard.
+function syncBacklogFromTargetOnResume(gitDir, root, story, target) {
+  const backlogFile = 'pipeline-backlog.yaml';
+  try {
+    if (!target || !branchExists(root, target)) return false;
+    const rec = readFlowRecord(gitDir, story) || readFlowRecord(root, story);
+    if (!rec || !rec.basedOnStory) return false;          // only inline bug fixes need this
+    if (mergeInProgress(gitDir)) return false;            // never touch a half-merged tree
+    const branch = rec.branch || currentBranch(gitDir);
+    if (!branch || isMergedInto(root, target, branch)) return false; // target not ahead → nothing to inherit
+    git(gitDir, ['checkout', target, '--', backlogFile]); // stage the target's canonical backlog blob
+    const staged = git(gitDir, ['diff', '--cached', '--name-only'])
+      .split('\n').map((s) => s.trim()).filter(Boolean);
+    if (!staged.includes(backlogFile)) return false;      // already current → no empty commit
+    git(gitDir, ['commit', '-m',
+      buildCommitMessage({ storyId: story, phase: 'sync',
+        summary: `inherit target backlog (filed bug entries) on resume — no code merge, pin intact (M-208)` }),
+      '--', backlogFile]);
+    return true;
+  } catch {
+    return false; // best-effort: a sync failure leaves the branch as it was (degraded, not wedged)
+  }
+}
+
 // --- worktree mode (parallel story execution) -------------------------------------------------
 // Each parallel story gets its own worktree under `<root>/<worktreeDir>/<storyId>` with the story
 // branch checked out there; the MAIN checkout stays on the target branch and is the only place
@@ -470,7 +506,10 @@ export function startStory({ root, story, targetBranch = '', prefix = 'story/',
   const onBranch = currentBranch(root);
 
   if (!worktree && onBranch === branch) {
-    return { branch, base: readFlowRecord(root, story)?.base ?? null, created: false, resumed: true };
+    const rec = readFlowRecord(root, story);
+    const backlogResynced = syncBacklogFromTargetOnResume(root, root, story, rec?.target);
+    return { branch, base: rec?.base ?? null, created: false, resumed: true,
+      ...(backlogResynced ? { backlogResynced: true } : {}) };
   }
 
   // Leftover dirt belongs to whatever produced it (planning artifacts, a prior crash) — sweep it
@@ -516,7 +555,10 @@ export function startStory({ root, story, targetBranch = '', prefix = 'story/',
       // when intact, and a half-created worktree (crash between `worktree add` and setup) gets
       // its missing pieces — setup_commands must therefore be idempotent (documented).
       const setup = setupWorktree(root, existing, setupCommands);
-      return { branch, base: readFlowRecord(existing, story)?.base ?? null, worktree: existing, created: false, resumed: true, snapshotSha, ...setup };
+      const rec = readFlowRecord(existing, story) || readFlowRecord(root, story);
+      const backlogResynced = syncBacklogFromTargetOnResume(existing, root, story, rec?.target);
+      return { branch, base: rec?.base ?? null, worktree: existing, created: false, resumed: true, snapshotSha,
+        ...(backlogResynced ? { backlogResynced: true } : {}), ...setup };
     }
     const creating = !branchExists(root, branch);
     if (creating) {
@@ -586,7 +628,10 @@ export function startStory({ root, story, targetBranch = '', prefix = 'story/',
 
   if (branchExists(root, branch)) {
     git(root, ['checkout', branch]);
-    return { branch, base: readFlowRecord(root, story)?.base ?? null, created: false, resumed: true, snapshotSha };
+    const rec = readFlowRecord(root, story);
+    const backlogResynced = syncBacklogFromTargetOnResume(root, root, story, rec?.target);
+    return { branch, base: rec?.base ?? null, created: false, resumed: true, snapshotSha,
+      ...(backlogResynced ? { backlogResynced: true } : {}) };
   }
   if (!branchExists(root, base)) throw new Error(`base branch "${base}" does not exist`);