agent-templates 0.1.0 → 0.2.1

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/workflows/run-milestone.js

@@ -1,223 +1,225 @@
-export const meta = {
-  name: 'run-milestone',
-  description: 'Autonomous milestone runner: each ticket flows architect -> builder -> reviewer (bounce-capped in code) -> deliver',
-}
-
-// Deterministic orchestrator for the three-agent pattern. Control flow that used to be
-// prose ("max 2 bounces", "never merge without CLEAR") is enforced HERE, in code.
-//
-// args:
-// {
-//   tickets: [{ id: 'FND-01', path: 'docs/prd/01-foo/tickets/FND-01-x.md', issue: 12 }],
-//   mode: 'supervised' | 'autonomous',
-//   defaultBranch: 'main',        // optional, default 'main'
-//   maxBounces: 2,                // optional, default 2
-//   continueOnFailure: false,     // optional; default fail-fast (tickets may depend on earlier ones)
-//   platform: 'gh' | 'glab'       // tracker CLI for the deliver step, default 'gh'
-// }
-//
-// Guarantees encoded below (each one exists because prose alone failed before):
-// - reviewer prompts carry ONLY artifact refs (ticket path, computed plan path, branch name)
-// - a reviewer infrastructure failure never consumes the bounce budget or dispatches a fix
-// - nothing counts as delivered unless merged AND issueClosed AND dodPassed are all true
-// - supervised mode STOPS the run after each CLEAR (later tickets may depend on the merge);
-//   re-running /start-milestone continues — already-closed issues are filtered out upstream
-
-const cfg = Object.assign(
-  { maxBounces: 2, continueOnFailure: false, defaultBranch: 'main', platform: 'gh' },
-  args
-)
-if (!Array.isArray(cfg.tickets) || cfg.tickets.length === 0) {
-  throw new Error('args.tickets must be a non-empty array of {id, path, issue}')
-}
-for (const t of cfg.tickets) {
-  if (!t || typeof t.id !== 'string' || !t.id || typeof t.path !== 'string' || !t.path) {
-    throw new Error('every ticket needs a non-empty string id and path; got: ' + JSON.stringify(t))
-  }
-}
-if (cfg.mode !== 'supervised' && cfg.mode !== 'autonomous') {
-  throw new Error("args.mode must be 'supervised' or 'autonomous'")
-}
-if (!Number.isInteger(cfg.maxBounces) || cfg.maxBounces < 0) {
-  throw new Error('args.maxBounces must be an integer >= 0')
-}
-if (typeof cfg.defaultBranch !== 'string' || !cfg.defaultBranch) throw new Error('args.defaultBranch must be a non-empty string')
-if (cfg.platform !== 'gh' && cfg.platform !== 'glab') throw new Error("args.platform must be 'gh' or 'glab'")
-
-const PLAN = {
-  type: 'object',
-  properties: { planPath: { type: 'string' }, summary: { type: 'string' } },
-  required: ['planPath', 'summary'],
-}
-const BUILD = {
-  type: 'object',
-  properties: {
-    branch: { type: 'string' },
-    testsPassed: { type: 'boolean' },
-    testOutput: { type: 'string' },
-    deviations: { type: 'string' },
-  },
-  required: ['branch', 'testsPassed', 'testOutput'],
-}
-const VERDICT = {
-  type: 'object',
-  properties: {
-    verdict: { enum: ['CLEAR', 'BOUNCE'] },
-    checkedNote: { type: 'string' },
-    findings: {
-      type: 'array',
-      items: {
-        type: 'object',
-        properties: {
-          file: { type: 'string' },
-          line: { type: 'integer' },
-          scenario: { type: 'string' },
-          severity: { enum: ['blocker', 'major', 'minor'] },
-        },
-        required: ['file', 'scenario', 'severity'],
-      },
-    },
-  },
-  required: ['verdict'],
-}
-const DELIVERY = {
-  type: 'object',
-  properties: {
-    merged: { type: 'boolean' },
-    issueClosed: { type: 'boolean' },
-    dodPassed: { type: 'boolean' },
-    notes: { type: 'string' },
-  },
-  required: ['merged', 'issueClosed', 'dodPassed'],
-}
-
-const normalizePath = function (p) {
-  return String(p || '').replace(/\\/g, '/').replace(/^\.\//, '').trim()
-}
-
-const results = []
-let stopRun = false
-
-for (const t of cfg.tickets) {
-  if (stopRun) break
-  const P = 'T:' + t.id
-  const branch = 'ticket/' + t.id
-  const planPath = 'docs/plans/' + t.id + '.md' // computed in code; agent-returned paths are verified, never trusted
-
-  log('[' + t.id + '] architect: planning')
-  const plan = await agent(
-    'You are running as the Architect stage of the three-agent pattern. Ticket file: ' + t.path +
-    '. Produce the implementation plan per your role definition and write it to EXACTLY ' + planPath +
-    '. Return planPath (must be ' + planPath + ') and a one-paragraph summary.',
-    { agentType: 'architect', label: 'plan:' + t.id, phase: P, schema: PLAN }
-  )
-  if (!plan || normalizePath(plan.planPath) !== planPath) {
-    results.push({ id: t.id, status: 'failed', stage: 'architect', detail: plan ? 'plan written to unexpected path: ' + plan.planPath : 'architect agent returned nothing' })
-    if (!cfg.continueOnFailure) break
-    continue
-  }
-
-  log('[' + t.id + '] builder: implementing on ' + branch)
-  let build = await agent(
-    'Builder stage. Ticket: ' + t.path + '. Plan: ' + planPath + '. Create branch ' + branch +
-    ' from ' + cfg.defaultBranch + ', implement the plan there, commit, run the tests. Do NOT merge and do NOT touch the tracker. ' +
-    'Return branch (must be ' + branch + '), testsPassed, testOutput (paste real output), deviations.',
-    { agentType: 'builder', label: 'build:' + t.id, phase: P, schema: BUILD }
-  )
-  const buildBad = function (b) { return !b || !b.testsPassed || String(b.branch).trim() !== branch }
-  if (buildBad(build)) {
-    results.push({
-      id: t.id, status: 'failed', stage: 'builder',
-      detail: !build ? 'builder agent returned nothing' : (String(build.branch).trim() !== branch ? 'worked on wrong branch: ' + build.branch : build.testOutput),
-    })
-    if (!cfg.continueOnFailure) break
-    continue
-  }
-
-  // Review loop — the bounce cap lives here, in code, not in prose.
-  const reviewOnce = function (tag) {
-    return agent(
-      'Reviewer stage. Inputs (artifact refs only): ticket ' + t.path + ', plan ' + planPath +
-      ', diff = branch ' + branch + ' vs ' + cfg.defaultBranch + '. Review per your role definition; ' +
-      'run the tests yourself — no test results are provided on purpose. Return verdict CLEAR or BOUNCE with findings ' +
-      '(a BOUNCE with zero findings is invalid).',
-      { agentType: 'reviewer', label: 'review:' + t.id + '#' + tag, phase: P, schema: VERDICT }
-    )
-  }
-  // A null/invalid reviewer result is an infrastructure failure, not a code finding:
-  // retry once (not counted against the bounce budget), then escalate — never sent to the builder.
-  const reviewValid = function (v) {
-    if (!v) return false
-    if (v.verdict === 'BOUNCE' && (!v.findings || v.findings.length === 0)) return false
-    return true
-  }
-
-  let bounces = 0
-  let verdict = await reviewOnce('0')
-  if (!reviewValid(verdict)) { log('[' + t.id + '] reviewer returned no usable verdict — retrying once'); verdict = await reviewOnce('0-retry') }
-  let reviewerBroken = !reviewValid(verdict)
-  let fixBroken = false
-
-  while (!reviewerBroken && verdict.verdict === 'BOUNCE' && bounces < cfg.maxBounces) {
-    bounces += 1
-    log('[' + t.id + '] bounce ' + bounces + '/' + cfg.maxBounces + ': back to builder with ' + verdict.findings.length + ' finding(s)')
-    build = await agent(
-      'Builder stage, bounce fix. Ticket: ' + t.path + '. Plan: ' + planPath + '. Stay on branch ' + branch +
-      ' — do NOT merge and do NOT touch the tracker. Reviewer findings — address ALL of them and add regression tests: ' +
-      JSON.stringify(verdict.findings) + '. Run the tests. Return branch (must be ' + branch + '), testsPassed, testOutput, deviations.',
-      { agentType: 'builder', label: 'fix:' + t.id + '#' + bounces, phase: P, schema: BUILD }
-    )
-    if (buildBad(build)) { fixBroken = true; break }
-    verdict = await reviewOnce(String(bounces))
-    if (!reviewValid(verdict)) { log('[' + t.id + '] reviewer returned no usable verdict — retrying once'); verdict = await reviewOnce(bounces + '-retry') }
-    reviewerBroken = !reviewValid(verdict)
-  }
-
-  if (reviewerBroken || fixBroken || verdict.verdict !== 'CLEAR') {
-    const stage = reviewerBroken ? 'reviewer-failed' : (fixBroken ? 'bounce-fix-build' : 'review')
-    results.push({
-      id: t.id, status: 'escalated', stage: stage, bounces: bounces,
-      findings: reviewValid(verdict) ? (verdict.findings || []) : [],
-      detail: fixBroken ? (!build ? 'fix builder returned nothing' : (String(build.branch).trim() !== branch ? 'fix worked on wrong branch: ' + build.branch : build.testOutput)) : (reviewerBroken ? 'reviewer produced no usable verdict after one retry' : 'bounce cap exhausted'),
-    })
-    log('[' + t.id + '] escalated to a human (stage: ' + stage + ', after ' + bounces + ' bounce(s))')
-    if (!cfg.continueOnFailure) break
-    continue
-  }
-
-  if (cfg.mode === 'supervised') {
-    results.push({ id: t.id, status: 'awaiting-human-merge', branch: branch, bounces: bounces, note: verdict.checkedNote || '' })
-    log('[' + t.id + '] CLEAR — supervised mode: stopping the run for the human merge. Re-run /start-milestone after merging (closed issues are skipped).')
-    stopRun = true
-    continue
-  }
-
-  log('[' + t.id + '] deliver: merge + close issue + DoD')
-  const delivery = await agent(
-    'Delivery step (autonomous mode — pre-authorized by the human Gate 1 start signal). ' +
-    'Merge branch ' + branch + ' into ' + cfg.defaultBranch + ' with --no-ff and push. ' +
-    'Close tracker issue ' + (t.issue ? '#' + t.issue : 'for ticket ' + t.id + ' (find it by its "[' + t.id + ']" title prefix)') +
-    ' via ' + cfg.platform + ' and verify it is ACTUALLY closed afterwards. ' +
-    'Then run the Definition-of-Done checks from .claude/commands/verify-delivery.md for ticket ' + t.id +
-    ' (plan exists; tests green on the merged ' + cfg.defaultBranch + ' — run them yourself; CLEAR verdict recorded; merged to ' + cfg.defaultBranch + '; issue closed; writeback done). ' +
-    'Never report an item you did not check. Return merged, issueClosed, dodPassed, notes.',
-    { label: 'deliver:' + t.id, phase: P, schema: DELIVERY }
-  )
-  // Delivered requires ALL THREE flags — a hallucinated dodPassed alone must not count.
-  if (!delivery || !(delivery.merged && delivery.issueClosed && delivery.dodPassed)) {
-    const missing = !delivery ? 'delivery agent returned nothing' : ['merged', 'issueClosed', 'dodPassed'].filter(function (k) { return !delivery[k] }).join(', ') + ' = false'
-    results.push({ id: t.id, status: 'delivery-incomplete', detail: missing + (delivery && delivery.notes ? ' — ' + delivery.notes : '') })
-    if (!cfg.continueOnFailure) break
-    continue
-  }
-  results.push({ id: t.id, status: 'delivered', bounces: bounces })
-}
-
-const throughPipeline = results.filter(function (r) { return r.status === 'delivered' || r.status === 'awaiting-human-merge' }).length
-log('milestone run finished: ' + throughPipeline + '/' + cfg.tickets.length + ' tickets through the pipeline')
-
-return {
-  mode: cfg.mode,
-  results: results,
-  notStarted: cfg.tickets.length - results.length, // > 0 means the run stopped early (fail-fast or supervised pause)
-}
+export const meta = {
+  name: 'run-milestone',
+  description: 'Autonomous milestone runner: each ticket flows architect -> builder -> reviewer (bounce-capped in code) -> deliver',
+}
+
+// Deterministic orchestrator for the three-agent pattern. Control flow that used to be
+// prose ("max 2 bounces", "never merge without CLEAR") is enforced HERE, in code.
+//
+// args:
+// {
+//   tickets: [{ id: 'FND-01', path: 'docs/prd/01-foo/tickets/FND-01-x.md', issue: 12 }],
+//   mode: 'supervised' | 'autonomous',
+//   defaultBranch: 'main',        // optional, default 'main'
+//   maxBounces: 2,                // optional, default 2
+//   continueOnFailure: false,     // optional; default fail-fast (tickets may depend on earlier ones)
+//   platform: 'gh' | 'glab'       // tracker CLI for the deliver step, default 'gh'
+// }
+//
+// Guarantees encoded below (each one exists because prose alone failed before):
+// - reviewer prompts carry ONLY artifact refs (ticket path, computed plan path, branch name)
+// - a reviewer infrastructure failure never consumes the bounce budget or dispatches a fix
+// - nothing counts as delivered unless merged AND issueClosed AND dodPassed are all true
+// - supervised mode STOPS the run after each CLEAR (later tickets may depend on the merge);
+//   re-running /start-milestone continues — already-closed issues are filtered out upstream
+
+// args may arrive as a JSON string depending on the harness (catalog issue #23)
+const parsedArgs = typeof args === 'string' ? JSON.parse(args) : (args || {})
+const cfg = Object.assign(
+  { maxBounces: 2, continueOnFailure: false, defaultBranch: 'main', platform: 'gh' },
+  parsedArgs
+)
+if (!Array.isArray(cfg.tickets) || cfg.tickets.length === 0) {
+  throw new Error('args.tickets must be a non-empty array of {id, path, issue}')
+}
+for (const t of cfg.tickets) {
+  if (!t || typeof t.id !== 'string' || !t.id || typeof t.path !== 'string' || !t.path) {
+    throw new Error('every ticket needs a non-empty string id and path; got: ' + JSON.stringify(t))
+  }
+}
+if (cfg.mode !== 'supervised' && cfg.mode !== 'autonomous') {
+  throw new Error("args.mode must be 'supervised' or 'autonomous'")
+}
+if (!Number.isInteger(cfg.maxBounces) || cfg.maxBounces < 0) {
+  throw new Error('args.maxBounces must be an integer >= 0')
+}
+if (typeof cfg.defaultBranch !== 'string' || !cfg.defaultBranch) throw new Error('args.defaultBranch must be a non-empty string')
+if (cfg.platform !== 'gh' && cfg.platform !== 'glab') throw new Error("args.platform must be 'gh' or 'glab'")
+
+const PLAN = {
+  type: 'object',
+  properties: { planPath: { type: 'string' }, summary: { type: 'string' } },
+  required: ['planPath', 'summary'],
+}
+const BUILD = {
+  type: 'object',
+  properties: {
+    branch: { type: 'string' },
+    testsPassed: { type: 'boolean' },
+    testOutput: { type: 'string' },
+    deviations: { type: 'string' },
+  },
+  required: ['branch', 'testsPassed', 'testOutput'],
+}
+const VERDICT = {
+  type: 'object',
+  properties: {
+    verdict: { enum: ['CLEAR', 'BOUNCE'] },
+    checkedNote: { type: 'string' },
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          file: { type: 'string' },
+          line: { type: 'integer' },
+          scenario: { type: 'string' },
+          severity: { enum: ['blocker', 'major', 'minor'] },
+        },
+        required: ['file', 'scenario', 'severity'],
+      },
+    },
+  },
+  required: ['verdict'],
+}
+const DELIVERY = {
+  type: 'object',
+  properties: {
+    merged: { type: 'boolean' },
+    issueClosed: { type: 'boolean' },
+    dodPassed: { type: 'boolean' },
+    notes: { type: 'string' },
+  },
+  required: ['merged', 'issueClosed', 'dodPassed'],
+}
+
+const normalizePath = function (p) {
+  return String(p || '').replace(/\\/g, '/').replace(/^\.\//, '').trim()
+}
+
+const results = []
+let stopRun = false
+
+for (const t of cfg.tickets) {
+  if (stopRun) break
+  const P = 'T:' + t.id
+  const branch = 'ticket/' + t.id
+  const planPath = 'docs/plans/' + t.id + '.md' // computed in code; agent-returned paths are verified, never trusted
+
+  log('[' + t.id + '] architect: planning')
+  const plan = await agent(
+    'You are running as the Architect stage of the three-agent pattern. Ticket file: ' + t.path +
+    '. Produce the implementation plan per your role definition and write it to EXACTLY ' + planPath +
+    '. Return planPath (must be ' + planPath + ') and a one-paragraph summary.',
+    { agentType: 'architect', label: 'plan:' + t.id, phase: P, schema: PLAN }
+  )
+  if (!plan || normalizePath(plan.planPath) !== planPath) {
+    results.push({ id: t.id, status: 'failed', stage: 'architect', detail: plan ? 'plan written to unexpected path: ' + plan.planPath : 'architect agent returned nothing' })
+    if (!cfg.continueOnFailure) break
+    continue
+  }
+
+  log('[' + t.id + '] builder: implementing on ' + branch)
+  let build = await agent(
+    'Builder stage. Ticket: ' + t.path + '. Plan: ' + planPath + '. Create branch ' + branch +
+    ' from ' + cfg.defaultBranch + ', implement the plan there, commit, run the tests. Do NOT merge and do NOT touch the tracker. ' +
+    'Return branch (must be ' + branch + '), testsPassed, testOutput (paste real output), deviations.',
+    { agentType: 'builder', label: 'build:' + t.id, phase: P, schema: BUILD }
+  )
+  const buildBad = function (b) { return !b || !b.testsPassed || String(b.branch).trim() !== branch }
+  if (buildBad(build)) {
+    results.push({
+      id: t.id, status: 'failed', stage: 'builder',
+      detail: !build ? 'builder agent returned nothing' : (String(build.branch).trim() !== branch ? 'worked on wrong branch: ' + build.branch : build.testOutput),
+    })
+    if (!cfg.continueOnFailure) break
+    continue
+  }
+
+  // Review loop — the bounce cap lives here, in code, not in prose.
+  const reviewOnce = function (tag) {
+    return agent(
+      'Reviewer stage. Inputs (artifact refs only): ticket ' + t.path + ', plan ' + planPath +
+      ', diff = branch ' + branch + ' vs ' + cfg.defaultBranch + '. Review per your role definition; ' +
+      'run the tests yourself — no test results are provided on purpose. Return verdict CLEAR or BOUNCE with findings ' +
+      '(a BOUNCE with zero findings is invalid).',
+      { agentType: 'reviewer', label: 'review:' + t.id + '#' + tag, phase: P, schema: VERDICT }
+    )
+  }
+  // A null/invalid reviewer result is an infrastructure failure, not a code finding:
+  // retry once (not counted against the bounce budget), then escalate — never sent to the builder.
+  const reviewValid = function (v) {
+    if (!v) return false
+    if (v.verdict === 'BOUNCE' && (!v.findings || v.findings.length === 0)) return false
+    return true
+  }
+
+  let bounces = 0
+  let verdict = await reviewOnce('0')
+  if (!reviewValid(verdict)) { log('[' + t.id + '] reviewer returned no usable verdict — retrying once'); verdict = await reviewOnce('0-retry') }
+  let reviewerBroken = !reviewValid(verdict)
+  let fixBroken = false
+
+  while (!reviewerBroken && verdict.verdict === 'BOUNCE' && bounces < cfg.maxBounces) {
+    bounces += 1
+    log('[' + t.id + '] bounce ' + bounces + '/' + cfg.maxBounces + ': back to builder with ' + verdict.findings.length + ' finding(s)')
+    build = await agent(
+      'Builder stage, bounce fix. Ticket: ' + t.path + '. Plan: ' + planPath + '. Stay on branch ' + branch +
+      ' — do NOT merge and do NOT touch the tracker. Reviewer findings — address ALL of them and add regression tests: ' +
+      JSON.stringify(verdict.findings) + '. Run the tests. Return branch (must be ' + branch + '), testsPassed, testOutput, deviations.',
+      { agentType: 'builder', label: 'fix:' + t.id + '#' + bounces, phase: P, schema: BUILD }
+    )
+    if (buildBad(build)) { fixBroken = true; break }
+    verdict = await reviewOnce(String(bounces))
+    if (!reviewValid(verdict)) { log('[' + t.id + '] reviewer returned no usable verdict — retrying once'); verdict = await reviewOnce(bounces + '-retry') }
+    reviewerBroken = !reviewValid(verdict)
+  }
+
+  if (reviewerBroken || fixBroken || verdict.verdict !== 'CLEAR') {
+    const stage = reviewerBroken ? 'reviewer-failed' : (fixBroken ? 'bounce-fix-build' : 'review')
+    results.push({
+      id: t.id, status: 'escalated', stage: stage, bounces: bounces,
+      findings: reviewValid(verdict) ? (verdict.findings || []) : [],
+      detail: fixBroken ? (!build ? 'fix builder returned nothing' : (String(build.branch).trim() !== branch ? 'fix worked on wrong branch: ' + build.branch : build.testOutput)) : (reviewerBroken ? 'reviewer produced no usable verdict after one retry' : 'bounce cap exhausted'),
+    })
+    log('[' + t.id + '] escalated to a human (stage: ' + stage + ', after ' + bounces + ' bounce(s))')
+    if (!cfg.continueOnFailure) break
+    continue
+  }
+
+  if (cfg.mode === 'supervised') {
+    results.push({ id: t.id, status: 'awaiting-human-merge', branch: branch, bounces: bounces, note: verdict.checkedNote || '' })
+    log('[' + t.id + '] CLEAR — supervised mode: stopping the run for the human merge. Re-run /start-milestone after merging (closed issues are skipped).')
+    stopRun = true
+    continue
+  }
+
+  log('[' + t.id + '] deliver: merge + close issue + DoD')
+  const delivery = await agent(
+    'Delivery step (autonomous mode — pre-authorized by the human Gate 1 start signal). ' +
+    'Merge branch ' + branch + ' into ' + cfg.defaultBranch + ' with --no-ff and push. ' +
+    'Close tracker issue ' + (t.issue ? '#' + t.issue : 'for ticket ' + t.id + ' (find it by its "[' + t.id + ']" title prefix)') +
+    ' via ' + cfg.platform + ' and verify it is ACTUALLY closed afterwards. ' +
+    'Then run the Definition-of-Done checks from .claude/commands/verify-delivery.md for ticket ' + t.id +
+    ' (plan exists; tests green on the merged ' + cfg.defaultBranch + ' — run them yourself; CLEAR verdict recorded; merged to ' + cfg.defaultBranch + '; issue closed; writeback done). ' +
+    'Never report an item you did not check. Return merged, issueClosed, dodPassed, notes.',
+    { label: 'deliver:' + t.id, phase: P, schema: DELIVERY }
+  )
+  // Delivered requires ALL THREE flags — a hallucinated dodPassed alone must not count.
+  if (!delivery || !(delivery.merged && delivery.issueClosed && delivery.dodPassed)) {
+    const missing = !delivery ? 'delivery agent returned nothing' : ['merged', 'issueClosed', 'dodPassed'].filter(function (k) { return !delivery[k] }).join(', ') + ' = false'
+    results.push({ id: t.id, status: 'delivery-incomplete', detail: missing + (delivery && delivery.notes ? ' — ' + delivery.notes : '') })
+    if (!cfg.continueOnFailure) break
+    continue
+  }
+  results.push({ id: t.id, status: 'delivered', bounces: bounces })
+}
+
+const throughPipeline = results.filter(function (r) { return r.status === 'delivered' || r.status === 'awaiting-human-merge' }).length
+log('milestone run finished: ' + throughPipeline + '/' + cfg.tickets.length + ' tickets through the pipeline')
+
+return {
+  mode: cfg.mode,
+  results: results,
+  notStarted: cfg.tickets.length - results.length, // > 0 means the run stopped early (fail-fast or supervised pause)
+}

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/workflows/start-all.js

@@ -0,0 +1,120 @@
+export const meta = {
+  name: 'start-all',
+  description: 'Whole-PRD driver: runs every module through the milestone pipeline in DAG order, composing run-milestone per module',
+}
+
+// Module-level driver above run-milestone (which is unchanged: per ticket it still runs
+// architect plan -> builder execute -> fresh-context reviewer, bounce-capped in code).
+//
+// args:
+// {
+//   modules: [{ name: '01-foundation', dependsOn: ['00-x'], tickets: [{id,path,issue}] }],
+//     // in DAG order (from milestone-dag.mjs); tickets pre-filtered of closed issues,
+//     // so an [] tickets list means "module already complete" (resume semantics)
+//   mode: 'supervised' | 'autonomous',
+//   defaultBranch: 'main',      // optional
+//   platform: 'gh' | 'glab'     // optional, default 'gh'
+// }
+//
+// Failure policy (maintainer decisions, catalog issue #20, 2026-07-18):
+// - a failed module blocks its dependents;
+// - autonomous: independent DAG branches CONTINUE past a failure;
+// - supervised: ANY pause or failure stops the whole run (re-run to resume — closed
+//   issues are filtered upstream, so completed modules arrive as already-complete);
+// - no cost ceiling.
+
+// args may arrive as a JSON string depending on the harness (catalog issue #23)
+const parsedArgs = typeof args === 'string' ? JSON.parse(args) : (args || {})
+const cfg = Object.assign({ defaultBranch: 'main', platform: 'gh' }, parsedArgs)
+if (!Array.isArray(cfg.modules) || cfg.modules.length === 0) {
+  throw new Error('args.modules must be a non-empty array of {name, dependsOn, tickets}')
+}
+for (const m of cfg.modules) {
+  if (!m || typeof m.name !== 'string' || !m.name || !Array.isArray(m.tickets) || !Array.isArray(m.dependsOn || [])) {
+    throw new Error('every module needs a name, a tickets array, and a dependsOn array; got: ' + JSON.stringify(m))
+  }
+}
+if (cfg.mode !== 'supervised' && cfg.mode !== 'autonomous') {
+  throw new Error("args.mode must be 'supervised' or 'autonomous'")
+}
+if (cfg.platform !== 'gh' && cfg.platform !== 'glab') throw new Error("args.platform must be 'gh' or 'glab'")
+
+const state = {} // name -> 'completed' | 'failed' | 'skipped' | 'paused'
+const results = []
+let stopped = false
+
+for (const m of cfg.modules) {
+  const deps = m.dependsOn || []
+  if (stopped) {
+    results.push({ name: m.name, state: 'not-started', detail: 'run stopped before this module' })
+    continue
+  }
+  for (const d of deps) {
+    if (!(d in state)) throw new Error('module order violates the DAG: ' + m.name + ' scheduled before its dependency ' + d)
+  }
+  const badDep = deps.find(function (d) { return state[d] !== 'completed' })
+  if (badDep) {
+    state[m.name] = 'skipped'
+    results.push({ name: m.name, state: 'skipped-dependency', detail: 'dependency ' + badDep + ' did not complete' })
+    log('module ' + m.name + ': skipped (dependency ' + badDep + ' did not complete)')
+    continue
+  }
+  if (m.tickets.length === 0) {
+    state[m.name] = 'completed'
+    results.push({ name: m.name, state: 'already-complete', detail: 'all tickets already closed (resume)' })
+    log('module ' + m.name + ': already complete')
+    continue
+  }
+
+  log('module ' + m.name + ': running ' + m.tickets.length + ' ticket(s) through run-milestone')
+  let child = null
+  let err = null
+  try {
+    child = await workflow('run-milestone', {
+      tickets: m.tickets,
+      mode: cfg.mode,
+      defaultBranch: cfg.defaultBranch,
+      platform: cfg.platform,
+    })
+  } catch (e) {
+    err = e && e.message ? e.message : String(e)
+  }
+  const rs = (child && child.results) || []
+
+  if (cfg.mode === 'supervised') {
+    // supervised run-milestone stops after each CLEAR; a module "completes" only via
+    // resume (its issues close, its ticket list arrives empty next run)
+    const paused = !err && rs.some(function (r) { return r.status === 'awaiting-human-merge' })
+    state[m.name] = 'paused'
+    results.push({
+      name: m.name,
+      state: paused ? 'paused-for-merge' : 'failed',
+      detail: err || (paused ? 'CLEAR reached — merge it, then re-run /start-all to continue' : 'module stopped without reaching a CLEAR'),
+      ticketResults: rs,
+    })
+    stopped = true
+    continue
+  }
+
+  const allDelivered = !err && rs.length === m.tickets.length && rs.every(function (r) { return r.status === 'delivered' })
+  if (allDelivered) {
+    state[m.name] = 'completed'
+    results.push({ name: m.name, state: 'completed', detail: rs.length + ' ticket(s) delivered', ticketResults: rs })
+    log('module ' + m.name + ': completed')
+  } else {
+    state[m.name] = 'failed'
+    const firstBad = rs.find(function (r) { return r.status !== 'delivered' })
+    results.push({
+      name: m.name,
+      state: 'failed',
+      detail: err || (firstBad ? firstBad.id + ': ' + firstBad.status + (firstBad.stage ? ' (' + firstBad.stage + ')' : '') : 'incomplete results'),
+      ticketResults: rs,
+    })
+    log('module ' + m.name + ': FAILED — dependents will be skipped; independent branches continue')
+  }
+}
+
+const done = results.filter(function (r) { return r.state === 'completed' || r.state === 'already-complete' }).length
+log('start-all finished: ' + done + '/' + cfg.modules.length + ' modules complete')
+
+return { mode: cfg.mode, results: results, stoppedEarly: stopped }