valent-pipeline 0.3.4 → 0.4.2

package/bin/cli.js

@@ -54,6 +54,86 @@ configCmd
     await validate();
   });
 
+// validate-handoff command
+program
+  .command('validate-handoff')
+  .description('Validate a handoff artifact\'s valent:handoff machine block against the schema')
+  .requiredOption('--file <path>', 'Path to the handoff markdown file')
+  .option('--gate', 'Force gate validation (verdict required + pass-requires-zero-Highs invariant)')
+  .action(async (options) => {
+    const { validateHandoffCmd } = await import('../src/commands/validate-handoff.js');
+    await validateHandoffCmd(options);
+  });
+
+// resolve-graph command
+program
+  .command('resolve-graph')
+  .description('Deterministically resolve a task graph against testing profiles (evaluate predicates, prune blockedBy)')
+  .option('--type <project-type>', 'Project type (resolves .valent-pipeline/task-graphs/<type>.yaml, falling back to packaged)')
+  .option('--file <path>', 'Explicit path to a task-graph YAML (overrides --type)')
+  .option('--profiles <list>', 'Comma-separated testing profiles, e.g. api,ui,iac', '')
+  .option('--validate-only', 'Validate the graph shape and references without resolving')
+  .action(async (options) => {
+    const { resolveGraphCmd } = await import('../src/commands/resolve-graph.js');
+    await resolveGraphCmd(options);
+  });
+
+// sprint-pack command (meta-loop: greedy story packing)
+program
+  .command('sprint-pack')
+  .description('Deterministically pack groomed stories into a sprint by priority within a velocity budget')
+  .requiredOption('--velocity <n>', 'Sprint capacity in story points')
+  .option('--backlog <path>', 'Backlog file (YAML/JSON); packs its `items`')
+  .option('--stories <path>', 'Explicit story array (YAML/JSON); overrides --backlog')
+  .action(async (options) => {
+    const { sprintPackCmd } = await import('../src/commands/sprint-pack.js');
+    await sprintPackCmd(options);
+  });
+
+// calibrate command (meta-loop: estimation-accuracy arithmetic)
+program
+  .command('calibrate')
+  .description('Compute calibration metrics (point/time ratios, deviation flags, velocity stability)')
+  .option('--sprint <id>', 'Sprint to pull calibration rows for (queries the SQLite store)')
+  .option('--db', 'Use all calibration rows from the store (no sprint filter)')
+  .option('--db-path <path>', 'Database path (defaults to config)')
+  .option('--data <path>', 'Explicit calibration rows (YAML/JSON); overrides the db source')
+  .option('--velocity-history <path>', 'Explicit velocity history (YAML/JSON) to pair with --data')
+  .option('--deviation-threshold <n>', 'Pairwise deviation flag threshold (default 0.5)')
+  .option('--cv-threshold <n>', 'Velocity coefficient-of-variation instability threshold (default 0.3)')
+  .action(async (options) => {
+    const { calibrateCmd } = await import('../src/commands/calibrate.js');
+    await calibrateCmd(options);
+  });
+
+// validate-sprint command (meta-loop: consistency cross-checks)
+program
+  .command('validate-sprint')
+  .description('Cross-check sprint status YAML and backlog for consistency (sprint-plan.md Step 6)')
+  .requiredOption('--status <path>', 'Sprint status YAML/JSON (machine-readable companion to the plan)')
+  .requiredOption('--backlog <path>', 'Backlog file (YAML/JSON)')
+  .option('--plan <path>', 'Optional structured plan (JSON/YAML), e.g. sprint-pack output; defaults to deriving from --status')
+  .action(async (options) => {
+    const { validateSprintCmd } = await import('../src/commands/validate-sprint.js');
+    await validateSprintCmd(options);
+  });
+
+// rejection-cap command (code-owned rejection cap for the prose/Codex shell)
+program
+  .command('rejection-cap')
+  .description('Track and enforce the per-story rejection cap in code (exits non-zero when tripped)')
+  .requiredOption('--story <id>', 'Story identifier')
+  .requiredOption('--gate <gate>', 'Gate name (readiness | critic | judge)')
+  .option('--agent <name>', 'Responsible agent the rejection is routed to (defaults to the gate)')
+  .option('--max <n>', 'Cap (max rejection cycles); defaults to 5')
+  .option('--increment', 'Record a new rejection (bump the counter), then report')
+  .option('--reset', 'Clear all counters for the story (call at a story boundary), then report')
+  .option('--state <path>', 'State file path (defaults to .valent-pipeline/rejection-state.json)')
+  .action(async (options) => {
+    const { rejectionCapCmd } = await import('../src/commands/rejection-cap.js');
+    await rejectionCapCmd(options);
+  });
+
 // db commands
 const dbCmd = program
   .command('db')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "valent-pipeline",
-  "version": "0.3.4",
+  "version": "0.4.2",
   "description": "v3 multi-agent AI pipeline for software development lifecycle",
   "type": "module",
   "bin": {
@@ -16,14 +16,16 @@
     "skills/"
   ],
   "scripts": {
-    "test": "node scripts/test-local.js",
-    "prepublishOnly": "node scripts/test-local.js"
+    "test": "node scripts/test-local.js && node scripts/test-workflow.js",
+    "prepublishOnly": "node scripts/test-local.js && node scripts/test-workflow.js"
   },
   "dependencies": {
+    "ajv": "^8.20.0",
+    "better-sqlite3": "^12.0.0",
     "commander": "^12.0.0",
     "inquirer": "^9.0.0",
-    "better-sqlite3": "^11.0.0",
-    "sqlite-vec": "^0.1.0"
+    "sqlite-vec": "^0.1.0",
+    "yaml": "^2.9.0"
   },
   "keywords": [
     "ai",

package/pipeline/docs/design/provider-adapter-guide.md

@@ -24,11 +24,9 @@ pipeline/
     claude-code/
       runtime.md                   ← PROVIDER — Claude Code runtime operations
       spawn.template.md            ← PROVIDER — Claude Code spawn template
-      knowledge-spawn.template.md  ← PROVIDER — Claude Code knowledge spawn
     codex/
       runtime.md                   ← PROVIDER — Codex runtime operations
       spawn.template.md            ← PROVIDER — Codex spawn template
-      knowledge-spawn.template.md  ← PROVIDER — Codex knowledge spawn
       AGENTS.md                    ← PROVIDER — Codex repo-level instructions
       cloud-task-protocol.md       ← PROVIDER — Codex cloud execution protocol
       cloud-task-prompts/          ← PROVIDER — Codex cloud task templates
@@ -56,7 +54,8 @@ Lead's prompt (`lead.md`) defines WHEN and WHY. The runtime adapter defines HOW.
 |------|---------|
 | `runtime.md` | All runtime operations: initialization, task registry, agent spawning, signal delivery, monitoring, teardown |
 | `spawn.template.md` | Agent spawn prompt template — what each agent instance receives at startup |
-| `knowledge-spawn.template.md` | Knowledge agent spawn template — knowledge-specific initialization |
+
+> **Note:** Knowledge is a self-service skill (`valent-knowledge`), not an agent — there is no `knowledge-spawn.template.md`. `scripts/validate-provider-sync.js` enforces this inventory (spawn-template parity + manifest prompt resolution).
 
 ### Codex-Only Files
 
@@ -133,7 +132,6 @@ Entirely shared. Quality gates are orchestration logic (when to reject, where to
 1. Create `providers/{new-provider}/` with:
    - `runtime.md` — all runtime operations for the new provider
    - `spawn.template.md` — spawn template adapted for the provider's agent model
-   - `knowledge-spawn.template.md` — knowledge spawn adapted
 
 2. Update `src/lib/config-schema.js`:
    - Add new provider to `validProviders` array
@@ -158,9 +156,10 @@ Entirely shared. Quality gates are orchestration logic (when to reject, where to
 
 The `scripts/validate-provider-sync.js` script runs in CI before every publish. It checks:
 
-1. **Template parity** — `spawn.template.md` and `knowledge-spawn.template.md` exist in both provider directories
-2. **Agent coverage** — Both runtime.md files reference the same set of agents from `agents-manifest.yaml`
-3. **Structural consistency** — Both runtime.md files have the same major sections (Initialization, Task Registry, Agent Spawning, Signal Delivery, Monitoring, Teardown)
+1. **Template parity** — `spawn.template.md` exists in both providers, and any `*spawn.template.md` in one provider has a counterpart in the other
+2. **Manifest integrity** — every `prompt_template` declared in `agents-manifest.yaml` resolves to a real file
+3. **Agent coverage** — both runtime.md files reference the critical agents (REQS, BEND, FEND, CRITIC, QA-B, JUDGE)
+4. **Structural consistency** — both runtime.md files have the major sections (Initialization, Task Registry, Agent Spawning, Signal Delivery, Monitoring, Teardown)
 
 If any check fails, the publish is blocked. Fix the discrepancy, then re-push.
 

package/pipeline/orchestrators/claude-code/README.md

@@ -0,0 +1,99 @@
+# Claude Code orchestrator (native Workflow)
+
+This is the Claude Code deployment of the valent-pipeline orchestrator, per the hybrid
+target in [`../../../docs-feedback/reimplementation-plan.md`](../../../docs-feedback/reimplementation-plan.md)
+(R3): the Claude Code provider runs a deterministic **Workflow script**, while the Codex
+provider keeps the markdown-skill Lead. Both consume the same shared substrate
+(`prompts/`, `steps/`, `task-graphs/`, `schemas/`, templates).
+
+## The three workflows
+
+| File | Step | Role |
+|---|---|---|
+| `plan.workflow.js` | 7 | Groom → size → pack → validate a set of pending stories into a planned sprint batch. Emits a batch shaped to feed straight into `sprint.workflow.js`. |
+| `sprint.workflow.js` | 4 + 6 | Execute a planned batch sequentially through the per-story pipeline with schema-validated gates. |
+| `retro.workflow.js` | 7 | Learn from a shipped batch: calibrate, loop-until-dry aggregate review, gated directives, embed. |
+
+They compose as `plan → sprint → retro`. The per-story pipeline is kept **inline** in
+`sprint.workflow.js` (not a nested `workflow()`), so the single `workflow()` nesting level
+stays free for a future sprint-cycle wrapper to call all three (reimplementation-plan §5b).
+
+## Status
+
+`sprint.workflow.js` implements **Steps 4 + 6** (R1 control flow, R4 gates-as-stages, the
+sprint batch loop, 3b parallel CRITIC, and full spawn-context prompts). `plan.workflow.js`
+and `retro.workflow.js` implement **Step 7**. **Step 8** (resume + state model, below) is
+wired. All three are control-flow-validated by `scripts/test-workflow.js` (21 scenarios,
+incl. a resume-safety lint), but:
+
+- It is **opt-in, not the default.** `skills/valent-run-story` still drives the prose Lead;
+  the Workflow runs only when the user opts in (see that skill's "Step 5 (alternative)").
+- It has **not been exercised end-to-end against a live story.** A Workflow runs via the
+  Workflow tool against a real project and spawns real agents; it cannot be unit-tested like
+  `src/lib/*`. Validate it against a `testResources/*` fixture before making it the default.
+
+## What it demonstrates
+
+| Concern | How | Replaces |
+|---|---|---|
+| DAG resolution | spawns an agent that runs `resolve-graph` (step 2) per story | Lead transcribing + pruning by judgment |
+| Sprint batch | sequential `for`-loop over `args.stories[]` (shared branch ⇒ no overlap) | prose six-phase sprint loop |
+| Quality gates | `runGate()` returns a `verdict.schema`-validated object | prose verdict, unchecked |
+| Pass-invariant | `assertGate()` rejects `pass` + open Highs | KANBAN-002 class |
+| Rejection cap | JS `while` loop, code-owned counter | model-counted circuit breaker |
+| Dev fan-out | `parallel()` barrier before CRITIC | wave/spawn_trigger overlay |
+| 3b CRITIC | `parallel([blind, edge, acceptance])` independent agents → triage barrier | one CRITIC context, passes anchored on each other |
+| Spawn context | `buildPrompt()` mirrors `spawn.template.md` (Setup/Task/Trigger/Completion) | terse inline instructions |
+| Roll-over | a rejected story is recorded and the batch continues | — |
+| Resume | journal (`resumeFromRunId`) | disk-state rehydration + re-decide |
+
+## Args
+
+```js
+// batch form (a planned sprint)
+{ stories: [{ storyId, projectType, profiles }, ...], maxRejectionCycles? }
+// single-story form (back-compat)
+{ storyId, projectType, profiles?, maxRejectionCycles? }
+```
+
+Returns `{ shipped, stories_shipped, stories_rolled_over, results: [{ storyId, shipped, verdict, skipped }] }`.
+
+## Resume & state model (step 8)
+
+**The journal is the state of record.** Each Workflow invocation returns a `runId`. To resume
+after an interruption (context limit, crash, manual stop, or a mid-run script edit), relaunch
+with `Workflow({ scriptPath, resumeFromRunId })` — **not** a fresh run. The journal replays the
+unchanged prefix of `agent()` calls instantly (same script + args → 100% cache hit) and re-runs
+only from the first changed/new call onward. Already-shipped stories and passed gates are not
+redone. This is the exact form of the durability the prose Lead approximated by re-reading
+`pipeline-state.json` and re-deciding.
+
+`pipeline-state.json`, `sprint-{n}-status.yaml`, and the markdown handoffs are **derived,
+human-readable views** in this path — agents write them for visibility; the orchestrator never
+reads them back to make a control-flow decision (its state lives in JS variables the journal
+captures). Because there is no multi-file state of record, the non-atomic multi-file desync the
+prose Lead can hit (feedback gap #2) is structurally impossible here. *Do not hand-edit a state
+file to resume — pass `resumeFromRunId`.* (The prose Lead path still uses `pipeline-state.json`
+as its mechanism; that's correct for that runtime.)
+
+**Resume-safety is linted.** Journal replay requires a deterministic, side-effect-free script
+body, so `scripts/test-workflow.js` statically rejects `Date.now`/`new Date(`/`Math.random`
+(nondeterminism) and `import`/`require`/`*FileSync`/`process.*` (in-script IO) in all three
+workflow files. All IO goes through agents; that's why resolve-graph/sprint-pack/calibrate/embed
+are invoked *through* an agent rather than imported.
+
+## Known simplifications (next slices)
+
+- A `sprint-cycle.workflow.js` that calls `plan → sprint → retro` via `workflow()` isn't built
+  yet; for now run the three workflows in sequence (the plan output feeds the sprint input).
+- Per-story dev fan-out re-runs ALL dev agents on a CRITIC rejection; routing rework to only
+  the agent(s) CRITIC targeted (via `rejectionTarget`) is a refinement once run live.
+- No PMCP / visual-validation stage yet; no PM/program-loop workflow (left agent-driven per §5b).
+
+## Runtime constraint that shaped the design
+
+A Workflow script body has **no filesystem or import access** — it cannot read
+`task-graphs/*.yaml`, parse handoffs, or run the CLI directly. All IO is performed by the
+agents it spawns (which have Bash/Read/Write); the script only sequences them and validates
+their structured returns. That is why `resolve-graph` is invoked *through* an agent rather
+than imported.

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

@@ -0,0 +1,284 @@
+/**
+ * valent-pipeline sprint PLANNING orchestrator — Claude Code (native Workflow) provider.
+ *
+ * STATUS: Step 7 (reimplementation-plan §5b). Reviewable; control flow validated by
+ * scripts/test-workflow.js. Opt-in, not the default — not yet run end-to-end against a
+ * live backlog. The Codex provider keeps the markdown-skill Lead (hybrid, R3).
+ *
+ * Produces a planned sprint batch from a set of pending stories:
+ *   groom (pipelined) -> size (parallel) -> persist points -> pack (CLI) -> validate (CLI)
+ *
+ * Why grooming is pipeline() but execution is for(): grooming runs Phase-1 SPEC agents
+ * (reqs/uxa/qa-a/readiness) that DON'T touch code, so stories can flow assembly-line —
+ * story B can be in QA-A while story C is still in REQS. (Execution, by contrast, shares
+ * one git branch and must be sequential — see sprint.workflow.js.)
+ *
+ * The deterministic packing/validation (greedy bin-packing, consistency cross-checks) is NOT
+ * done in this script — it lives in `valent-pipeline sprint-pack` / `validate-sprint`
+ * (src/lib/sprint.js), invoked through an agent because a Workflow script has no CLI/fs
+ * access. Both runtimes reuse those CLIs; this workflow just sequences the agents.
+ *
+ * The return value is shaped to feed straight into sprint.workflow.js:
+ *   { sprintId, points_planned, stories: [{ storyId, projectType, profiles }] }
+ *
+ * args: { stories: [{ storyId, projectType }], sprintId, velocity, backlogPath?, maxRejectionCycles? }
+ */
+
+export const meta = {
+  name: 'valent-plan',
+  description: 'Groom, size, and pack a set of stories into a validated sprint plan (Workflow)',
+  phases: [
+    { title: 'Groom', detail: 'reqs -> uxa? -> qa-a -> readiness gate, pipelined across the batch' },
+    { title: 'Size', detail: 'profile-matched estimators per story, summed (parallel)' },
+    { title: 'Persist', detail: 'write story_points + groomed status to the backlog' },
+    { title: 'Pack', detail: 'valent-pipeline sprint-pack (greedy bin-packing, in code)' },
+    { title: 'Validate', detail: 'write plan/status artifacts + valent-pipeline validate-sprint' },
+  ],
+}
+
+// --- schemas (inlined; a Workflow script cannot read pipeline/schemas/*.json) ---
+
+const HANDOFF_SCHEMA = {
+  type: 'object',
+  required: ['schema', 'agent', 'story'],
+  additionalProperties: true,
+  properties: {
+    schema: { const: 1 },
+    agent: { type: 'string' },
+    story: { type: 'string' },
+    files: { type: 'array', items: { type: 'string' } },
+    flags: { type: 'array', items: { type: 'string' } },
+  },
+}
+
+// REQS also tags testing_profiles during grooming (sprint-groom.md Step 0).
+const REQS_GROOM_SCHEMA = {
+  type: 'object',
+  required: ['schema', 'agent', 'story', 'testing_profiles'],
+  additionalProperties: true,
+  properties: {
+    schema: { const: 1 },
+    agent: { type: 'string' },
+    story: { type: 'string' },
+    testing_profiles: { type: 'array', items: { type: 'string' } },
+  },
+}
+
+const VERDICT_SCHEMA = {
+  type: 'object',
+  required: ['schema', 'agent', 'story', 'verdict', 'highFindingsOpen'],
+  additionalProperties: true,
+  properties: {
+    schema: { const: 1 },
+    agent: { type: 'string' },
+    story: { type: 'string' },
+    verdict: { enum: ['pass', 'fail', 'needs-review'] },
+    highFindingsOpen: { type: 'integer', minimum: 0 },
+    rejectionTarget: { type: ['string', 'null'] },
+  },
+}
+
+const ESTIMATE_SCHEMA = {
+  type: 'object',
+  required: ['schema', 'agent', 'story', 'points'],
+  additionalProperties: true,
+  properties: {
+    schema: { const: 1 },
+    agent: { type: 'string' },
+    story: { type: 'string' },
+    points: { type: 'integer', minimum: 0 },
+  },
+}
+
+const PACK_SCHEMA = {
+  type: 'object',
+  required: ['sprint_stories', 'buffer_story_ids', 'points_planned'],
+  properties: {
+    sprint_stories: { type: 'array', items: { type: 'string' } },
+    buffer_story_ids: { type: 'array', items: { type: 'string' } },
+    points_planned: { type: 'integer' },
+    remaining_capacity: { type: 'integer' },
+  },
+}
+
+const VALIDATE_SCHEMA = {
+  type: 'object',
+  required: ['valid'],
+  additionalProperties: true,
+  properties: { valid: { type: 'boolean' }, errors: { type: 'array', items: { type: 'string' } } },
+}
+
+// Which estimator agent owns each testing profile (sprint-size.md Step 2).
+const PROFILE_ESTIMATORS = {
+  api: 'BEND', ui: 'FEND', 'data-pipeline': 'DATA', 'mcp-server': 'MCP-DEV',
+  library: 'LIBDEV', 'document-generation': 'DOCGEN', iac: 'IAC',
+}
+
+// --- args ---
+
+const a = args || {}
+const stories = Array.isArray(a.stories) ? a.stories : []
+const sprintId = a.sprintId
+const velocity = a.velocity
+const backlogPath = a.backlogPath || 'pipeline-backlog.yaml'
+const maxRejectionCycles = a.maxRejectionCycles ?? 5
+if (!stories.length || !sprintId || typeof velocity !== 'number') {
+  throw new Error('args must include { stories:[{storyId,projectType}], sprintId, velocity }')
+}
+
+function buildPrompt({ role, promptFile, storyId, taskSubject, trigger, returnContract }) {
+  const outputDir = `stories/${storyId}/output`
+  return [
+    `You are **${role}**, for story ${storyId} in the valent-pipeline (sprint ${sprintId} planning).`,
+    '',
+    '## Setup',
+    `1. Read your core prompt: \`.valent-pipeline/prompts/${promptFile}\` — identity, protocols, step sequence.`,
+    `2. Read shared context: \`${outputDir}/pipeline-context.md\` (and correction directives if present).`,
+    '3. Read each step file at the point of execution, not before. Check decision gates first.',
+    '',
+    '## Task Assignment',
+    taskSubject,
+    '',
+    '## Trigger',
+    trigger || 'Begin now.',
+    '',
+    '## On Completion',
+    returnContract || 'Write your handoff artifact, then return ONLY your `valent:handoff` machine block fields as JSON.',
+  ].join('\n')
+}
+
+// ---------------------------------------------------------------------------
+
+phase('Groom')
+// Pipelined: spec agents don't touch code, so stories flow assembly-line through the stages.
+const groomed = await pipeline(
+  stories,
+  // Stage 1: REQS analyzes the story AND tags testing_profiles (sprint-groom.md Step 0 + REQS).
+  async (story) => {
+    const r = await agent(
+      buildPrompt({
+        role: 'REQS', promptFile: 'reqs.md', storyId: story.storyId,
+        taskSubject: 'Tag testing_profiles for this story, then produce reqs-brief.md.',
+        returnContract: 'Return ONLY { schema:1, agent:"reqs", story, testing_profiles:[...], files:[...] } as JSON.',
+      }),
+      { label: `reqs:${story.storyId}`, phase: 'Groom', schema: REQS_GROOM_SCHEMA },
+    )
+    return { ...story, profiles: r.testing_profiles || [] }
+  },
+  // Stage 2: UXA only for UI stories (skipped otherwise — no idle agent).
+  async (g) => {
+    if (g.profiles.includes('ui')) {
+      await agent(
+        buildPrompt({ role: 'UXA', promptFile: 'uxa.md', storyId: g.storyId, taskSubject: 'Translate the brief into uxa-spec.md.' }),
+        { label: `uxa:${g.storyId}`, phase: 'Groom', schema: HANDOFF_SCHEMA },
+      )
+    }
+    return g
+  },
+  // Stage 3: QA-A writes the test spec before any code.
+  async (g) => {
+    await agent(
+      buildPrompt({ role: 'QA-A', promptFile: 'qa-a.md', storyId: g.storyId, taskSubject: 'Produce qa-test-spec.md before any code is written.' }),
+      { label: `qa-a:${g.storyId}`, phase: 'Groom', schema: HANDOFF_SCHEMA },
+    )
+    return g
+  },
+  // Stage 4: READINESS gate with a code-owned rejection loop. Rework routes upstream.
+  async (g) => {
+    let rejections = 0
+    while (true) {
+      const v = await agent(
+        buildPrompt({
+          role: 'READINESS', promptFile: 'readiness.md', storyId: g.storyId,
+          taskSubject: 'Validate the spec chain (reqs/uxa/qa) is implementation-ready; run cross-story checks (sprint mode).',
+        }),
+        { label: `gate:readiness:${g.storyId}`, phase: 'Groom', schema: VERDICT_SCHEMA },
+      )
+      if (v.verdict === 'pass') return { ...g, groomedStatus: 'groomed' }
+      rejections += 1
+      if (rejections >= maxRejectionCycles) {
+        log(`${g.storyId}: readiness cap tripped after ${rejections} — blocked-on-user, removed from pipeline`)
+        return { ...g, groomedStatus: 'blocked-on-user' }
+      }
+      const target = v.rejectionTarget || 'REQS'
+      log(`${g.storyId}: readiness rejection ${rejections}/${maxRejectionCycles} -> ${target}`)
+      await agent(
+        buildPrompt({ role: target, promptFile: `${target.toLowerCase()}.md`, storyId: g.storyId, taskSubject: 'Address the READINESS rejection and rewrite the affected spec.' }),
+        { label: `rework:${target.toLowerCase()}:${g.storyId}`, phase: 'Groom', schema: HANDOFF_SCHEMA },
+      )
+    }
+  },
+)
+
+const readyStories = groomed.filter(Boolean).filter((g) => g.groomedStatus === 'groomed')
+log(`groomed ${readyStories.length}/${stories.length} stories`)
+
+phase('Size')
+// Each story is sized by every estimator whose profile is present; story_points = the sum.
+// Sizing is estimation only (no code), so stories size in parallel.
+const sized = await parallel(
+  readyStories.map((g) => () => {
+    const estimators = [...new Set(g.profiles.map((p) => PROFILE_ESTIMATORS[p]).filter(Boolean))]
+    return parallel(
+      estimators.map((est) => () =>
+        agent(
+          buildPrompt({
+            role: est, promptFile: `${est.toLowerCase()}.md`, storyId: g.storyId,
+            taskSubject: 'Estimate this story (read your estimate.md step; apply calibration directives if present).',
+            returnContract: 'Return ONLY { schema:1, agent, story, points:<int> } as JSON.',
+          }),
+          { label: `estimate:${est.toLowerCase()}:${g.storyId}`, phase: 'Size', schema: ESTIMATE_SCHEMA },
+        )),
+    ).then((ests) => ({
+      ...g,
+      points: ests.filter(Boolean).reduce((sum, e) => sum + (e.points || 0), 0),
+    }))
+  }),
+)
+const sizedStories = sized.filter(Boolean)
+
+phase('Persist')
+// One agent persists the summed points + groomed status to the backlog so sprint-pack can
+// read them. (The script can't write files; the agent does the IO.)
+await agent(
+  `Update \`${backlogPath}\`: for each of these stories set \`story_points\` and \`status: groomed\`, ` +
+    `and write \`testing_profiles\`. Stories (JSON): ${JSON.stringify(sizedStories.map((s) => ({ id: s.storyId, story_points: s.points, testing_profiles: s.profiles })))}. ` +
+    `Return your \`valent:handoff\` machine block fields as JSON.`,
+  { label: 'persist-sizing', phase: 'Persist', schema: HANDOFF_SCHEMA },
+)
+
+phase('Pack')
+// Deterministic greedy packing happens in code (src/lib/sprint.js), invoked via the CLI.
+const pack = await agent(
+  `Run exactly: \`valent-pipeline sprint-pack --velocity ${velocity} --backlog ${backlogPath}\` ` +
+    `in the project root and return its stdout JSON verbatim (fields: sprint_stories, buffer_story_ids, points_planned, remaining_capacity).`,
+  { label: 'sprint-pack', phase: 'Pack', schema: PACK_SCHEMA },
+)
+log(`packed ${pack.sprint_stories.length} stories (${pack.points_planned} pts); buffer: ${pack.buffer_story_ids.length}`)
+
+phase('Validate')
+// Write the human plan + machine status artifacts, tag the backlog, then cross-check in code.
+const validation = await agent(
+  `For sprint ${sprintId}: (1) write \`sprint-${sprintId}-plan.md\` from \`.valent-pipeline/templates/sprint-plan.template.md\` ` +
+    `and \`sprint-${sprintId}-status.yaml\` from the status template for the packed stories ${JSON.stringify(pack.sprint_stories)}; ` +
+    `(2) tag those stories \`sprint: ${sprintId}\` + \`status: sprint-planned\` in \`${backlogPath}\`; ` +
+    `(3) run \`valent-pipeline validate-sprint --status sprint-${sprintId}-status.yaml --backlog ${backlogPath}\` and ` +
+    `return its result as JSON { valid:boolean, errors:[...] } (errors = the lines it printed on failure, else []).`,
+  { label: 'validate-sprint', phase: 'Validate', schema: VALIDATE_SCHEMA },
+)
+if (!validation.valid) {
+  throw new Error(`sprint ${sprintId} plan failed validation: ${(validation.errors || []).join('; ')}`)
+}
+
+// Shaped to feed straight into sprint.workflow.js.
+const packedSet = new Set(pack.sprint_stories)
+const plannedStories = sizedStories
+  .filter((s) => packedSet.has(s.storyId))
+  .map((s) => ({ storyId: s.storyId, projectType: s.projectType, profiles: s.profiles }))
+
+return {
+  sprintId,
+  points_planned: pack.points_planned,
+  stories: plannedStories,
+  buffer_story_ids: pack.buffer_story_ids,
+}