@juangcarmona/lighthouse-sdlc 0.15.2 → 0.16.1

package/src/product-change-actions.mjs

@@ -0,0 +1,308 @@
+import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { validateProductChangeFiles, validateProductCheckpoint, validateProductWorkspace, loadProductBridge, productReviewBinding, parseProductDecision, verifyProductDecision, authorizeProductApply, createProductApplyReceipt, productModelDigest, productModelDirectory } from './product-change.mjs';
+import { checkImplementationPullRequest } from './proposal-review.mjs';
+
+const marker = '<!-- lighthouse-product-change:';
+export async function validateProductCandidate(root, changeName, files, bridge) {
+  const summary = validateProductChangeFiles(files, { changeName });
+  const temp = await mkdtemp(join(tmpdir(), 'lighthouse-product-change-'));
+  try {
+    const productRoot = dirname(await productModelDirectory(root));
+    for (const name of [productRoot, '.product/config.yaml', 'openspec/config.yaml', 'openspec/schemas']) {
+      const source = join(root, name);
+      try {
+        const stat = await import('node:fs/promises').then(fs => fs.lstat(source));
+        if (stat.isDirectory()) {
+          await mkdir(dirname(join(temp, name)), { recursive: true });
+          await cp(source, join(temp, name), { recursive: true, errorOnExist: true, force: false });
+        }
+        else {
+          const destination = join(temp, name);
+          await mkdir(dirname(destination), { recursive: true });
+          await writeFile(destination, await readFile(source));
+        }
+      } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    }
+    for (const file of files) {
+      const destination = join(temp, file.path);
+      await mkdir(dirname(destination), { recursive: true });
+      await writeFile(destination, file.content, { flag: 'wx' });
+    }
+    execFileSync('npx', ['--yes', '--package', '@fission-ai/openspec@1.15.0', 'openspec', 'validate', changeName, '--strict', '--no-interactive'], { cwd: temp, encoding: 'utf8', timeout: 120000, maxBuffer: 1024 * 1024, env: { ...process.env, OPENSPEC_TELEMETRY: '0', CI: 'true' } });
+    const checked = await validateProductWorkspace(temp, changeName, bridge);
+    return { ...summary, baselineDigest: await productModelDigest(root), modelRoot: await productModelDirectory(root), openSpec: 'passed', provider: 'passed', diagnosticCount: checked.diagnostics?.length ?? 0 };
+  } finally { await rm(temp, { recursive: true, force: true }); }
+}
+
+export async function loadProductCandidateFromPullRequest(api, repository, pr, changeName) {
+  if (pr?.state !== 'open' || pr.merged || pr.user?.login !== 'github-actions[bot]' || pr.user?.type !== 'Bot' || pr.head?.repo?.full_name !== repository || pr.base?.repo?.full_name !== repository) throw Error('Product Change review needs an open bot-owned PR in this repository');
+  const changed = await api(`pulls/${pr.number}/files?per_page=100`);
+  if (!Array.isArray(changed) || changed.length >= 100 || changed.some(file => file.status === 'removed' || file.status === 'renamed')) throw Error('Product Change PR file list exceeds its bound or contains removals');
+  const files = [];
+  for (const item of changed) {
+    if (!item.filename.startsWith(`openspec/changes/${changeName}/`)) continue;
+    const value = await api(`contents/${item.filename}?ref=${pr.head.sha}`);
+    if (value.type !== 'file' || value.encoding !== 'base64' || value.size > 65536) throw Error(`Product Change file cannot be reviewed: ${item.filename}`);
+    files.push({ path: item.filename, content: Buffer.from(value.content, 'base64').toString('utf8') });
+  }
+  const checked = validateProductChangeFiles(files, { changeName });
+  return { files, ...checked };
+}
+
+export async function productModelDigestFromApi(api, revision) {
+  const tree = await api(`git/trees/${revision}?recursive=1`);
+  if (tree.truncated || !Array.isArray(tree.tree) || tree.tree.length > 10000) throw Error('Accepted product model tree exceeds the API bound');
+  let modelRoot = 'docs/product/model';
+  const config = await api(`contents/.product/config.yaml?ref=${revision}`, 'GET', undefined, true);
+  if (config) {
+    if (config.type !== 'file' || config.encoding !== 'base64' || config.size > 65536) throw Error('ProductShape config is not a bounded regular file');
+    const value = Buffer.from(config.content, 'base64').toString('utf8').match(/^product-root:\s*(.*?)\s*$/m)?.[1]?.replace(/^(?:"(.*)"|'(.*)')$/, (_match, doubleQuoted, singleQuoted) => doubleQuoted ?? singleQuoted);
+    if (value) modelRoot = `${value}/model`;
+  }
+  if (!safeRelative(modelRoot) || modelRoot.split('/').some(part => part.startsWith('.'))) throw Error('ProductShape product-root is unsafe');
+  const entries = tree.tree.filter(item => item.path.startsWith(`${modelRoot}/`) && item.type === 'blob').sort((a, b) => a.path.localeCompare(b.path));
+  if (!entries.length || entries.length > 512) throw Error('Accepted product model file list is empty or exceeds its bound');
+  const rows = [];
+  let bytes = 0;
+  for (const entry of entries) {
+    if (entry.mode !== '100644' && entry.mode !== '100755' || entry.size > 65536) throw Error(`Accepted product model path is not a bounded regular file: ${entry.path}`);
+    const blob = await api(`git/blobs/${entry.sha}`);
+    if (blob.encoding !== 'base64' || blob.size > 65536) throw Error(`Accepted product artifact exceeds its bound: ${entry.path}`);
+    const content = Buffer.from(blob.content, 'base64');
+    bytes += content.length;
+    if (bytes > 8 * 1024 * 1024) throw Error('Accepted product model exceeds its aggregate bound');
+    rows.push(`${entry.path.slice(`${modelRoot}/`.length)}\0${createHash('sha256').update(content).digest('hex')}\n`);
+  }
+  return { digest: createHash('sha256').update(rows.join('')).digest('hex'), modelRoot };
+}
+
+function reviewText({ repository, snapshot, head, changeId, changeName, files, candidate, validation, runUrl, approvalKey }) {
+  const manifest = files.find(file => file.path.endsWith('/product-change/change.md'))?.content ?? '';
+  const sections = [...manifest.matchAll(/^## (.+?)\n([\s\S]*?)(?=^## |\s*$)/gm)].map(match => `### ${match[1]}\n${match[2].trim()}`).join('\n\n');
+  const artifacts = files.filter(file => file.path.includes('/proposed/')).map(file => `- [${file.path}](https://github.com/${repository}/blob/${head}/${file.path})`).join('\n');
+  const areas = candidate.affectedAreas?.map(area => `- ${area}`).join('\n') || '- See the change manifest.';
+  const decisions = candidate.decisions?.map(decision => `- ${decision}`).join('\n') || '- Review the proposed behavior in the change manifest.';
+  return `## Product decision: ${changeId}\n\nThis product proposal was prepared for [issue #${snapshot.issue}](https://github.com/${repository}/issues/${snapshot.issue}). Review the problem, proposed outcome and affected product areas before deciding.\n\n### Affected product areas\n${areas}\n\n### Decisions and trade-offs\n${decisions}\n\n### Product Change\n${sections}\n\n### Proposed artifacts\n${artifacts || 'No artifact links were produced.'}\n\nValidation: ProductShape overlay and OpenSpec strict validation passed (${validation.provider}, ${validation.openSpec}). [Review the branch diff](https://github.com/${repository}/compare/${snapshot.defaultBranch}...${head}).\n\n### Decide\nApprove this exact product delta with:\n\n\`/product-change approve ${changeName} ${approvalKey}\`\n\nTo request a revision, use this as the first line of a new comment and add the requested change on the next line:\n\n/product-change request-changes ${changeName} ${approvalKey}\nDescribe the change\n\nApproval authorizes trusted ProductShape apply. This idea entry does not grant implementation permission. PR merge, release and deployment remain separate decisions. [Preparation run](${runUrl}).`;
+}
+
+export async function publishProductChangePullRequest(api, repository, snapshot, candidate, { validation, runUrl, beforeWrite }) {
+  const files = validateProductChangeFiles(candidate.files, { changeName: candidate.changeName });
+  if (files.changeId !== candidate.changeId || files.digest !== candidate.proposalDigest || validation.provider !== 'passed' || validation.openSpec !== 'passed') throw Error('Product Change candidate validation evidence is stale');
+  const pulls = await api('pulls?state=open&per_page=100');
+  if (pulls.length >= 100) throw Error('Open pull request list exceeds bounds');
+  const issuePulls = pulls.filter(pr => pr.head?.ref?.startsWith(`lighthouse/implement-${snapshot.issue}-`) || pr.head?.ref?.startsWith(`lighthouse/product-change-${snapshot.issue}-`));
+  if (issuePulls.length > 1) throw Error('Issue has multiple eligible delivery PRs; owner review is required');
+  let pr = issuePulls[0] ? await api(`pulls/${issuePulls[0].number}`) : null;
+  let base, branch, parent;
+  if (pr) {
+    if (pr.head.ref.startsWith(`lighthouse/implement-${snapshot.issue}-`) && pr.body?.includes('<!-- lighthouse-product-change:')) {
+      if (pr.user?.login !== 'github-actions[bot]' || pr.user?.type !== 'Bot' || pr.state !== 'open' || pr.merged || pr.head?.repo?.full_name !== repository) throw Error('Existing Product Change PR is not a current bot-owned PR');
+    } else if (pr.head.ref.startsWith(`lighthouse/implement-${snapshot.issue}-`)) checkImplementationPullRequest(pr, repository);
+    else if (pr.user?.login !== 'github-actions[bot]' || pr.user?.type !== 'Bot' || pr.state !== 'open' || pr.merged || !pr.body?.includes('<!-- lighthouse-product-change:')) throw Error('Existing issue PR is not an eligible Lighthouse Product Change draft');
+    if (pr.base?.ref !== snapshot.defaultBranch || pr.head?.repo?.full_name !== repository) throw Error('Existing issue PR targets an unexpected repository or base');
+    if (!pr.draft) throw Error('Product Change cannot modify a PR already submitted for review');
+    branch = pr.head.ref; parent = pr.head.sha;
+    base = await api(`git/commits/${parent}`);
+  } else {
+    branch = `lighthouse/implement-${snapshot.issue}-${snapshot.runId.slice(0, 12)}`;
+    parent = snapshot.sourceRevision;
+    base = await api(`git/commits/${parent}`);
+  }
+  const tree = await api('git/trees', 'POST', { base_tree: base.tree.sha, tree: candidate.files.map(file => ({ path: file.path, mode: '100644', type: 'blob', content: file.content })) });
+  const commit = await api('git/commits', 'POST', { message: `docs: prepare product change for #${snapshot.issue}`, tree: tree.sha, parents: [parent] });
+  await beforeWrite();
+  if (pr) {
+    if ((await api(`pulls/${pr.number}`)).head.sha !== parent) throw Error('Issue PR changed before Product Change publication');
+    await api(`git/refs/heads/${branch}`, 'PATCH', { sha: commit.sha, force: false });
+    pr = await api(`pulls/${pr.number}`);
+  } else {
+    const existingBranch = await api(`git/ref/heads/${branch}`, 'GET', undefined, true);
+    if (existingBranch) throw Error('Product Change branch already exists without its reviewed PR; reconcile before retry');
+    await api('git/refs', 'POST', { ref: `refs/heads/${branch}`, sha: commit.sha });
+    const title = `Product change for #${snapshot.issue}: ${snapshot.title.slice(0, 150)}`;
+    pr = await api('pulls', 'POST', { title, head: branch, base: snapshot.defaultBranch, draft: true, body: `Product Change ${candidate.changeId} prepared for #${snapshot.issue}.\n\n${runUrl}\n\n<!-- lighthouse-product-change:${JSON.stringify({ schemaVersion: 1, issue: snapshot.issue, changeName: candidate.changeName, changeId: candidate.changeId, proposalDigest: candidate.proposalDigest })} -->` });
+  }
+  const repositoryInfo = await api('');
+  const policyDigest = snapshot.policyDigest;
+  const binding = productReviewBinding({ repository, issue: snapshot.issue, pullRequest: pr.number, changeName: candidate.changeName, changeId: candidate.changeId, proposalDigest: candidate.proposalDigest, baselineDigest: candidate.baselineDigest, policyDigest, authorityDigest: snapshot.authorizationDigest, head: pr.head.sha });
+  const checkpoint = {
+    schemaVersion: 1, kind: 'checkpoint',
+    identity: { repository, issue: snapshot.issue, parentRunId: String(snapshot.dispatch?.routerRunId ?? snapshot.workflowRunId), authorizationDigest: snapshot.authorizationDigest, policyDigest, workflowRevision: snapshot.workflowRevision, head: pr.head.sha },
+    requestDigest: snapshot.dispatch?.digest ?? snapshot.taskDigest,
+    changeName: candidate.changeName, changeId: candidate.changeId, proposalDigest: candidate.proposalDigest, baselineDigest: candidate.baselineDigest,
+    state: 'waiting-product-decision', effectIds: [`pr:${pr.number}:${pr.head.sha}`]
+  };
+  const checkpointErrors = validateProductCheckpoint(checkpoint);
+  if (checkpointErrors.length) throw Error(checkpointErrors.join('; '));
+  const body = reviewText({ repository, snapshot, head: pr.head.sha, changeId: candidate.changeId, changeName: candidate.changeName, files: candidate.files, candidate, validation, runUrl, approvalKey: binding.key });
+  const reviewMarker = `${marker}review:${JSON.stringify(binding)} -->`;
+  const checkpointMarker = `${marker}checkpoint:${JSON.stringify(checkpoint)} -->`;
+  let prBody = pr.body ?? '';
+  prBody = prBody.includes('<!-- lighthouse-product-change-review:')
+    ? prBody.replace(/<!-- lighthouse-product-change-review:\{[^\n]*\} -->/g, reviewMarker)
+    : `${prBody}\n\n${reviewMarker}`;
+  prBody = prBody.includes('<!-- lighthouse-product-change-checkpoint:')
+    ? prBody.replace(/<!-- lighthouse-product-change-checkpoint:\{[^\n]*\} -->/g, checkpointMarker)
+    : `${prBody}\n${checkpointMarker}`;
+  await api(`pulls/${pr.number}`, 'PATCH', { body: prBody });
+  const previous = await api(`issues/${pr.number}/comments?per_page=100`);
+  const notice = previous.find(comment => comment.user?.login === 'github-actions[bot]' && comment.body?.includes(`Product decision: ${candidate.changeId}`));
+  if (notice) await api(`issues/comments/${notice.id}`, 'PATCH', { body });
+  else await api(`issues/${pr.number}/comments`, 'POST', { body });
+  const issueComments = await api(`issues/${snapshot.issue}/comments?per_page=100`);
+  const issueNotice = issueComments.find(comment => comment.user?.login === 'github-actions[bot]' && comment.body?.includes(`<!-- lighthouse-product-change-link:${candidate.proposalDigest} -->`));
+  const issueBody = `A draft Product Change is ready in [PR #${pr.number}](${pr.html_url}). Review the proposed behavior, affected product areas, decisions, trade-offs and validation evidence there. Approve the identified product proposal or request changes in that PR. Approval starts trusted ProductShape apply; this idea entry does not start implementation. PR merge remains separate.\n\n<!-- lighthouse-product-change-link:${candidate.proposalDigest} -->`;
+  if (issueNotice) await api(`issues/comments/${issueNotice.id}`, 'PATCH', { body: issueBody });
+  else await api(`issues/${snapshot.issue}/comments`, 'POST', { body: issueBody });
+  return { pullRequest: pr, binding, checkpoint, body, repositoryDefaultBranch: repositoryInfo.default_branch };
+}
+
+export async function applyApprovedProductChange({ root, changeName, checkpoint, approval, currentBinding, currentIdentity, bridge, headAfter, resultingModelDigest, reportBeforeWrite, publish }) {
+  const intent = authorizeProductApply({ checkpoint, approval, currentBinding, currentIdentity });
+  const provider = bridge ?? await loadProductBridge();
+  const manifest = join(root, 'openspec', 'changes', changeName, 'product-change', 'change.md');
+  const original = await readFile(manifest, 'utf8');
+  if (!/^status:\s*draft\s*$/m.test(original)) throw Error('Only a draft Product Change can enter the authenticated apply path');
+  await writeFile(manifest, original.replace(/^status:\s*draft\s*$/m, 'status: approved'));
+  await validateProductWorkspace(root, changeName, provider);
+  const preview = await provider.applyOpenSpecProductChange(root, changeName, { dryRun: true });
+  if (preview.outcome !== 'dry-run' || preview.plan?.changeId && preview.plan.changeId !== checkpoint.changeId) throw Error('ProductShape dry-run does not match the reviewed change');
+  const applied = await provider.applyOpenSpecProductChange(root, changeName, { reportBeforeWrite });
+  if (applied.outcome !== 'applied' || applied.change?.id !== checkpoint.changeId) throw Error('ProductShape apply was refused or returned a different change');
+  if ((applied.resultingModel?.diagnostics ?? []).some(item => item.severity === 'error')) throw Error('ProductShape resulting model has validation errors');
+  const computedDigest = await productModelDigest(root);
+  if (resultingModelDigest && resultingModelDigest !== computedDigest) throw Error('Product model changed while the apply receipt was being prepared');
+  const receipt = createProductApplyReceipt({ intent, approval, checkpoint, headAfter, resultingModelDigest: computedDigest, validated: true });
+  if (typeof publish !== 'function') throw Error('Trusted publisher is required for Product Change apply');
+  await publish(receipt, applied, { manifest, affectedCitations: applied.affectedCitations ?? [], resultingModelDigest: computedDigest });
+  return { receipt, applied, affectedCitations: applied.affectedCitations ?? [], resultingModelDigest: computedDigest };
+}
+
+export async function collectProductApplyFiles(root, changeName, baseRevision) {
+  const prefix = `openspec/changes/${changeName}/product-change/change.md`;
+  const modelRoot = await productModelDirectory(root);
+  const paths = execFileSync('git', ['diff', '--name-only', '--no-renames', baseRevision, '--', modelRoot, prefix], { cwd: root, encoding: 'utf8', maxBuffer: 128000 }).trim().split('\n').filter(Boolean).sort();
+  if (!paths.includes(prefix) || paths.length > 520 || paths.some(path => path !== prefix && !path.startsWith(`${modelRoot}/`))) throw Error('Trusted apply wrote outside the Product Change manifest and accepted model');
+  const files = [];
+  let bytes = 0;
+  for (const path of paths) {
+    const absolute = join(root, path);
+    const stat = await import('node:fs/promises').then(fs => fs.lstat(absolute));
+    if (!stat.isFile() || stat.isSymbolicLink()) throw Error(`Trusted apply produced a non-regular path: ${path}`);
+    if (stat.size > 65536) throw Error(`Trusted apply artifact exceeds its bound: ${path}`);
+    const content = await readFile(absolute, 'utf8');
+    bytes += Buffer.byteLength(content);
+    if (bytes > 8 * 1024 * 1024) throw Error('Trusted apply output exceeds its aggregate bound');
+    files.push({ path, content });
+  }
+  const manifest = files.find(file => file.path === prefix)?.content ?? '';
+  if (!/^status:\s*applied\s*$/m.test(manifest)) throw Error('Provider did not record the applied Product Change status');
+  return { files, modelRoot };
+}
+
+export function validateProductApplyFiles(files, changeName, modelRoot = 'docs/product/model') {
+  if (!safeRelative(modelRoot) || modelRoot.split('/').some(part => part.startsWith('.'))) throw Error('Product apply model root is unsafe');
+  const manifestPath = `openspec/changes/${changeName}/product-change/change.md`;
+  if (!Array.isArray(files) || !files.length || files.length > 520) throw Error('Product apply output file list is empty or exceeds its bound');
+  const seen = new Set(); let bytes = 0;
+  for (const file of files) {
+    if (!file || Object.keys(file).sort().join(',') !== 'content,path' || typeof file.path !== 'string' || typeof file.content !== 'string' || seen.has(file.path)) throw Error('Invalid or duplicated Product apply output file');
+    if (file.path !== manifestPath && !file.path.startsWith(`${modelRoot}/`)) throw Error(`Product apply output escaped the accepted model: ${file.path}`);
+    if (!safeRelative(file.path) || file.content.includes('\0')) throw Error(`Unsafe Product apply output: ${file.path}`);
+    const size = Buffer.byteLength(file.content);
+    if (size > 65536) throw Error(`Product apply output exceeds its file bound: ${file.path}`);
+    bytes += size;
+    if (bytes > 8 * 1024 * 1024) throw Error('Product apply output exceeds its aggregate bound');
+    seen.add(file.path);
+  }
+  const manifest = files.find(file => file.path === manifestPath)?.content ?? '';
+  if (!/^status:\s*applied\s*$/m.test(manifest)) throw Error('Product apply output does not retain the provider applied status');
+  return files;
+}
+
+const safeRelative = path => !path.startsWith('/') && !path.includes('\\') && !path.split('/').some(part => !part || part === '.' || part === '..');
+
+export async function publishProductApply(api, repository, owner, dispatch, result, beforeWrite) {
+  const approvalInfo = dispatch.request.productApproval;
+  if (dispatch.request.worker !== 'apply-product-change' || !approvalInfo || !result || result.head !== approvalInfo.head) throw Error('Product apply result does not match its authenticated dispatch');
+  const files = validateProductApplyFiles(result.files, approvalInfo.changeName, result.modelRoot);
+  const fresh = await loadProductApproval(api, { eventName: dispatch.request.eventName, event: dispatch.request.event, owner, repository, root: process.cwd() });
+  if (!fresh || fresh.head !== approvalInfo.head || fresh.pullRequest !== approvalInfo.pullRequest || fresh.approval.reviewKey !== approvalInfo.reviewKey || fresh.checkpoint.changeId !== result.receipt.changeId) throw Error('Product approval or reviewed branch changed before publication');
+  if (result.receipt.resultingModelDigest !== result.resultingModelDigest || result.receipt.baselineDigest !== fresh.checkpoint.baselineDigest || result.receipt.proposalDigest !== fresh.checkpoint.proposalDigest) throw Error('Product apply receipt does not match the approved candidate');
+  const pr = await api(`pulls/${fresh.pullRequest}`);
+  if (pr.head.sha !== fresh.head || pr.state !== 'open' || pr.merged || pr.head.repo?.full_name !== repository) throw Error('Product PR head changed before apply publication');
+  const commit = await api(`git/commits/${fresh.head}`);
+  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: apply product change ${fresh.checkpoint.changeId}`, tree: tree.sha, parents: [fresh.head] });
+  await beforeWrite(fresh);
+  await api(`git/refs/heads/${pr.head.ref}`, 'PATCH', { sha: created.sha, force: false });
+  const updated = await api(`pulls/${fresh.pullRequest}`);
+  const receipt = { ...result.receipt, headAfter: updated.head.sha };
+  let prBody = updated.body ?? '';
+  const checkpoint = { ...fresh.checkpoint, state: 'applied', identity: { ...fresh.checkpoint.identity, head: updated.head.sha }, effectIds: [...new Set([...fresh.checkpoint.effectIds, `apply:${receipt.intentId}:${updated.head.sha}`])].slice(0, 32) };
+  validateProductCheckpoint(checkpoint);
+  prBody = prBody.replace(/<!-- lighthouse-product-change-checkpoint:\{[^\n]*\} -->/g, `${marker}checkpoint:${JSON.stringify(checkpoint)} -->`);
+  await api(`pulls/${fresh.pullRequest}`, 'PATCH', { body: prBody });
+  const issueBody = `Product Change ${receipt.changeId} was applied to [PR #${fresh.pullRequest}](${updated.html_url}). The issue branch contains the provider-validated product model. Merge is still separate.\n\nAffected citations:\n${(result.affectedCitations ?? []).map(item => `- \`${item.document ?? item.file ?? item.id ?? 'consumer'}\`: ${item.status ?? 'refresh required'}`).join('\n') || '- None reported.'}\n\n<!-- lighthouse-product-apply:${JSON.stringify(receipt)} -->`;
+  const comments = await api(`issues/${fresh.issue}/comments?per_page=100`);
+  const prior = comments.find(comment => comment.user?.login === 'github-actions[bot]' && [...(comment.body ?? '').matchAll(/<!-- lighthouse-product-apply:(\{[^\n]*\}) -->/g)].some(match => JSON.parse(match[1]).intentId === receipt.intentId));
+  if (prior) await api(`issues/comments/${prior.id}`, 'PATCH', { body: issueBody });
+  else await api(`issues/${fresh.issue}/comments`, 'POST', { body: issueBody });
+  return { pullRequest: updated, receipt, checkpoint };
+}
+
+export function productApprovalFromGitHub({ eventName, event, owner, repository, currentBinding }) {
+  let source, actor, actorType, body, decisionId, submitted = true;
+  if (eventName === 'issue_comment' && event.action === 'created' && event.issue?.pull_request) {
+    source = 'pull-request-comment'; actor = event.comment?.user?.login; actorType = event.comment?.user?.type; body = event.comment?.body; decisionId = String(event.comment?.id);
+  } else if (eventName === 'pull_request_review' && event.action === 'submitted') {
+    source = 'pull-request-review'; actor = event.review?.user?.login; actorType = event.review?.user?.type; body = event.review?.body; decisionId = String(event.review?.id);
+  } else if (eventName === 'issue_comment' && event.action === 'created') {
+    source = 'issue-comment'; actor = event.comment?.user?.login; actorType = event.comment?.user?.type; body = event.comment?.body; decisionId = String(event.comment?.id);
+  } else submitted = false;
+  const decision = parseProductDecision(body);
+  if (!decision || decision.action !== 'approve') return null;
+  const pr = event.pull_request?.number ?? event.issue?.number;
+  if (currentBinding.repository !== repository || currentBinding.pullRequest !== pr) throw Error('Product approval targets another PR');
+  return verifyProductDecision({ decision, actor, actorType, owner, source, submitted, currentBinding, observedBinding: currentBinding, decisionId });
+}
+
+export async function loadProductApproval(api, { eventName, event, owner, repository, root }) {
+  let body, actor, actorType, source, decisionId;
+  if (eventName === 'issue_comment' && event.action === 'created' && event.issue?.pull_request) {
+    body = event.comment?.body; actor = event.comment?.user?.login; actorType = event.comment?.user?.type; source = 'pull-request-comment'; decisionId = String(event.comment?.id);
+  } else if (eventName === 'pull_request_review' && event.action === 'submitted') {
+    body = event.review?.body; actor = event.review?.user?.login; actorType = event.review?.user?.type; source = 'pull-request-review'; decisionId = String(event.review?.id);
+  } else return null;
+  const decision = parseProductDecision(body);
+  if (!decision || !['approve', 'request-changes', 'answer'].includes(decision.action)) return null;
+  const number = event.pull_request?.number ?? event.issue?.number;
+  const pr = await api(`pulls/${number}`);
+  if (pr.user?.login !== 'github-actions[bot]' || pr.user?.type !== 'Bot' || pr.state !== 'open' || pr.merged || pr.head?.repo?.full_name !== repository || pr.base?.repo?.full_name !== repository) throw Error('Product approval target is not a current Lighthouse PR');
+  const markers = [...(pr.body ?? '').matchAll(/<!-- lighthouse-product-change-review:(\{[^\n]*\}) -->/g)];
+  if (markers.length !== 1) throw Error('PR has no unique Product Change review binding');
+  const raw = JSON.parse(markers[0][1]);
+  const { key, ...fields } = raw;
+  const bound = productReviewBinding(fields);
+  if (bound.key !== key || bound.head !== pr.head.sha || bound.pullRequest !== pr.number || bound.repository !== repository) throw Error('Product Change review binding is stale or belongs to another PR');
+  const checkpoints = [...(pr.body ?? '').matchAll(/<!-- lighthouse-product-change-checkpoint:(\{[^\n]*\}) -->/g)];
+  if (checkpoints.length !== 1) throw Error('PR has no unique Product Change checkpoint');
+  const checkpoint = JSON.parse(checkpoints[0][1]);
+  const checkpointErrors = validateProductCheckpoint(checkpoint);
+  if (checkpointErrors.length || checkpoint.state !== 'waiting-product-decision' || checkpoint.changeName !== bound.changeName || checkpoint.changeId !== bound.changeId || checkpoint.proposalDigest !== bound.proposalDigest || checkpoint.baselineDigest !== bound.baselineDigest || checkpoint.identity.head !== pr.head.sha || checkpoint.identity.issue !== bound.issue || checkpoint.identity.repository !== repository || checkpoint.effectIds.length !== 1 || checkpoint.effectIds[0] !== `pr:${pr.number}:${pr.head.sha}`) throw Error('Product Change checkpoint is stale or invalid');
+  if (decision.changeName !== bound.changeName || decision.reviewKey !== bound.key) throw Error('Product approval action does not identify the current Product Change');
+  const candidate = await loadProductCandidateFromPullRequest(api, repository, pr, bound.changeName);
+  const repositoryInfo = await api('');
+  const defaultHead = (await api(`commits/${repositoryInfo.default_branch}`)).sha;
+  const accepted = await productModelDigestFromApi(api, defaultHead);
+  if (candidate.changeId !== bound.changeId || candidate.digest !== bound.proposalDigest || accepted.digest !== bound.baselineDigest) throw Error('Product Change proposal or accepted baseline changed after review');
+  const verified = verifyProductDecision({ decision, actor, actorType, owner, source, submitted: true, currentBinding: bound, observedBinding: bound, decisionId });
+  const issue = await api(`issues/${bound.issue}`);
+  if (issue.state !== 'open' || issue.labels?.some(label => ['future', 'human-working', 'agent-working'].includes(label.name))) throw Error('Product apply is blocked by the current issue state or reservation');
+  const feedback = decision.action === 'approve' ? null : { action: decision.action, changeName: decision.changeName, reviewKey: decision.reviewKey, text: decision.detail, sourceCommentId: decisionId, source: 'pull-request' };
+  return { ...(decision.action === 'approve' ? { approval: verified } : { feedback }), binding: bound, checkpoint, issue: bound.issue, pullRequest: pr.number, head: pr.head.sha, changeName: bound.changeName, candidate, modelRoot: accepted.modelRoot };
+}

package/src/product-change.mjs

@@ -0,0 +1,277 @@
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { cp, lstat, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve, sep } from 'node:path';
+import { tmpdir } from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+
+export const PRODUCT_CHANGE_SCHEMA_VERSION = 1;
+export const PRODUCT_CHANGE_WORKER = 'product-change';
+export const PRODUCT_FILE_LIMITS = Object.freeze({ files: 64, fileBytes: 65536, totalBytes: 524288 });
+const namePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const hashPattern = /^[a-f0-9]{64}$/;
+const revisionPattern = /^[a-f0-9]{40}$/;
+const require = createRequire(import.meta.url);
+const openspec = (cwd, args) => execFileSync('npx', ['--yes', '--package', '@fission-ai/openspec@1.15.0', 'openspec', ...args], { cwd, encoding: 'utf8', timeout: 120000, maxBuffer: 1024 * 1024, env: { ...process.env, OPENSPEC_TELEMETRY: '0', CI: 'true' } });
+
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const exact = (value, fields) => record(value) && Object.keys(value).every(key => fields.includes(key)) && fields.every(key => Object.hasOwn(value, key));
+const sha = value => createHash('sha256').update(value).digest('hex');
+const digest = sha;
+const safePath = value => typeof value === 'string' && !value.includes('\\') && !value.startsWith('/') && !/^[A-Za-z]:/.test(value) && value.split('/').every(part => part && part !== '.' && part !== '..');
+
+export function validateProductRequest(value) {
+  const errors = [];
+  if (!exact(value, ['schemaVersion', 'kind', 'identity', 'entry', 'idea', 'scope', 'createdAt', ...(['changeName'].filter(k => Object.hasOwn(value ?? {}, k))), ...(['feedback'].filter(k => Object.hasOwn(value ?? {}, k))) ])) return ['Product Change request has unsupported or missing fields'];
+  if (value.schemaVersion !== 1 || value.kind !== 'request') errors.push('Product Change request identity is unsupported');
+  if (!['idea', 'parent-handoff', 'feedback'].includes(value.entry)) errors.push('Product Change request entry is unsupported');
+  if (typeof value.idea !== 'string' || !value.idea.trim() || value.idea.length > 12000) errors.push('Product Change request idea must contain 1-12000 characters');
+  if (typeof value.scope !== 'string' || !value.scope.trim() || value.scope.length > 12000) errors.push('Product Change request scope must contain 1-12000 characters');
+  if (!Number.isFinite(Date.parse(value.createdAt))) errors.push('Product Change request createdAt must be a timestamp');
+  if (value.changeName !== undefined && !namePattern.test(value.changeName)) errors.push('Product Change request changeName must be a kebab-case OpenSpec name');
+  if (value.feedback !== undefined && (typeof value.feedback !== 'string' || value.feedback.length > 12000)) errors.push('Product Change request feedback exceeds its bound');
+  errors.push(...validateProductIdentity(value.identity));
+  if (value.entry === 'feedback' && (!value.changeName || !value.feedback?.trim())) errors.push('Product feedback must identify the existing change and contain feedback');
+  return errors;
+}
+
+export function validateProductChangeOutput(value) {
+  const fields = ['schemaVersion', 'outcome', 'entry', 'affectedAreas', 'decisions', ...(['changeName', 'changeId', 'files', 'question', '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.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');
+    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');
+    } 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 (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');
+  if (value.files !== undefined && value.outcome !== 'candidate') errors.push('only a candidate Product Change can include files');
+  return errors;
+}
+
+export async function productModelDigest(root) {
+  const modelRoot = await productModelDirectory(root);
+  const base = resolve(root, modelRoot);
+  const files = [];
+  async function collect(directory, relative = '') {
+    for (const entry of await (await import('node:fs/promises')).readdir(directory, { withFileTypes: true })) {
+      const path = relative ? `${relative}/${entry.name}` : entry.name;
+      const target = join(directory, entry.name), stat = await lstat(target);
+      if (stat.isSymbolicLink() || !stat.isDirectory() && !stat.isFile()) throw Error(`Unsafe accepted product model path: ${path}`);
+      if (stat.isDirectory()) await collect(target, path);
+      else {
+        if (files.length >= 512 || stat.size > 65536) throw Error('Accepted product model exceeds fingerprint bounds');
+        files.push({ path, content: await readFile(target) });
+      }
+    }
+  }
+  await collect(base);
+  return digest(files.sort((a, b) => a.path.localeCompare(b.path)).map(file => `${file.path}\0${sha(file.content)}\n`).join(''));
+}
+
+export async function productModelDirectory(root) {
+  let productRoot = 'docs/product';
+  try {
+    const config = await readFile(resolve(root, '.product/config.yaml'), 'utf8');
+    const declared = config.match(/^product-root:\s*(.*?)\s*$/m)?.[1]?.replace(/^(?:"(.*)"|'(.*)')$/, (_match, doubleQuoted, singleQuoted) => doubleQuoted ?? singleQuoted);
+    if (declared) productRoot = declared;
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (!safePath(productRoot) || productRoot.includes('\\') || productRoot.split('/').some(part => part.startsWith('.'))) throw Error('ProductShape product-root is unsafe');
+  return `${productRoot}/model`;
+}
+
+export function validateProductIdentity(value) {
+  if (!exact(value, ['repository', 'issue', 'parentRunId', 'authorizationDigest', 'policyDigest', 'workflowRevision', 'head'])) return ['Product Change identity has unsupported or missing fields'];
+  const errors = [];
+  if (typeof value.repository !== 'string' || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(value.repository)) errors.push('Product Change repository identity is invalid');
+  if (!Number.isSafeInteger(value.issue) || value.issue < 1) errors.push('Product Change issue identity is invalid');
+  if (typeof value.parentRunId !== 'string' || !value.parentRunId.trim() || value.parentRunId.length > 128) errors.push('Product Change parent run identity is invalid');
+  if (!hashPattern.test(value.authorizationDigest ?? '') || !hashPattern.test(value.policyDigest ?? '')) errors.push('Product Change authority and policy digests must be SHA-256');
+  if (!revisionPattern.test(value.workflowRevision ?? '') || !revisionPattern.test(value.head ?? '')) errors.push('Product Change revisions must be full commit SHAs');
+  return errors;
+}
+
+export function validateProductCheckpoint(value) {
+  const fields = ['schemaVersion', 'kind', 'identity', 'requestDigest', 'changeName', 'changeId', 'proposalDigest', 'baselineDigest', 'state', 'effectIds'];
+  const optional = ['pendingQuestion'];
+  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');
+  if (!namePattern.test(value.changeName ?? '') || !/^CHG-[A-Z0-9-]{1,156}$/.test(value.changeId ?? '')) errors.push('Product Change checkpoint identity is invalid');
+  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.pendingQuestion !== undefined && (typeof value.pendingQuestion !== 'string' || value.pendingQuestion.length > 4000)) errors.push('Product Change checkpoint pendingQuestion exceeds its bound');
+  return errors;
+}
+
+function parseStatus(path, content) {
+  if (!path.endsWith('/product-change/change.md')) return null;
+  const frontmatter = content.match(/^---\s*\n([\s\S]*?)\n---(?:\n|$)/);
+  if (!frontmatter) throw Error('Product Change manifest needs YAML frontmatter');
+  const status = frontmatter[1].match(/^status:\s*([A-Za-z-]+)\s*$/m)?.[1];
+  if (!status) throw Error('Product Change manifest needs a status');
+  if (!['draft', 'in-review', 'rejected', 'superseded'].includes(status)) throw Error(`Worker output cannot set Product Change status '${status}'`);
+  const changeId = frontmatter[1].match(/^id:\s*([A-Z0-9-]+)\s*$/m)?.[1];
+  if (!/^CHG-[A-Z0-9-]+$/.test(changeId ?? '')) throw Error('Product Change manifest needs a valid CHG ID');
+  return { status, changeId };
+}
+
+export function validateProductChangeFiles(files, { changeName, root = 'openspec/changes' } = {}) {
+  if (!namePattern.test(changeName ?? '')) throw Error('Product Change name must be lowercase kebab-case');
+  if (!Array.isArray(files) || !files.length || files.length > PRODUCT_FILE_LIMITS.files) throw Error('Product Change candidate must contain a bounded non-empty file list');
+  const seen = new Set();
+  let total = 0, manifest;
+  const base = `${root}/${changeName}/`;
+  for (const file of files) {
+    if (!exact(file, ['path', 'content', ...(['mode'].filter(key => Object.hasOwn(file ?? {}, key))) ])) throw Error('Product Change candidate file has unsupported or missing fields');
+    if (!safePath(file.path) || !file.path.startsWith(base)) throw Error(`Product Change file is outside its hosted change: ${file.path}`);
+    if (seen.has(file.path)) throw Error(`Duplicate Product Change path: ${file.path}`);
+    seen.add(file.path);
+    if (file.mode !== undefined && file.mode !== '100644' && file.mode !== '100755') throw Error(`Product Change file mode is not regular: ${file.path}`);
+    const relative = file.path.slice(base.length);
+    const allowed = relative === '.openspec.yaml' || relative === 'proposal.md' || relative === 'product-change/change.md' || relative === 'product-change/impact.json' || /^product-change\/proposed\/[A-Za-z0-9._/-]+\.(?:md|json|ya?ml)$/.test(relative);
+    if (!allowed || relative.split('/').some(part => part.startsWith('.'))) throw Error(`Unsupported Product Change file: ${file.path}`);
+    if (file.path.startsWith('docs/product/model/')) throw Error('Product Change candidates cannot write accepted model artifacts');
+    if (typeof file.content !== 'string') throw Error(`Product Change file content must be text: ${file.path}`);
+    const bytes = Buffer.byteLength(file.content, 'utf8');
+    if (bytes > PRODUCT_FILE_LIMITS.fileBytes) throw Error(`Product Change file exceeds its size bound: ${file.path}`);
+    total += bytes;
+    if (total > PRODUCT_FILE_LIMITS.totalBytes) throw Error('Product Change candidate exceeds its total size bound');
+    const parsed = parseStatus(file.path, file.content);
+    if (parsed) manifest = parsed;
+  }
+  if (!seen.has(`${base}.openspec.yaml`) || !manifest) throw Error('Product Change candidate needs its OpenSpec schema pin and provider manifest');
+  const spec = files.find(file => file.path === `${base}.openspec.yaml`)?.content;
+  if (!/^schema:\s*product-change\s*$/m.test(spec ?? '')) throw Error('Product Change must use the installed product-change schema');
+  if (!files.some(file => file.path.startsWith(`${base}product-change/proposed/`))) throw Error('Product Change candidate must include proposed provider artifacts');
+  const digestValue = sha([...files].sort((a, b) => a.path.localeCompare(b.path)).map(file => `${file.path}\0${sha(file.content)}\n`).join(''));
+  return { files: files.length, bytes: total, ...manifest, digest: digestValue };
+}
+
+export async function validateProductWorkspace(root, changeName, bridge) {
+  if (!bridge || typeof bridge.validateOpenSpecProductChange !== 'function') throw Error('Pinned ProductShape OpenSpec bridge is unavailable');
+  const result = await bridge.validateOpenSpecProductChange(resolve(root), changeName);
+  const blocking = result.blocking ?? [];
+  if (blocking.length) throw Error(`Product Change overlay validation failed: ${blocking.map(item => item.message ?? item.code).join('; ')}`);
+  return result;
+}
+
+export async function prepareProductChange(root, changeName, files, bridge) {
+  if (!namePattern.test(changeName ?? '')) throw Error('Product Change name must be lowercase kebab-case');
+  const temp = await mkdtemp(join(tmpdir(), 'lighthouse-product-workflow-'));
+  try {
+    const productRoot = dirname(await productModelDirectory(root));
+    for (const relative of [productRoot, '.product/config.yaml', 'openspec/config.yaml', 'openspec/schemas/product-change']) {
+      const source = join(root, relative), target = join(temp, relative);
+      await mkdir(dirname(target), { recursive: true });
+      await cp(source, target, { recursive: true, errorOnExist: true, force: false });
+    }
+    openspec(temp, ['new', 'change', changeName, '--schema', 'product-change', '--json']);
+    const rootPath = `openspec/changes/${changeName}`;
+    if (!files) {
+      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 };
+    }
+    const summary = validateProductChangeFiles(files, { changeName });
+    for (const file of files) {
+      const target = join(temp, file.path);
+      await mkdir(dirname(target), { recursive: true });
+      await writeFile(target, file.content);
+    }
+    openspec(temp, ['validate', changeName, '--strict', '--no-interactive']);
+    const validation = bridge ? await validateProductWorkspace(temp, changeName, bridge) : null;
+    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 };
+    }
+    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 };
+  } finally { await rm(temp, { recursive: true, force: true }); }
+}
+
+export async function loadProductBridge({ entry = process.env.PRODSHAPE_INTEGRATION_OPENSPEC_ENTRY } = {}) {
+  const spec = entry ?? require.resolve('@prodshape/integration-openspec');
+  const bridge = await import(spec.startsWith('/') ? pathToFileURL(spec).href : spec);
+  for (const name of ['validateOpenSpecProductChange', 'applyOpenSpecProductChange']) if (typeof bridge[name] !== 'function') throw Error(`Pinned ProductShape bridge does not provide ${name}`);
+  return bridge;
+}
+
+export function productReviewBinding(input) {
+  const fields = ['repository', 'issue', 'pullRequest', 'changeName', 'changeId', 'proposalDigest', 'baselineDigest', 'policyDigest', 'authorityDigest', 'head'];
+  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 (!revisionPattern.test(input.head ?? '')) throw Error('Product review head must be a full commit SHA');
+  const key = digest(JSON.stringify(input));
+  return { ...input, key };
+}
+
+export function parseProductDecision(text) {
+  const match = typeof text === 'string' && text.trim().match(/^\/product-change (approve|request-changes|answer) ([a-z0-9]+(?:-[a-z0-9]+)*) ([a-f0-9]{64})(?:\n([\s\S]{1,4000}))?$/);
+  if (!match) return null;
+  return { action: match[1], changeName: match[2], reviewKey: match[3], detail: match[4]?.trim() ?? '' };
+}
+
+export function verifyProductDecision({ decision, actor, owner, actorType = 'User', source, submitted = true, currentBinding, observedBinding, decisionId }) {
+  const errors = [];
+  if (!decision || !['approve', 'request-changes', 'answer'].includes(decision.action)) errors.push('Explicit Product Change action is required');
+  if (actor !== owner || actorType !== 'User') errors.push('Product Change decision must come from the authenticated repository owner');
+  if (!['pull-request-comment', 'pull-request-review', 'issue-comment'].includes(source) || submitted !== true) errors.push('Product Change decision must come from a newly submitted supported GitHub event');
+  if (!currentBinding || !observedBinding || currentBinding.key !== observedBinding.key || currentBinding.key !== decision?.reviewKey || currentBinding.changeName !== decision?.changeName) errors.push('Product Change decision does not match the current reviewed binding');
+  if (!decisionId || typeof decisionId !== 'string') errors.push('Product Change decision event identity is missing');
+  if (errors.length) throw Error(errors.join('; '));
+  return { schemaVersion: 1, kind: 'approval', actor, source, reviewKey: currentBinding.key, changeId: currentBinding.changeId, proposalDigest: currentBinding.proposalDigest, baselineDigest: currentBinding.baselineDigest, policyDigest: currentBinding.policyDigest, head: currentBinding.head, decisionId, observedAt: new Date().toISOString() };
+}
+
+export function authorizeProductApply({ checkpoint, approval, currentBinding, currentIdentity }) {
+  const errors = [...validateProductCheckpoint(checkpoint)];
+  if (!approval || approval.kind !== 'approval' || approval.schemaVersion !== 1) errors.push('Authenticated Product Change approval is required');
+  if (!currentBinding || !currentIdentity) errors.push('Fresh product authority and review observations are required');
+  else {
+    const { key: currentKey, ...bindingFields } = currentBinding;
+    const fresh = productReviewBinding(bindingFields);
+    if (currentKey !== fresh.key) errors.push('Current Product Change review binding is malformed');
+    if (fresh.key !== approval?.reviewKey) errors.push('Product Change approval is stale');
+    if (currentIdentity.repository !== checkpoint.identity.repository || currentIdentity.issue !== checkpoint.identity.issue || currentIdentity.parentRunId !== checkpoint.identity.parentRunId || currentIdentity.authorizationDigest !== checkpoint.identity.authorizationDigest || currentIdentity.policyDigest !== checkpoint.identity.policyDigest || currentIdentity.workflowRevision !== checkpoint.identity.workflowRevision || currentIdentity.head !== checkpoint.identity.head) errors.push('Product Change parent authority or branch head changed');
+  }
+  if (checkpoint.changeId !== approval?.changeId || checkpoint.proposalDigest !== approval?.proposalDigest || checkpoint.baselineDigest !== approval?.baselineDigest || checkpoint.state !== 'waiting-product-decision') errors.push('Product Change checkpoint does not match the approved candidate');
+  if (errors.length) throw Error(errors.join('; '));
+  return { intentId: digest(`${checkpoint.identity.repository}:${checkpoint.identity.issue}:${checkpoint.changeId}:${approval.reviewKey}:apply`), approvalDigest: digest(JSON.stringify(approval)) };
+}
+
+export function createProductApplyReceipt({ intent, approval, checkpoint, headAfter, resultingModelDigest, validated, appliedAt = new Date().toISOString() }) {
+  if (!intent || intent.intentId !== digest(`${checkpoint.identity.repository}:${checkpoint.identity.issue}:${checkpoint.changeId}:${approval.reviewKey}:apply`) || intent.approvalDigest !== digest(JSON.stringify(approval))) throw Error('Product apply intent does not match its approval');
+  if (!revisionPattern.test(headAfter ?? '') || !hashPattern.test(resultingModelDigest ?? '') || validated !== true || !Number.isFinite(Date.parse(appliedAt))) throw Error('Product apply result is not validated');
+  return { schemaVersion: 1, kind: 'apply-receipt', intentId: intent.intentId, approvalDigest: intent.approvalDigest, changeId: checkpoint.changeId, headBefore: checkpoint.identity.head, headAfter, proposalDigest: checkpoint.proposalDigest, baselineDigest: checkpoint.baselineDigest, resultingModelDigest, validated: true, appliedAt };
+}
+
+export function verifyProductChangePath(root, relativePath) {
+  if (!safePath(relativePath)) throw Error('Invalid Product Change path');
+  const absolute = resolve(root, relativePath);
+  const prefix = `${resolve(root)}${sep}`;
+  if (!absolute.startsWith(prefix)) throw Error('Product Change path escapes its workspace');
+  return lstat(absolute).then(stat => {
+    if (!stat.isFile() || stat.isSymbolicLink()) throw Error(`Product Change path is not a regular file: ${relativePath}`);
+    return absolute;
+  });
+}

package/src/proposal-review.mjs

@@ -21,7 +21,7 @@ export function checkProposal(pr, repo, expected) {
 export function checkImplementationPullRequest(pr, repo, expected) {
   const match = pr.head?.ref?.match(/^lighthouse\/implement-([1-9][0-9]*)-([a-f0-9]{12})$/);
   const marker = pr.body?.match(/<!-- lighthouse-implementation:([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 implementation PR');
+  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');
   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 };
 }