@juangcarmona/lighthouse-sdlc 0.11.0 → 0.13.0

package/src/opencode-execute.mjs

@@ -0,0 +1,188 @@
+// gh-aw engine adapter: one foreground container, no service or orchestration state.
+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 { validateStageEnvelope } from './host-contract.mjs';
+import { formatOpenCodeEvent, progressText, boundedEventLines } from './opencode-progress.mjs';
+
+export function completionOutput(envelope, request) {
+  const errors = validateStageEnvelope(envelope, request);
+  if (errors.length) throw Error(errors.join('\n'));
+  if (!['passed', 'blocked'].includes(envelope.result.status)) throw Error('Stage did not complete');
+  return { type: 'noop', message: `Lighthouse ${request.stage} result validated: ${envelope.result.status}. GitHub publication belongs to the separate publisher job.` };
+}
+export function redactLog(text) {
+  return text.replace(/Bearer\s+[^\s"']+/gi, 'Bearer [REDACTED]')
+    .replace(/\b(?:sk-|ghp_|github_pat_)[A-Za-z0-9_-]{15,}/g, '[REDACTED]')
+    .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, '[REDACTED]');
+}
+export async function snapshotSource(root, destination) {
+  const files = execFileSync('git', ['-C', root, 'ls-files', '-z'], { encoding: 'utf8' }).split('\0').filter(Boolean);
+  if (files.length > 5000) throw Error('Source snapshot exceeds file bound');
+  let bytes = 0;
+  for (const file of files) {
+    if (file.split('/').some(part => part === '..' || part === '.git') || file.startsWith('/')) throw Error('Unsafe source path');
+    const source = join(root, file), stat = await lstat(source);
+    if (!stat.isFile() || stat.isSymbolicLink()) continue;
+    bytes += stat.size;
+    if (bytes > 32 * 1024 * 1024) throw Error('Source snapshot exceeds byte bound');
+    const target = join(destination, file);
+    await mkdir(dirname(target), { recursive: true }); await copyFile(source, target); await chmod(target, stat.mode & 0o111 ? 0o555 : 0o444);
+  }
+}
+export function acquireEngineSlot(path, seconds = 240) {
+  if (!isAbsolute(path ?? '')) throw Error('Operator engine lock must be an absolute path');
+  const fd = openSync(path, 'a', 0o600);
+  try {
+    // Linux flock belongs to the shared open file description, held until closeSync.
+    execFileSync('flock', ['--exclusive', '--wait', String(seconds), '3'], { stdio: ['ignore', 'inherit', 'inherit', fd] });
+    return fd;
+  } catch { closeSync(fd); throw Error('Host engine capacity unavailable'); }
+}
+async function main() {
+  const env = process.env;
+  const config = JSON.parse(await readFile(env.LIGHTHOUSE_ENGINE_CONFIG, 'utf8'));
+  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'));
+  if (request.stage === 'implement') {
+    if (!/^sha256:[a-f0-9]{64}$/.test(config.implementationImage ?? '')) throw Error('Operator must provision and pin an implementation image');
+    config.image = config.implementationImage;
+  }
+  if (!/^[a-f0-9]{64}$/.test(request.runId)) throw Error('Invalid execution identity');
+  const dir = await mkdtemp(join(env.RUNNER_TEMP, 'lighthouse-engine-'));
+  await chmod(dir, 0o755);
+  const source = join(dir, 'source'), output = join(dir, 'output');
+  await mkdir(source); await mkdir(output); await chmod(output, 0o777);
+  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;
+  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);
+    console.log('Engine slot acquired; starting isolated OpenCode');
+    await snapshotSource(env.GITHUB_WORKSPACE, source);
+    baseline = implementing ? await sourceFiles(source) : null;
+    trackedSource = baseline ? new Map(baseline) : null;
+    if (implementing) {
+      if (request.seedDigest) {
+        const seed = validateChanges(JSON.parse(await readFile(join(runDir, 'seed.json'), 'utf8')), request.implementation.policy);
+        if (changesDigest(seed) !== request.seedDigest) throw Error('Seed artifact identity mismatch');
+        for (const file of seed) if (file.content !== null) trackedSource.set(file.path, {});
+        await rm(source, { recursive: true, force: true }); await mkdir(source);
+        await materializeCandidate(baseline, seed, source);
+      }
+      await writableTree(source);
+    }
+    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';
+    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 }));
+    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}`,
+      '--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];
+    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)); };
+    const eventLine = line => {
+      const redacted = redactLog(line);
+      appendFileSync(eventsPath, redacted + '\n');
+      const visible = formatOpenCodeEvent(redacted);
+      if (visible) report(visible);
+    };
+    report(progressText('Run', `${request.stage} for issue #${request.issue}. Public progress and tool activity appear below; structured events are retained as an artifact.`));
+    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) => {
+      child = spawn('docker', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+      const consume = line => {
+        try {
+          eventLine(line);
+        } catch (error) { no(error); cancel(); }
+      };
+      // Keep line boundaries across chunks so credential shapes cannot bypass redaction.
+      for (const stream of [child.stdout, child.stderr]) {
+        const lines = boundedEventLines(consume, () => {
+          eventLine(JSON.stringify({ type: 'diagnostic_omitted', reason: 'Event exceeded the 8 MiB character limit' }));
+          report(progressText('Run', 'One oversized diagnostic event was omitted. Execution continues; candidate files are collected separately.'));
+        });
+        stream.setEncoding('utf8');
+        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);
+    });
+    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'));
+    clearTimeout(timer);
+    completionOutput(envelope, request);
+    if (implementing) {
+      const changes = collectChanges(baseline, await sourceFiles(source, trackedSource), request.implementation.policy);
+      await writeFile(join(runDir, 'changes.json'), JSON.stringify(changes));
+      await copyEvidence(join(output, 'evidence'), join(runDir, 'evidence', 'agent'));
+      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 (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) {
+        envelope.result.status = 'blocked';
+        envelope.result.pendingReview.push('Repository policy requires owner acceptance of this candidate; engine assertions cannot grant it.');
+      }
+      if (!changes.length && envelope.result.status === 'passed') { envelope.result.status = 'blocked'; envelope.result.missingEvidence.push('No implementation changes were returned'); }
+      if (receipt.checks.some(c => c.exitCode !== 0)) {
+        envelope.result.status = 'blocked';
+        envelope.result.missingEvidence.push('The independent host checks did not all pass; inspect checks.json and host logs.');
+        envelope.effect.body += '\n\nIndependent host checks failed. This candidate requires corrections before completion.';
+      }
+      if (cancelled) throw Error('Implementation cancelled before publication');
+    }
+    const completion = completionOutput(envelope, request);
+    report(progressText('Result', redactLog(envelope.effect.body)));
+    report(progressText('Run', `Validated outcome: ${envelope.result.status}. The publisher will recheck authority before updating the issue.`));
+    await writeFile(join(runDir, 'envelope.json'), JSON.stringify(envelope));
+    // gh-aw requires a terminal safe output even when a separate job owns publication.
+    await mkdir(dirname(env.GH_AW_SAFE_OUTPUTS), { recursive: true });
+    await writeFile(env.GH_AW_SAFE_OUTPUTS, JSON.stringify(completion) + '\n');
+  } catch (error) {
+    if (implementing && baseline) {
+      try {
+        try { docker(['rm', '-f', name, `${name}-checks`]); } catch {}
+        const changes = collectChanges(baseline, await sourceFiles(source, trackedSource), request.implementation.policy);
+        await writeFile(join(runDir, 'changes.json'), JSON.stringify(changes));
+        await copyEvidence(join(output, 'evidence'), join(runDir, 'evidence', 'agent'));
+        console.error(progressText('Recovery', 'Retained bounded candidate changes and available evidence. This failed run cannot publish a PR.'));
+      } catch (recoveryError) { console.error(progressText('Recovery', redactLog(`Candidate could not be retained: ${recoveryError.message}`))); }
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer); clearInterval(heartbeat); process.removeListener('SIGTERM', cancel); process.removeListener('SIGINT', cancel);
+    try { docker(['rm', '-f', name, `${name}-checks`]); } catch {}
+    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'); }
+    }
+    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; });

package/src/opencode-progress.mjs

@@ -0,0 +1,48 @@
+// Human-facing projection; the redacted event stream remains the diagnostic record.
+export function progressText(label, text) {
+  return String(text).replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '').replaceAll('##[', '# #[ ').replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, '').split('\n').map(line => `[${label}] ${line}`).join('\n');
+}
+
+export function formatOpenCodeEvent(line) {
+  let event;
+  try { event = JSON.parse(line); }
+  catch {
+    if (/\b(error|warn|fatal)\b/i.test(line)) return progressText('Engine', line.slice(0, 500));
+    return null;
+  }
+  if (!event || typeof event !== 'object') return null;
+  const part = event.part ?? {};
+  if (event.type === 'text' && typeof part.text === 'string') return progressText('OpenCode', part.text);
+  if (event.type === 'tool_use') {
+    const state = part.state ?? {}, input = state.input ?? {};
+    const patchPaths = typeof input.patchText === 'string' ? [...input.patchText.matchAll(/^\*\*\* (?:Add|Update|Delete) File: (.+)$/gm)].map(m => m[1]) : [];
+    const target = input.path ?? input.filePath ?? input.file_path ?? (part.tool === 'shell' ? input.command?.split('\n')[0] : patchPaths.length ? patchPaths.slice(0, 3).join(', ') + (patchPaths.length > 3 ? ` (+${patchPaths.length - 3} files)` : '') : undefined);
+    const description = `${part.tool ?? 'tool'}${typeof target === 'string' ? ` ${target}` : ''}`.slice(0, 240);
+    if (state.status === 'completed') return progressText('Tool', `${description} — completed`);
+    if (state.status === 'error') return progressText('Tool error', `${description}: ${String(state.error ?? 'see diagnostic events').slice(0, 500)}`);
+    if (state.status === 'running') return progressText('Tool', `${description} — running`);
+  }
+  if (event.type === 'error') return progressText('Engine error', String(event.error?.data?.message ?? event.error?.message ?? 'OpenCode reported an error; see diagnostic events.').slice(0, 500));
+  return null;
+}
+
+// Bound diagnostics independently of the execution; a large patch event is not a failed task.
+export function boundedEventLines(consume, omitted, limit = 8 * 1024 * 1024) {
+  let pending = '', dropping = false;
+  const finish = () => { if (dropping) omitted(); else if (pending) consume(pending); pending = ''; dropping = false; };
+  return {
+    write(chunk) {
+      let start = 0;
+      while (start < chunk.length) {
+        const end = chunk.indexOf('\n', start), piece = chunk.slice(start, end < 0 ? undefined : end);
+        if (!dropping) {
+          if (pending.length + piece.length > limit) { pending = ''; dropping = true; }
+          else pending += piece;
+        }
+        if (end < 0) break;
+        finish(); start = end + 1;
+      }
+    },
+    end: finish,
+  };
+}

package/src/process-publication.mjs

@@ -0,0 +1,90 @@
+import { createHash } from 'node:crypto';
+import { evidenceProtection } from './completion.mjs';
+import { buildEvidenceIndex, validateEvidenceRecord, validateEvidenceIndex } from './evidence.mjs';
+
+const digest = value => createHash('sha256').update(value).digest('hex');
+const blobSha = content => createHash('sha1').update(`blob ${Buffer.byteLength(content)}\0`).update(content).digest('hex');
+const json = value => JSON.stringify(value, null, 2) + '\n';
+export function validatePublishable(files) {
+  let bytes = 0;
+  if (!files || Object.keys(files).length > 32) throw Error('Evidence file count exceeds bounds');
+  for (const [path, content] of Object.entries(files)) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._/-]*$/.test(path) || path.split('/').some(p => !p || ['.', '..', '.git'].includes(p)) || typeof content !== 'string') throw Error('Unsafe evidence path or payload');
+    bytes += Buffer.byteLength(content);
+    if (Buffer.byteLength(content) > 1024 * 1024 || bytes > 4 * 1024 * 1024) throw Error('Evidence payload exceeds bounds');
+    if (/\b(?:sk-|ghp_|github_pat_)[A-Za-z0-9_-]{15,}|-----BEGIN (?:RSA |OPENSSH |EC )?PRIVATE KEY-----|Bearer\s+[A-Za-z0-9_.-]{10,}|\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+|https?:\/\/[^\s<>"\)]+[?][^\s<>"\)]*(?:token|signature|credential|sig|X-Amz-)[=]/i.test(content)) throw Error('Credential-shaped or signed content is not publishable');
+  }
+  return files;
+}
+export function completionBundle(request, envelope, receipt) {
+  const observation = request.completion;
+  const priorIntegration = request.priorIntegration ? Object.fromEntries(['evidenceId', 'commit', 'path', 'recordSha256', 'url', 'workflow'].map(key => [key, request.priorIntegration[key]])) : null;
+  const files = {
+    'report.md': `# ${request.stage} result\n\n[Work item](${observation.issueUrl}) · [PR](${observation.prUrl}) · [Actions run](${request.runUrl})\n\nAccepted head: \`${observation.binding.head}\`. Base observed: \`${observation.binding.base}\`.\n\nOutcome: ${receipt.state}. Merged revision: ${receipt.sha ?? 'not merged'}.\n\n${envelope.effect.body}\n\n## Verification\n\n${observation.checks.map(c => `- ${c.context}: ${c.state ?? c.status} at \`${c.revision}\`.`).join('\n')}\n\n## Post-merge checks\n\n${receipt.postMerge?.map(c => `- ${c.workflow}: ${c.state ?? c.status}${c.url ? ` ([run](${c.url}))` : ''}.`).join('\n') || 'Not performed by this invocation.'}\n\n## Limits\n\nThe agent assessment is separate from authenticated GitHub check results. This bundle retains reports and receipts; raw sessions and earlier screenshots remain in their original evidence locations. No additional test or visual acceptance is implied.\n`,
+    'retrospective.md': envelope.result.output?.retrospective ?? '# Retrospective\n\nNo retrospective finding was established in this stage.\n',
+    '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 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' } });
+  if (buildErrors.length) throw Error(JSON.stringify(buildErrors));
+  const indexErrors = validateEvidenceIndex(index); if (indexErrors.length) throw Error(JSON.stringify(indexErrors));
+  files['evidence-index.json'] = json(index);
+  return validatePublishable(files);
+}
+export async function publishProcessBundle(api, request, files, beforeWrite = async () => {}) {
+  validatePublishable(files);
+  const branch = request.completion.profile.evidenceBranch, issue = request.issue;
+  if (!Number.isSafeInteger(issue) || issue < 1 || !/^\d+$/.test(request.workflowRunId) || !/^\d+$/.test(request.attempt) || !['integrate', 'review'].includes(request.stage)) throw Error('Invalid publication identity');
+  const date = request.observedAt.slice(0, 10).replaceAll('-', '');
+  if (!/^\d{8}$/.test(date)) throw Error('Invalid publication date');
+  const slug = request.title.toLowerCase().normalize('NFKD').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 64).replace(/-$/, '') || 'change';
+  const phase = request.stage === 'review' || request.completion.merged ? 'post-integration' : 'pr-ready';
+  const relative = `runs/${request.workflowRunId}/attempt-${request.attempt.padStart(4, '0')}/${phase}`;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    await evidenceProtection(api, branch, request.completion.profile.completion.protectionObservations);
+    const ref = await api(`git/ref/heads/${branch}`), tip = ref.object.sha;
+    const tree = await api(`git/trees/${tip}?recursive=1`);
+    if (tree.truncated || tree.tree.length > 10000) throw Error('Evidence tree exceeds bounds');
+    const paths = new Map(tree.tree.map(f => [f.path, f]));
+    const roots = tree.tree.filter(f => f.type === 'tree' && new RegExp(`^docs/process/\\d{8}-${issue}-[a-z0-9-]+$`).test(f.path)).map(f => f.path);
+    if (roots.length > 1) throw Error('Ambiguous work-item evidence mapping');
+    const root = roots[0] ?? `docs/process/${date}-${issue}-${slug}`, prefix = `${root}/${relative}`;
+    for (const path of [prefix, root]) {
+      const parts = path.split('/');
+      for (let i = 1; i <= parts.length; i++) {
+        const ancestor = paths.get(parts.slice(0, i).join('/'));
+        if (ancestor && ancestor.type !== 'tree') throw Error('Evidence ancestor must be a directory');
+      }
+    }
+    const desired = Object.fromEntries(Object.entries(files).map(([name, content]) => [`${prefix}/${name}`, content]));
+    const existing = [...paths.keys()].filter(p => p.startsWith(`${prefix}/`) && paths.get(p).type !== 'tree');
+    const url = commit => `https://github.com/${request.completion.binding.repository}/blob/${commit}/${prefix}/report.md`;
+    if (existing.length) {
+      if (existing.length !== Object.keys(desired).length || existing.some(p => paths.get(p).mode !== '100644' || paths.get(p).type !== 'blob' || paths.get(p).sha !== blobSha(desired[p] ?? ''))) throw Error('Conflicting immutable evidence bundle');
+      return { commit: tip, url: url(tip), duplicate: true };
+    }
+    const indexPath = `${root}/README.md`, prior = paths.get(indexPath);
+    if (prior && (prior.type !== 'blob' || prior.mode !== '100644')) throw Error('Evidence index must be a regular file');
+    const old = prior ? await api(`git/blobs/${prior.sha}`) : null;
+    if (old && (old.encoding !== 'base64' || old.size > 1024 * 1024)) throw Error('Evidence index exceeds bounds');
+    const content = old ? Buffer.from(old.content, 'base64').toString() : `# Process evidence for issue #${issue}\n\n[Work item](${request.completion.issueUrl}). Publication dates use UTC. Earlier attempts remain available.\n`;
+    desired[indexPath] = `${content.trimEnd()}\n\n- [${request.stage}, run ${request.workflowRunId}, attempt ${request.attempt}](${relative}/report.md)\n`;
+    validatePublishable(desired);
+    const entries = [];
+    for (const [path, content] of Object.entries(desired)) entries.push({ path, mode: '100644', type: 'blob', sha: (await api('git/blobs', 'POST', { content, encoding: 'utf-8' })).sha });
+    const nextTree = await api('git/trees', 'POST', { base_tree: tree.sha, tree: entries });
+    const commit = await api('git/commits', 'POST', { message: `docs: retain ${request.stage} evidence for #${issue}`, tree: nextTree.sha, parents: [tip] });
+    await beforeWrite(); await evidenceProtection(api, branch, request.completion.profile.completion.protectionObservations);
+    try {
+      await api(`git/refs/heads/${branch}`, 'PATCH', { sha: commit.sha, force: false });
+      return { commit: commit.sha, url: url(commit.sha), duplicate: false };
+    } catch (error) {
+      // Only a changed remote tip justifies rebuilding; the next pass also detects a lost successful response.
+      if ((await api(`git/ref/heads/${branch}`)).object.sha === tip) throw error;
+    }
+  }
+  throw Error('Evidence branch remained busy; retry the same publication');
+}

package/src/proposal.mjs

@@ -0,0 +1,96 @@
+import { mkdtemp, mkdir, readFile, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+export const changeName = issue => {
+  if (!Number.isSafeInteger(issue) || issue < 1) throw Error('Invalid proposal issue');
+  return `issue-${issue}-proposal`;
+};
+export const proposalRoot = issue => `openspec/changes/${changeName(issue)}`;
+
+export function validateProposalFiles(files, issue) {
+  const root = proposalRoot(issue), seen = new Set();
+  if (!Array.isArray(files) || files.length < 4 || files.length > 24) throw Error('Proposal needs 4-24 bounded Markdown files');
+  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') throw Error('Invalid proposal file');
+    const relative = file.path.slice(root.length + 1);
+    if (!file.path.startsWith(`${root}/`) || !/^(proposal\.md|design\.md|tasks\.md|specs\/[a-z0-9]+(?:-[a-z0-9]+)*(?:\/[a-z0-9]+(?:-[a-z0-9]+)*)*\/spec\.md)$/.test(relative)) throw Error('Proposal write outside authorized Markdown paths');
+    if (seen.has(file.path) || !file.content.trim() || file.content.includes('\0')) throw Error('Duplicate or empty proposal file');
+    seen.add(file.path); bytes += Buffer.byteLength(file.content);
+    if (bytes > 96000) throw Error('Proposal exceeds 96000 bytes');
+  }
+  for (const name of ['proposal.md', 'design.md', 'tasks.md']) if (!seen.has(`${root}/${name}`)) throw Error(`Missing ${name}`);
+  if (![...seen].some(path => path.startsWith(`${root}/specs/`))) throw Error('Missing specification');
+  const tasks = files.find(file => file.path === `${root}/tasks.md`).content;
+  if (!/^- \[ \] /m.test(tasks) || /^\s*[-*] \[[xX]\]/m.test(tasks)) throw Error('Proposal tasks must be pending implementation');
+  return files;
+}
+
+const openspec = (cwd, args) => execFileSync('npx', ['--yes', '--package', '@fission-ai/openspec@1.15.0', 'openspec', ...args], { cwd, encoding: 'utf8', timeout: 120000, maxBuffer: 1024 * 1024, env: { ...process.env, OPENSPEC_TELEMETRY: '0', CI: 'true' }, stdio: ['ignore', 'pipe', 'pipe'] });
+
+// Use the provider's scaffold, instructions and validator; never maintain a copied schema.
+export async function prepareProposal(issue, files, provider = openspec) {
+  if (files) validateProposalFiles(files, issue);
+  const dir = await mkdtemp(join(tmpdir(), 'lighthouse-proposal-'));
+  const name = changeName(issue);
+  try {
+    provider(dir, ['new', 'change', name, '--schema', 'spec-driven', '--json']);
+    if (!files) {
+      const instructions = {};
+      for (const artifact of ['proposal', 'specs', 'design', 'tasks']) {
+        const value = JSON.parse(provider(dir, ['instructions', artifact, '--change', name, '--json']));
+        instructions[artifact] = { outputPath: value.outputPath, instruction: value.instruction, template: value.template };
+      }
+      return { provider: '@fission-ai/openspec@1.15.0', schema: 'spec-driven', root: proposalRoot(issue), instructions };
+    }
+    for (const file of files) { const path = join(dir, file.path); await mkdir(dirname(path), { recursive: true }); await writeFile(path, file.content); }
+    provider(dir, ['validate', name, '--strict', '--no-interactive']);
+    const status = JSON.parse(provider(dir, ['status', '--change', name, '--json']));
+    if (!status.isPlanningComplete) throw Error('OpenSpec planning artifacts are incomplete');
+    const metadata = `${proposalRoot(issue)}/.openspec.yaml`;
+    return [...files, { path: metadata, content: await readFile(join(dir, metadata), 'utf8') }];
+  } finally { await rm(dir, { recursive: true, force: true }); }
+}
+
+export function checkRefinement(predecessor, envelope, run, current, marker) {
+  if (run.status !== 'completed' || run.conclusion !== 'success' || run.event !== 'issues' && run.event !== 'issue_comment' && run.event !== 'workflow_dispatch' || run.path !== '.github/workflows/lighthouse-sdlc-router.yml' || run.actor?.login !== current.owner) throw Error('Predecessor is not a successful owner workflow');
+  if (String(run.id) !== String(predecessor.workflowRunId) || run.head_sha !== predecessor.sourceRevision || predecessor.stage !== 'refine' || predecessor.issue !== current.issue || envelope.result?.stage !== 'refine' || envelope.result?.status !== 'passed' || envelope.result?.gate !== 'ready' || envelope.result?.runId !== predecessor.runId || marker !== predecessor.runId) throw Error('Refinement evidence identity mismatch');
+  if (predecessor.sourceRevision !== current.sourceRevision || predecessor.taskDigest !== current.taskDigest) throw Error('Refinement is stale; run refine against the current source and owner intent first');
+}
+
+export async function loadRefinement(api, repo, reports, current) {
+  const report = [...reports].reverse().find(c => c.user.login === 'github-actions[bot]' && /<!-- lighthouse-actions:[a-f0-9]{64} -->/.test(c.body));
+  const marker = report?.body.match(/<!-- lighthouse-actions:([a-f0-9]{64}) -->/)?.[1];
+  const runId = report?.body.match(/\[Workflow run\]\(https:\/\/github\.com\/[^/]+\/[^/]+\/actions\/runs\/(\d+)\)/)?.[1];
+  if (!marker || !runId) throw Error('No authenticated refinement report; run refine first');
+  const run = await api(`actions/runs/${runId}`);
+  const artifacts = await api(`actions/runs/${runId}/artifacts?per_page=100`);
+  const dir = await mkdtemp(join(tmpdir(), 'lighthouse-predecessor-'));
+  try {
+    const values = {};
+    for (const [kind, file] of [['input', 'request.json'], ['result', 'envelope.json']]) {
+      const artifact = artifacts.artifacts.find(a => a.name === `lighthouse-${kind}-${current.issue}-${run.run_attempt}` && !a.expired);
+      if (!artifact || artifact.size_in_bytes > 2 * 1024 * 1024) throw Error('Refinement artifact unavailable or too large; run refine first');
+      const archive = join(dir, `${kind}.zip`);
+      const bytes = execFileSync('gh', ['api', `repos/${repo}/actions/artifacts/${artifact.id}/zip`], { maxBuffer: 2 * 1024 * 1024, timeout: 30000 });
+      await writeFile(archive, bytes);
+      values[kind] = JSON.parse(execFileSync('python3', ['-c', 'import sys,zipfile; z=zipfile.ZipFile(sys.argv[1]); matches=[i for i in z.infolist() if i.filename==sys.argv[2]]; assert len(matches)==1 and matches[0].file_size<=128000, "Invalid artifact member"; data=z.open(matches[0]).read(128001); assert len(data)<=128000; sys.stdout.buffer.write(data)', archive, file], { encoding: 'utf8', maxBuffer: 128000, timeout: 10000 }));
+    }
+    checkRefinement(values.input, values.result, run, current, marker);
+    return { request: values.input, envelope: values.result, report: report.html_url };
+  } finally { await rm(dir, { recursive: true, force: true }); }
+}
+
+export async function createProposalPullRequest(api, snapshot, files, body, runUrl, beforeWrite) {
+  const branch = `lighthouse/propose-${snapshot.issue}-${snapshot.runId.slice(0, 12)}`;
+  // A fresh immutable branch per run avoids updating a human's or another run's work.
+  const commit = await api(`git/commits/${snapshot.sourceRevision}`);
+  const tree = await api('git/trees', 'POST', { base_tree: commit.tree.sha, tree: files.map(file => ({ path: file.path, mode: '100644', type: 'blob', content: file.content })) });
+  const created = await api('git/commits', 'POST', { message: `docs: propose issue #${snapshot.issue}`, tree: tree.sha, parents: [snapshot.sourceRevision] });
+  await beforeWrite();
+  await api('git/refs', 'POST', { ref: `refs/heads/${branch}`, sha: created.sha });
+  const pr = await api('pulls', 'POST', { title: `Proposal for #${snapshot.issue}: ${snapshot.title.slice(0, 160)}`, head: branch, base: snapshot.defaultBranch, body: `${body}\n\nRelated to #${snapshot.issue}. Proposal only; implementation requires a separate owner decision.\n\nOpenSpec 1.15.0 strict validation passed. [Execution evidence](${runUrl}).\n\n<!-- lighthouse-proposal:${snapshot.runId} -->` });
+  return pr;
+}