@juangcarmona/lighthouse-sdlc 0.15.1 → 0.16.0

package/src/opencode-execute.mjs

@@ -1,15 +1,16 @@
 // gh-aw engine adapter: one foreground container and optional host-owned test services.
-import { readFile, writeFile, mkdir, mkdtemp, readdir, copyFile, chmod, rm, lstat } from 'node:fs/promises';
+import { readFile, writeFile, appendFile, mkdir, mkdtemp, readdir, copyFile, chmod, rm, lstat } from 'node:fs/promises';
 import { dirname, join, resolve, isAbsolute } from 'node:path';
 import { openSync, closeSync, appendFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { spawn, execFileSync } from 'node:child_process';
 import { sourceFiles, collectChanges, materializeCandidate, validateChanges, changesDigest } from './implementation.mjs';
-import { prepareImplementationWorkspace, copyEvidence, runImplementationChecks } from './implementation-runtime.mjs';
+import { prepareImplementationWorkspace, copyEvidence, runImplementationChecks, restoreWorkspaceOwnership } from './implementation-runtime.mjs';
 import { validateStageEnvelope } from './host-contract.mjs';
 import { formatOpenCodeEvent, progressText, boundedEventLines } from './opencode-progress.mjs';
 import { selectEnvironment, startEnvironment, environmentArgs, environmentReceipt, redactEnvironmentLog } from './execution-environment.mjs';
 import { resolveModelProfile, modelExecutionReceipt } from './model-profiles.mjs';
+import { executionLimits, resourceArgs, imageCommand, executionReceipt, executionFailure } from './execution-resources.mjs';
 
 export function completionOutput(envelope, request) {
   const errors = validateStageEnvelope(envelope, request);
@@ -52,7 +53,8 @@ async function main() {
   const runDir = join(env.RUNNER_TEMP, `lighthouse-${env.GITHUB_RUN_ID}-${env.GITHUB_RUN_ATTEMPT}`);
   const request = JSON.parse(await readFile(join(runDir, 'request.json'), 'utf8'));
   // Sequential workers share the runner temp directory; only this stage's outputs may survive.
-  for (const file of ['envelope.json', 'runtime.json', 'changes.json', 'checks.json']) await rm(join(runDir, file), { force: true });
+  for (const file of ['envelope.json', 'runtime.json', 'changes.json', 'checks.json', 'engine-error.json']) await rm(join(runDir, file), { force: true });
+  const limits = executionLimits(config, request.stage === 'implement');
   let projectModels = null;
   try {
     const directory = join(env.GITHUB_WORKSPACE, '.lighthouse'), directoryStat = await lstat(directory);
@@ -62,7 +64,7 @@ async function main() {
     projectModels = JSON.parse(await readFile(path, 'utf8'));
   }
   catch (error) { if (error.code !== 'ENOENT') throw error; }
-  const modelSelection = resolveModelProfile({ project: projectModels, operator: config, worker: env.LIGHTHOUSE_WORKER ?? request.stage });
+  const modelSelection = resolveModelProfile({ project: projectModels, operator: config, worker: env.LIGHTHOUSE_WORKER ?? request.stage, ...(env.LIGHTHOUSE_MODEL_PROFILE ? { profile: env.LIGHTHOUSE_MODEL_PROFILE } : {}) });
   const selected = request.stage === 'implement' ? selectEnvironment(config, request.implementation?.environment) : null;
   if (request.stage === 'implement') {
     if (selected) config.implementationImage = selected.image;
@@ -77,9 +79,10 @@ async function main() {
   const implementing = request.stage === 'implement';
   const name = `lighthouse-engine-${request.runId}`;
   const docker = args => execFileSync('docker', args, { stdio: 'ignore', timeout: 30000 });
-  let child, timer, heartbeat, slot, baseline, trackedSource, runtime, cancelled = false;
-  const cancel = () => { cancelled = true; child?.kill('SIGTERM'); try { docker(['rm', '-f', name, `${name}-checks`]); } catch {} };
-  process.once('SIGTERM', cancel); process.once('SIGINT', cancel);
+  let child, timer, heartbeat, slot, baseline, trackedSource, runtime, cancelled = false, stopReason = null;
+  const cancel = (reason = 'cancelled') => { cancelled = true; stopReason ??= reason; child?.kill('SIGTERM'); try { docker(['rm', '-f', name, `${name}-checks`]); } catch {} };
+  const onSignal = () => cancel();
+  process.once('SIGTERM', onSignal); process.once('SIGINT', onSignal);
   try {
     console.log('Waiting for the operator host engine slot');
     slot = acquireEngineSlot(config.lock);
@@ -97,7 +100,7 @@ async function main() {
         await rm(source, { recursive: true, force: true }); await mkdir(source);
         await materializeCandidate(baseline, seed, source);
       }
-      await prepareImplementationWorkspace(source, config);
+      await prepareImplementationWorkspace(source, config, request.issue);
     }
     const context = join(dir, 'context.json');
     await copyFile(join(runDir, 'context.json'), context); await chmod(context, 0o444);
@@ -106,11 +109,13 @@ async function main() {
     await writeFile(prompt, await readFile(env.GH_AW_PROMPT, 'utf8') + completionBoundary, { mode: 0o444 });
     const harness = resolve(dirname(fileURLToPath(import.meta.url)), '..');
     const pkg = JSON.parse(await readFile(join(harness, 'package.json'), 'utf8'));
-    await writeFile(join(runDir, 'runtime.json'), JSON.stringify({ package: { name: pkg.name, version: pkg.version }, harnessRevision: execFileSync('git', ['-C', harness, 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim(), image: config.image, environment: environmentReceipt(selected), model: modelSelection.model, modelExecution: modelExecutionReceipt(modelSelection), engine: 'OpenCode 2.1.0', isolation: 'Docker; no AWF egress filtering', skills: await readdir(join(harness, 'skills')), sourceRevision: request.sourceRevision, seed: request.implementation?.policy.seed ?? null, seedDigest: request.seedDigest ?? null }));
-    const args = ['run', '--rm', '--init', '--name', name, '--user', `${config.uid}:${config.uid}`, '--cpus', '2', '--memory', implementing ? '4g' : '2g', '--pids-limit', implementing ? '256' : '128', '--cap-drop', 'ALL', '--security-opt', 'no-new-privileges', '--read-only',
+    const runtimeReceipt = { package: { name: pkg.name, version: pkg.version }, harnessRevision: execFileSync('git', ['-C', harness, 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim(), image: config.image, limits, environment: environmentReceipt(selected), model: modelSelection.model, modelExecution: modelExecutionReceipt(modelSelection), engine: 'OpenCode 2.1.0', isolation: 'Docker; no AWF egress filtering', skills: await readdir(join(harness, 'skills')), sourceRevision: request.sourceRevision, seed: request.implementation?.policy.seed ?? null, seedDigest: request.seedDigest ?? null };
+    await writeFile(join(runDir, 'runtime.json'), JSON.stringify(runtimeReceipt));
+    const command = imageCommand(config.image);
+    const args = ['run', '--rm', '--init', '--name', name, '--user', `${config.uid}:${config.uid}`, ...resourceArgs(limits), '--cap-drop', 'ALL', '--security-opt', 'no-new-privileges', '--read-only',
       '--tmpfs', '/tmp:rw,exec,size=1g,mode=1777', '--tmpfs', `/home/engine/.cache:rw,size=1g,uid=${config.uid},gid=${config.uid}`, '--tmpfs', `/home/engine/.config:rw,size=16m,uid=${config.uid},gid=${config.uid}`, '--tmpfs', `/home/engine/.local/state:rw,size=64m,uid=${config.uid},gid=${config.uid}`,
       '--mount', `type=bind,src=${source},dst=/workspace${implementing ? '' : ',readonly'}`, '--mount', `type=bind,src=${output},dst=/output`, '--mount', `type=bind,src=${context},dst=/input/context.json,readonly`, '--mount', `type=bind,src=${prompt},dst=/input/prompt.txt,readonly`, '--mount', `type=bind,src=${harness},dst=/harness,readonly`,
-      '--mount', `type=volume,src=${config.authVolume},dst=/home/engine/.local/share/opencode`, '--env', `ENGINE_SESSION=ses_${request.runId}`, '--env', `ENGINE_MODEL=${modelSelection.engineModel}`, '--env', `ENGINE_STAGE=${request.stage}`, '--env', 'NPM_CONFIG_CACHE=/tmp/npm-cache', '--env', 'PLAYWRIGHT_BROWSERS_PATH=/workspace/.cache/ms-playwright', ...environmentArgs(runtime), config.image];
+      '--mount', `type=volume,src=${config.authVolume},dst=/home/engine/.local/share/opencode`, '--env', `ENGINE_SESSION=ses_${request.runId}`, '--env', `ENGINE_MODEL=${modelSelection.engineModel}`, '--env', `ENGINE_STAGE=${request.stage}`, '--env', 'NPM_CONFIG_CACHE=/tmp/npm-cache', '--env', 'PLAYWRIGHT_BROWSERS_PATH=/workspace/.cache/ms-playwright', ...environmentArgs(runtime), '--entrypoint', 'node', config.image, '/harness/src/managed-command.mjs', 'run', '/output/execution', 'engine', '--', ...command];
     const eventsPath = join(env.RUNNER_TEMP, 'gh-aw', `opencode-events-${env.GITHUB_RUN_ID}-${env.GITHUB_RUN_ATTEMPT}.jsonl`);
     await mkdir(dirname(eventsPath), { recursive: true });
     await writeFile(eventsPath, '', { mode: 0o600 });
@@ -129,7 +134,7 @@ async function main() {
     heartbeat = setInterval(() => {
       if (Date.now() - lastVisible >= 30000) report(progressText('Run', `OpenCode is still running (${Math.floor((Date.now() - started) / 1000)}s elapsed). No new public update; waiting for the next event.`));
     }, 10000);
-    await new Promise((ok, no) => {
+    const exit = await new Promise((ok, no) => {
       child = spawn('docker', args, { stdio: ['ignore', 'pipe', 'pipe'] });
       const consume = line => {
         try {
@@ -146,9 +151,12 @@ async function main() {
         stream.on('data', chunk => { if (!cancelled) lines.write(chunk); });
         stream.on('end', () => { if (!cancelled) lines.end(); });
       }
-      child.on('error', no); child.on('close', code => code === 0 && !cancelled ? ok() : no(Error('OpenCode failed or was cancelled')));
-      timer = setTimeout(cancel, implementing ? 1800000 : 600000);
+      child.on('error', () => ok({ code: 127, signal: null })); child.on('close', (code, signal) => ok({ code, signal }));
+      timer = setTimeout(() => cancel('timeout'), implementing ? 1800000 : 600000);
     });
+    runtimeReceipt.execution = await executionReceipt(join(output, 'execution/engine.json'), exit, stopReason);
+    await writeFile(join(runDir, 'runtime.json'), JSON.stringify(runtimeReceipt));
+    if (exit.code !== 0 || cancelled || runtimeReceipt.execution.status !== 'passed') throw Error(executionFailure(runtimeReceipt.execution));
     if (engineError) throw Error('OpenCode reported an execution error; no model fallback attempted');
     const result = join(output, 'envelope.json'), stat = await lstat(result);
     if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 128000) throw Error('Invalid engine result file');
@@ -197,15 +205,22 @@ async function main() {
     }
     throw error;
   } finally {
-    clearTimeout(timer); clearInterval(heartbeat); process.removeListener('SIGTERM', cancel); process.removeListener('SIGINT', cancel);
+    clearTimeout(timer); clearInterval(heartbeat); process.removeListener('SIGTERM', onSignal); process.removeListener('SIGINT', onSignal);
     try { docker(['rm', '-f', name, `${name}-checks`]); } catch {}
     runtime?.cleanup();
     try { docker(['run', '--rm', '--network', 'none', '--user', `${config.uid}:${config.uid}`, '--cap-drop', 'ALL', '--security-opt', 'no-new-privileges', '--mount', `type=volume,src=${config.authVolume},dst=/home/engine/.local/share/opencode`, config.image, 'cleanup-session', `ses_${request.runId}`]); } catch { console.error('Session cleanup failed; operator inspection required'); }
     if (slot !== undefined) closeSync(slot);
-    if (implementing) {
-      try { docker(['run', '--rm', '--network', 'none', '--user', '0:0', '--mount', `type=bind,src=${dir},dst=/cleanup`, '--entrypoint', 'chown', config.image, '-R', `${process.getuid()}:${process.getgid()}`, '/cleanup']); } catch { console.error('Workspace ownership cleanup failed; operator inspection required'); }
-    }
+    // Read-only stages also create engine-owned command receipt directories.
+    try { restoreWorkspaceOwnership(dir, config); } catch { console.error('Workspace ownership cleanup failed; operator inspection required'); }
     await rm(dir, { recursive: true, force: true });
   }
 }
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main().catch(error => { console.error(progressText('Engine error', redactLog(error.message))); process.exitCode = 1; });
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main().catch(async error => {
+  const message = redactLog(error.message);
+  console.error(progressText('Engine error', message));
+  try { await writeFile(join(process.env.RUNNER_TEMP, `lighthouse-${process.env.GITHUB_RUN_ID}-${process.env.GITHUB_RUN_ATTEMPT}`, 'engine-error.json'), JSON.stringify({ schemaVersion: 1, message: message.slice(0, 3000) })); } catch {}
+  if (process.env.GITHUB_STEP_SUMMARY) {
+    try { await appendFile(process.env.GITHUB_STEP_SUMMARY, `\n### Execution failed\n\n${message.replaceAll('<', '&lt;').replaceAll('>', '&gt;')}\n\nInspect runtime.json and the retained engine events before retrying.\n`); } catch {}
+  }
+  process.exitCode = 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 };
+}