valent-pipeline 0.19.66 → 0.19.68

package/package.json

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

package/src/commands/check-spec-conformance.js

@@ -3,6 +3,7 @@ import { isAbsolute, join } from 'path';
 import { checkSpecConformance } from '../lib/spec-conformance.js';
 import { evidenceDir, latestRun } from '../lib/evidence.js';
 import { parseJunit } from '../lib/junit.js';
+import { detectManifestCaseDrift } from '../lib/spec-manifest.js';
 
 const DEFAULT_TEST_RE = /\.(test|spec)\.(js|ts|jsx|tsx|mjs|cjs)$/;
 const IGNORE_DIRS = new Set([
@@ -79,6 +80,12 @@ export async function checkSpecConformanceCmd(options) {
     process.exit(2);
   }
 
+  const drift = detectManifestCaseDrift(manifest);
+  if (drift) {
+    console.error(`spec-conformance: ${drift}`);
+    process.exit(1);
+  }
+
   if (!Array.isArray(manifest?.cases) || manifest.cases.length === 0) {
     console.log(`spec-conformance: manifest has no cases — skipping (no-op pass).`);
     process.exit(0);

package/src/commands/trace.js

@@ -11,6 +11,7 @@ import { join, isAbsolute, dirname } from 'path';
 import { traceCheck, traceMatrix } from '../lib/trace.js';
 import { evidenceDir, resolveRunForAssert, requiredCaseIdsForRun, resolveRoot } from '../lib/evidence.js';
 import { parseJunit } from '../lib/junit.js';
+import { detectManifestCaseDrift } from '../lib/spec-manifest.js';
 
 /** Load an exact evidence run by id (for `--run`), or null if absent/unreadable. */
 function loadRunById(evDir, runId) {
@@ -48,6 +49,8 @@ function loadInputs(options) {
   if (!existsSync(specPath)) return { noop: `no spec manifest at ${specPath} — skipping (no-op pass).` };
   const reqsManifest = readJson(reqsPath, 'reqs manifest');
   const specManifest = readJson(specPath, 'spec manifest');
+  const drift = detectManifestCaseDrift(specManifest);
+  if (drift) return { error: drift };
   const cases = Array.isArray(specManifest?.cases) ? specManifest.cases : [];
   if (cases.length > 0 && !cases.some((c) => Array.isArray(c.ac) && c.ac.length > 0)) {
     return { noop: 'spec manifest predates the per-case `ac` field — skipping (no-op pass). Re-run QA-A to gain mechanical AC coverage.' };
@@ -93,6 +96,10 @@ export async function traceCheckCmd(options) {
     process.exit(2);
   }
   const inputs = loadInputs(options);
+  if (inputs.error) {
+    console.error(`trace-check: ${inputs.error}`);
+    process.exit(1);
+  }
   if (inputs.noop) {
     console.log(`trace-check: ${inputs.noop}`);
     process.exit(0);
@@ -108,6 +115,10 @@ export async function traceMatrixCmd(options) {
     process.exit(2);
   }
   const inputs = loadInputs(options);
+  if (inputs.error) {
+    console.error(`trace-matrix: ${inputs.error}`);
+    process.exit(1);
+  }
   if (inputs.noop) {
     console.log(`trace-matrix: ${inputs.noop}`);
     process.exit(0);

package/src/lib/git-flow.js

@@ -139,15 +139,19 @@ const REFRESH_TARGET_WINS = new Set(['pipeline-backlog.yaml']);
 // bug entry never reached the branch and `backlog ship --story <bug>` then errored "not found" →
 // manual reconcile every bug-fix sprint. The ship CLAMP is untouched — evidence still verifies against
 // the branch's own tree; this only delivers the backlog ENTRY the target already committed.
-function resolveRefreshConflict(dir) {
-  if (!mergeInProgress(dir)) return false; // a non-conflict merge failure — the caller aborts
-  let conflicted;
+// The repo-relative paths git reports as unmerged (conflicted) in the current merge. [] on error.
+function conflictedPaths(dir) {
   try {
-    conflicted = git(dir, ['diff', '--name-only', '--diff-filter=U'])
+    return git(dir, ['diff', '--name-only', '--diff-filter=U'])
       .split('\n').map((s) => s.trim()).filter(Boolean);
   } catch {
-    return false;
+    return [];
   }
+}
+
+function resolveRefreshConflict(dir) {
+  if (!mergeInProgress(dir)) return false; // a non-conflict merge failure — the caller aborts
+  const conflicted = conflictedPaths(dir);
   if (!conflicted.length || !conflicted.every((p) => REFRESH_TARGET_WINS.has(p))) return false;
   for (const p of conflicted) {
     git(dir, ['checkout', '--theirs', '--', p]);
@@ -181,7 +185,6 @@ function isMergedInto(root, branch, target) {
 // 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);
@@ -189,20 +192,33 @@ function syncBacklogFromTargetOnResume(gitDir, root, story, target) {
     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;
+    return commitTargetBacklog(gitDir, story, target,
+      'inherit target backlog (filed bug entries) on resume — no code merge, pin intact (M-208)');
   } catch {
     return false; // best-effort: a sync failure leaves the branch as it was (degraded, not wedged)
   }
 }
 
+// Deliver ONLY the target's canonical pipeline-backlog.yaml blob onto the CURRENT branch as a
+// path-scoped chore commit (no code merge, HEAD/pin/code untouched). Returns true iff it committed a
+// change (no-op + false when the branch backlog already matches the target — never an empty commit).
+// Shared by the resume-path sync (M-208) and the create-path refresh-abort fallback (M-219): a refresh
+// merge that ABORTS on a non-backlog co-conflict (a project coordination doc, the M-52 untrack reset, …)
+// rolls the cleanly-mergeable bug entry back with the whole merge, so the disposition's filed entry never
+// reaches the branch and `backlog ship --story <bug>` later errors "not found". The backlog is
+// target-canonical (never legitimately branch-edited — target-wins on every merge), so deliver it
+// directly. Caller must ensure no merge is in progress (a clean tree at base).
+function commitTargetBacklog(gitDir, story, target, summary) {
+  const backlogFile = 'pipeline-backlog.yaml';
+  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 }), '--', backlogFile]);
+  return true;
+}
+
 // --- 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
@@ -586,6 +602,7 @@ export function startStory({ root, story, targetBranch = '', prefix = 'story/',
     // a conflict aborts cleanly in the worktree, leaving the branch at its base. Needed for parallel:2.
     let refreshedFromTarget = false;
     let refreshConflict = false;
+    let backlogCleanlyMergeable = false;
     if (creating && basedOnStory && branchExists(root, target) && !isMergedInto(root, target, branch)) {
       try {
         git(wtPath, ['merge', '--no-ff', '-m',
@@ -595,14 +612,27 @@ export function startStory({ root, story, targetBranch = '', prefix = 'story/',
         // A conflict ONLY on target-authoritative shared state (the backlog with the filed bug entry)
         // → resolve toward the target so the entry reaches this branch (M-65/M-69); any real-code
         // conflict aborts cleanly (setupWorktree re-materializes the install if the sync removed it).
+        const conflicted = conflictedPaths(wtPath); // captured BEFORE resolve concludes/abort clears it
         if (resolveRefreshConflict(wtPath)) {
           refreshedFromTarget = true;
         } else {
           if (mergeInProgress(wtPath)) git(wtPath, ['merge', '--abort']);
           refreshConflict = true;
+          backlogCleanlyMergeable = conflicted.length > 0 && !conflicted.some((p) => REFRESH_TARGET_WINS.has(p));
         }
       }
     }
+    // M-219 (worktree variant): the refresh aborted on a non-backlog co-conflict while the backlog itself
+    // would have merged clean → deliver ONLY the target backlog blob into the worktree so the filed bug
+    // entry is present for `backlog ship` (code stays at base; conflict still surfaced via refreshConflict).
+    // Runs in wtPath BEFORE setupWorktree re-materializes the install — the tree is clean at base.
+    let backlogDelivered = false;
+    if (creating && basedOnStory && refreshConflict && !refreshedFromTarget && backlogCleanlyMergeable && branchExists(root, target)) {
+      try {
+        backlogDelivered = commitTargetBacklog(wtPath, story, target,
+          'inherit target backlog (filed bug entries) after refresh aborted on a co-conflict — no code merge (M-219)');
+      } catch { /* best-effort: leave the branch at its base */ }
+    }
     const setup = setupWorktree(root, wtPath, setupCommands);
     if (creating) {
       writeFlowRecord(wtPath, story, {
@@ -622,6 +652,7 @@ export function startStory({ root, story, targetBranch = '', prefix = 'story/',
       ...(orphanMovedTo ? { orphanMovedTo, warning: `orphaned worktree directory moved aside to ${orphanMovedTo} (crashed run; inspect/delete it manually)` } : {}),
       ...(refreshedFromTarget ? { refreshedFromTarget: true } : {}),
       ...(refreshConflict ? { refreshConflict: true } : {}),
+      ...(backlogDelivered ? { backlogDelivered: true } : {}),
       ...setup,
     };
   }
@@ -650,6 +681,7 @@ export function startStory({ root, story, targetBranch = '', prefix = 'story/',
   // than wedging a half-merge that would hard-stop every later commit in this checkout.
   let refreshedFromTarget = false;
   let refreshConflict = false;
+  let backlogCleanlyMergeable = false;
   if (basedOnStory && branchExists(root, target) && !isMergedInto(root, target, branch)) {
     // Capture whether the vendored install is present BEFORE the sync, so the hazard guard below fires
     // ONLY when the merge actually REMOVED it — not when a repo simply never had a materialized install
@@ -664,11 +696,17 @@ export function startStory({ root, story, targetBranch = '', prefix = 'story/',
       // bug entry into) is resolved toward the target so the entry reaches this branch (M-65/M-69); a
       // conflict touching any real code aborts cleanly as before (degraded, but no worse). The M-52
       // framework-deletion guard below still runs on the concluded merge.
+      const conflicted = conflictedPaths(root); // captured BEFORE resolve concludes/abort clears it
       if (resolveRefreshConflict(root)) {
         refreshedFromTarget = true;
       } else {
         if (mergeInProgress(root)) git(root, ['merge', '--abort']);
         refreshConflict = true;
+        // M-219: deliver the backlog entry below ONLY when the backlog itself did NOT conflict — i.e. the
+        // entry would have merged clean but an UNRELATED file's conflict (a project coordination doc, …)
+        // aborted the whole merge. A backlog+code divergence is a genuinely diverged branch (recut) —
+        // leave it untouched so the negative guard "never swallows a code conflict" holds.
+        backlogCleanlyMergeable = conflicted.length > 0 && !conflicted.some((p) => REFRESH_TARGET_WINS.has(p));
       }
     }
     // M-52 transition hazard: when `target` UNTRACKS the vendored framework (the post-untrack install
@@ -690,6 +728,19 @@ export function startStory({ root, story, targetBranch = '', prefix = 'story/',
       );
     }
   }
+  // M-219: a refresh that ABORTED (a non-backlog co-conflict — e.g. a project coordination doc whose
+  // conflict makes resolveRefreshConflict bail — or the M-52 untrack reset above) rolled the
+  // cleanly-mergeable target backlog back with the whole merge, so the disposition's filed bug entry
+  // never reached this branch and `backlog ship --story <bug>` would error "not found" (3.5/3.7-BUG-001).
+  // The tree is clean at base here (merge --abort / reset --hard ran), so deliver ONLY the target
+  // backlog blob directly — code stays at base (the conflict is still surfaced via refreshConflict).
+  let backlogDelivered = false;
+  if (basedOnStory && refreshConflict && !refreshedFromTarget && backlogCleanlyMergeable && branchExists(root, target)) {
+    try {
+      backlogDelivered = commitTargetBacklog(root, story, target,
+        'inherit target backlog (filed bug entries) after refresh aborted on a co-conflict — no code merge (M-219)');
+    } catch { /* best-effort: leave the branch at its base */ }
+  }
   writeFlowRecord(root, story, {
     schema: 1,
     kind: 'git-flow',
@@ -702,7 +753,8 @@ export function startStory({ root, story, targetBranch = '', prefix = 'story/',
   });
   return { branch, base, target, created: true, resumed: false, snapshotSha,
     ...(refreshedFromTarget ? { refreshedFromTarget: true } : {}),
-    ...(refreshConflict ? { refreshConflict: true } : {}) };
+    ...(refreshConflict ? { refreshConflict: true } : {}),
+    ...(backlogDelivered ? { backlogDelivered: true } : {}) };
 }
 
 /**

package/src/lib/spec-manifest.js

@@ -0,0 +1,30 @@
+// Shared guard against qa-test-spec.manifest.json schema drift (M-223).
+//
+// The canonical manifest carries its spec'd cases under `cases` (pipeline/schemas/qa-spec-manifest.schema.json,
+// `required: ["schema","story","cases"]`). QA-A is an LLM and can drift the key — e.g. emit `testCases` instead
+// of `cases`. The downstream readers (`trace check`, `check-spec-conformance`) then silently see ZERO cases:
+// trace check reports every AC uncovered (a phantom `uncoveredAcs` coverage gap that reads as a real defect),
+// and spec-conformance takes its empty-manifest no-op PASS (masking the drift entirely). Both cost a confused
+// diagnosis + a re-run (3.9, 2026-06-28). The schema existed but was never enforced at ingestion.
+//
+// This detects the specific, recoverable drift — `cases` absent/empty WHILE a case-like array (objects with a
+// string `id`) sits under another top-level key — and returns an actionable message so the gate fails LOUD with
+// the real reason instead of a phantom coverage gap or a vacuous pass. It deliberately does NOT fire for a
+// genuinely empty/absent `cases` (a pre-Phase manifest or a story with no spec'd cases yet) — that stays a
+// legitimate no-op, so this adds a clear failure ONLY where the manifest is populated-but-misnamed. Returns the
+// message string, or null when there is no drift.
+export function detectManifestCaseDrift(manifest) {
+  if (!manifest || typeof manifest !== 'object') return null;
+  if (Array.isArray(manifest.cases) && manifest.cases.length > 0) return null; // canonical + populated
+
+  const caseLike = (arr) => Array.isArray(arr) && arr.length > 0
+    && arr.every((c) => c && typeof c === 'object' && typeof c.id === 'string' && c.id.length > 0);
+  const aliases = Object.keys(manifest).filter((k) => k !== 'cases' && caseLike(manifest[k]));
+  if (!aliases.length) return null; // genuinely empty/absent — legitimate no-op, not drift
+
+  const k = aliases[0];
+  const n = manifest[k].length;
+  return `no populated \`cases\` array but found ${n} case-like entr${n === 1 ? 'y' : 'ies'} under \`${k}\` `
+    + `— qa-test-spec.manifest.json schema drift (the canonical key is \`cases\`). Re-author the manifest with `
+    + `the cases under \`cases\` (see pipeline/schemas/qa-spec-manifest.schema.json).`;
+}