@juangcarmona/lighthouse-sdlc 0.3.0 → 0.4.0

package/src/github.mjs

@@ -0,0 +1,67 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+export async function ghJson(args, { command = 'gh', cwd } = {}) {
+  const { stdout } = await execFileAsync(command, ['api', ...args], { cwd, maxBuffer: 10 * 1024 * 1024 });
+  return JSON.parse(stdout);
+}
+
+export async function readGithubIssue(repo, number, options = {}) {
+  if (!repo || !number) throw new Error('repo and issue number are required');
+  const issueRecord = await ghJson([`repos/${repo}/issues/${number}`], options);
+  return {
+    schemaVersion: 1,
+    workItem: { id: `GH-${issueRecord.number}`, title: issueRecord.title, type: issueRecord.pull_request ? 'pull-request' : 'issue', url: issueRecord.html_url, state: issueRecord.state },
+    currentLabels: (issueRecord.labels ?? []).map((label) => typeof label === 'string' ? label : label.name).filter(Boolean).sort(),
+    links: { url: issueRecord.html_url, parent: issueRecord.parent ?? null, subIssues: issueRecord.sub_issues ?? [] },
+    dependencies: issueRecord.dependencies ?? [],
+    source: { provider: 'github', repository: repo, number: issueRecord.number },
+  };
+}
+
+export async function readGithubLabels(repo, options = {}) {
+  if (!repo) throw new Error('repo is required');
+  const labels = await ghJson([`repos/${repo}/labels?per_page=100`], options);
+  return Array.isArray(labels) ? labels.map((label) => ({ name: label.name, color: label.color, description: label.description ?? null })).sort((left, right) => left.name.localeCompare(right.name)) : [];
+}
+
+export async function createGithubLabel(repo, label, options = {}) {
+  if (!label?.name) throw new Error('label name is required');
+  if (options.dryRun !== false) return { applied: false, label };
+  const created = await ghJson(['--method', 'POST', `repos/${repo}/labels`, '-f', `name=${label.name}`, '-f', `color=${String(label.color ?? '8B949E').replace(/^#/u, '')}`, '-f', `description=${label.description ?? ''}`], options);
+  return { applied: true, label: { name: created.name, color: created.color, description: created.description ?? null } };
+}
+
+export function mergeGithubTriage(issueRecord, assessment, configuration) {
+  if (!issueRecord || typeof issueRecord !== 'object') return { errors: [issue('github.issue', 'issue metadata is required')] };
+  if (!assessment || typeof assessment !== 'object') return { errors: [issue('github.assessment', 'structured assessment is required')] };
+  return { ...issueRecord, assessment, configuration };
+}
+
+export async function replaceGithubLabels(repo, number, labels, options = {}) {
+  if (!Array.isArray(labels)) throw new Error('labels must be an array');
+  if (options.dryRun !== false) return { applied: false, labels: [...labels] };
+  const { stdout } = await execFileAsync(options.command ?? 'gh', ['api', '--method', 'PUT', `repos/${repo}/issues/${number}/labels`, ...labels.flatMap((label) => ['-f', `labels[]=${label}`])], { cwd: options.cwd, maxBuffer: 10 * 1024 * 1024 });
+  return { applied: true, labels: JSON.parse(stdout).map((label) => label.name).sort() };
+}
+
+export async function createGithubSubIssues(repo, parentNumber, plan, options = {}) {
+  if (!plan?.canApply) throw new Error('Decomposition plan is not ready to apply. Resolve its errors first.');
+  const operations = plan.order.map((id) => {
+    const slice = plan.slices.find((candidate) => candidate.id === id);
+    return { type: 'create-child-issue', parent: Number(parentNumber), sliceId: id, title: slice.title, body: `Parent issue: #${parentNumber}\n\nAcceptance evidence:\n${slice.acceptance.map((item) => `- ${item}`).join('\n')}` };
+  });
+  if (options.dryRun !== false) return { applied: false, operations };
+  const created = [];
+  for (const operation of operations) {
+    const issueRecord = await ghJson(['--method', 'POST', `repos/${repo}/issues`, '-f', `title=${operation.title}`, '-f', `body=${operation.body}`], options);
+    created.push({ ...operation, number: issueRecord.number, url: issueRecord.html_url });
+  }
+  return { applied: true, operations: created };
+}

package/src/memory.mjs

@@ -0,0 +1,22 @@
+export const MEMORY_SCOPES = Object.freeze(['run', 'project', 'shared']);
+const scopeSet = new Set(MEMORY_SCOPES);
+
+function isRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+export function validateMemoryRecord(record, policy = {}) {
+  const errors = [];
+  if (!isRecord(record)) return [issue('memory.invalid', 'memory record must be an object')];
+  for (const field of ['id', 'owner', 'source', 'confidence', 'retention', 'sensitivity']) if (typeof record[field] !== 'string' || !record[field].trim()) errors.push(issue(`memory.${field}`, `${field} must be a non-empty string`, field));
+  if (!scopeSet.has(record.scope)) errors.push(issue('memory.scope', `scope must be one of ${MEMORY_SCOPES.join(', ')}`, 'scope'));
+  if (record.scope === 'run' && (typeof record.runId !== 'string' || !record.runId.trim())) errors.push(issue('memory.run-id', 'run-scoped memory needs runId', 'runId'));
+  if (record.scope === 'project' && (typeof record.projectId !== 'string' || !record.projectId.trim())) errors.push(issue('memory.project-id', 'project-scoped memory needs projectId', 'projectId'));
+  if (record.scope === 'shared' && policy.shared !== true) errors.push(issue('memory.shared-disabled', 'shared memory is not enabled by the control-plane policy', 'scope'));
+  if (!isRecord(record.value)) errors.push(issue('memory.value', 'value must be an object', 'value'));
+  return errors;
+}

package/src/reconcile.mjs

@@ -0,0 +1,165 @@
+import { createHash } from 'node:crypto';
+import { validateConfiguration, suggestedLabelColors } from './triage.mjs';
+
+const CAPABILITY_ID = 'labels';
+const SUPPORTED_PROVIDER = 'github';
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+function isRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function stable(value) {
+  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
+  if (!isRecord(value)) return JSON.stringify(value);
+  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stable(value[key])}`).join(',')}}`;
+}
+
+function digest(value) {
+  return createHash('sha256').update(stable(value)).digest('hex');
+}
+
+function color(value) {
+  return typeof value === 'string' ? value.replace(/^#/u, '').toUpperCase() : null;
+}
+
+function comparableName(value) {
+  return String(value).toLowerCase().replace(/[^a-z0-9]/gu, '');
+}
+
+function normalizeExisting(labels) {
+  const errors = [];
+  if (!Array.isArray(labels)) return { labels: [], errors: [issue('labels.existing', 'existing labels must be an array', 'existing')] };
+  const seen = new Set();
+  const normalized = [];
+  for (const [index, item] of labels.entries()) {
+    const value = typeof item === 'string' ? { name: item } : item;
+    if (!isRecord(value) || typeof value.name !== 'string' || !value.name.trim()) {
+      errors.push(issue('labels.existing-item', `existing label ${index} needs a name`, `existing[${index}]`));
+      continue;
+    }
+    const name = value.name.trim();
+    if (seen.has(name)) errors.push(issue('labels.existing-duplicate', `existing label ${name} appears more than once`, 'existing'));
+    seen.add(name);
+    normalized.push({ name, color: color(value.color), description: value.description ?? null });
+  }
+  normalized.sort((left, right) => left.name.localeCompare(right.name));
+  return { labels: normalized, errors };
+}
+
+function capabilityConfig(capability) {
+  return capability?.configuration && isRecord(capability.configuration) ? capability.configuration : capability;
+}
+
+export function validateCapabilityDeclaration(declaration) {
+  const errors = [];
+  if (!isRecord(declaration)) return [issue('capabilities.invalid', 'capability declaration must be an object')];
+  if (declaration.schemaVersion !== 1) errors.push(issue('capabilities.schema-version', 'schemaVersion must be 1', 'schemaVersion'));
+  if (!Array.isArray(declaration.capabilities) || declaration.capabilities.length === 0) {
+    errors.push(issue('capabilities.list', 'capabilities must be a non-empty array', 'capabilities'));
+    return errors;
+  }
+  const selected = declaration.capabilities.filter((capability) => capability?.id === CAPABILITY_ID);
+  if (selected.length !== 1) errors.push(issue('capabilities.labels-selection', 'exactly one labels capability must be selected', 'capabilities'));
+  for (const [index, capability] of declaration.capabilities.entries()) {
+    if (!isRecord(capability) || typeof capability.id !== 'string' || !capability.id.trim()) {
+      errors.push(issue('capability.invalid', `capability ${index} needs an id`, `capabilities[${index}]`));
+      continue;
+    }
+    if (typeof capability.provider !== 'string' || !capability.provider.trim()) errors.push(issue('capability.provider', `capability ${capability.id} needs a provider`, `capabilities[${index}].provider`));
+    if (typeof capability.version !== 'string' || !capability.version.trim()) errors.push(issue('capability.version', `capability ${capability.id} needs a version`, `capabilities[${index}].version`));
+  }
+  const labels = selected[0];
+  if (labels) errors.push(...validateConfiguration(capabilityConfig(labels)).errors);
+  return errors;
+}
+
+export function buildLabelReconciliationPlan(declaration, existingLabels, previousRecord = null) {
+  const errors = validateCapabilityDeclaration(declaration);
+  const capability = declaration?.capabilities?.find((item) => item?.id === CAPABILITY_ID);
+  const existing = normalizeExisting(existingLabels);
+  errors.push(...existing.errors);
+  if (capability && capability.provider !== SUPPORTED_PROVIDER) errors.push(issue('capability.provider-unsupported', `labels provider ${capability.provider} is not supported by this adapter`, 'capabilities'));
+  const configuration = capabilityConfig(capability);
+  const desired = (Array.isArray(configuration?.labels) ? configuration.labels : []).filter((label) => isRecord(label) && typeof label.name === 'string' && label.name.trim()).map((label) => ({
+    name: label.name.trim(),
+    color: color(label.color ?? suggestedLabelColors[label.name]),
+    description: label.description ?? null,
+    role: label.role,
+    dimension: label.dimension,
+    value: label.value,
+  })).sort((left, right) => left.name.localeCompare(right.name));
+  const existingByName = new Map(existing.labels.map((label) => [label.name, label]));
+  const existingByComparableName = new Map();
+  for (const label of existing.labels) {
+    const key = comparableName(label.name);
+    existingByComparableName.set(key, [...(existingByComparableName.get(key) ?? []), label]);
+  }
+  const desiredNames = new Set();
+  const changes = [];
+  const operations = [];
+  for (const label of desired) {
+    if (desiredNames.has(label.name)) {
+      errors.push(issue('labels.desired-duplicate', `desired label ${label.name} appears more than once`, 'capabilities'));
+      continue;
+    }
+    desiredNames.add(label.name);
+    const current = existingByName.get(label.name);
+    if (!current) {
+      const equivalents = existingByComparableName.get(comparableName(label.name)) ?? [];
+      if (equivalents.length) {
+        changes.push({ name: label.name, status: 'conflict', desired: label, candidates: equivalents });
+        continue;
+      }
+      changes.push({ name: label.name, status: 'missing', desired: label });
+      operations.push({ type: 'create-label', name: label.name, color: label.color ?? '8B949E', description: label.description ?? '' });
+      continue;
+    }
+    const customized = (label.color !== null && current.color !== label.color) || (label.description !== null && current.description !== label.description);
+    changes.push({ name: label.name, status: customized ? 'customized' : 'unchanged', existing: current, desired: label });
+  }
+  for (const label of existing.labels) if (!desiredNames.has(label.name)) changes.push({ name: label.name, status: 'preserved', existing: label });
+  changes.sort((left, right) => left.name.localeCompare(right.name));
+  const target = [...existing.labels, ...operations.map((operation) => ({ name: operation.name, color: operation.color, description: operation.description }))].sort((left, right) => left.name.localeCompare(right.name));
+  const observedHash = digest(existing.labels);
+  const targetHash = digest(target);
+  const drift = previousRecord && previousRecord.targetHash !== observedHash
+    ? { status: 'drift', expectedHash: previousRecord.targetHash, observedHash }
+    : { status: 'none', expectedHash: previousRecord?.targetHash ?? null, observedHash };
+  const conflicts = changes.filter((change) => change.status === 'conflict');
+  const status = errors.length ? 'invalid' : conflicts.length ? 'blocked' : 'ready';
+  return {
+    schemaVersion: 1,
+    status,
+    valid: errors.length === 0,
+    canApply: status === 'ready',
+    capability: capability ? { id: capability.id, provider: capability.provider, version: capability.version } : null,
+    desiredHash: digest(desired),
+    observedHash,
+    targetHash,
+    drift,
+    changes,
+    operations,
+    errors,
+    record: {
+      schemaVersion: 1,
+      capability: capability ? { id: capability.id, provider: capability.provider, version: capability.version } : null,
+      desiredHash: digest(desired),
+      observedHash: targetHash,
+      targetHash,
+      operations: operations.map(({ type, name, color: labelColor, description }) => ({ type, name, color: labelColor, description })),
+      verified: false,
+    },
+  };
+}
+
+export function applyLabelReconciliationPlan(plan, existingLabels) {
+  if (!plan?.canApply) throw new Error('Label reconciliation is not ready to apply. Resolve its errors first.');
+  const existing = normalizeExisting(existingLabels);
+  if (existing.errors.length) throw new Error(existing.errors.map((error) => error.message).join('\n'));
+  const names = new Set(existing.labels.map((label) => label.name));
+  return [...existing.labels, ...plan.operations.filter((operation) => !names.has(operation.name)).map((operation) => ({ name: operation.name, color: operation.color, description: operation.description }))].sort((left, right) => left.name.localeCompare(right.name));
+}

package/src/routes.mjs

@@ -0,0 +1,22 @@
+import { GATES, STAGES } from './contracts.mjs';
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+export function validateRouteDescriptor(route, contract = {}) {
+  const errors = [];
+  if (!route || typeof route !== 'object') return [issue('route.invalid', 'route must be an object')];
+  if (typeof route.id !== 'string' || !route.id.trim()) errors.push(issue('route.id', 'route id must be a non-empty string', 'id'));
+  if (!Array.isArray(route.stages) || route.stages.length === 0 || route.stages.some((stage) => !STAGES.includes(stage))) errors.push(issue('route.stages', `stages must use ${STAGES.join(', ')}`, 'stages'));
+  if (!Array.isArray(route.humanGates) || route.humanGates.some((gate) => !GATES.includes(gate))) errors.push(issue('route.gates', `humanGates must use ${GATES.join(', ')}`, 'humanGates'));
+  if (contract.stages && route.stages?.some((stage, index) => stage !== contract.stages[index])) errors.push(issue('route.order', 'route stages must preserve the package stage order', 'stages'));
+  return errors;
+}
+
+export function buildRoutePlan(route, { available = [], decisions = {} } = {}) {
+  const errors = validateRouteDescriptor(route);
+  const prerequisites = (route.requires ?? []).map((requirement) => ({ id: requirement, status: available.includes(requirement) ? 'passed' : 'pending-review' }));
+  const status = errors.length ? 'invalid' : prerequisites.some((item) => item.status !== 'passed') ? 'blocked' : 'ready';
+  return { schemaVersion: 1, status, valid: errors.length === 0, canRun: status === 'ready', route: route.id, stages: [...(route.stages ?? [])], humanGates: [...(route.humanGates ?? [])], requires: prerequisites, decisions, errors };
+}

package/src/sdlc.mjs

@@ -1,9 +1,18 @@
 #!/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';
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const contractPath = resolve(packageRoot, 'contract.json');
@@ -29,10 +38,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]) {
     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', '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 +54,12 @@ 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}`); }
+  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 +119,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 +354,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 };