@juangcarmona/lighthouse-sdlc 0.13.0 → 0.15.0

package/src/model-profiles.mjs

@@ -0,0 +1,58 @@
+// Selection is configuration, never authority or proof of provider access.
+export const MODEL_PROFILES = Object.freeze(['plan', 'build', 'fast']);
+export const REASONING_EFFORTS = Object.freeze(['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const own = (value, key) => Object.hasOwn(value ?? {}, key);
+function keys(value, allowed, label) {
+  if (!record(value) || Object.keys(value).some(key => !allowed.includes(key))) throw Error(`Invalid ${label}`);
+}
+function validateSettings(value, operator = false) {
+  keys(value, ['schemaVersion', 'profiles', 'workers', 'defaultProfile', ...(operator ? ['enabled'] : [])], 'model profile configuration');
+  if (value.schemaVersion !== 1) throw Error('Model profiles require schemaVersion 1');
+  if (operator && typeof value.enabled !== 'boolean') throw Error('Operator model profiles require explicit enabled');
+  if (own(value, 'defaultProfile') && !MODEL_PROFILES.includes(value.defaultProfile)) throw Error('Invalid default model profile');
+  if (own(value, 'profiles')) {
+    keys(value.profiles, MODEL_PROFILES, 'profile names');
+    for (const profile of Object.values(value.profiles)) {
+      keys(profile, ['model', 'reasoningEffort'], 'model profile settings');
+      if (own(profile, 'model') && !/^openai\/[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(profile.model)) throw Error('Profile model must be an OpenAI provider/model identifier without a variant');
+      if (own(profile, 'reasoningEffort') && !REASONING_EFFORTS.includes(profile.reasoningEffort)) throw Error('Invalid reasoning effort');
+    }
+  }
+  if (own(value, 'workers')) {
+    if (!record(value.workers) || Object.entries(value.workers).some(([worker, profile]) => !/^[a-z][a-z0-9-]{0,63}$/.test(worker) || !MODEL_PROFILES.includes(profile))) throw Error('Invalid worker profile assignments');
+  }
+  return value;
+}
+
+export function resolveModelProfile({ project = null, operator, worker, profile } = {}) {
+  if (!record(operator)) throw Error('Operator model configuration required');
+  if (project !== null) validateSettings(project);
+  const local = operator.modelProfiles;
+  if (local !== undefined) validateSettings(local, true);
+  if (!local?.enabled) {
+    if (profile !== undefined) throw Error('Delegated profiles require operator opt-in');
+    if (typeof operator.model !== 'string' || !operator.model.trim() || /[\0\r\n]/.test(operator.model)) throw Error('Legacy operator model required');
+    return { mode: 'legacy', profile: null, model: operator.model, reasoningEffort: null, engineModel: operator.model, source: 'operator.model', capabilityEvidence: 'not-checked-legacy' };
+  }
+  if (profile !== undefined && !MODEL_PROFILES.includes(profile)) throw Error('Invalid requested model profile');
+  const choices = [[profile, 'task.profile'], [own(local.workers, worker) ? local.workers[worker] : undefined, 'operator.workers'], [own(project?.workers, worker) ? project.workers[worker] : undefined, 'project.workers'], [local.defaultProfile, 'operator.defaultProfile'], [project?.defaultProfile, 'project.defaultProfile']];
+  const choice = choices.find(([name]) => name !== undefined);
+  if (!choice) throw Error('No model profile assigned to worker');
+  const [name, source] = choice;
+  const base = project?.profiles?.[name] ?? {}, override = local.profiles?.[name] ?? {};
+  const selected = { ...base, ...override };
+  if (!selected.model || !selected.reasoningEffort) throw Error(`Incomplete model profile: ${name}`);
+  const capability = operator.modelCapabilities?.[selected.model];
+  if (!record(capability) || capability.available !== true || capability.tools !== true || !Array.isArray(capability.reasoningEfforts) || !capability.reasoningEfforts.includes(selected.reasoningEffort)) throw Error(`Model or reasoning unavailable in operator capabilities: ${name}`);
+  return { mode: 'profile', profile: name, ...selected, engineModel: `${selected.model}#${selected.reasoningEffort}`, source, fields: { model: own(override, 'model') ? 'operator' : 'project', reasoningEffort: own(override, 'reasoningEffort') ? 'operator' : 'project' }, capabilityEvidence: 'operator-configuration-only' };
+}
+
+export function modelExecutionReceipt(selection) {
+  return {
+    requested: { profile: selection.profile, model: selection.model, reasoningEffort: selection.reasoningEffort },
+    resolved: selection,
+    providerReported: { model: null, reasoningEffort: null, status: 'unverified', reason: 'The current adapter has no authenticated provider-settings receipt' },
+    billing: { route: 'unchanged', actualCost: null, estimatedApiEquivalentCost: null, subscriptionUsage: null },
+  };
+}

package/src/opencode-execute.mjs

@@ -1,13 +1,15 @@
-// gh-aw engine adapter: one foreground container, no service or orchestration state.
+// 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 { 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 { writableTree, copyEvidence, runImplementationChecks } from './implementation-runtime.mjs';
+import { prepareImplementationWorkspace, copyEvidence, runImplementationChecks } 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';
 
 export function completionOutput(envelope, request) {
   const errors = validateStageEnvelope(envelope, request);
@@ -49,7 +51,21 @@ async function main() {
   if (!/^sha256:[a-f0-9]{64}$/.test(config.image) || !/^[\w-]+$/.test(config.authVolume) || !Number.isInteger(config.uid)) throw Error('Invalid operator engine configuration');
   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 });
+  let projectModels = null;
+  try {
+    const directory = join(env.GITHUB_WORKSPACE, '.lighthouse'), directoryStat = await lstat(directory);
+    if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink()) throw Error('Invalid project model configuration directory');
+    const path = join(directory, 'models.json'), stat = await lstat(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 65536) throw Error('Invalid project model configuration file');
+    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 selected = request.stage === 'implement' ? selectEnvironment(config, request.implementation?.environment) : null;
   if (request.stage === 'implement') {
+    if (selected) config.implementationImage = selected.image;
     if (!/^sha256:[a-f0-9]{64}$/.test(config.implementationImage ?? '')) throw Error('Operator must provision and pin an implementation image');
     config.image = config.implementationImage;
   }
@@ -61,12 +77,14 @@ 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, cancelled = false;
+  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);
   try {
     console.log('Waiting for the operator host engine slot');
     slot = acquireEngineSlot(config.lock);
+    runtime = await startEnvironment({ selected, name: `${name}-agent`, uid: config.uid });
+    if (cancelled) throw Error('Execution cancelled before agent startup');
     console.log('Engine slot acquired; starting isolated OpenCode');
     await snapshotSource(env.GITHUB_WORKSPACE, source);
     baseline = implementing ? await sourceFiles(source) : null;
@@ -79,28 +97,30 @@ async function main() {
         await rm(source, { recursive: true, force: true }); await mkdir(source);
         await materializeCandidate(baseline, seed, source);
       }
-      await writableTree(source);
+      await prepareImplementationWorkspace(source, config);
     }
     const context = join(dir, 'context.json');
     await copyFile(join(runDir, 'context.json'), context); await chmod(context, 0o444);
     const prompt = join(dir, 'prompt.txt');
-    const completionBoundary = '\n\n# Completion in this custom engine adapter\nThe trusted host, outside this container, records the gh-aw terminal noop after validating /output/envelope.json. The safeoutputs CLI and /tmp/gh-aw/agent instructions describe host duties in this integration. Their absence inside the engine is expected, not an unavailable product check. Write the envelope and stop; do not install or invoke safeoutputs.\n';
+    const completionBoundary = '\n\n# Completion in this custom engine adapter\nThe trusted host, outside this container, records the gh-aw terminal noop after validating /output/envelope.json. The safeoutputs CLI and /tmp/gh-aw/agent instructions describe host duties in this integration. Their absence inside the engine is expected, not an unavailable product check. Read /harness/skills/concise-results/SKILL.md when writing effect.body. Write the envelope and stop; do not install or invoke safeoutputs.\n';
     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, model: config.model, 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({ 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',
-      '--tmpfs', '/tmp:rw,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}`,
+      '--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=${config.model}`, '--env', `ENGINE_STAGE=${request.stage}`, '--env', 'NPM_CONFIG_CACHE=/tmp/npm-cache', '--env', 'PLAYWRIGHT_BROWSERS_PATH=/workspace/.cache/ms-playwright', 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), config.image];
     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 });
     const started = Date.now();
-    let lastVisible = started;
-    const report = text => { lastVisible = Date.now(); console.log(redactLog(text)); };
+    let lastVisible = started, engineError = false;
+    const redact = text => redactLog(redactEnvironmentLog(runtime, text));
+    const report = text => { lastVisible = Date.now(); console.log(redact(text)); };
     const eventLine = line => {
-      const redacted = redactLog(line);
+      const redacted = redact(line);
+      try { if (JSON.parse(redacted).type === 'error') engineError = true; } catch {}
       appendFileSync(eventsPath, redacted + '\n');
       const visible = formatOpenCodeEvent(redacted);
       if (visible) report(visible);
@@ -129,6 +149,7 @@ async function main() {
       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);
     });
+    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');
     const envelope = JSON.parse(await readFile(result, 'utf8'));
@@ -141,7 +162,8 @@ async function main() {
       const candidate = join(dir, 'candidate'); await mkdir(candidate);
       await materializeCandidate(baseline, changes, candidate);
       const checkBaseline = await sourceFiles(candidate);
-      const receipt = await runImplementationChecks({ config, request, changes, workspace: candidate, output: join(runDir, 'evidence', 'host'), name, redact: redactLog, cancelled: () => cancelled });
+      if (runtime.cleanup() === false) throw Error('Agent test service cleanup failed; operator action required');
+      const receipt = await runImplementationChecks({ config, request, changes, workspace: candidate, output: join(runDir, 'evidence', 'host'), name, redact: redactLog, cancelled: () => cancelled, selected });
       if (collectChanges(checkBaseline, await sourceFiles(candidate, checkBaseline), request.implementation.policy).length) { receipt.checks.at(-1).exitCode = 1; receipt.checks.at(-1).reason = 'Checks modified source; candidate not validated'; }
       await writeFile(join(runDir, 'checks.json'), JSON.stringify(receipt));
       if (request.implementation.policy.reviewRequired) {
@@ -177,6 +199,7 @@ async function main() {
   } finally {
     clearTimeout(timer); clearInterval(heartbeat); process.removeListener('SIGTERM', cancel); process.removeListener('SIGINT', cancel);
     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) {

package/src/pr-state-actions.mjs

@@ -0,0 +1,106 @@
+import { readFile } from 'node:fs/promises';
+import { checkImplementationPullRequest } from './proposal-review.mjs';
+import { authorizedCiCallback, projectImplementationPrState, reconcileImplementationPr, scheduledImplementationPulls, setPullRequestDraft } from './pr-state.mjs';
+
+const apiFor = (repo, token) => async (path, method = 'GET', body, optional = false) => {
+  const response = await fetch(`https://api.github.com/repos/${repo}${path ? `/${path}` : ''}`, {
+    method, headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28', ...(body ? { 'Content-Type': 'application/json' } : {}) },
+    ...(body ? { body: JSON.stringify(body) } : {}), signal: AbortSignal.timeout(30000),
+  });
+  if (optional && response.status === 404) return null;
+  if (!response.ok) throw Error(`GitHub ${method} ${path}: ${response.status}`);
+  return response.status === 204 ? null : response.json();
+};
+const commentsFor = async (api, issue) => {
+  const comments = [];
+  for (let page = 1; page <= 10; page++) {
+    const batch = await api(`issues/${issue}/comments?per_page=100&page=${page}`);
+    comments.push(...batch);
+    if (batch.length < 100) return comments;
+  }
+  throw Error('Issue comment history exceeds bound');
+};
+const requiredChecks = profile => {
+  const checks = profile.requiredChecks;
+  if (!Array.isArray(checks) || !checks.length || checks.length > 20 || checks.some(item => !item.context || item.integrationId !== null && !Number.isSafeInteger(item.integrationId))) throw Error('Invalid required-check profile');
+  return checks.map(item => ({ context: item.context, app: item.integrationId }));
+};
+async function main() {
+  const env = process.env, repo = env.GITHUB_REPOSITORY, owner = env.GITHUB_REPOSITORY_OWNER;
+  if (!/^[\w.-]+\/[\w.-]+$/.test(repo ?? '') || !env.GH_TOKEN) throw Error('Missing repository or token');
+  const api = apiFor(repo, env.GH_TOKEN);
+  const event = JSON.parse(await readFile(env.GITHUB_EVENT_PATH, 'utf8'));
+  const metadata = await api('');
+  const config = await api(`contents/.lighthouse/github.json?ref=${metadata.default_branch}`, 'GET', undefined, true);
+  if (!config) return;
+  const profile = JSON.parse(Buffer.from(config.content, 'base64').toString());
+  if (profile.repository !== repo) throw Error('Repository profile differs from the event');
+  let candidates = [];
+  const ciCallback = env.GITHUB_EVENT_NAME === 'workflow_dispatch' && env.LIGHTHOUSE_CI_RECONCILE === 'true';
+  if (env.GITHUB_EVENT_NAME === 'pull_request') {
+    if (env.GITHUB_ACTOR !== owner || !['ready_for_review', 'converted_to_draft', 'closed', 'reopened'].includes(event.action)) return;
+    candidates = [event.pull_request?.number];
+  } else if (env.GITHUB_EVENT_NAME === 'workflow_run') {
+    const id = event.workflow_run?.id;
+    if (event.action !== 'completed' || !Number.isSafeInteger(id)) return;
+    const run = await api(`actions/runs/${id}`);
+    if (run.status !== 'completed' || run.conclusion !== 'success' || run.head_sha !== event.workflow_run.head_sha || run.repository?.full_name !== repo || !profile.completion?.postMergeWorkflows?.some(name => run.path === `.github/workflows/${name}`)) return;
+    const pulls = await api(`commits/${run.head_sha}/pulls?per_page=100`);
+    if (pulls.length >= 100) throw Error('PR lookup exceeds bound');
+    candidates = pulls.filter(pr => pr.head?.sha === run.head_sha).map(pr => pr.number);
+  } else if (env.GITHUB_EVENT_NAME === 'schedule') {
+    candidates = await scheduledImplementationPulls(api);
+  } else if (ciCallback) {
+    const id = Number(env.GITHUB_RUN_ID);
+    if (!Number.isSafeInteger(id) || !/^[a-f0-9]{40}$/.test(env.GITHUB_SHA ?? '')) throw Error('CI callback lacks a run or head');
+    const run = await api(`actions/runs/${id}`);
+    if (!authorizedCiCallback(run, { id, sha: env.GITHUB_SHA, repo, workflows: profile.completion?.postMergeWorkflows })) return;
+    const pulls = await api(`commits/${run.head_sha}/pulls?per_page=100`);
+    if (pulls.length >= 100) throw Error('PR lookup exceeds bound');
+    candidates = pulls.filter(pr => pr.head?.sha === run.head_sha).map(pr => pr.number);
+  } else return;
+  for (const number of candidates) {
+    if (!Number.isSafeInteger(number)) continue;
+    const pr = await api(`pulls/${number}`);
+    if (env.GITHUB_EVENT_NAME === 'pull_request' && pr.head.sha !== event.pull_request.head.sha) continue;
+    if (env.GITHUB_EVENT_NAME === 'workflow_run' && pr.head.sha !== event.workflow_run.head_sha) continue;
+    if (ciCallback && pr.head.sha !== env.GITHUB_SHA) continue;
+    if (pr.base.ref !== metadata.default_branch) continue;
+    let target;
+    try { target = checkImplementationPullRequest({ ...pr, state: 'open', merged: false }, repo); }
+    catch {
+      const match = pr.head.ref.match(/^lighthouse\/implement-([1-9][0-9]*)-[a-f0-9]{12}$/);
+      if (!match || pr.user?.login !== 'github-actions[bot]' || pr.head.repo?.full_name !== repo || pr.base.repo?.full_name !== repo || pr.state !== 'open') continue;
+      const issue = await api(`issues/${match[1]}`);
+      if (issue.state !== 'open') continue;
+      if (!pr.draft) await setPullRequestDraft(env.GH_TOKEN, pr, true);
+      await projectImplementationPrState(api, issue.number, true);
+      const notice = `<!-- lighthouse-pr-link-changed:${pr.number}:${pr.head.sha} -->`;
+      if (!(await commentsFor(api, issue.number)).some(comment => comment.user?.login === 'github-actions[bot]' && comment.body?.includes(notice))) await api(`issues/${issue.number}/comments`, 'POST', { body: `PR #${pr.number} is back in draft because its Lighthouse link changed. Restore the PR description before review. [Open PR](${pr.html_url}).\n\n${notice}` });
+      continue;
+    }
+    const issue = await api(`issues/${target.issue}`);
+    if (issue.state !== 'open') continue;
+    if (pr.state !== 'open' || pr.merged) {
+      for (const name of ['pr-draft', 'pr-ready']) if (issue.labels.some(label => label.name === name)) await api(`issues/${issue.number}/labels/${name}`, 'DELETE', undefined, true);
+      if (!pr.merged) {
+        await api(`issues/${issue.number}/labels`, 'POST', { labels: ['waiting-review'] });
+        const notice = `<!-- lighthouse-pr-closed:${pr.number}:${pr.head.sha} -->`;
+        if (!(await commentsFor(api, issue.number)).some(comment => comment.user?.login === 'github-actions[bot]' && comment.body?.includes(notice))) await api(`issues/${issue.number}/comments`, 'POST', { body: `PR #${pr.number} was closed without merging. Reopen it or request a new implementation. [Open PR](${pr.html_url}).\n\n${notice}` });
+      }
+      continue;
+    }
+    const comments = await commentsFor(api, target.issue);
+    if (event.action === 'converted_to_draft') {
+      const hold = `<!-- lighthouse-pr-hold:${pr.number}:${pr.head.sha} -->`;
+      if (!comments.some(comment => comment.user?.login === 'github-actions[bot]' && comment.body?.includes(hold))) await api(`issues/${target.issue}/comments`, 'POST', { body: `PR #${pr.number} is a draft by owner choice. [Open PR](${pr.html_url}).\n\n${hold}` });
+      await projectImplementationPrState(api, target.issue, true);
+      continue;
+    }
+    const hold = comments.some(comment => comment.user?.login === 'github-actions[bot]' && comment.body?.includes(`<!-- lighthouse-pr-hold:${pr.number}:${pr.head.sha} -->`));
+    const auto = (['workflow_run', 'schedule'].includes(env.GITHUB_EVENT_NAME) || ciCallback) && !hold;
+    const result = await reconcileImplementationPr(api, repo, pr, issue, comments, requiredChecks(profile), (current, draft) => setPullRequestDraft(env.GH_TOKEN, current, draft), { auto });
+    if (event.action === 'ready_for_review' && result.status === 'draft') await api(`issues/${target.issue}/comments`, 'POST', { body: `PR #${pr.number} remains a draft: ${result.reason}. [Open PR](${pr.html_url}).` });
+  }
+}
+main().catch(error => { console.error(`::error::${error.message}`); process.exitCode = 1; });

package/src/pr-state.mjs

@@ -0,0 +1,75 @@
+import { checkImplementationPullRequest } from './proposal-review.mjs';
+import { checkCommit } from './completion.mjs';
+
+const marker = /<!-- lighthouse-pr-state:(\{[^\n]*\}) -->/;
+
+export async function scheduledImplementationPulls(api) {
+  const numbers = [];
+  for (let page = 1; page <= 10; page++) {
+    const pulls = await api(`pulls?state=open&per_page=100&page=${page}`);
+    numbers.push(...pulls.filter(pr => /^lighthouse\/implement-[1-9][0-9]*-[a-f0-9]{12}$/.test(pr.head?.ref ?? '') && pr.user?.login === 'github-actions[bot]').map(pr => pr.number));
+    if (pulls.length < 100) return numbers;
+  }
+  throw Error('Open PR history exceeds reconciliation bound');
+}
+
+export function authorizedCiCallback(run, { id, sha, repo, workflows }) {
+  return Number.isSafeInteger(id) && /^[a-f0-9]{40}$/.test(sha ?? '') && run.id === id && run.event === 'workflow_dispatch' && run.head_sha === sha && run.repository?.full_name === repo && workflows?.some(name => run.path === `.github/workflows/${name}`) === true;
+}
+
+export async function setPullRequestDraft(token, pr, draft) {
+  if (!pr.node_id) throw Error('PR lacks GraphQL identity');
+  const field = draft ? 'convertPullRequestToDraft' : 'markPullRequestReadyForReview';
+  const response = await fetch('https://api.github.com/graphql', {
+    method: 'POST', headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ query: `mutation($id:ID!){${field}(input:{pullRequestId:$id}){pullRequest{id isDraft}}}`, variables: { id: pr.node_id } }),
+    signal: AbortSignal.timeout(30000),
+  });
+  const result = await response.json();
+  if (!response.ok || result.errors?.length || result.data?.[field]?.pullRequest?.isDraft !== draft) throw Error('GitHub could not change PR draft state');
+}
+
+export function implementationPrProof(comments, pr) {
+  for (const comment of [...comments].reverse()) {
+    if (comment.user?.login !== 'github-actions[bot]' || comment.user.type !== 'Bot') continue;
+    const raw = comment.body?.match(marker)?.[1];
+    if (!raw) continue;
+    let proof;
+    try { proof = JSON.parse(raw); } catch { continue; }
+    if (proof.pr === pr.number && proof.head === pr.head.sha && typeof proof.complete === 'boolean' && /^[1-9][0-9]*$/.test(String(proof.run))) return proof;
+  }
+  return null;
+}
+
+export async function projectImplementationPrState(api, issue, draft) {
+  const current = await api(`issues/${issue}`);
+  if (current.state !== 'open') return;
+  const wanted = draft ? 'pr-draft' : 'pr-ready';
+  for (const label of ['ready', 'waiting-review', draft ? 'pr-ready' : 'pr-draft']) {
+    if (current.labels.some(item => item.name === label)) await api(`issues/${issue}/labels/${label}`, 'DELETE', undefined, true);
+  }
+  if (!current.labels.some(item => item.name === wanted)) await api(`issues/${issue}/labels`, 'POST', { labels: [wanted] });
+}
+
+export async function reconcileImplementationPr(api, repo, pr, issue, comments, requiredChecks, setDraft, { auto = false } = {}) {
+  const target = checkImplementationPullRequest(pr, repo);
+  if (target.issue !== issue.number || issue.state !== 'open') return { status: 'ignored', reason: 'Issue or PR changed' };
+  const proof = implementationPrProof(comments, pr);
+  const checks = await checkCommit(api, pr.head.sha, requiredChecks);
+  const reserved = issue.labels.some(label => ['agent-working', 'human-working'].includes(label.name));
+  const complete = !reserved && proof?.complete === true && checks.length > 0 && checks.every(check => check.status === 'passed');
+  if (pr.draft && auto && complete) {
+    try { await setDraft(pr, false); }
+    catch (error) { if ((await api(`pulls/${pr.number}`)).draft) throw error; }
+    await projectImplementationPrState(api, issue.number, false);
+    return { status: 'ready', reason: 'Candidate and required checks passed' };
+  }
+  if (!pr.draft && !complete) {
+    try { await setDraft(pr, true); }
+    catch (error) { if (!(await api(`pulls/${pr.number}`)).draft) throw error; }
+    await projectImplementationPrState(api, issue.number, true);
+    return { status: 'draft', reason: reserved ? 'Implementation or owner work is still active' : !proof?.complete ? 'Implementation is incomplete' : 'Required checks have not passed' };
+  }
+  await projectImplementationPrState(api, issue.number, pr.draft);
+  return { status: pr.draft ? 'draft' : 'ready', reason: pr.draft ? 'PR is a draft' : 'Candidate and required checks passed' };
+}

package/src/process-publication.mjs

@@ -25,7 +25,7 @@ export function completionBundle(request, envelope, receipt) {
     'receipt.json': json(receipt),
     'stage-result.json': json(envelope.result),
   };
-  const record = { schemaVersion: 1, id: `completion:${request.runId}`, runId: request.runId, kind: 'stage-result', scope: 'delivery', status: envelope.result.status === 'passed' ? 'passed' : 'pending-review', producer: 'Lighthouse GitHub Actions completion adapter', subject: { type: 'issue', id: observation.issueUrl }, observedAt: request.observedAt, artifacts: Object.entries(files).map(([path, content]) => ({ type: path.endsWith('.md') ? 'report' : 'receipt', path, sha256: digest(content) })), payload: { stage: request.stage, priorIntegration, binding: observation.binding, requiredChecks: observation.checks, observedChecks: observation.observedChecks, finalization: observation.finalization, receipt, checkSource: 'GitHub REST API', workflow: { runId: request.workflowRunId, attempt: request.attempt, url: request.runUrl, harnessRevision: request.harnessRevision } }, nextAction: envelope.result.nextAction };
+  const record = { schemaVersion: 1, id: `completion:${request.runId}`, runId: request.runId, kind: 'stage-result', scope: 'delivery', status: envelope.result.status === 'passed' ? 'passed' : 'pending-review', producer: 'Lighthouse GitHub Actions completion adapter', subject: { type: 'issue', id: observation.issueUrl }, observedAt: request.observedAt, artifacts: Object.entries(files).map(([path, content]) => ({ type: path.endsWith('.md') ? 'report' : 'receipt', path, sha256: digest(content) })), payload: { stage: request.stage, priorIntegration, binding: observation.binding, requiredChecks: observation.checks, observedChecks: observation.observedChecks, finalization: observation.finalization, receipt, checkSource: 'GitHub REST API', workflow: { ...(request.dispatchOrigin ? { dispatchOrigin: request.dispatchOrigin } : {}), runId: request.workflowRunId, attempt: request.attempt, url: request.runUrl, harnessRevision: request.harnessRevision } }, nextAction: envelope.result.nextAction };
   const errors = validateEvidenceRecord(record); if (errors.length) throw Error(JSON.stringify(errors));
   files['evidence-record.json'] = JSON.stringify(record);
   const { index, errors: buildErrors } = buildEvidenceIndex([record], { runId: request.runId, repository: observation.binding.repository, revision: receipt.sha ?? observation.binding.head, recordPaths: { [record.id]: 'evidence-record.json' } });

package/src/profile-delegation.mjs

@@ -0,0 +1,111 @@
+import { randomUUID } from 'node:crypto';
+import { validateLaunchRequest } from './control-plane.mjs';
+import { withinScope } from './implementation.mjs';
+import { resolveModelProfile, modelExecutionReceipt } from './model-profiles.mjs';
+
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const name = value => typeof value === 'string' && /^[a-z][a-z0-9-]{0,63}$/.test(value);
+const validScope = value => typeof value === 'string' && !/[?*\[\]{}\\]/.test(value) && withinScope(value.replace(/\/$/, ''), { paths: ['*'] });
+const contains = (scope, file) => scope === '*' || (scope.endsWith('/') ? file.startsWith(scope) : file === scope);
+const overlaps = (a, b) => a.replace(/\/$/, '') === b.replace(/\/$/, '') || contains(a, b) || contains(b, a);
+const boundedLimits = limits => record(limits) && Number.isInteger(limits.timeoutSeconds) && limits.timeoutSeconds > 0 && limits.timeoutSeconds <= 1800 && Number.isInteger(limits.maxAttempts) && limits.maxAttempts === 1;
+
+export function prepareDelegatedTasks({ tasks, parent, controlPlane, project = null, operator, maxParallel }) {
+  if (!Number.isInteger(maxParallel) || maxParallel < 1 || maxParallel > 8) throw Error('Host parallel limit must be 1..8');
+  if (!record(parent) || !record(controlPlane?.roles?.[parent.role]) || validateLaunchRequest(parent, controlPlane).length || !boundedLimits(parent.limits)) throw Error('Invalid bounded parent launch contract');
+  if (!Array.isArray(tasks) || !tasks.length || tasks.length > 100) throw Error('Delegation requires 1..100 tasks');
+  const ids = new Set();
+  const prepared = structuredClone(tasks).map(task => {
+    if (!record(task) || Object.keys(task).some(key => !['id', 'specialist', 'profile', 'dependencies', 'affectedFiles', 'input', 'tools', 'outputSchema', 'limits', 'stopConditions'].includes(key)) || !name(task.id) || ids.has(task.id) || !name(task.specialist)) throw Error('Invalid or duplicate delegated task');
+    ids.add(task.id);
+    if (!Array.isArray(task.dependencies) || task.dependencies.some(id => !name(id)) || new Set(task.dependencies).size !== task.dependencies.length) throw Error('Task dependencies must be unique task IDs');
+    if (!Array.isArray(task.affectedFiles) || !task.affectedFiles.length || task.affectedFiles.length > 100 || new Set(task.affectedFiles).size !== task.affectedFiles.length || task.affectedFiles.some(file => !validScope(file) || !parent.writeScope.some(scope => contains(scope, file)))) throw Error('Task affected files exceed parent scope or use unsupported paths');
+    if (task.tools !== undefined && !Array.isArray(task.tools) || task.stopConditions !== undefined && !Array.isArray(task.stopConditions)) throw Error('Task tools and stop conditions must be arrays');
+    if (task.limits !== undefined && (!record(task.limits) || Object.keys(task.limits).some(key => !['timeoutSeconds', 'maxAttempts'].includes(key)))) throw Error('Task limits may only narrow timeout and attempts');
+    if (!record(controlPlane.roles[task.specialist])) throw Error('Task specialist needs a declared launch contract');
+    const input = JSON.stringify(task.input ?? {});
+    if (Buffer.byteLength(input) > 65536) throw Error('Task context exceeds 64 KiB');
+    const child = {
+      runId: `${parent.runId}-${task.id}-${randomUUID()}`, parentRun: parent.runId, role: task.specialist,
+      input: JSON.parse(input), outputSchema: task.outputSchema ?? controlPlane.roles[task.specialist].outputSchema,
+      tools: task.tools ?? [...parent.tools], writeScope: [...task.affectedFiles], limits: { ...parent.limits, ...task.limits },
+      stopConditions: [...parent.stopConditions, ...(task.stopConditions ?? [])],
+    };
+    if (!boundedLimits(child.limits) || child.limits.timeoutSeconds > parent.limits.timeoutSeconds || child.tools.some(tool => !parent.tools.includes(tool)) || validateLaunchRequest(child, controlPlane).length) throw Error('Task launch exceeds specialist or parent contract');
+    const selection = resolveModelProfile({ project, operator, worker: task.specialist, profile: task.profile });
+    if (selection.mode !== 'profile' || !task.profile) throw Error('Delegated task must declare a profile');
+    return { id: task.id, dependencies: task.dependencies, affectedFiles: task.affectedFiles, child, selection };
+  });
+  for (const task of prepared) if (task.dependencies.some(id => !ids.has(id) || id === task.id)) throw Error('Unknown or self task dependency');
+  const visited = new Set(), active = new Set(), byId = new Map(prepared.map(task => [task.id, task]));
+  function visit(task) {
+    if (active.has(task.id)) throw Error('Delegated task dependency cycle');
+    if (visited.has(task.id)) return;
+    active.add(task.id);
+    for (const id of task.dependencies) visit(byId.get(id));
+    active.delete(task.id); visited.add(task.id);
+  }
+  for (const task of prepared) visit(task);
+  return prepared;
+}
+
+// Callbacks are host-owned: enforce paths/tools, stop on abort, validate output schemas,
+// retain evidence and check actual file changes. This scheduler grants no permissions.
+export async function runDelegatedTasks(options) {
+  const { launch, verifyWave, signal } = options;
+  if (typeof launch !== 'function' || typeof verifyWave !== 'function') throw Error('Host launch and wave verification callbacks required');
+  const tasks = prepareDelegatedTasks(options), results = new Map(), waves = [];
+  const deadline = Date.now() + options.parent.limits.timeoutSeconds * 1000;
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  signal?.addEventListener('abort', abort, { once: true });
+  if (signal?.aborted) abort();
+  const timer = setTimeout(abort, Math.max(1, deadline - Date.now()));
+  const validResult = result => result?.status === 'passed' && Array.isArray(result.evidence) && result.evidence.length > 0;
+  async function bounded(callback, seconds) {
+    if (controller.signal.aborted) throw Error('Delegation stopped');
+    let timeout, onAbort;
+    try {
+      return await Promise.race([
+        Promise.resolve().then(() => callback(controller.signal)),
+        new Promise((_, reject) => {
+          onAbort = () => reject(Error('Delegation stopped'));
+          controller.signal.addEventListener('abort', onAbort, { once: true });
+          timeout = setTimeout(() => { controller.abort(); reject(Error('Delegation deadline exceeded')); }, Math.min(seconds * 1000, Math.max(1, deadline - Date.now())));
+        }),
+      ]);
+    } finally { clearTimeout(timeout); controller.signal.removeEventListener('abort', onAbort); }
+  }
+  try {
+    while (results.size < tasks.length && !controller.signal.aborted) {
+      // Propagate failures transitively before selecting eligible tasks.
+      let changed;
+      do {
+        changed = false;
+        for (const task of tasks) if (!results.has(task.id) && task.dependencies.some(id => results.has(id) && results.get(id).status !== 'passed')) {
+          results.set(task.id, { id: task.id, status: 'blocked', reason: 'dependency-failed' }); changed = true;
+        }
+      } while (changed);
+      const wave = [];
+      for (const task of tasks) {
+        if (results.has(task.id) || task.dependencies.some(id => results.get(id)?.status !== 'passed')) continue;
+        if (wave.length < options.maxParallel && !wave.some(other => other.affectedFiles.some(a => task.affectedFiles.some(b => overlaps(a, b))))) wave.push(task);
+      }
+      if (!wave.length) break;
+      const executions = await Promise.all(wave.map(async task => {
+        try {
+          const outcome = await bounded(signal => launch({ ...structuredClone(task.child), model: structuredClone(task.selection), signal }), task.child.limits.timeoutSeconds);
+          return { id: task.id, status: validResult(outcome) ? 'passed' : 'failed', reason: validResult(outcome) ? undefined : 'launch-result-failed', outcome, modelExecution: modelExecutionReceipt(task.selection) };
+        } catch { return { id: task.id, status: 'failed', reason: 'launch-failed-or-stopped', modelExecution: modelExecutionReceipt(task.selection) }; }
+      }));
+      let verification;
+      try { verification = await bounded(signal => verifyWave({ tasks: structuredClone(wave), results: structuredClone(executions), signal }), options.parent.limits.timeoutSeconds); }
+      catch { verification = { status: 'failed', evidence: [] }; }
+      const passed = validResult(verification);
+      for (const execution of executions) results.set(execution.id, execution.status === 'passed' && !passed ? { ...execution, status: 'failed', reason: 'wave-verification-failed' } : execution);
+      waves.push({ tasks: wave.map(task => task.id), status: passed && executions.every(result => result.status === 'passed') ? 'passed' : 'failed', verification });
+    }
+    for (const task of tasks) if (!results.has(task.id)) results.set(task.id, { id: task.id, status: 'blocked', reason: controller.signal.aborted ? 'execution-stopped' : 'dependency-failed' });
+    return { status: [...results.values()].every(result => result.status === 'passed') ? 'passed' : 'blocked', waves, tasks: tasks.map(task => results.get(task.id)) };
+  } finally { clearTimeout(timer); signal?.removeEventListener('abort', abort); }
+}

package/src/proposal-review.mjs

@@ -0,0 +1,91 @@
+import { digest } from './host-contract.mjs';
+import { proposalRoot, validateProposalFiles } from './proposal.mjs';
+
+export const feedbackKey = review => digest(`${review.number}:${review.kind}:${review.id}:${review.feedbackDigest}`);
+export const feedbackWorker = review => review && !review.approved ? 'apply-review' : undefined;
+
+export function reviewTarget(event, eventName) {
+  if (eventName === 'issue_comment' && event.issue?.pull_request) return event.issue.number;
+  if (['pull_request_review', 'pull_request_review_comment'].includes(eventName)) return event.pull_request?.number;
+  return null;
+}
+
+export function checkProposal(pr, repo, expected) {
+  const match = pr.head?.ref?.match(/^lighthouse\/propose-([1-9][0-9]*)-([a-f0-9]{12})$/);
+  const marker = pr.body?.match(/<!-- lighthouse-proposal:([a-f0-9]{64}) -->/)?.[1];
+  if (!match || !marker?.startsWith(match[2]) || pr.user?.login !== 'github-actions[bot]' || pr.user.type !== 'Bot' || pr.state !== 'open' || pr.merged || pr.head.repo?.full_name !== repo || pr.base.repo?.full_name !== repo) throw Error('Not an open repository-owned Lighthouse proposal');
+  if (expected && (pr.head.sha !== expected.head || pr.head.ref !== expected.branch || Number(match[1]) !== expected.issue || pr.base.ref !== expected.base)) throw Error('Proposal changed during review; no update published');
+  return { number: pr.number, issue: Number(match[1]), head: pr.head.sha, branch: pr.head.ref, base: pr.base.ref, url: pr.html_url };
+}
+
+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 (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 };
+}
+
+export async function loadProposalReview(api, repo, owner, event, eventName, implementation = false) {
+  const number = reviewTarget(event, eventName);
+  if (!number) return null;
+  const pr = await api(`pulls/${number}`), target = (implementation ? checkImplementationPullRequest : checkProposal)(pr, repo);
+  const kind = eventName === 'pull_request_review' ? 'review' : eventName === 'pull_request_review_comment' ? 'inline' : 'comment';
+  const id = kind === 'review' ? event.review?.id : event.comment?.id;
+  if (!Number.isSafeInteger(id) || id < 1) throw Error('Missing feedback identity');
+  const path = kind === 'review' ? `pulls/${number}/reviews/${id}` : kind === 'inline' ? `pulls/comments/${id}` : `issues/comments/${id}`;
+  const feedback = await api(path);
+  if (feedback.user?.login !== owner || feedback.user.type === 'Bot') throw Error('Feedback is not from the repository owner');
+  if (kind === 'comment' && feedback.issue_url !== `https://api.github.com/repos/${repo}/issues/${number}` || kind === 'inline' && feedback.pull_request_url !== `https://api.github.com/repos/${repo}/pulls/${number}`) throw Error('Feedback belongs to another PR');
+  if (kind !== 'comment' && feedback.commit_id !== target.head) throw Error('Feedback targets an older proposal commit; review the current diff');
+  const approved = kind === 'review' && feedback.state?.toLowerCase() === 'approved';
+  if (kind === 'review' && !['approved', 'commented', 'changes_requested'].includes(feedback.state?.toLowerCase())) throw Error('Review is not submitted feedback');
+  const inline = kind === 'review' ? await api(`pulls/${number}/reviews/${id}/comments?per_page=100`) : [];
+  if (inline.length >= 100) throw Error('Review exceeds bounded feedback collection');
+  const body = [feedback.body, ...inline.map(c => `${c.path}:${c.line ?? c.original_line}\n${c.body}`)].filter(Boolean).join('\n\n');
+  if (!approved && !body.trim()) throw Error('No review feedback to apply');
+  return { ...target, kind, id, path, feedback: body, feedbackDigest: digest(JSON.stringify(feedback)), receipt: `<!-- lighthouse-review:${kind}:${id}:${digest(JSON.stringify(feedback))} -->`, url: pr.html_url, feedbackUrl: feedback.html_url, approved };
+}
+
+export async function reviewThread(api, number, owner) {
+  const messages = [];
+  for (const path of [`issues/${number}/comments`, `pulls/${number}/comments`, `pulls/${number}/reviews`]) {
+    const rows = await api(`${path}?per_page=100`);
+    if (rows.length >= 100) throw Error('Proposal discussion exceeds bounded collection');
+    for (const c of rows) if (c.user?.login === owner && c.user.type !== 'Bot' && (!c.state || ['commented', 'changes_requested'].includes(c.state.toLowerCase()))) messages.push({ id: c.id, body: c.body, path: c.path, url: c.html_url, updated: c.updated_at, submitted: c.submitted_at });
+  }
+  return messages;
+}
+
+export async function loadProposalFiles(api, review) {
+  const changed = await api(`pulls/${review.number}/files?per_page=100`);
+  const root = proposalRoot(review.issue);
+  if (changed.length >= 100 || changed.some(f => !f.filename.startsWith(`${root}/`) || f.status === 'removed' || f.status === 'renamed')) throw Error('Proposal PR includes changes outside the proposal');
+  const files = [];
+  for (const f of changed) {
+    if (f.filename === `${root}/.openspec.yaml`) continue;
+    const value = await api(`contents/${f.filename}?ref=${review.head}`);
+    if (value.type !== 'file' || value.encoding !== 'base64' || value.size > 96000) throw Error('Unsupported proposal file');
+    files.push({ path: f.filename, content: Buffer.from(value.content, 'base64').toString('utf8') });
+  }
+  return validateProposalFiles(files, review.issue);
+}
+
+export async function checkReviewCurrent(api, repo, review, implementation = false) {
+  (implementation ? checkImplementationPullRequest : checkProposal)(await api(`pulls/${review.number}`), repo, review);
+  if (digest(JSON.stringify(await api(review.path))) !== review.feedbackDigest) throw Error('Review feedback changed; no update published');
+}
+
+export async function updateProposal(api, repo, snapshot, files, beforeWrite) {
+  const review = snapshot.proposalReview;
+  const commit = await api(`git/commits/${review.head}`);
+  const old = await loadProposalFiles(api, review);
+  const removed = old.filter(f => !files.some(n => n.path === f.path)).map(f => ({ path: f.path, mode: '100644', type: 'blob', sha: null }));
+  const tree = await api('git/trees', 'POST', { base_tree: commit.tree.sha, tree: [...files.map(f => ({ path: f.path, mode: '100644', type: 'blob', content: f.content })), ...removed] });
+  const created = await api('git/commits', 'POST', { message: `docs: address proposal review for #${snapshot.issue}`, tree: tree.sha, parents: [review.head] });
+  await beforeWrite();
+  await checkReviewCurrent(api, repo, review);
+  // Non-forced update rejects a concurrent writer after the final head check.
+  await api(`git/refs/heads/${review.branch}`, 'PATCH', { sha: created.sha, force: false });
+  return { number: review.number, html_url: review.url };
+}