@juangcarmona/lighthouse-sdlc 0.3.0 → 0.5.0

package/src/sdlc.mjs

@@ -1,9 +1,19 @@
 #!/usr/bin/env node
-import { access, readFile, writeFile } from 'node:fs/promises';
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { constants } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { buildDecompositionPlan, applyDecompositionPlan } from './decompose.mjs';
+import { validateControlPlane, validateLaunchRequest } from './control-plane.mjs';
+import { createGithubLabel, createGithubSubIssues, mergeGithubTriage, readGithubIssue, readGithubLabels, replaceGithubLabels } from './github.mjs';
+import { applyLabelReconciliationPlan, buildLabelReconciliationPlan } from './reconcile.mjs';
+import { buildRoutePlan } from './routes.mjs';
+import { buildStackedPlan } from './stacked.mjs';
 import { applyTriageLabels, buildTriageReport } from './triage.mjs';
+import { validateMemoryRecord } from './memory.mjs';
+import { replayWorkflow } from './workflow.mjs';
+import { validateStageResult } from './contracts.mjs';
+import { readCapabilityCatalog, validateCapabilityCatalog } from './capabilities.mjs';
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const contractPath = resolve(packageRoot, 'contract.json');
@@ -29,10 +39,10 @@ async function verifyContract() {
   for (const stage of stages) {
     for (const asset of [stage.skill, stage.command]) if (!(await exists(resolve(packageRoot, asset)))) problems.push(`missing stage asset ${asset}`);
   }
-  for (const asset of [contract.assets?.routes, contract.assets?.gates, contract.assets?.controlPlaneSchema, contract.assets?.triageSchema]) {
+  for (const asset of [contract.assets?.routes, contract.assets?.gates, contract.assets?.stages, contract.assets?.controlPlaneSchema, contract.assets?.triageSchema, contract.assets?.stageResultSchema, contract.assets?.stateSchema, contract.assets?.decompositionSchema, contract.assets?.capabilitiesSchema, contract.assets?.capabilityCatalog, contract.assets?.capabilityCatalogSchema]) {
     if (!asset || !(await exists(resolve(packageRoot, asset)))) problems.push(`missing contract asset ${asset ?? '(empty)'}`);
   }
-  for (const asset of ['routes.json', 'gates.json', 'schemas/routes.schema.json', 'schemas/gates.schema.json', 'schemas/control-plane.schema.json', 'schemas/triage.schema.json', 'src/triage.mjs']) {
+  for (const asset of ['routes.json', 'gates.json', 'stages.json', 'schemas/routes.schema.json', 'schemas/gates.schema.json', 'schemas/stages.schema.json', 'schemas/control-plane.schema.json', 'schemas/triage.schema.json', 'schemas/stage-result.schema.json', 'schemas/workflow-state.schema.json', 'schemas/decomposition.schema.json', 'schemas/capabilities.schema.json', 'schemas/capability-catalog.schema.json', 'src/capabilities.mjs', 'src/contracts.mjs', 'src/control-plane.mjs', 'src/decompose.mjs', 'src/github.mjs', 'src/memory.mjs', 'src/reconcile.mjs', 'src/routes.mjs', 'src/stacked.mjs', 'src/triage.mjs', 'src/workflow.mjs']) {
     if (!(await exists(resolve(packageRoot, asset)))) problems.push(`missing package asset ${asset}`);
   }
   try {
@@ -45,7 +55,16 @@ async function verifyContract() {
     const gateIds = gates.gates?.map((gate) => gate.id) ?? [];
     if (gateIds.join(',') !== contract.gates.join(',')) problems.push('gates.json does not match contract gates');
   } catch (error) { problems.push(`Cannot read gates.json: ${error.message}`); }
-  for (const command of ['status', ...expectedStages]) if (!(await exists(resolve(packageRoot, `commands/${command}.md`)))) problems.push(`missing command asset ${command}`);
+  try {
+    const stages = await readJson(resolve(packageRoot, 'stages.json'));
+    const stageIds = stages.stages?.map((stage) => stage.id) ?? [];
+    if (stageIds.join(',') !== expectedStages.join(',')) problems.push('stages.json does not match contract stages');
+  } catch (error) { problems.push(`Cannot read stages.json: ${error.message}`); }
+  try {
+    const catalog = await readCapabilityCatalog();
+    problems.push(...validateCapabilityCatalog(catalog).map((error) => `${error.code}: ${error.message}`));
+  } catch (error) { problems.push(`Cannot read capabilities.json: ${error.message}`); }
+  for (const command of ['status', ...expectedStages, ...(contract.utilities ?? []).filter((command) => command !== 'status')]) if (!(await exists(resolve(packageRoot, `commands/${command}.md`)))) problems.push(`missing command asset ${command}`);
   for (const metaCommand of contract.metaCommands ?? []) if (!(await exists(resolve(packageRoot, `meta-commands/${metaCommand}.md`)))) problems.push(`missing meta-command asset ${metaCommand}`);
   return problems;
 }
@@ -105,15 +124,232 @@ async function runTriage(args) {
   if (report.status !== 'ready') process.exit(1);
 }
 
+function output(value, format = 'json') {
+  if (format === 'json') console.log(JSON.stringify(value, null, 2));
+  else console.log(JSON.stringify(value));
+}
+
+async function runState(args) {
+  const inputPath = option(args, '--input');
+  const format = option(args, '--format') ?? 'json';
+  if (!inputPath) { console.error('Usage: lighthouse-sdlc state --input <events.json> [--format <json|text>]'); process.exit(2); }
+  const input = await readJson(resolve(process.cwd(), inputPath));
+  const result = replayWorkflow(Array.isArray(input) ? input : input.events);
+  output(result, format);
+  if (!result.valid) process.exit(1);
+}
+
+async function runControlPlane(args) {
+  const inputPath = option(args, '--input');
+  const format = option(args, '--format') ?? 'json';
+  if (!inputPath) { console.error('Usage: lighthouse-sdlc control-plane --input <control-plane.json> [--format <json|text>]'); process.exit(2); }
+  const input = await readJson(resolve(process.cwd(), inputPath));
+  const errors = validateControlPlane(input);
+  const result = { schemaVersion: 1, status: errors.length ? 'invalid' : 'valid', valid: errors.length === 0, errors };
+  output(result, format);
+  if (errors.length) process.exit(1);
+}
+
+async function runStageResult(args) {
+  const inputPath = option(args, '--input');
+  const format = option(args, '--format') ?? 'json';
+  if (!inputPath) { console.error('Usage: lighthouse-sdlc stage-result --input <result.json> [--format <json|text>]'); process.exit(2); }
+  const result = await readJson(resolve(process.cwd(), inputPath));
+  const errors = validateStageResult(result);
+  output({ schemaVersion: 1, status: errors.length ? 'invalid' : 'valid', valid: errors.length === 0, errors }, format);
+  if (errors.length) process.exit(1);
+}
+
+async function runMemory(args) {
+  const inputPath = option(args, '--input');
+  const policyPath = option(args, '--policy');
+  const format = option(args, '--format') ?? 'json';
+  if (!inputPath) { console.error('Usage: lighthouse-sdlc memory --input <record.json> [--policy <memory-policy.json>] [--format <json|text>]'); process.exit(2); }
+  const record = await readJson(resolve(process.cwd(), inputPath));
+  const policy = policyPath ? await readJson(resolve(process.cwd(), policyPath)) : {};
+  const errors = validateMemoryRecord(record, policy);
+  output({ schemaVersion: 1, status: errors.length ? 'invalid' : 'valid', valid: errors.length === 0, errors }, format);
+  if (errors.length) process.exit(1);
+}
+
+async function runLaunch(args) {
+  const inputPath = option(args, '--input');
+  const controlPlanePath = option(args, '--control-plane');
+  const format = option(args, '--format') ?? 'json';
+  if (!inputPath || !controlPlanePath) { console.error('Usage: lighthouse-sdlc launch --input <request.json> --control-plane <control-plane.json> [--format <json|text>]'); process.exit(2); }
+  const request = await readJson(resolve(process.cwd(), inputPath));
+  const controlPlane = await readJson(resolve(process.cwd(), controlPlanePath));
+  const errors = [...validateControlPlane(controlPlane), ...validateLaunchRequest(request, controlPlane)];
+  output({ schemaVersion: 1, status: errors.length ? 'invalid' : 'valid', valid: errors.length === 0, executed: false, errors }, format);
+  if (errors.length) process.exit(1);
+}
+
+async function runDecompose(args) {
+  const inputPath = option(args, '--input');
+  const outputPath = option(args, '--output');
+  const format = option(args, '--format') ?? 'json';
+  const apply = args.includes('--apply');
+  if (!inputPath || (apply && !outputPath)) { console.error('Usage: lighthouse-sdlc decompose --input <file> [--format <json|text>] [--apply --output <file>]'); process.exit(2); }
+  const plan = buildDecompositionPlan(await readJson(resolve(process.cwd(), inputPath)));
+  if (apply && plan.canApply) await writeFile(resolve(process.cwd(), outputPath), `${JSON.stringify(applyDecompositionPlan(plan), null, 2)}\n`);
+  output({ ...plan, applied: Boolean(apply && plan.canApply) }, format);
+  if (!plan.valid) process.exit(1);
+}
+
+async function runRoute(args) {
+  const routeId = option(args, '--route');
+  const format = option(args, '--format') ?? 'json';
+  if (!routeId) { console.error('Usage: lighthouse-sdlc route --route <name> [--available <comma-separated-prerequisites>] [--format <json|text>]'); process.exit(2); }
+  const routes = await readJson(resolve(packageRoot, 'routes.json'));
+  const route = routes.routes?.find((candidate) => candidate.id === routeId);
+  if (!route) { output({ schemaVersion: 1, status: 'invalid', valid: false, errors: [{ code: 'route.unknown', message: `unknown route ${routeId}` }] }, format); process.exit(1); }
+  const available = (option(args, '--available') ?? '').split(',').map((item) => item.trim()).filter(Boolean);
+  const plan = buildRoutePlan(route, { available });
+  output(plan, format);
+  if (!plan.valid) process.exit(1);
+}
+
+async function runStacked(args) {
+  const inputPath = option(args, '--input');
+  const outputPath = option(args, '--output');
+  const format = option(args, '--format') ?? 'json';
+  const apply = args.includes('--apply');
+  if (!inputPath || (apply && !outputPath)) { console.error('Usage: lighthouse-sdlc stacked --input <file> [--format <json|text>] [--apply --output <file>]'); process.exit(2); }
+  const plan = buildStackedPlan(await readJson(resolve(process.cwd(), inputPath)));
+  if (apply && plan.canApply) await writeFile(resolve(process.cwd(), outputPath), `${JSON.stringify({ ...plan, applied: true }, null, 2)}\n`);
+  output({ ...plan, applied: Boolean(apply && plan.canApply) }, format);
+  if (!plan.valid) process.exit(1);
+}
+
+async function runGithubTriage(args) {
+  const repo = option(args, '--repo');
+  const issueNumber = option(args, '--issue');
+  const assessmentPath = option(args, '--assessment');
+  const format = option(args, '--format') ?? 'json';
+  const apply = args.includes('--apply');
+  if (!repo || !issueNumber || !assessmentPath) { console.error('Usage: lighthouse-sdlc github-triage --repo <owner/repo> --issue <number> --assessment <file> [--apply] [--format <json|text>]'); process.exit(2); }
+  const assessmentInput = await readJson(resolve(process.cwd(), assessmentPath));
+  const issueMetadata = await readGithubIssue(repo, issueNumber);
+  const report = buildTriageReport(mergeGithubTriage(issueMetadata, assessmentInput.assessment, assessmentInput.configuration));
+  report.applied = false;
+  if (apply && report.canApply) {
+    const reread = await readGithubIssue(repo, issueNumber);
+    if (JSON.stringify(reread.currentLabels) !== JSON.stringify(report.labels.current)) throw new Error('GitHub labels changed since the triage read; refusing to apply the projection');
+    const applied = await replaceGithubLabels(repo, issueNumber, applyTriageLabels(report), { dryRun: false });
+    report.applied = applied.applied;
+  }
+  output(report, format);
+  if (report.status !== 'ready') process.exit(1);
+}
+
+async function runGithubDecompose(args) {
+  const repo = option(args, '--repo');
+  const issueNumber = option(args, '--issue');
+  const inputPath = option(args, '--input');
+  const format = option(args, '--format') ?? 'json';
+  const apply = args.includes('--apply');
+  if (!repo || !issueNumber || !inputPath) { console.error('Usage: lighthouse-sdlc github-decompose --repo <owner/repo> --issue <number> --input <file> [--apply] [--format <json|text>]'); process.exit(2); }
+  const parent = await readGithubIssue(repo, issueNumber);
+  const input = await readJson(resolve(process.cwd(), inputPath));
+  const plan = buildDecompositionPlan({ ...input, parent: { ...input.parent, id: parent.workItem.id, number: Number(issueNumber), title: parent.workItem.title } });
+  const result = plan.canApply ? await createGithubSubIssues(repo, issueNumber, plan, { dryRun: !apply }) : { applied: false, operations: [] };
+  output({ ...plan, github: result }, format);
+  if (!plan.valid) process.exit(1);
+}
+
+async function optionalJson(path) {
+  if (!path || !(await exists(path))) return null;
+  return readJson(path);
+}
+
+async function writeRecord(path, plan, verified = true) {
+  const recordPath = resolve(process.cwd(), path);
+  await mkdir(dirname(recordPath), { recursive: true });
+  await writeFile(recordPath, `${JSON.stringify({ ...plan.record, observedHash: plan.targetHash, verified }, null, 2)}\n`);
+}
+
+async function runReconcileLabels(args) {
+  const declarationPath = option(args, '--input');
+  const existingPath = option(args, '--existing');
+  const recordPath = option(args, '--record') ?? '.lighthouse/reconciliation/labels.json';
+  const format = option(args, '--format') ?? 'json';
+  const apply = args.includes('--apply');
+  if (!declarationPath || !existingPath) { console.error('Usage: lighthouse-sdlc reconcile-labels --input <capabilities.json> --existing <labels.json> [--record <path>] [--apply] [--format <json|text>]'); process.exit(2); }
+  const declaration = await readJson(resolve(process.cwd(), declarationPath));
+  const existing = await readJson(resolve(process.cwd(), existingPath));
+  const plan = buildLabelReconciliationPlan(declaration, existing, await optionalJson(resolve(process.cwd(), recordPath)));
+  if (apply && plan.canApply) {
+    const current = await readJson(resolve(process.cwd(), existingPath));
+    const reread = buildLabelReconciliationPlan(declaration, current);
+    if (reread.observedHash !== plan.observedHash) throw new Error('Label reconciliation changed since the plan was created; refusing to apply.');
+    const updated = applyLabelReconciliationPlan(reread, current);
+    await writeFile(resolve(process.cwd(), existingPath), `${JSON.stringify(updated, null, 2)}\n`);
+    await writeRecord(recordPath, reread);
+    plan.applied = true;
+    plan.record = { ...reread.record, observedHash: reread.targetHash, verified: true };
+  } else plan.applied = false;
+  output(plan, format);
+  if (!plan.valid || !plan.canApply) process.exit(1);
+}
+
+async function runGithubLabels(args) {
+  const repo = option(args, '--repo');
+  const declarationPath = option(args, '--input');
+  const recordPath = option(args, '--record') ?? '.lighthouse/reconciliation/labels.json';
+  const format = option(args, '--format') ?? 'json';
+  const apply = args.includes('--apply');
+  if (!repo || !declarationPath) { console.error('Usage: lighthouse-sdlc github-labels --repo <owner/repo> --input <capabilities.json> [--record <path>] [--apply] [--format <json|text>]'); process.exit(2); }
+  const declaration = await readJson(resolve(process.cwd(), declarationPath));
+  const labels = await readGithubLabels(repo);
+  const plan = buildLabelReconciliationPlan(declaration, labels, await optionalJson(resolve(process.cwd(), recordPath)));
+  if (apply && plan.canApply) {
+    const current = await readGithubLabels(repo);
+    if (buildLabelReconciliationPlan(declaration, current).observedHash !== plan.observedHash) throw new Error('GitHub labels changed since the plan was created; refusing to apply.');
+    for (const operation of plan.operations) await createGithubLabel(repo, operation, { dryRun: false });
+    const finalLabels = await readGithubLabels(repo);
+    const appliedPlan = buildLabelReconciliationPlan(declaration, finalLabels);
+    if (!appliedPlan.canApply || appliedPlan.operations.length > 0) throw new Error('GitHub label reconciliation did not reach the declared state.');
+    await writeRecord(recordPath, appliedPlan);
+    plan.applied = true;
+    plan.record = { ...appliedPlan.record, observedHash: appliedPlan.targetHash, verified: true };
+  } else plan.applied = false;
+  output(plan, format);
+  if (!plan.valid || !plan.canApply) process.exit(1);
+}
+
 const command = process.argv[2] ?? 'verify';
-if (!['contract', 'verify', 'triage'].includes(command)) {
-  console.error('Usage: lighthouse-sdlc <contract|verify|triage>');
+if (!['contract', 'verify', 'triage', 'state', 'stage-result', 'control-plane', 'memory', 'launch', 'decompose', 'stacked', 'route', 'github-triage', 'github-decompose', 'reconcile-labels', 'github-labels'].includes(command)) {
+  console.error('Usage: lighthouse-sdlc <contract|verify|triage|state|stage-result|control-plane|memory|launch|decompose|stacked|route|github-triage|github-decompose|reconcile-labels|github-labels>');
   process.exit(2);
 }
 if (command === 'contract') {
   console.log(await readFile(contractPath, 'utf8'));
 } else if (command === 'triage') {
   await runTriage(process.argv.slice(3));
+} else if (command === 'state') {
+  await runState(process.argv.slice(3));
+} else if (command === 'control-plane') {
+  await runControlPlane(process.argv.slice(3));
+} else if (command === 'stage-result') {
+  await runStageResult(process.argv.slice(3));
+} else if (command === 'memory') {
+  await runMemory(process.argv.slice(3));
+} else if (command === 'launch') {
+  await runLaunch(process.argv.slice(3));
+} else if (command === 'decompose') {
+  await runDecompose(process.argv.slice(3));
+} else if (command === 'route') {
+  await runRoute(process.argv.slice(3));
+} else if (command === 'stacked') {
+  await runStacked(process.argv.slice(3));
+} else if (command === 'github-triage') {
+  await runGithubTriage(process.argv.slice(3));
+} else if (command === 'github-decompose') {
+  await runGithubDecompose(process.argv.slice(3));
+} else if (command === 'reconcile-labels') {
+  await runReconcileLabels(process.argv.slice(3));
+} else if (command === 'github-labels') {
+  await runGithubLabels(process.argv.slice(3));
 } else {
   const problems = await verifyContract();
   if (problems.length) {
@@ -123,4 +359,4 @@ if (command === 'contract') {
   console.log('Lighthouse SDLC package contract is valid.');
 }
 
-export { contractPath, runTriage, verifyContract };
+export { contractPath, runTriage, verifyContract, runState, runStageResult, runControlPlane, runMemory, runLaunch, runDecompose, runRoute, runStacked, runGithubTriage, runGithubDecompose, runReconcileLabels, runGithubLabels };

package/src/stacked.mjs

@@ -0,0 +1,50 @@
+function isRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+function slug(value) {
+  return String(value ?? '').toLowerCase().replace(/[^a-z0-9]+/gu, '-').replace(/^-|-$/gu, '');
+}
+
+export function buildStackedPlan(input) {
+  const errors = [];
+  if (!isRecord(input) || !isRecord(input.parent) || !Array.isArray(input.slices)) return { schemaVersion: 1, status: 'invalid', valid: false, canApply: false, errors: [issue('stacked.invalid', 'stacked input needs parent and slices')] };
+  const parentRef = input.parent.number ?? input.parent.id;
+  if (parentRef === undefined || parentRef === null || String(parentRef).trim() === '') errors.push(issue('stacked.parent', 'parent needs an id or number', 'parent'));
+  const seenBranches = new Set();
+  const slices = input.slices.map((slice, index) => {
+    if (!isRecord(slice) || typeof slice.id !== 'string' || !slice.id.trim() || typeof slice.title !== 'string' || !slice.title.trim()) { errors.push(issue('stacked.slice', `slice ${index} needs id and title`, `slices[${index}]`)); return null; }
+    const branchPrefix = String(parentRef).match(/[1-9]\d*/u)?.[0];
+    const branch = slice.branch ?? (branchPrefix ? `feat/${branchPrefix}-${slug(slice.title)}` : null);
+    if (!branch) { errors.push(issue('stacked.branch', `slice ${slice.id} needs an explicit branch when the parent has no numeric issue id`, `slices[${index}].branch`)); return null; }
+    if (seenBranches.has(branch)) errors.push(issue('stacked.branch-duplicate', `branch ${branch} appears more than once`, `slices[${index}].branch`));
+    seenBranches.add(branch);
+    return { id: slice.id, title: slice.title, branch, base: slice.base ?? null, dependencies: [...(slice.dependencies ?? [])].sort(), acceptance: [...(slice.acceptance ?? [])] };
+  }).filter(Boolean);
+  const byId = new Map(slices.map((slice) => [slice.id, slice]));
+  const order = [];
+  const visiting = new Set();
+  const visited = new Set();
+  function visit(id) {
+    if (visited.has(id)) return;
+    if (visiting.has(id)) { errors.push(issue('stacked.cycle', `dependency cycle includes ${id}`, 'slices')); return; }
+    visiting.add(id);
+    for (const dependency of byId.get(id)?.dependencies ?? []) {
+      if (!byId.has(dependency)) errors.push(issue('stacked.unknown-dependency', `slice ${id} depends on unknown slice ${dependency}`, 'slices'));
+      else visit(dependency);
+    }
+    visiting.delete(id);
+    visited.add(id);
+    order.push(id);
+  }
+  for (const slice of slices) visit(slice.id);
+  const operations = order.map((id, index) => {
+    const slice = byId.get(id);
+    return { type: 'open-pull-request', sliceId: id, branch: slice.branch, base: slice.base ?? (index === 0 ? input.parent.base ?? 'main' : slices.find((candidate) => candidate.id === order[index - 1])?.branch) };
+  });
+  return { schemaVersion: 1, status: errors.length ? 'invalid' : 'ready', valid: errors.length === 0, canApply: errors.length === 0, parent: input.parent, slices, order, operations, errors };
+}

package/src/triage.mjs

@@ -54,7 +54,7 @@ function addIssue(issues, code, message, field) {
   issues.push(issue(code, message, field));
 }
 
-function validateConfiguration(configuration) {
+export function validateConfiguration(configuration) {
   const errors = [];
   const labels = Array.isArray(configuration?.labels) ? configuration.labels : null;
   const byName = new Map();
@@ -281,4 +281,4 @@ export function applyTriageLabels(report) {
   return [...report.labels.proposed];
 }
 
-export { DIMENSIONS, ROUTES, validateConfiguration };
+export { DIMENSIONS, ROUTES };

package/src/workflow.mjs

@@ -0,0 +1,66 @@
+export const WORKFLOW_STATES = Object.freeze(['ready', 'running', 'waiting-human', 'blocked', 'succeeded', 'failed', 'cancelled']);
+
+const transitions = Object.freeze({
+  ready: ['running', 'cancelled'],
+  running: ['waiting-human', 'blocked', 'succeeded', 'failed', 'cancelled'],
+  'waiting-human': ['running', 'blocked', 'cancelled'],
+  blocked: ['ready', 'cancelled'],
+  failed: ['ready', 'cancelled'],
+  succeeded: [],
+  cancelled: [],
+});
+const stateSet = new Set(WORKFLOW_STATES);
+
+function isRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function problem(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+export function allowedTransitions(state) {
+  return [...(transitions[state] ?? [])];
+}
+
+export function validateStateEvent(event, previousState = null) {
+  const errors = [];
+  if (!isRecord(event)) return [problem('state-event.invalid', 'state event must be an object')];
+  if (event.schemaVersion !== 1) errors.push(problem('state-event.schema-version', 'schemaVersion must be 1', 'schemaVersion'));
+  for (const field of ['eventId', 'runId', 'route', 'stage', 'actor', 'timestamp', 'reason']) if (typeof event[field] !== 'string' || !event[field].trim()) errors.push(problem(`state-event.${field}`, `${field} must be a non-empty string`, field));
+  if (!stateSet.has(event.to)) errors.push(problem('state-event.to', `to must be one of ${WORKFLOW_STATES.join(', ')}`, 'to'));
+  if (event.from !== null && !stateSet.has(event.from)) errors.push(problem('state-event.from', `from must be one of ${WORKFLOW_STATES.join(', ')} or null`, 'from'));
+  if (previousState !== null && event.from !== previousState) errors.push(problem('state-event.previous', `event from ${event.from} does not match current state ${previousState}`, 'from'));
+  if (event.from !== null && !allowedTransitions(event.from).includes(event.to)) errors.push(problem('state-event.transition', `transition ${event.from}->${event.to} is not allowed`, 'to'));
+  if (event.from === null && event.to !== 'ready') errors.push(problem('state-event.initial', 'the first event must enter ready', 'to'));
+  if (!Array.isArray(event.evidence)) errors.push(problem('state-event.evidence', 'evidence must be an array', 'evidence'));
+  return errors;
+}
+
+export function replayWorkflow(events) {
+  if (!Array.isArray(events)) return { valid: false, errors: [problem('state.events', 'events must be an array')], runs: {} };
+  const runs = new Map();
+  const errors = [];
+  const eventIds = new Set();
+  for (const [index, event] of events.entries()) {
+    const previous = runs.get(event?.runId)?.state ?? null;
+    const eventErrors = validateStateEvent(event, previous);
+    if (eventErrors.length) {
+      errors.push(...eventErrors.map((error) => ({ ...error, index })));
+      continue;
+    }
+    const current = runs.get(event.runId);
+    if (eventIds.has(event.eventId)) {
+      errors.push(problem('state-event.duplicate', `event ${event.eventId} appears more than once`, `events[${index}]`));
+      continue;
+    }
+    eventIds.add(event.eventId);
+    runs.set(event.runId, { state: event.to, route: event.route, stage: event.stage, events: [...(current?.events ?? []), event] });
+  }
+  const result = Object.fromEntries([...runs.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([runId, run]) => [runId, { ...run, events: run.events.map((event) => ({ ...event })) }]));
+  return { valid: errors.length === 0, errors, runs: result };
+}
+
+export function createStateEvent({ eventId, runId, route, stage, from, to, actor, timestamp, reason, evidence = [], parentRunId }) {
+  return { schemaVersion: 1, eventId, runId, ...(parentRunId ? { parentRunId } : {}), route, stage, from, to, actor, timestamp, reason, evidence };
+}

package/stages.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "./schemas/stages.schema.json",
+  "version": 1,
+  "stages": [
+    { "id": "triage", "gate": "triaged", "input": "work-item", "output": "triage-report", "mutation": "explicit" },
+    { "id": "refine", "gate": "ready", "input": "triage-report", "output": "ready-change", "mutation": "none" },
+    { "id": "propose", "gate": "planned", "input": "ready-change", "output": "change-artifacts", "mutation": "explicit" },
+    { "id": "implement", "gate": "done", "input": "change-artifacts", "output": "implementation-evidence", "mutation": "workspace" },
+    { "id": "integrate", "gate": "done", "input": "implementation-evidence", "output": "integration-evidence", "mutation": "explicit" },
+    { "id": "review", "gate": null, "input": "integration-evidence", "output": "review-report", "mutation": "explicit" }
+  ]
+}