valent-pipeline 0.5.2 → 0.5.3

package/package.json

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

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

@@ -5,15 +5,19 @@
  * by scripts/test-workflow.js. Opt-in, not the default. The Codex provider keeps the
  * markdown-skill Lead (hybrid, R3).
  *
- * The retrospective is the ONE place the meta-loop adds genuine *quality*, not just reliable
- * structure (R5): the prose retro is a fixed single pass; here the aggregate review runs
- * LOOP-UNTIL-DRY (keep reviewing until K consecutive rounds surface nothing new) followed by a
- * COMPLETENESS-CRITIC ("which pattern did we not check?"). That is the same rigor that makes
- * CRITIC's 3-pass and JUDGE the strongest existing features, applied to the learning loop.
+ * A retrospective LEARNS from what the sprint already produced — it does NOT re-review the code.
+ * Finding bugs is CRITIC/JUDGE's job, and they already did it as a gate DURING the sprint; by the
+ * time the retro runs the code has shipped, so a fresh review here is both too late to gate and a
+ * duplication of work. (An earlier design ran a loop-until-dry aggregate review + completeness-
+ * critic on opus — that bolted the pipeline's most expensive pattern onto the stage that should be
+ * the cheapest, for little value. The one genuine cross-story blind spot — seams between stories
+ * that per-story CRITIC can't see — now lives where it can still gate: the sprint-end integration
+ * gate in sprint.workflow.js.)
  *
- * Flow: calibrate (CLI) -> analyze -> aggregate-review (loop-until-dry) -> completeness-critic
- *       -> directives (agent proposes; CODE enforces impact gating + the architectural-invariant
- *          guard) -> embed (CLI).
+ * Flow: calibrate (CLI) -> synthesize (mine the sprint's OWN artifacts — CRITIC reviews, JUDGE
+ *       rejections, QA bugs, rejection-cycle/cost data — into correction directives) -> directives
+ *       gating (agent proposes; CODE enforces impact gating + the architectural-invariant guard)
+ *       -> embed (CLI). Bounded and cheap: no opus review loop.
  *
  * The deterministic pieces are NOT in this script: calibration arithmetic is
  * `node .valent-pipeline/bin/cli.js calibrate` (src/lib/sprint.js); embedding is `node .valent-pipeline/bin/cli.js db embed`.
@@ -21,21 +25,19 @@
  * GATING and INVARIANT GUARD are deterministic policy, so they are enforced HERE in code —
  * the agent only proposes; the script decides what gets applied vs. surfaced for approval.
  *
- * args: { batchNumber, sprintId?, storyOutputDirs?: string[], dryRounds?: number, maxRounds?: number, models? }
- *   sprintId present => sprint-mode (calibration runs). dryRounds = consecutive empty rounds
- *   that end the loop-until-dry (default 2). maxRounds caps it (default 5). `models` is the
- *   pipeline-config.yaml `models` tier->roles map, passed through by the invoking skill so
- *   per-agent model tiers stay config-driven (editable via `valent configure`). Omit it to use
- *   the baked-in default. See sprint.workflow.js for the full rationale.
+ * args: { batchNumber, sprintId?, storyOutputDirs?: string[], models?, reasoning? }
+ *   sprintId present => sprint-mode (calibration runs). `models` is the pipeline-config.yaml
+ *   `models` tier->roles map, passed through by the invoking skill so per-agent model tiers stay
+ *   config-driven (editable via `valent configure`). Omit it to use the baked-in default. See
+ *   sprint.workflow.js for the full rationale.
  */
 
 export const meta = {
   name: 'valent-retro',
-  description: 'Retrospective: calibrate, loop-until-dry aggregate review, gated directives, embed (Workflow)',
+  description: 'Retrospective: calibrate, synthesize directives from sprint artifacts, gate, embed (Workflow)',
   phases: [
     { title: 'Calibrate', detail: 'node .valent-pipeline/bin/cli.js calibrate (estimation accuracy, in code) — sprint mode' },
-    { title: 'Analyze', detail: 'CRITIC/QA/JUDGE batch outputs + cost' },
-    { title: 'Aggregate', detail: 'loop-until-dry 3-pass aggregate review + completeness critic (R5)' },
+    { title: 'Synthesize', detail: 'mine CRITIC/QA/JUDGE/cost artifacts -> propose correction directives' },
     { title: 'Directives', detail: 'agent proposes; code enforces impact gating + invariant guard' },
     { title: 'Embed', detail: 'node .valent-pipeline/bin/cli.js db embed (persist curated patterns)' },
   ],
@@ -43,39 +45,6 @@ export const meta = {
 
 // --- schemas (inlined) ---
 
-const FINDINGS_SCHEMA = {
-  type: 'object',
-  required: ['schema', 'findings'],
-  additionalProperties: true,
-  properties: {
-    schema: { const: 1 },
-    findings: {
-      type: 'array',
-      items: {
-        type: 'object',
-        required: ['id', 'summary'],
-        properties: {
-          id: { type: 'string' },
-          summary: { type: 'string' },
-          severity: { type: 'string' },
-          stories: { type: 'array', items: { type: 'string' } },
-        },
-      },
-    },
-  },
-}
-
-const COMPLETENESS_SCHEMA = {
-  type: 'object',
-  required: ['schema', 'gaps'],
-  additionalProperties: true,
-  // gaps = review angles NOT yet covered (e.g. "no security-boundary scan run"). Empty => complete.
-  properties: {
-    schema: { const: 1 },
-    gaps: { type: 'array', items: { type: 'string' } },
-  },
-}
-
 const DIRECTIVES_SCHEMA = {
   type: 'object',
   required: ['schema', 'directives'],
@@ -124,8 +93,6 @@ function parseArgs(x) {
 const a = parseArgs(args)
 const batchNumber = a.batchNumber
 const sprintId = a.sprintId || null
-const dryRounds = a.dryRounds ?? 2
-const maxRounds = a.maxRounds ?? 5
 if (batchNumber == null) throw new Error('args must include { batchNumber }')
 
 // --- per-agent model tiers ----------------------------------------------------
@@ -133,12 +100,11 @@ if (batchNumber == null) throw new Error('args must include { batchNumber }')
 // args.models by the invoking skill — a Workflow script can't read files. We invert it
 // to role->tier and overlay it on a baked-in default so the workflow self-hosts a sane
 // assignment even when args.models is absent. Static + args only => journal-replay safe.
-// Retro stages map to synthetic role keys (not the single RETROSPECTIVE persona) so each
-// stage can be tuned independently: the loop-until-dry aggregate review + completeness
-// critic are the genuine quality work (RETRO-REVIEW -> opus); analyze/directives are
-// lighter (RETRO -> sonnet); calibrate/embed/IO are mechanical (haiku).
+// Retro stages map to synthetic role keys (not the single RETROSPECTIVE persona) so each stage can
+// be tuned independently. The retro is learning, not review, so there is no opus tier here:
+// synthesis/judgment over existing artifacts is RETRO -> sonnet; calibrate/embed/IO are mechanical
+// (haiku). The cross-story review that used to justify opus now lives in the sprint-end gate.
 const DEFAULT_MODELS = {
-  'RETRO-REVIEW': 'opus',
   RETRO: 'sonnet',
   CALIBRATE: 'haiku', EMBED: 'haiku', PERSIST: 'haiku',
 }
@@ -185,9 +151,6 @@ const retroPrompt = (instruction, returnContract) => {
     (returnContract || 'Return your findings as the JSON object specified.')
 }
 
-// A stable de-dup key so loop-until-dry converges (don't re-count the same finding).
-const findingKey = (f) => `${(f.summary || '').toLowerCase().trim().slice(0, 80)}`
-
 // ---------------------------------------------------------------------------
 
 let calibration = null
@@ -202,93 +165,33 @@ if (sprintId) {
   log(`calibration: ${(calibration.flagged_pairs || []).length} flagged pair(s); velocity unstable=${calibration.velocity?.unstable}`)
 }
 
-phase('Analyze')
-await agent(
-  retroPrompt(
-    'Run analyze.md: read all CRITIC reviews, QA-B bug reports, JUDGE rejections, and cost data; categorize rejection/bug patterns.',
-    'Return ONLY { schema:1, findings:[{id,summary,severity,stories}] } as JSON.',
-  ),
-  { label: 'analyze', phase: 'Analyze', schema: FINDINGS_SCHEMA, model: modelFor('RETRO') },
-)
-
-phase('Aggregate')
-// LOOP-UNTIL-DRY (R5): re-run the 3-pass aggregate review until `dryRounds` consecutive
-// rounds surface nothing new, deduping against everything already seen. A simple
-// fixed-pass review (the prose behavior) misses the tail; this does not.
-const seen = new Set()
-const confirmed = []
-let dry = 0
-let round = 0
-while (dry < dryRounds && round < maxRounds) {
-  round += 1
-  const r = await agent(
-    retroPrompt(
-      `Run aggregate-review.md (round ${round}): 3-pass CRITIC-style review of the aggregate diff (last retro tag to HEAD) — ` +
-        `correctness across story boundaries, convention/pattern drift, architecture/integration. ` +
-        `Report ONLY findings not already reported in earlier rounds.`,
-      'Return ONLY { schema:1, findings:[{id,summary,severity,stories}] } as JSON.',
-    ),
-    { label: `aggregate:round-${round}`, phase: 'Aggregate', schema: FINDINGS_SCHEMA, model: modelFor('RETRO-REVIEW') },
-  )
-  const fresh = (r.findings || []).filter((f) => !seen.has(findingKey(f)))
-  if (!fresh.length) {
-    dry += 1
-    log(`aggregate round ${round}: dry (${dry}/${dryRounds})`)
-    continue
-  }
-  dry = 0
-  for (const f of fresh) seen.add(findingKey(f))
-  confirmed.push(...fresh)
-  log(`aggregate round ${round}: +${fresh.length} new finding(s) (${confirmed.length} total)`)
-}
-
-// COMPLETENESS-CRITIC (R5): ask what review angle we never ran. Each named gap gets one
-// targeted review round; anything it surfaces joins the confirmed set.
-const critic = await agent(
-  retroPrompt(
-    `We ran ${round} aggregate-review round(s) and found ${confirmed.length} finding(s). ` +
-      `What review angle was NOT covered (e.g. a modality, a security boundary, a contract surface)? ` +
-      `List only genuine gaps — empty if coverage is complete.`,
-    'Return ONLY { schema:1, gaps:["..."] } as JSON.',
-  ),
-  { label: 'completeness-critic', phase: 'Aggregate', schema: COMPLETENESS_SCHEMA, model: modelFor('RETRO-REVIEW') },
-)
-if ((critic.gaps || []).length) {
-  log(`completeness-critic surfaced ${critic.gaps.length} gap(s) — running targeted reviews`)
-  const extra = await parallel(
-    critic.gaps.map((gap, i) => () =>
-      agent(
-        retroPrompt(`Targeted aggregate review for the previously-uncovered angle: "${gap}". Report only findings not already reported.`,
-          'Return ONLY { schema:1, findings:[{id,summary,severity,stories}] } as JSON.'),
-        { label: `aggregate:gap-${i + 1}`, phase: 'Aggregate', schema: FINDINGS_SCHEMA, model: modelFor('RETRO-REVIEW') },
-      )),
-  )
-  for (const r of extra.filter(Boolean)) {
-    for (const f of (r.findings || [])) {
-      if (!seen.has(findingKey(f))) { seen.add(findingKey(f)); confirmed.push(f) }
-    }
-  }
-}
-log(`aggregate review complete: ${confirmed.length} confirmed finding(s)`)
-
-phase('Directives')
-// The agent PROPOSES directives (with impact_level + a touchesInvariant flag). The CODE
-// enforces the policy — deterministic, uncheatable — per the §5b determinism map:
+phase('Synthesize')
+// Learning, not review: one pass mines the artifacts the sprint ALREADY produced (CRITIC reviews,
+// QA-B bug reports, JUDGE rejections, rejection-cycle counts, cost data) per analyze.md, then drafts
+// correction directives per directives.md — no fresh code review, no opus loop. The agent proposes
+// directives (with impact_level + a touchesInvariant flag); the CODE below enforces the policy —
+// deterministic, uncheatable — per the §5b determinism map:
 //   - touchesInvariant      -> ARCHITECTURE-CONFLICT: never auto-applied, surfaced to the user
 //   - impact_level 'high'   -> proposal only, requires user approval
 //   - 'low' / 'medium'      -> auto-applied (medium also notifies the Lead)
 const drafted = await agent(
   retroPrompt(
-    `Run directives.md against the ${confirmed.length} confirmed finding(s)` +
-      (calibration ? ' and the calibration metrics' : '') +
-      `. For EACH proposed directive set impact_level (low|medium|high) and touchesInvariant=true if it would skip test ` +
-      `execution, allow shipping without evidence, weaken a quality gate, or exempt mandatory tests. Do NOT self-censor — ` +
-      `propose it and flag it; the orchestrator decides what gets applied.`,
+    `Run analyze.md then directives.md: read all CRITIC reviews, QA-B bug reports, JUDGE rejections, ` +
+      `rejection-cycle counts, and cost data from this sprint's story outputs; categorize the recurring ` +
+      `rejection/bug patterns; then propose correction directives for those patterns` +
+      (calibration ? ' and for the calibration metrics' : '') +
+      `. Do NOT re-review the shipped code for new bugs — that was CRITIC/JUDGE's job during the sprint; ` +
+      `your job is to learn from what they already found. For EACH proposed directive set impact_level ` +
+      `(low|medium|high) and touchesInvariant=true if it would skip test execution, allow shipping without ` +
+      `evidence, weaken a quality gate, or exempt mandatory tests. Do NOT self-censor — propose it and flag ` +
+      `it; the orchestrator decides what gets applied.`,
     'Return ONLY { schema:1, directives:[{target_agent,directive,reason,impact_level,touchesInvariant,category}] } as JSON.',
   ),
-  { label: 'draft-directives', phase: 'Directives', schema: DIRECTIVES_SCHEMA, model: modelFor('RETRO') },
+  { label: 'synthesize', phase: 'Synthesize', schema: DIRECTIVES_SCHEMA, model: modelFor('RETRO') },
 )
 
+phase('Directives')
+
 const all = drafted.directives || []
 const conflicts = all.filter((d) => d.touchesInvariant)
 const highImpact = all.filter((d) => !d.touchesInvariant && d.impact_level === 'high')
@@ -328,9 +231,7 @@ const embed = await agent(
 return {
   batchNumber,
   sprintId,
-  aggregate_findings: confirmed.length,
-  aggregate_rounds: round,
-  completeness_gaps: (critic.gaps || []).length,
+  directives_proposed: all.length,
   directives_applied: applied.length,
   directives_pending_approval: proposals.length,
   architecture_conflicts: conflicts.length,

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

@@ -59,6 +59,7 @@ export const meta = {
     { title: 'Critic', detail: 'three independent passes in parallel -> triage -> rejection loop (code-owned cap)' },
     { title: 'QA', detail: 'execute tests against real infra' },
     { title: 'Judge', detail: 'evidence-based ship decision' },
+    { title: 'Integration', detail: 'single cross-story seam review — only when >1 story touched overlapping files' },
   ],
 }
 
@@ -123,6 +124,31 @@ const FINDINGS_SCHEMA = {
   },
 }
 
+// Sprint-end cross-story seam review. Advisory: stories already passed JUDGE, so this does not
+// re-gate them — it surfaces integration findings to be filed as bugs against the affected stories.
+const INTEGRATION_SCHEMA = {
+  type: 'object',
+  required: ['schema', 'verdict', 'findings'],
+  additionalProperties: true,
+  properties: {
+    schema: { const: 1 },
+    verdict: { enum: ['clean', 'findings'] },
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['summary'],
+        properties: {
+          summary: { type: 'string' },
+          severity: { enum: ['High', 'Med', 'Low'] },
+          files: { type: 'array', items: { type: 'string' } },
+          stories: { type: 'array', items: { type: 'string' } },
+        },
+      },
+    },
+  },
+}
+
 const RESOLVED_GRAPH_SCHEMA = {
   type: 'object',
   required: ['tasks', 'skipped'],
@@ -190,7 +216,7 @@ for (const s of batch) {
 // assignment even when args.models is absent. Static + args only => journal-replay safe.
 //   gates -> opus (judgment), spec/build -> sonnet, CLI-runners/IO -> haiku.
 const DEFAULT_MODELS = {
-  READINESS: 'opus', CRITIC: 'opus', JUDGE: 'opus',
+  READINESS: 'opus', CRITIC: 'opus', JUDGE: 'opus', INTEGRATION: 'opus',
   REQS: 'sonnet', UXA: 'sonnet', 'QA-A': 'sonnet', 'QA-B': 'sonnet',
   BEND: 'sonnet', FEND: 'sonnet', DATA: 'sonnet', 'MCP-DEV': 'sonnet',
   LIBDEV: 'sonnet', DOCGEN: 'sonnet', IAC: 'sonnet', MOBILE: 'sonnet',
@@ -284,11 +310,66 @@ for (let i = 0; i < batch.length; i++) {
 
 const shippedCount = results.filter((r) => r.shipped).length
 log(`sprint complete: ${shippedCount}/${results.length} shipped`)
+
+// Sprint-end integration gate: per-story CRITIC reviews each diff in ISOLATION and never sees two
+// stories together, so cross-story SEAMS (a module touched by >1 story, mismatched integration
+// points) are its one structural blind spot. Cover it with a SINGLE bounded review — but only when
+// it could find something: >1 story shipped AND at least two of them touched an overlapping file.
+// No loop, no completeness-critic (that disproportionate apparatus was removed from the retro for
+// the same reason). Advisory only — stories already passed JUDGE, so findings are surfaced as bugs
+// to file, not a re-gate. Overlap is computed from the dev handoff `files`, so a disjoint sprint
+// (every story in its own corner of the tree) skips the gate entirely.
+const integration = await runIntegrationGate(results.filter((r) => r.shipped))
+
 return {
   shipped: results.every((r) => r.shipped),
   stories_shipped: shippedCount,
   stories_rolled_over: results.length - shippedCount,
   results,
+  integration,
+}
+
+// runIntegrationGate: returns null when not warranted (≤1 shipped story or no file overlap), else
+// the single review's structured result ({ verdict, findings }) for the orchestrator to file as bugs.
+async function runIntegrationGate(shipped) {
+  if (shipped.length < 2) return null
+
+  // Files touched by more than one shipped story = the seams worth reviewing.
+  const owners = new Map() // file -> Set(storyId)
+  for (const r of shipped) {
+    for (const f of r.files || []) {
+      if (!owners.has(f)) owners.set(f, new Set())
+      owners.get(f).add(r.storyId)
+    }
+  }
+  const overlapFiles = [...owners.entries()].filter(([, s]) => s.size > 1).map(([f]) => f)
+  if (!overlapFiles.length) {
+    log(`integration gate: skipped — ${shipped.length} stories shipped but no overlapping files`)
+    return null
+  }
+
+  log(`integration gate: ${overlapFiles.length} file(s) touched by >1 story — running single cross-story review`)
+  const result = await agent(
+    [
+      `You are **INTEGRATION**, the sprint-end cross-story seam reviewer for this batch.`,
+      ``,
+      `Per-story CRITIC reviewed each story's diff in isolation and CANNOT see two stories together.`,
+      `Review ONLY the cross-story SEAMS — the files below were each modified by more than one story`,
+      `this sprint, so that is where integration mismatches hide (incompatible signatures, ordering`,
+      `assumptions, duplicated/diverging logic, broken shared invariants).`,
+      ``,
+      `Overlapping files: ${JSON.stringify(overlapFiles)}`,
+      `Shipped stories: ${JSON.stringify(shipped.map((r) => r.storyId))}`,
+      ``,
+      `Do a SINGLE focused pass. Do NOT re-review within-story correctness (CRITIC already did) and do`,
+      `NOT hunt for unrelated issues. Report only genuine cross-story seam problems; empty if the seams`,
+      `are clean. Return ONLY { schema:1, verdict:"clean"|"findings", findings:[{summary,severity,files,stories}] } as JSON.`,
+    ].join('\n'),
+    { label: 'gate:integration', phase: 'Integration', schema: INTEGRATION_SCHEMA, model: modelFor('INTEGRATION') },
+  )
+  const findings = result.findings || []
+  log(`integration gate: ${findings.length} cross-story finding(s)`)
+  return { verdict: result.verdict, findings, overlapFiles }
 }
 
 // ===========================================================================
@@ -373,7 +454,7 @@ async function runStory(story) {
   const devFiles = builds.filter(Boolean).flatMap((b) => (Array.isArray(b.files) ? b.files : []))
   if (devFiles.length === 0) {
     log(`${storyId}: dev phase reported no files — nothing to review; skipping CRITIC/QA/JUDGE, rolling over`)
-    return { storyId, shipped: false, verdict: 'blocked', reason: 'no-dev-output', skipped: graph.skipped }
+    return { storyId, shipped: false, verdict: 'blocked', reason: 'no-dev-output', skipped: graph.skipped, files: [] }
   }
 
   phase('Critic')
@@ -386,7 +467,7 @@ async function runStory(story) {
   const decision = await runGate(storyId, 'JUDGE', 'judge.md',
     'Review evidence (tests, traceability, bugs) and make the ship decision.', 'Judge', null)
 
-  return { storyId, shipped: decision.verdict === 'pass', verdict: decision.verdict, skipped: graph.skipped }
+  return { storyId, shipped: decision.verdict === 'pass', verdict: decision.verdict, skipped: graph.skipped, files: devFiles }
 
   // --- per-story closures over storyId/devTasks ----------------------------
 

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

@@ -96,11 +96,13 @@ Workflow({
 })
 ```
 
-Runs each story sequentially through the per-story pipeline on a shared branch, rolling over any story JUDGE rejects or that trips the cap. Returns `{ shipped, stories_shipped, stories_rolled_over, results: [...] }`. Record its `runId`.
+Runs each story sequentially through the per-story pipeline on a shared branch, rolling over any story JUDGE rejects or that trips the cap. After the batch, a **sprint-end integration gate** runs a single cross-story seam review — but ONLY when >1 story shipped and at least two touched an overlapping file (otherwise it's skipped). Returns `{ shipped, stories_shipped, stories_rolled_over, results: [...], integration }`, where `integration` is `null` (not warranted) or `{ verdict, findings, overlapFiles }`. Record its `runId`.
 
 #### 4e. Update progress + re-resolve dependencies
 For each shipped story: move it to `stories_completed` with a compact one-line outcome tagged with its epic; update `total_completed` / `last_updated`; **FIFO at 80 lines** (evict oldest). Read and follow `.valent-pipeline/steps/orchestration/update-backlog-status.md`. Then **re-check whether any previously blocked stories are now unblocked** (their `depends_on` / `blocked_by_bugs` may have been resolved by what just shipped) — these become eligible for the next sprint's candidate list.
 
+If the sprint result's `integration.findings` is non-empty, file each as a `bug` backlog item (per `update-backlog-status.md`'s conditional-ship bug format) against the affected stories' epic, so the cross-story seam issue is tracked and prioritized like any other bug.
+
 #### 4f. Retrospective (mandatory, blocking)
 Invoke `retro.workflow.js`:
 
@@ -111,7 +113,7 @@ Workflow({
 })
 ```
 
-Record its `runId`. Retro runs every sprint and tightens future sizing.
+Record its `runId`. Retro runs every sprint and tightens future sizing. It **learns from the sprint's own artifacts** — calibration (CLI), one synthesis pass that mines CRITIC/JUDGE/QA/cost data into correction directives, then embed — and is bounded and cheap (no fresh code review; that is CRITIC/JUDGE's job during the sprint, and cross-story seams are covered by the sprint-end integration gate in 4d).
 
 #### 4g. Continue
 Increment `{n}` and return to Step 4a. **Do NOT ask permission to continue between sprints** — the project loop is autonomous.