@juangcarmona/lighthouse-sdlc 0.17.0 → 0.18.0

package/src/product-change.mjs

@@ -37,27 +37,33 @@ export function validateProductRequest(value) {
 }
 
 export function validateProductChangeOutput(value) {
-  const fields = ['schemaVersion', 'outcome', 'entry', 'affectedAreas', 'decisions', ...(['changeName', 'changeId', 'files', 'question', 'proposalDigest', 'baselineDigest', 'providerValidation'].filter(key => Object.hasOwn(value ?? {}, key)))];
+  const fields = ['schemaVersion', 'outcome', 'entry', 'affectedAreas', 'decisions', ...(['changeName', 'changeId', 'files', 'question', 'blocker', 'recovery', 'proposalDigest', 'baselineDigest', 'providerValidation'].filter(key => Object.hasOwn(value ?? {}, key)))];
   if (!exact(value, fields)) return ['result.output.productChange has unsupported or missing fields'];
   const errors = [];
   if (value.schemaVersion !== 1 || !['aligned', 'candidate', 'blocked'].includes(value.outcome) || !['idea', 'parent-handoff', 'feedback'].includes(value.entry)) errors.push('result.output.productChange identity is unsupported');
   if (!Array.isArray(value.affectedAreas) || value.affectedAreas.length > 32 || value.affectedAreas.some(item => typeof item !== 'string' || !item.trim() || item.length > 256)) errors.push('result.output.productChange affectedAreas is invalid');
   if (!Array.isArray(value.decisions) || value.decisions.length > 32 || value.decisions.some(item => typeof item !== 'string' || !item.trim() || item.length > 1000)) errors.push('result.output.productChange decisions is invalid');
-  if (value.question !== undefined && (typeof value.question !== 'string' || value.question.length > 4000)) errors.push('result.output.productChange question exceeds its bound');
+  if (value.question !== undefined && (typeof value.question !== 'string' || !value.question.trim() || value.question.length > 4000 || /<!--\s*lighthouse-/i.test(value.question))) errors.push('result.output.productChange question is invalid');
+  if (value.blocker !== undefined && (typeof value.blocker !== 'string' || !value.blocker.trim() || value.blocker.length > 4000 || /<!--\s*lighthouse-/i.test(value.blocker))) errors.push('result.output.productChange blocker is invalid');
+  if (value.recovery !== undefined && (typeof value.recovery !== 'string' || !value.recovery.trim() || value.recovery.length > 4000 || /<!--\s*lighthouse-/i.test(value.recovery))) errors.push('result.output.productChange recovery is invalid');
   if (value.changeName !== undefined && !namePattern.test(value.changeName)) errors.push('result.output.productChange changeName is invalid');
   if (value.changeId !== undefined && !/^CHG-[A-Z0-9-]+$/.test(value.changeId)) errors.push('result.output.productChange changeId is invalid');
   if (value.proposalDigest !== undefined && !hashPattern.test(value.proposalDigest)) errors.push('result.output.productChange proposalDigest is invalid');
   if (value.baselineDigest !== undefined && !hashPattern.test(value.baselineDigest)) errors.push('result.output.productChange baselineDigest is invalid');
   if (value.outcome === 'candidate') {
-    if (!value.changeName || !value.changeId || !value.proposalDigest || !value.baselineDigest || !Array.isArray(value.files)) errors.push('candidate Product Change output needs its change identity, proposal and baseline digests, and files');
+    if (!value.changeName || !value.changeId || !value.baselineDigest || !Array.isArray(value.files)) errors.push('candidate Product Change output needs its change identity, baseline digest, and files');
     else try {
       const checked = validateProductChangeFiles(value.files, { changeName: value.changeName });
-      if (checked.changeId !== value.changeId || checked.digest !== value.proposalDigest) errors.push('candidate Product Change identity or digest does not match its files');
+      if (checked.changeId !== value.changeId || value.proposalDigest !== undefined && checked.digest !== value.proposalDigest) errors.push('candidate Product Change identity or digest does not match its files');
     } catch (error) { errors.push(error.message); }
-    if (!exact(value.providerValidation, ['status', 'diagnosticCount']) || value.providerValidation.status !== 'passed' || !Number.isSafeInteger(value.providerValidation.diagnosticCount) || value.providerValidation.diagnosticCount < 0) errors.push('candidate Product Change needs successful provider overlay validation');
+    if (!exact(value.providerValidation, ['status', 'diagnosticCount']) || !['pending', 'passed'].includes(value.providerValidation.status) || !Number.isSafeInteger(value.providerValidation.diagnosticCount) || value.providerValidation.diagnosticCount < 0 || value.providerValidation.status === 'pending' && value.providerValidation.diagnosticCount !== 0 || value.providerValidation.status === 'passed' && !value.proposalDigest) errors.push('candidate Product Change needs pending host validation or a bound successful provider validation');
   }
   if (value.outcome === 'aligned' && (value.files !== undefined || value.changeName !== undefined || value.changeId !== undefined)) errors.push('aligned Product Change output cannot include a delta');
-  if (value.outcome === 'blocked' && (!value.question?.trim() || value.files !== undefined)) errors.push('blocked Product Change output needs one decision question and no candidate files');
+  const hasQuestion = typeof value.question === 'string' && !!value.question.trim();
+  const hasBlocker = typeof value.blocker === 'string' && !!value.blocker.trim();
+  const hasRecovery = typeof value.recovery === 'string' && !!value.recovery.trim();
+  if (value.outcome === 'blocked' && ((!hasQuestion && !hasBlocker) || (value.question !== undefined && (value.blocker !== undefined || value.recovery !== undefined)) || (hasBlocker && !hasRecovery) || value.files !== undefined)) errors.push('blocked Product Change output needs either one decision question or one technical blocker with recovery and no candidate files');
+  if (value.outcome !== 'blocked' && (value.blocker !== undefined || value.recovery !== undefined)) errors.push('only a blocked Product Change can include a technical blocker or recovery');
   if (value.files !== undefined && value.outcome !== 'candidate') errors.push('only a candidate Product Change can include files');
   return errors;
 }
@@ -106,7 +112,7 @@ export function validateProductIdentity(value) {
 
 export function validateProductCheckpoint(value) {
   const fields = ['schemaVersion', 'kind', 'identity', 'requestDigest', 'changeName', 'changeId', 'proposalDigest', 'baselineDigest', 'state', 'effectIds'];
-  const optional = ['pendingQuestion'];
+  const optional = ['pendingQuestion', 'parent'];
   if (!exact(value, [...fields, ...optional.filter(key => Object.hasOwn(value ?? {}, key))])) return ['Product Change checkpoint has unsupported or missing fields'];
   const errors = [...validateProductIdentity(value.identity)];
   if (value.schemaVersion !== 1 || value.kind !== 'checkpoint') errors.push('Product Change checkpoint identity is unsupported');
@@ -114,6 +120,22 @@ export function validateProductCheckpoint(value) {
   for (const field of ['requestDigest', 'proposalDigest', 'baselineDigest']) if (!hashPattern.test(value[field] ?? '')) errors.push(`${field} must be SHA-256`);
   if (!['preparing', 'waiting-product-decision', 'approved', 'applying', 'applied', 'blocked'].includes(value.state)) errors.push('Product Change checkpoint state is unsupported');
   if (!Array.isArray(value.effectIds) || value.effectIds.length > 32 || value.effectIds.some(item => typeof item !== 'string' || !item.trim() || item.length > 256) || new Set(value.effectIds).size !== value.effectIds.length) errors.push('Product Change checkpoint effectIds are invalid');
+  if (value.parent !== undefined) {
+    const parent = value.parent;
+    if (!exact(parent, ['issue', 'stage', 'predecessor', 'gap', 'sourceRevision', 'baseRevision', 'taskDigest', 'autoImplement', ...(['feedback', 'pullRequest', 'review'].filter(key => Object.hasOwn(parent ?? {}, key)))]) || parent.issue !== value.identity?.issue || !['triage', 'refine', 'propose', 'implement'].includes(parent.stage) || !exact(parent.predecessor, ['runId', 'attempt']) || !/^[1-9][0-9]*$/.test(parent.predecessor.runId ?? '') || !Number.isSafeInteger(parent.predecessor.attempt) || parent.predecessor.attempt < 1 || !exact(parent.gap, ['summary', 'scope']) || !['summary', 'scope'].every(key => typeof parent.gap[key] === 'string' && parent.gap[key].trim() && parent.gap[key].length <= 4000 && !/<!--\s*lighthouse-/i.test(parent.gap[key])) || !revisionPattern.test(parent.sourceRevision ?? '') || !revisionPattern.test(parent.baseRevision ?? '') || !hashPattern.test(parent.taskDigest ?? '') || typeof parent.autoImplement !== 'boolean') errors.push('Product Change parent checkpoint is invalid');
+  }
+  if (value.parent?.pullRequest !== undefined) {
+    const pr = value.parent.pullRequest;
+    if (!exact(pr, ['number', 'head', 'branch']) || !Number.isSafeInteger(pr.number) || pr.number < 1 || !revisionPattern.test(pr.head ?? '') || typeof pr.branch !== 'string' || !new RegExp(`^lighthouse/(?:implement|propose)-${value.identity?.issue}-[a-f0-9]{12}$`).test(pr.branch)) errors.push('Product Change parent PR evidence is invalid');
+  }
+  if (value.parent?.review !== undefined) {
+    const review = value.parent.review;
+    if (!exact(review, ['number', 'path', 'feedbackDigest', 'threadDigest']) || !Number.isSafeInteger(review.number) || review.number < 1 || review.number !== value.parent.pullRequest?.number || typeof review.path !== 'string' || !/^(?:issues\/comments|pulls\/comments|pulls\/[1-9][0-9]*\/reviews)\/[1-9][0-9]*$/.test(review.path) || !hashPattern.test(review.feedbackDigest ?? '') || !hashPattern.test(review.threadDigest ?? '')) errors.push('Product Change parent review evidence is invalid');
+  }
+  if (value.parent?.feedback !== undefined) {
+    const feedback = value.parent.feedback;
+    if (!exact(feedback, ['runId', 'attempt', 'taskDigest', 'replyTo', 'commentId']) || !/^[1-9][0-9]*$/.test(feedback.runId ?? '') || !Number.isSafeInteger(feedback.attempt) || feedback.attempt < 1 || !hashPattern.test(feedback.taskDigest ?? '') || !hashPattern.test(feedback.replyTo ?? '') || !Number.isSafeInteger(feedback.commentId) || feedback.commentId < 1) errors.push('Product Change parent answer evidence is invalid');
+  }
   if (value.pendingQuestion !== undefined && (typeof value.pendingQuestion !== 'string' || value.pendingQuestion.length > 4000)) errors.push('Product Change checkpoint pendingQuestion exceeds its bound');
   return errors;
 }
@@ -183,14 +205,17 @@ export async function prepareProductChange(root, changeName, files, bridge) {
     openspec(temp, ['new', 'change', changeName, '--schema', 'product-change', '--json']);
     const rootPath = `openspec/changes/${changeName}`;
     if (!files) {
+      const schemaPin = await readFile(join(temp, rootPath, '.openspec.yaml'), 'utf8');
+      if ((schemaPin.match(/^skip_specs:\s*true\s*$/gm) ?? []).length !== 1) throw Error('OpenSpec scaffold must declare skip_specs exactly once');
       const instructions = {};
       for (const artifact of ['intent', 'delta']) {
         const value = JSON.parse(openspec(temp, ['instructions', artifact, '--change', changeName, '--json']));
         instructions[artifact] = { outputPath: value.outputPath, instruction: value.instruction, template: value.template };
       }
-      return { provider: '@fission-ai/openspec@1.15.0', schema: 'product-change', root: rootPath, changeName, instructions };
+      return { provider: '@fission-ai/openspec@1.15.0', schema: 'product-change', root: rootPath, changeName, schemaPin, instructions };
     }
     const summary = validateProductChangeFiles(files, { changeName });
+    const schemaPin = files.find(file => file.path === `${rootPath}/.openspec.yaml`).content;
     for (const file of files) {
       const target = join(temp, file.path);
       await mkdir(dirname(target), { recursive: true });
@@ -203,8 +228,8 @@ export async function prepareProductChange(root, changeName, files, bridge) {
       const value = JSON.parse(openspec(temp, ['instructions', artifact, '--change', changeName, '--json']));
       instructions[artifact] = { outputPath: value.outputPath, instruction: value.instruction, template: value.template };
     }
-    if (bridge && validation) return { ...summary, provider: '@prodshape/integration-openspec', root: rootPath, openSpec: 'passed', diagnostics: validation.diagnostics, instructions, files };
-    return { ...summary, root: rootPath, openSpec: 'passed', provider: 'unavailable', instructions, files };
+    if (bridge && validation) return { ...summary, provider: '@prodshape/integration-openspec', root: rootPath, openSpec: 'passed', diagnostics: validation.diagnostics, schemaPin, instructions, files };
+    return { ...summary, root: rootPath, openSpec: 'passed', provider: 'unavailable', schemaPin, instructions, files };
   } finally { await rm(temp, { recursive: true, force: true }); }
 }
 
@@ -215,12 +240,45 @@ export async function loadProductBridge({ entry = process.env.PRODSHAPE_INTEGRAT
   return bridge;
 }
 
+export async function loadProductCore() {
+  const entry = require.resolve('@prodshape/core');
+  const metadata = JSON.parse(await readFile(join(dirname(dirname(entry)), 'package.json'), 'utf8'));
+  if (metadata.name !== '@prodshape/core' || metadata.version !== '0.25.0') throw Error('Pinned ProductShape core 0.25.0 is unavailable');
+  const core = await import(pathToFileURL(entry).href);
+  for (const name of ['openRepository', 'validateBaseline', 'inspectArtifact', 'analyzeImpact', 'emitCitation']) if (typeof core[name] !== 'function') throw Error(`Pinned ProductShape core does not provide ${name}`);
+  return { ...core, version: metadata.version };
+}
+
+export async function prepareProductEvidence(root, destination, core, { baselineDigest } = {}) {
+  if (baselineDigest && await productModelDigest(root) !== baselineDigest) throw Error('ProductShape baseline changed before evidence preparation');
+  const repository = await core.openRepository(resolve(root));
+  const baseline = await core.validateBaseline(repository);
+  const errors = baseline.diagnostics.filter(item => item.severity === 'error');
+  if (errors.length) throw Error(`ProductShape baseline has ${errors.length} blocking diagnostic(s); validate the adopter model before retrying`);
+  const nodes = baseline.graph.nodes;
+  if (!Array.isArray(nodes) || nodes.length > 512) throw Error('ProductShape evidence exceeds the artifact bound');
+  await mkdir(destination, { recursive: true });
+  const index = []; let bytes = 0;
+  for (const node of nodes) {
+    if (!/^[A-Z0-9][A-Z0-9-]{0,159}$/.test(node.id ?? '')) throw Error('ProductShape evidence has an unsafe artifact identity');
+    const report = { inspect: core.inspectArtifact(baseline.graph, node.id), impact: core.analyzeImpact(baseline.graph, node.id), citation: core.emitCitation({ id: node.id, digest: node.digest, form: 'payload' }) };
+    const content = JSON.stringify(report, null, 2) + '\n'; bytes += Buffer.byteLength(content);
+    if (Buffer.byteLength(content) > 512 * 1024 || bytes > 16 * 1024 * 1024) throw Error('ProductShape evidence exceeds the byte bound');
+    await writeFile(join(destination, `${node.id}.json`), content, { flag: 'wx' });
+    index.push({ id: node.id, type: node.type, title: node.title, report: `${node.id}.json` });
+  }
+  if (baselineDigest && await productModelDigest(root) !== baselineDigest) throw Error('ProductShape baseline changed during evidence preparation');
+  await writeFile(join(destination, 'index.json'), JSON.stringify({ schemaVersion: 1, source: '@prodshape/core', version: core.version, ...(baselineDigest ? { baselineDigest } : {}), artifacts: index }, null, 2) + '\n', { flag: 'wx' });
+  return { artifacts: index.length, bytes };
+}
+
 export function productReviewBinding(input) {
-  const fields = ['repository', 'issue', 'pullRequest', 'changeName', 'changeId', 'proposalDigest', 'baselineDigest', 'policyDigest', 'authorityDigest', 'head'];
+  const fields = ['repository', 'issue', 'pullRequest', 'changeName', 'changeId', 'proposalDigest', 'baselineDigest', 'policyDigest', 'authorityDigest', 'head', ...(Object.hasOwn(input ?? {}, 'parentDigest') ? ['parentDigest'] : [])];
   if (!exact(input, fields)) throw Error('Product review binding has unsupported or missing fields');
   if (typeof input.repository !== 'string' || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(input.repository) || !Number.isSafeInteger(input.issue) || input.issue < 1 || !Number.isSafeInteger(input.pullRequest) || input.pullRequest < 1) throw Error('Product review target is invalid');
   if (!namePattern.test(input.changeName) || !/^CHG-[A-Z0-9-]+$/.test(input.changeId)) throw Error('Product review change identity is invalid');
   for (const field of ['proposalDigest', 'baselineDigest', 'policyDigest', 'authorityDigest']) if (!hashPattern.test(input[field] ?? '')) throw Error(`Product review ${field} is invalid`);
+  if (input.parentDigest !== undefined && !hashPattern.test(input.parentDigest)) throw Error('Product review parent digest is invalid');
   if (!revisionPattern.test(input.head ?? '')) throw Error('Product review head must be a full commit SHA');
   const key = digest(JSON.stringify(input));
   return { ...input, key };
@@ -275,3 +333,26 @@ export function verifyProductChangePath(root, relativePath) {
     return absolute;
   });
 }
+
+export function checkProductResumePullRequest(pr, repository, resume) {
+  if (!resume || pr?.number !== resume.pullRequest || pr.state !== 'open' || pr.merged || !pr.draft || pr.user?.login !== 'github-actions[bot]' || pr.user?.type !== 'Bot' || pr.head?.repo?.full_name !== repository || pr.base?.repo?.full_name !== repository || pr.head.sha !== resume.head || pr.head.ref !== resume.branch) throw Error('Applied product PR changed before parent continuation');
+  const matches = [...(pr.body ?? '').matchAll(/<!-- lighthouse-product-change(?:-checkpoint|:checkpoint):(\{[^\n]*\}) -->/g)];
+  if (matches.length !== 1) throw Error('Applied product checkpoint is unavailable');
+  const checkpoint = JSON.parse(matches[0][1]);
+  if (validateProductCheckpoint(checkpoint).length || checkpoint.state !== 'applied' || checkpoint.identity.issue !== resume.issue || checkpoint.identity.head !== resume.head || JSON.stringify(checkpoint.parent) !== JSON.stringify(resume.parent) || !checkpoint.effectIds.includes(`apply:${resume.receiptIntent}:${resume.head}`)) throw Error('Applied product checkpoint changed before parent continuation');
+  return checkpoint;
+}
+
+function productDeliveryProof(pr, kind) {
+  const expression = new RegExp(`<!-- lighthouse-product-${kind}:(\\{[^\\n]*\\}) -->`, 'g');
+  const proofs = [...(pr?.body ?? '').matchAll(expression)];
+  const checkpoints = [...(pr?.body ?? '').matchAll(/<!-- lighthouse-product-change(?:-checkpoint|:checkpoint):(\{[^\n]*\}) -->/g)];
+  if (proofs.length !== 1 || checkpoints.length !== 1) return null;
+  let proof, checkpoint;
+  try { proof = JSON.parse(proofs[0][1]); checkpoint = JSON.parse(checkpoints[0][1]); } catch { return null; }
+  if (!exact(proof, ['schemaVersion', 'issue', 'runId', 'applyIntent', 'head']) || proof.schemaVersion !== 1 || !Number.isSafeInteger(proof.issue) || proof.issue < 1 || !hashPattern.test(proof.runId ?? '') || !hashPattern.test(proof.applyIntent ?? '') || proof.head !== pr.head?.sha || validateProductCheckpoint(checkpoint).length || checkpoint.state !== 'applied' || checkpoint.identity.issue !== proof.issue || !checkpoint.parent || !checkpoint.effectIds.includes(`apply:${proof.applyIntent}:${checkpoint.identity.head}`)) return null;
+  return proof;
+}
+
+export const productImplementationProof = pr => productDeliveryProof(pr, 'implementation');
+export const productProposalProof = pr => productDeliveryProof(pr, 'proposal');

package/src/proposal-review.mjs

@@ -1,5 +1,6 @@
 import { digest } from './host-contract.mjs';
 import { proposalRoot, validateProposalFiles } from './proposal.mjs';
+import { productImplementationProof, productProposalProof } from './product-change.mjs';
 
 export const feedbackKey = review => digest(`${review.number}:${review.kind}:${review.id}:${review.feedbackDigest}`);
 export const feedbackWorker = review => review && !review.approved ? 'apply-review' : undefined;
@@ -11,17 +12,21 @@ export function reviewTarget(event, eventName) {
 }
 
 export function checkProposal(pr, repo, expected) {
-  const match = pr.head?.ref?.match(/^lighthouse\/propose-([1-9][0-9]*)-([a-f0-9]{12})$/);
+  const match = pr.head?.ref?.match(/^lighthouse\/(?:propose|implement)-([1-9][0-9]*)-([a-f0-9]{12})$/);
   const marker = pr.body?.match(/<!-- lighthouse-proposal:([a-f0-9]{64}) -->/)?.[1];
-  if (!match || !marker?.startsWith(match[2]) || pr.user?.login !== 'github-actions[bot]' || pr.user.type !== 'Bot' || pr.state !== 'open' || pr.merged || pr.head.repo?.full_name !== repo || pr.base.repo?.full_name !== repo) throw Error('Not an open repository-owned Lighthouse proposal');
+  const productProof = productProposalProof(pr);
+  const standard = pr.head?.ref?.startsWith('lighthouse/propose-') && !/<!-- lighthouse-product-change(?:-checkpoint|:checkpoint):/.test(pr.body ?? '') && marker?.startsWith(match?.[2] ?? 'invalid');
+  if (!match || !(standard || productProof?.issue === Number(match[1])) || pr.user?.login !== 'github-actions[bot]' || pr.user.type !== 'Bot' || pr.state !== 'open' || pr.merged || pr.head.repo?.full_name !== repo || pr.base.repo?.full_name !== repo) throw Error('Not an open repository-owned Lighthouse proposal');
   if (expected && (pr.head.sha !== expected.head || pr.head.ref !== expected.branch || Number(match[1]) !== expected.issue || pr.base.ref !== expected.base)) throw Error('Proposal changed during review; no update published');
-  return { number: pr.number, issue: Number(match[1]), head: pr.head.sha, branch: pr.head.ref, base: pr.base.ref, url: pr.html_url };
+  return { number: pr.number, issue: Number(match[1]), head: pr.head.sha, branch: pr.head.ref, base: pr.base.ref, url: pr.html_url, ...(productProof ? { productProposal: true } : {}) };
 }
 
 export function checkImplementationPullRequest(pr, repo, expected) {
-  const match = pr.head?.ref?.match(/^lighthouse\/implement-([1-9][0-9]*)-([a-f0-9]{12})$/);
+  const match = pr.head?.ref?.match(/^lighthouse\/(?:implement|propose)-([1-9][0-9]*)-([a-f0-9]{12})$/);
   const marker = pr.body?.match(/<!-- lighthouse-implementation:([a-f0-9]{64}) -->/)?.[1];
-  if (!match || pr.body?.includes('<!-- lighthouse-product-change:') || !marker?.startsWith(match[2]) || pr.user?.login !== 'github-actions[bot]' || pr.user.type !== 'Bot' || pr.state !== 'open' || pr.merged || pr.head.repo?.full_name !== repo || pr.base.repo?.full_name !== repo) throw Error('Not an open repository-owned implementation PR');
+  const productProof = productImplementationProof(pr);
+  const standard = pr.head?.ref?.startsWith('lighthouse/implement-') && !pr.body?.includes('<!-- lighthouse-product-change:') && !/<!-- lighthouse-product-change(?:-checkpoint|:checkpoint):/.test(pr.body ?? '') && marker?.startsWith(match?.[2] ?? 'invalid');
+  if (!match || !(standard || productProof?.issue === Number(match[1])) || pr.user?.login !== 'github-actions[bot]' || pr.user.type !== 'Bot' || pr.state !== 'open' || pr.merged || pr.head.repo?.full_name !== repo || pr.base.repo?.full_name !== repo) throw Error('Not an open repository-owned implementation PR');
   if (expected && (pr.head.sha !== expected.head || pr.head.ref !== expected.branch || Number(match[1]) !== expected.issue || pr.base.ref !== expected.base)) throw Error('Implementation changed during review');
   return { number: pr.number, issue: Number(match[1]), head: pr.head.sha, branch: pr.head.ref, base: pr.base.ref, url: pr.html_url };
 }
@@ -60,9 +65,10 @@ export async function reviewThread(api, number, owner) {
 export async function loadProposalFiles(api, review) {
   const changed = await api(`pulls/${review.number}/files?per_page=100`);
   const root = proposalRoot(review.issue);
-  if (changed.length >= 100 || changed.some(f => !f.filename.startsWith(`${root}/`) || f.status === 'removed' || f.status === 'renamed')) throw Error('Proposal PR includes changes outside the proposal');
+  if (changed.length >= 100 || changed.some(f => (!review.productProposal || f.filename.startsWith(`${root}/`)) && (!f.filename.startsWith(`${root}/`) || f.status === 'removed' || f.status === 'renamed'))) throw Error('Proposal PR includes unsupported proposal changes');
   const files = [];
   for (const f of changed) {
+    if (!f.filename.startsWith(`${root}/`)) continue;
     const value = await api(`contents/${f.filename}?ref=${review.head}`);
     if (value.type !== 'file' || value.encoding !== 'base64' || value.size > 96000) throw Error('Unsupported proposal file');
     const content = Buffer.from(value.content, 'base64').toString('utf8');
@@ -86,7 +92,11 @@ export async function updateProposal(api, repo, snapshot, files, beforeWrite) {
   const created = await api('git/commits', 'POST', { message: `docs: address proposal review for #${snapshot.issue}`, tree: tree.sha, parents: [review.head] });
   await beforeWrite();
   await checkReviewCurrent(api, repo, review);
+  const current = review.productProposal ? await api(`pulls/${review.number}`) : null;
+  const proof = current ? productProposalProof(current) : null;
+  if (review.productProposal && (!proof || current.head.sha !== review.head)) throw Error('Product proposal changed before publication');
   // Non-forced update rejects a concurrent writer after the final head check.
   await api(`git/refs/heads/${review.branch}`, 'PATCH', { sha: created.sha, force: false });
+  if (proof) await api(`pulls/${review.number}`, 'PATCH', { body: current.body.replace(/<!-- lighthouse-product-proposal:\{[^\n]*\} -->/g, `<!-- lighthouse-product-proposal:${JSON.stringify({ ...proof, runId: snapshot.runId, head: created.sha })} -->`) });
   return { number: review.number, html_url: review.url };
 }

package/src/proposal.mjs

@@ -3,6 +3,8 @@ import { mkdtemp, mkdir, readFile, writeFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { execFileSync } from 'node:child_process';
+import { isDeepStrictEqual } from 'node:util';
+import { checkProductResumePullRequest } from './product-change.mjs';
 
 export const changeName = issue => {
   if (!Number.isSafeInteger(issue) || issue < 1) throw Error('Invalid proposal issue');
@@ -89,7 +91,8 @@ export async function loadStageReport(api, repo, report, current) {
     if (request.dispatch) {
       if (!['triage', 'refine', 'propose', 'implement'].includes(request.stage) || !report.body.includes(`<!-- lighthouse-stage:${request.stage}:`)) throw Error('Unexpected dispatched stage');
       const dispatch = await loadDispatch(api, repo, current.owner, current.issue, request.dispatch.commentId, run);
-      if (dispatch.request.stage !== request.stage || dispatch.request.id !== request.dispatch.requestId || dispatch.request.sourceRevision !== request.sourceRevision || dispatch.request.workflowRevision !== request.workflowRevision) throw Error('Dispatched report identity mismatch');
+      const dispatchedRevision = request.epic && request.stage === 'implement' ? request.baseRevision : request.sourceRevision;
+      if (dispatch.request.stage !== request.stage || dispatch.request.id !== request.dispatch.requestId || dispatch.request.sourceRevision !== dispatchedRevision || dispatch.request.workflowRevision !== request.workflowRevision || !isDeepStrictEqual(dispatch.request.epic, request.epic)) throw Error('Dispatched report identity mismatch');
       await checkDispatchClaim(api, repo, current.issue, request.dispatch, run.id);
     } else if (!['issues', 'issue_comment', 'workflow_dispatch'].includes(run.event) || run.path !== '.github/workflows/lighthouse-sdlc-router.yml' || run.actor?.login !== current.owner || run.head_sha !== request.sourceRevision) throw Error('Stage report identity mismatch');
     if (run.status !== 'completed' || run.conclusion !== 'success' || String(run.id) !== String(request.workflowRunId) || request.issue !== current.issue || marker !== request.runId) throw Error('Stage report identity mismatch');
@@ -111,6 +114,15 @@ export async function createProposalPullRequest(api, snapshot, files, body, runU
   const tree = await api('git/trees', 'POST', { base_tree: commit.tree.sha, tree: files.map(file => ({ path: file.path, mode: '100644', type: 'blob', content: file.content })) });
   const created = await api('git/commits', 'POST', { message: `docs: propose issue #${snapshot.issue}`, tree: tree.sha, parents: [snapshot.sourceRevision] });
   await beforeWrite();
+  if (snapshot.productResume) {
+    const resume = snapshot.productResume;
+    const current = await api(`pulls/${resume.pullRequest}`);
+    checkProductResumePullRequest(current, snapshot.repository, resume);
+    await api(`git/refs/heads/${resume.branch}`, 'PATCH', { sha: created.sha, force: false });
+    const proof = { schemaVersion: 1, issue: snapshot.issue, runId: snapshot.runId, applyIntent: resume.receiptIntent, head: created.sha };
+    await api(`pulls/${resume.pullRequest}`, 'PATCH', { body: `${current.body}\n\n${body.trim()}\n\n[Proposal evidence](${runUrl}).\n\n<!-- lighthouse-product-proposal:${JSON.stringify(proof)} -->` });
+    return { number: resume.pullRequest, html_url: current.html_url };
+  }
   await api('git/refs', 'POST', { ref: `refs/heads/${branch}`, sha: created.sha });
   const pr = await api('pulls', 'POST', { title: `Proposal for #${snapshot.issue}: ${snapshot.title.slice(0, 160)}`, head: branch, base: snapshot.defaultBranch, body: `${body}\n\nRelated to #${snapshot.issue}. Proposal only; implementation requires a separate owner decision.\n\nOpenSpec 1.15.0 strict validation passed. [Execution evidence](${runUrl}).\n\n<!-- lighthouse-proposal:${snapshot.runId} -->` });
   return pr;

package/src/stacked.mjs

@@ -14,6 +14,11 @@ 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;
+  const epic = input.mode === 'epic';
+  if (epic && input.slices.length === 0) errors.push(issue('stacked.empty', 'epic mode requires at least one child', 'slices'));
+  if (input.mode !== undefined && !['epic', 'nested'].includes(input.mode)) errors.push(issue('stacked.mode', 'mode must be epic or nested', 'mode'));
+  const epicParent = String(parentRef ?? '').match(/^(?:GH-)?([1-9]\d*)$/)?.[1];
+  if (epic && (!epicParent || input.parent.integrationBranch !== `lighthouse/epic-${epicParent}` || input.parent.integrationBranch === (input.parent.base ?? 'main'))) errors.push(issue('stacked.integration-branch', 'epic mode needs the integration branch for its parent issue', 'parent.integrationBranch'));
   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) => {
@@ -23,9 +28,14 @@ export function buildStackedPlan(input) {
     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 ?? [])] };
+    if (epic && slice.base !== undefined && slice.base !== input.parent.integrationBranch) errors.push(issue('stacked.epic-base', 'epic children must target the shared integration branch', `slices[${index}].base`));
+    const strings = value => Array.isArray(value) && value.every(item => typeof item === 'string' && item.trim());
+    if ((epic || slice.dependencies != null) && !strings(slice.dependencies)) errors.push(issue('stacked.dependencies', 'dependencies must be a string array', `slices[${index}].dependencies`));
+    if (slice.acceptance != null && !strings(slice.acceptance)) errors.push(issue('stacked.acceptance', 'acceptance must be a string array', `slices[${index}].acceptance`));
+    return { id: slice.id, title: slice.title, branch, base: slice.base ?? null, dependencies: strings(slice.dependencies) ? [...slice.dependencies].sort() : [], acceptance: strings(slice.acceptance) ? [...slice.acceptance] : [] };
   }).filter(Boolean);
   const byId = new Map(slices.map((slice) => [slice.id, slice]));
+  if (byId.size !== slices.length) errors.push(issue('stacked.duplicate', 'slice identities must be unique', 'slices'));
   const order = [];
   const visiting = new Set();
   const visited = new Set();
@@ -44,7 +54,8 @@ export function buildStackedPlan(input) {
   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 { type: 'open-pull-request', sliceId: id, branch: slice.branch, base: epic ? input.parent.integrationBranch : 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 };
+  if (epic) operations.push({ type: 'open-aggregate-pull-request', branch: input.parent.integrationBranch, base: input.parent.base ?? 'main', requires: [...order] });
+  return { schemaVersion: 1, status: errors.length ? 'invalid' : 'ready', valid: errors.length === 0, canApply: errors.length === 0, parent: input.parent, slices, order, operations: errors.length ? [] : operations, errors };
 }

package/src/stage-dispatch.mjs

@@ -1,5 +1,7 @@
 import { digest } from './host-contract.mjs';
 import { readActionsJson } from './actions-artifact.mjs';
+import { handoff } from './handoff.mjs';
+import { isDeepStrictEqual } from 'node:util';
 
 const routerPath = '.github/workflows/lighthouse-sdlc-router.yml';
 export const stages = ['triage', 'refine', 'propose', 'implement', 'integrate', 'review'];
@@ -7,13 +9,15 @@ export const workers = [...stages, 'apply-review', 'product-change', 'apply-prod
 export const workerFor = request => request.worker ?? request.stage ?? 'implement';
 export const stagePath = stage => { if (!workers.includes(stage)) throw Error('Unknown dispatch worker'); return `.github/workflows/lighthouse-sdlc-${stage}.lock.yml`; };
 export const implementPath = stagePath('implement');
-export const statusText = (stage, status) => `${({ requested: '📥 Requested', running: '▶️ Execution admitted', completed: '✅ Completed', waiting: '⏸️ Waiting for your response', failed: '❌ Failed or cancelled' })[status]} · ${stage}`;
+export const statusText = (stage, status) => `${({ requested: 'Requested', running: 'Queued', completed: 'Stage completed', waiting: 'Waiting for your answer', blocked: 'Blocked', failed: 'Execution failed', cancelled: 'Cancelled', unknown: 'Execution status unknown' })[status] ?? 'Execution status unknown'} · ${stage}`;
 const positive = value => /^[1-9][0-9]*$/.test(String(value));
-export const isBotContinuation = (event, eventName, actor, triggeringActor) => eventName === 'workflow_dispatch' && actor === 'github-actions[bot]' && triggeringActor === actor && event.inputs?.stage === 'implement' && positive(event.inputs?.issue) && positive(event.inputs?.after_run);
+export const isBotContinuation = (event, eventName, actor, triggeringActor) => eventName === 'workflow_dispatch' && actor === 'github-actions[bot]' && triggeringActor === actor && (event.inputs?.stage === 'implement' && event.inputs?.workflow !== 'product-change' || ['triage', 'refine', 'propose', 'implement'].includes(event.inputs?.stage) && ['product-change', 'resume-product'].includes(event.inputs?.workflow)) && positive(event.inputs?.issue) && positive(event.inputs?.after_run);
+export const isBotEpicTriage = (event, eventName, actor, triggeringActor) => eventName === 'workflow_dispatch' && actor === 'github-actions[bot]' && triggeringActor === actor && event.inputs?.stage === 'triage' && positive(event.inputs?.issue) && positive(event.inputs?.epic_parent) && positive(event.inputs?.epic_run);
 const sha = value => /^[a-f0-9]{40}$/.test(value ?? '');
 const hash = value => /^[a-f0-9]{64}$/.test(value ?? '');
 export const dispatchId = (repository, runId, stage = 'implement') => digest(`${repository}:${runId}:${stage}`);
-export const receiptId = (repository, receipt) => receipt.recovery ? digest(`${repository}:${receipt.recovery.rootId}:retry:${receipt.recovery.attempt}`) : dispatchId(repository, receipt.feedbackKey ?? receipt.eventRunId ?? receipt.routerRunId, receipt.stage ?? 'implement');
+export const epicTriageKey = (repository, parent, child, planDigest) => digest(`${repository}:epic-triage:${parent}:${child}:${planDigest}`);
+export const receiptId = (repository, receipt) => receipt.recovery ? digest(`${repository}:${receipt.recovery.rootId}:retry:${receipt.recovery.attempt}`) : dispatchId(repository, receipt.epicKey ?? receipt.feedbackKey ?? receipt.eventRunId ?? receipt.routerRunId, receipt.stage ?? 'implement');
 export const dispatchArtifact = request => `lighthouse-dispatch-${request.id}`;
 
 export function readDispatchReceipt(comment, repository, issue) {
@@ -22,16 +26,28 @@ export function readDispatchReceipt(comment, repository, issue) {
   if (matches.length !== 1) throw Error('Missing or ambiguous dispatch receipt');
   const receipt = JSON.parse(matches[0][1]);
   if (receipt.recovery && (!hash(receipt.recovery.rootId) || !positive(receipt.recovery.previousComment) || !Number.isSafeInteger(receipt.recovery.attempt) || receipt.recovery.attempt < 1 || receipt.recovery.attempt > 2)) throw Error('Invalid recovery receipt');
-  if (receipt.schemaVersion !== 1 || !hash(receipt.id) || !hash(receipt.digest) || !positive(receipt.routerRunId) || !positive(receipt.routerAttempt) || !stages.includes(receipt.stage ?? 'implement') || !workers.includes(workerFor(receipt)) || (receipt.feedbackKey !== undefined && !hash(receipt.feedbackKey)) || (receipt.eventRunId !== undefined && !positive(receipt.eventRunId)) || receipt.id !== receiptId(repository, receipt) || (receipt.workerRunId !== null && !positive(receipt.workerRunId))) throw Error('Invalid dispatch receipt');
+  if (receipt.schemaVersion !== 1 || !hash(receipt.id) || !hash(receipt.digest) || !positive(receipt.routerRunId) || !positive(receipt.routerAttempt) || !stages.includes(receipt.stage ?? 'implement') || !workers.includes(workerFor(receipt)) || (receipt.epicKey !== undefined && !hash(receipt.epicKey)) || (receipt.feedbackKey !== undefined && !hash(receipt.feedbackKey)) || (receipt.eventRunId !== undefined && !positive(receipt.eventRunId)) || receipt.id !== receiptId(repository, receipt) || (receipt.workerRunId !== null && !positive(receipt.workerRunId))) throw Error('Invalid dispatch receipt');
   return receipt;
 }
 
 export function dispatchReceiptBody(repository, receipt) {
   const root = `https://github.com/${repository}/actions/runs/`;
-  const heading = statusText(workerFor(receipt), receipt.status ?? (receipt.workerRunId ? 'running' : 'requested'));
-  const status = receipt.workerRunId ? `[Execution](${root}${receipt.workerRunId}). Open the execution for its current status and result.` : 'Execution requested; execution is not yet confirmed. Do not resend while confirmation is pending.';
-  const recovery = receipt.recovery ? `\n\nRetry ${receipt.recovery.attempt}/2 · [Previous request](https://github.com/${repository}/issues/${receipt.issue ?? ''}#issuecomment-${receipt.recovery.previousComment})` : '';
-  return `${heading}\n\n${status}${recovery}\n\n[Dispatch origin](${root}${receipt.routerRunId})\n\n<!-- lighthouse-dispatch:${JSON.stringify(receipt)} -->`;
+  const status = receipt.status ?? (receipt.workerRunId ? 'running' : 'requested');
+  const states = {
+    requested: ['requested', 'The request is recorded; execution is not confirmed.', 'None. Wait for admission.', 'The workflow will report the outcome when the request is processed.'],
+    running: ['queued', 'The worker admitted the request; agent execution is not yet confirmed.', 'None. Wait for the result.', 'The workflow will publish a result or an actionable stop.'],
+    completed: ['completed', 'The stage published a validated result.', 'Follow the latest stage handoff.', 'The configured continuation applies only when authorized.'],
+    waiting: ['blocked', 'The stage published a blocked result.', 'Follow the latest stage handoff.', 'Continuation depends on the recorded blocker and authorization.'],
+    blocked: ['blocked', 'The stage published a blocker without a pending owner question.', 'The workflow maintainer should follow the latest stage handoff.', 'Work remains stopped until the blocker is resolved and continuation is authorized.'],
+    failed: ['failed', 'This attempt did not publish a validated result.', 'The workflow maintainer should inspect the execution and recovery policy.', 'Any retry requires the configured authorization.'],
+    cancelled: ['cancelled', 'This attempt was cancelled before a validated result was published.', 'The workflow maintainer should inspect the execution.', 'Any restart requires the configured authorization.'],
+    unknown: ['unknown', 'Publication of a validated result could not be confirmed.', 'The workflow maintainer should inspect the execution.', 'Reconcile the outcome before requesting another attempt.'],
+  };
+  const item = states[status];
+  if (!item) throw Error('Unknown dispatch status');
+  const recovery = receipt.recovery ? `\nRetry ${receipt.recovery.attempt}/2 · [Previous request](https://github.com/${repository}/issues/${receipt.issue ?? ''}#issuecomment-${receipt.recovery.previousComment})` : '';
+  const details = `[Dispatch origin](${root}${receipt.routerRunId})${receipt.workerRunId ? ` · [Execution](${root}${receipt.workerRunId})` : ''}${recovery}\n\n<!-- lighthouse-dispatch:${JSON.stringify(receipt)} -->`;
+  return handoff({ status: item[0], stage: workerFor(receipt), happened: item[1], action: item[2], next: item[3], details });
 }
 
 export async function issueComments(api, issue) {
@@ -57,7 +73,7 @@ export async function recordDispatch(api, repository, request) {
     const run = await api(`actions/runs/${receipt.workerRunId}`);
     if (run.path !== stagePath(workerFor(receipt)) || run.status !== 'completed' && request.queue !== true) throw Error('A stage execution is still pending or running');
   }
-  const receipt = { schemaVersion: 1, stage: request.stage, ...(request.recovery ? { recovery: request.recovery, issue: request.issue } : {}), ...(request.worker ? { worker: request.worker } : {}), ...(request.feedbackKey ? { feedbackKey: request.feedbackKey } : {}), status: 'requested', ...(request.eventRunId ? { eventRunId: request.eventRunId } : {}), id: request.id, digest: digest(JSON.stringify(request)), routerRunId: request.routerRunId, routerAttempt: request.routerAttempt, workerRunId: null };
+  const receipt = { schemaVersion: 1, stage: request.stage, ...(request.recovery ? { recovery: request.recovery, issue: request.issue } : {}), ...(request.worker ? { worker: request.worker } : {}), ...(request.feedbackKey ? { feedbackKey: request.feedbackKey } : {}), ...(request.epicKey ? { epicKey: request.epicKey } : {}), status: 'requested', ...(request.eventRunId ? { eventRunId: request.eventRunId } : {}), id: request.id, digest: digest(JSON.stringify(request)), routerRunId: request.routerRunId, routerAttempt: request.routerAttempt, workerRunId: null };
   const comment = await api(`issues/${request.issue}/comments`, 'POST', { body: dispatchReceiptBody(repository, receipt) });
   return { send: true, comment, receipt };
 }
@@ -67,7 +83,20 @@ export async function sendDispatch(api, repository, request, commentId) {
   if (receipt.id !== request.id || receipt.digest !== digest(JSON.stringify(request))) throw Error('Dispatch request changed');
   if (receipt.workerRunId) return;
   // Never retry this POST automatically: its response can be lost after admission.
-  return api(`actions/workflows/lighthouse-sdlc-${workerFor(request)}.lock.yml/dispatches`, 'POST', { ref: request.ref, inputs: { issue: String(request.issue), 'dispatch-request': String(commentId), ...(workerFor(request) === 'apply-product-change' ? { 'pull-request': String(request.productApproval.pullRequest), head: request.productApproval.head } : {}) } });
+  const parent = epicLeaseParent(request);
+  return api(`actions/workflows/lighthouse-sdlc-${workerFor(request)}.lock.yml/dispatches`, 'POST', { ref: request.ref, inputs: { issue: String(request.issue), 'dispatch-request': String(commentId), ...(parent ? { 'epic-parent': String(parent) } : {}), ...(workerFor(request) === 'apply-product-change' ? { 'pull-request': String(request.productApproval.pullRequest), head: request.productApproval.head } : {}) } });
+}
+
+export function epicLeaseParent(request) {
+  if (request.epic === undefined) return null;
+  const epic = request.epic;
+  if (!epic || !Number.isSafeInteger(epic.parent) || epic.parent < 1 || epic.parent === request.issue || !(['triage', 'refine', 'implement'].includes(workerFor(request)) || workerFor(request) === 'apply-review' && request.stage === 'implement') || epic.base !== `lighthouse/epic-${epic.parent}` || !hash(epic.planDigest)) throw Error('Invalid epic dispatch lease');
+  return epic.parent;
+}
+
+export function checkEpicWorkerLease(request, inputs) {
+  const parent = epicLeaseParent(request);
+  if ((inputs?.['epic-parent'] ?? '') !== (parent ? String(parent) : '')) throw Error('Worker epic lease does not match the authenticated dispatch');
 }
 
 // Called only for a dispatch whose router identity is authenticated by the host.
@@ -83,13 +112,14 @@ export function executionModelSelection(request) {
 }
 
 export function verifyDispatchOrigin(request, receipt, parent, worker, repository, owner, issue) {
-  const delegatedWorker = workerFor(request) === 'apply-review' && ['propose', 'implement'].includes(request.stage) || workerFor(request) === 'product-change' && ['propose', 'implement'].includes(request.stage);
+  const delegatedWorker = workerFor(request) === 'apply-review' && ['propose', 'implement'].includes(request.stage) || workerFor(request) === 'product-change' && ['triage', 'refine', 'propose', 'implement'].includes(request.stage);
   const applyProductWorker = workerFor(request) === 'apply-product-change' && ['propose', 'implement'].includes(request.stage);
   if (workerFor(request) !== workerFor(receipt) || request.feedbackKey !== receipt.feedbackKey || workerFor(request) !== request.stage && !delegatedWorker && !applyProductWorker) throw Error('Dispatch worker responsibility mismatch');
   if (workerFor(request) === 'product-change') {
     const idea = request.eventName === 'workflow_dispatch' && request.event?.inputs?.workflow === 'product-change';
     const feedback = request.productFeedback && ['answer', 'request-changes'].includes(request.productFeedback.action) && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(request.productFeedback.changeName ?? '') && typeof request.productFeedback.text === 'string' && request.productFeedback.text.trim().length > 0 && request.productFeedback.text.length <= 12000 && ['issue_comment', 'pull_request_review'].includes(request.eventName);
-    if (!idea && !feedback) throw Error('Product Change worker needs an authorized idea selector or authenticated owner feedback');
+    const parent = request.productParent && request.productParent.issue === issue && request.productParent.stage === request.stage && (request.eventName === 'workflow_run' && String(request.productParent.predecessor?.runId) === String(request.event?.workflow_run?.id) || request.eventName === 'workflow_dispatch' && request.event?.inputs?.workflow === 'product-change' && String(request.productParent.predecessor?.runId) === String(request.event.inputs.after_run));
+    if (!idea && !feedback && !parent) throw Error('Product Change worker needs an authorized idea, owner feedback or authenticated parent prerequisite');
   }
   if (workerFor(request) === 'apply-product-change' && (!request.productApproval || request.productApproval.kind !== 'approval' || !hash(request.productApproval.reviewKey))) throw Error('Trusted Product Change apply requires a bound approval');
   if (JSON.stringify(request.recovery) !== JSON.stringify(receipt.recovery)) throw Error('Recovery receipt identity mismatch');
@@ -98,10 +128,12 @@ export function verifyDispatchOrigin(request, receipt, parent, worker, repositor
   const recovery = !!request.recovery;
   const originPath = recovery ? '.github/workflows/lighthouse-worker-maintenance.yml' : routerPath;
   const originEvent = recovery ? request.routerEventName : request.eventName;
-  const continuation = !recovery && isBotContinuation(request.event, parent.event, parent.actor?.login, parent.triggering_actor?.login) && request.stage === 'implement' && request.handoff && !request.worker && !request.feedbackKey && Number(request.event.inputs.issue) === issue && request.predecessor?.runId === request.event.inputs.after_run;
-  if (String(parent.id) !== String(receipt.routerRunId) || parent.run_attempt !== receipt.routerAttempt || request.routerRunId !== receipt.routerRunId || request.routerAttempt !== receipt.routerAttempt || parent.path !== originPath || (parent.event !== 'workflow_run' && !continuation && (parent.actor?.login !== owner || parent.triggering_actor?.login !== owner)) || !(recovery ? ['schedule', 'workflow_dispatch'] : events).includes(parent.event) || parent.event !== originEvent || parent.head_sha !== (request.routerRevision ?? request.workflowRevision) || parent.head_branch !== (request.routerRef ?? request.ref) || parent.repository?.full_name !== repository) throw Error('Dispatch origin is not an authorized router execution');
+  const continuation = !recovery && isBotContinuation(request.event, parent.event, parent.actor?.login, parent.triggering_actor?.login) && Number(request.event.inputs.issue) === issue && (request.stage === 'implement' && request.handoff && !request.worker && !request.feedbackKey && request.predecessor?.runId === request.event.inputs.after_run || request.worker === 'product-change' && request.productParent?.predecessor?.runId === request.event.inputs.after_run || (!request.worker || request.worker === 'apply-review' && request.productResume?.parent.review) && request.event.inputs.workflow === 'resume-product' && request.productResume?.applyRun?.runId === request.event.inputs.after_run);
+  const epicTriage = !recovery && isBotEpicTriage(request.event, parent.event, parent.actor?.login, parent.triggering_actor?.login) && request.stage === 'triage' && !request.handoff && !request.worker && Number(request.event.inputs.issue) === issue && Number(request.event.inputs.epic_parent) === request.epic?.parent;
+  if (epicTriage ? request.epicKey !== epicTriageKey(repository, request.epic.parent, issue, request.epic.planDigest) || receipt.epicKey !== request.epicKey : request.epicKey !== undefined || receipt.epicKey !== undefined) throw Error('Epic triage identity is invalid');
+  if (String(parent.id) !== String(receipt.routerRunId) || parent.run_attempt !== receipt.routerAttempt || request.routerRunId !== receipt.routerRunId || request.routerAttempt !== receipt.routerAttempt || parent.path !== originPath || (parent.event !== 'workflow_run' && !continuation && !epicTriage && (parent.actor?.login !== owner || parent.triggering_actor?.login !== owner)) || !(recovery ? ['schedule', 'workflow_dispatch'] : events).includes(parent.event) || parent.event !== originEvent || parent.head_sha !== (request.routerRevision ?? request.workflowRevision) || parent.head_branch !== (request.routerRef ?? request.ref) || parent.repository?.full_name !== repository) throw Error('Dispatch origin is not an authorized router execution');
   executionModelSelection(request);
-  const eventRunId = request.eventName === 'workflow_run' ? request.event?.workflow_run?.id : request.event?.inputs?.after_run;
+  const eventRunId = request.eventName === 'workflow_run' ? request.event?.workflow_run?.id : request.event?.inputs?.epic_run ?? request.event?.inputs?.after_run;
   if (String(eventRunId ?? '') !== String(receipt.eventRunId ?? '') || String(request.eventRunId ?? '') !== String(receipt.eventRunId ?? '')) throw Error('Completion event identity mismatch');
   if (worker.path !== stagePath(workerFor(request)) || worker.event !== 'workflow_dispatch' || worker.head_sha !== request.workflowRevision || worker.head_branch !== request.ref || worker.repository?.full_name !== repository || ![owner, 'github-actions[bot]'].includes(worker.actor?.login) || ![owner, 'github-actions[bot]'].includes(worker.triggering_actor?.login)) throw Error('Dispatch worker identity mismatch');
 }
@@ -114,11 +146,25 @@ export async function loadDispatch(api, repository, owner, issue, commentId, wor
   const parent = await api(`actions/runs/${receipt.routerRunId}/attempts/${receipt.routerAttempt}`);
   const request = await readArtifact(api, repository, receipt.routerRunId, dispatchArtifact(receipt), 'dispatch.json');
   verifyDispatchOrigin(request, receipt, parent, worker, repository, owner, issue);
-  if (isBotContinuation(request.event, parent.event, parent.actor?.login, parent.triggering_actor?.login)) {
+  if (isBotContinuation(request.event, parent.event, parent.actor?.login, parent.triggering_actor?.login) && !request.productParent && request.event?.inputs?.workflow !== 'resume-product') {
     const predecessor = await api(`actions/runs/${request.predecessor.runId}`);
     const next = await (await import('./stage-transition.mjs')).refinementAfterRun(api, repository, owner, { action: 'completed', workflow_run: { id: predecessor.id, head_sha: predecessor.head_sha } }, readArtifact);
     if (next?.issue !== issue || JSON.stringify(next.predecessor) !== JSON.stringify(request.predecessor)) throw Error('Bot continuation lacks an authenticated refinement');
   }
+  if (request.productResume) {
+    const apply = await api(`actions/runs/${request.productResume.applyRun.runId}`);
+    const observed = await (await import('./stage-transition.mjs')).productApplyAfterRun(api, repository, owner, { action: 'completed', workflow_run: { id: apply.id, head_sha: apply.head_sha } }, readArtifact);
+    if (JSON.stringify(observed) !== JSON.stringify(request.productResume) || observed.baseRevision !== request.sourceRevision || (observed.parent.feedback?.taskDigest ?? observed.parent.taskDigest) !== request.taskDigest) throw Error('Applied product prerequisite or parent authorization changed');
+  }
+  if (request.productParent) {
+    const parentRun = await api(`actions/runs/${request.productParent.predecessor.runId}`);
+    const observed = await (await import('./stage-transition.mjs')).productGapAfterRun(api, repository, owner, { action: 'completed', workflow_run: { id: parentRun.id, head_sha: parentRun.head_sha } }, readArtifact);
+    if (JSON.stringify(observed) !== JSON.stringify(request.productParent) || observed.baseRevision !== request.sourceRevision || observed.taskDigest !== request.taskDigest) throw Error('Product prerequisite or parent authorization changed');
+  }
+  if (isBotEpicTriage(request.event, parent.event, parent.actor?.login, parent.triggering_actor?.login)) {
+    const verified = await (await import('./epic-dispatch.mjs')).verifyEpicTriageOrigin(api, { repository, owner, child: issue, parent: Number(request.event.inputs.epic_parent), runId: request.event.inputs.epic_run }, { readArtifact });
+    if (!isDeepStrictEqual(verified.current, request.epic)) throw Error('Epic triage authority changed');
+  }
   const dispatch = { request, receipt, commentId: Number(commentId) };
   if (request.recovery) await (await import('./worker-recovery.mjs')).verifyRecoveryOrigin(api, repository, owner, dispatch, parent, readArtifact, depth);
   return dispatch;
@@ -146,6 +192,7 @@ export async function admitDispatch(api, repository, owner, env, event) {
   if (!Number.isSafeInteger(issue) || issue < 1 || String(issue) !== env.LIGHTHOUSE_ISSUE) throw Error('Dispatch issue must be a canonical positive integer');
   const worker = await api(`actions/runs/${env.GITHUB_RUN_ID}/attempts/${env.GITHUB_RUN_ATTEMPT}`);
   const dispatch = await loadDispatch(api, repository, owner, issue, event.inputs?.['dispatch-request'], worker);
+  checkEpicWorkerLease(dispatch.request, event.inputs);
   if (env.LIGHTHOUSE_WORKER ? workerFor(dispatch.request) !== env.LIGHTHOUSE_WORKER : dispatch.request.stage !== env.LIGHTHOUSE_STAGE) throw Error('Dispatch targets a different stage or worker');
   if (dispatch.request.recovery) {
     if (env.LIGHTHOUSE_RECOVERY_ENABLED !== 'true') throw Error('Automatic recovery has been disabled');
@@ -160,7 +207,7 @@ export async function finishDispatch(api, repository, issue, commentId, workerId
   if (!positive(commentId)) return;
   const receipt = readDispatchReceipt(await api(`issues/comments/${commentId}`), repository, issue);
   if (String(receipt.workerRunId) !== String(workerId)) return;
-  receipt.status = outcome === 'passed' ? 'completed' : outcome === 'blocked' ? 'waiting' : 'failed';
+  receipt.status = outcome === 'passed' ? 'completed' : outcome === 'question' ? 'waiting' : outcome === 'blocked' ? 'blocked' : outcome === 'failed' ? 'failed' : outcome === 'cancelled' ? 'cancelled' : 'unknown';
   await api(`issues/comments/${commentId}`, 'PATCH', { body: dispatchReceiptBody(repository, receipt) });
 }
 
@@ -174,12 +221,12 @@ export async function completedEvent(api, event, env, wait = ms => new Promise(r
   if (!bot && (env.GITHUB_EVENT_NAME !== 'workflow_dispatch' || env.GITHUB_ACTOR !== env.GITHUB_REPOSITORY_OWNER || env.GITHUB_TRIGGERING_ACTOR !== env.GITHUB_REPOSITORY_OWNER || !positive(id))) throw Error('Completion replay requires an owner and a run ID, or a verified refinement continuation');
   let run = await api(`actions/runs/${id}`);
   if (bot) {
-    if (run.path !== stagePath('refine')) throw Error('Bot continuation must reference a refinement');
+    if (event.inputs?.workflow === 'resume-product' ? run.path !== stagePath('apply-product-change') : event.inputs?.workflow === 'product-change' ? !['triage', 'refine', 'propose', 'implement', 'apply-review'].some(stage => run.path === stagePath(stage)) : run.path !== stagePath('refine')) throw Error(event.inputs?.workflow === 'resume-product' ? 'Bot continuation must reference a product apply' : event.inputs?.workflow === 'product-change' ? 'Bot continuation must reference a supported parent execution' : 'Bot continuation must reference a refinement');
     // The publisher signals before its own workflow has finished its final jobs.
     for (let attempt = 0; run.status !== 'completed' && attempt < 24; attempt++) {
       await wait(5000); run = await api(`actions/runs/${id}`);
     }
-    if (run.status !== 'completed') throw Error('Refinement completion timed out; replay after the execution completes');
+    if (run.status !== 'completed') throw Error('Parent completion timed out; replay after the execution completes');
   }
   return { action: 'completed', workflow_run: { id: run.id, head_sha: run.head_sha } };
 }