@namewta/speculo 1.0.24 → 2.0.1

package/template/workflows/specdev/common/tools/publish-design.mjs

@@ -0,0 +1,341 @@
+import { link, lstat, mkdir, open, readFile, readdir, rename, unlink } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { hostname } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { canonicalToolPath } from './plan-contract.mjs';
+import * as runtime from '../../../../lib/speculo-runtime.mjs';
+import { prototypeDigest, sha256, validateProjectDesign, designContext } from './design-artifacts.mjs';
+
+const OWNER = 'specdev/archive-and-consolidate';
+const HASH = /^[a-f0-9]{64}$/;
+const CHANGE = /^\d{4}-\d{2}-\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const REVISION = /^DESIGN-(\d{4,})$/;
+const portable = path => path.split(sep).join('/');
+const present = async path => { try { return await lstat(path); } catch (e) { if (e.code === 'ENOENT') return null; throw e; } };
+const fail = message => { throw new Error(message); };
+
+/** Reject symlinks in every existing component, including not-yet-created leaves. */
+async function safe(root, path) {
+  const target = resolve(path), rel = portable(relative(root, target));
+  return runtime.safeWorkPathSync(root, rel, {allowRoot:true});
+}
+
+async function localFile(context, locator, binding = null) {
+  let root = context.projectRoot;
+  if (binding?.base === 'change') {
+    if (binding.change !== context.sourceName) fail('change-relative approval locator has the wrong owning identity');
+    root = (await changeFor(context, binding.change)).root;
+  } else if (binding?.base !== undefined && binding.base !== 'project') fail('unknown design locator base');
+  if (typeof locator !== 'string' || !locator || isAbsolute(locator) || locator.includes('\\')) fail('unsafe design source locator');
+  let logical = /^<Path>([^<>]+)<\/Path>$/.exec(locator)?.[1] ?? locator;
+  if (logical.startsWith('{roots.')) {
+    if (binding?.base === 'change') fail('change-relative locator cannot contain root aliases');
+    const roots = {state:context.stateRoot,speculo:context.methodRoot,workflows:join(context.methodRoot,'workflows'),references:join(context.methodRoot,'references'),skills:join(context.projectRoot,'.agents/skills'),commands:join(context.methodRoot,'commands'),config:join(context.methodRoot,'config.json')};
+    const match = /^\{roots\.(\w+)\}\/(.+)$/.exec(logical);
+    if (!match || !roots[match[1]]) fail('unknown design locator alias');
+    root = roots[match[1]]; logical = match[2];
+  }
+  const path = runtime.safeWorkPathSync(root, logical, {mustExist:true,type:'file'});
+  await safe(context.projectRoot, path);
+  return path;
+}
+
+async function fileHash(path) { return sha256(await readFile(path)); }
+
+/** Write a complete fsynced file, then publish it with no replacement or rename. */
+async function atomicFile(context, target, content, exclusive = false) {
+  await safe(context.projectRoot, target);
+  const temporary = join(dirname(target), `.design-${randomUUID()}.tmp`);
+  const existing = await present(target);
+  if (existing && !existing.isFile()) fail('design target is not a regular file');
+  const handle = await open(temporary, 'wx', existing ? existing.mode & 0o777 : 0o644);
+  try {
+    try { await handle.writeFile(content); await handle.sync(); } finally { await handle.close(); }
+    await safe(context.projectRoot, target);
+    if (exclusive) await link(temporary, target); // atomic create-if-absent; rename would clobber another bootstrap
+    else await rename(temporary, target);
+  } finally {
+    try { await unlink(temporary); } catch (e) { if (e.code !== 'ENOENT') throw e; }
+  }
+}
+
+function processEnded(pid) {
+  if (!Number.isSafeInteger(pid) || pid < 1) return false;
+  try { process.kill(pid, 0); return false; } catch (e) { return e.code === 'ESRCH'; }
+}
+
+/** A short-lived file mutex, not a workflow transaction or a lock takeover service. */
+async function acquire(context, operation, source, resume) {
+  const path = join(context.store, '.publish-lock');
+  const recovery = join(context.store, '.publish-resume');
+  await safe(context.projectRoot, path);
+  await safe(context.projectRoot, recovery);
+  if (await present(recovery)) fail('design recovery is unfinished; inspect original gateway evidence');
+  const record = { owner: OWNER, operation, source, host: hostname(), pid: process.pid, token: randomUUID() };
+  if (await present(path)) {
+    if (!resume) fail('design publication is locked; do not remove another owner lock');
+    const originalBytes = await readFile(path), previous = JSON.parse(originalBytes);
+    if (previous.owner !== OWNER || previous.operation !== operation || previous.source !== source || previous.host !== hostname() || !processEnded(previous.pid)) fail('design lock cannot be resumed by this operation');
+    // An exclusive recovery guard prevents two resumptions from deleting each other's new lock.
+    await atomicFile(context, recovery, JSON.stringify(record), true);
+    try {
+      if (!originalBytes.equals(await readFile(path))) fail('design lock changed during recovery');
+      if (!processEnded(previous.pid)) fail('original publication process is still running');
+      await unlink(path);
+      await atomicFile(context, path, JSON.stringify(record), true);
+    } finally {
+      if (JSON.parse(await readFile(recovery, 'utf8')).token === record.token) await unlink(recovery);
+    }
+  } else {
+    try { await atomicFile(context, path, JSON.stringify(record), true); }
+    catch (e) { if (e.code === 'EEXIST') fail('design publication is locked'); throw e; }
+  }
+  const release = async () => {
+    const actual = await present(path);
+    if (!actual) return;
+    await safe(context.projectRoot, path);
+    const current = JSON.parse(await readFile(path, 'utf8'));
+    if (current.token !== record.token) fail('design lock owner changed; preserving lock');
+    await unlink(path);
+  };
+  if (await present(recovery)) { await release(); fail('design recovery is in progress'); }
+  return release;
+}
+
+async function changeFor(context, id) {
+  const location = runtime.resolveChangeSync(context, id, {includeArchived:true});
+  const facts = location.kind === 'legacy-archive' ? runtime.readLegacyChangeEvidenceSync(context, location) : runtime.readChangeFactsSync(context, location);
+  return {root:location.root, location, facts};
+}
+
+function within(root, path) {
+  const rel = relative(root, path);
+  return rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+async function assertWriterState(context, change, mode, alreadyPublished = false) {
+  if (change.location.kind === 'legacy-archive') fail('legacy archive is read-only; it cannot own a new design publication');
+  if (change.location.kind === 'archive' && !alreadyPublished) fail('new design publication must complete before change archival');
+  const { readChangeOwner } = await import('./change-artifacts.mjs');
+  const owner = readChangeOwner(context, change.location.name);
+  if (mode === 'bootstrap' && !alreadyPublished) {
+    if (change.facts.outcome !== 'active') fail('bootstrap must remain in its active change');
+    if (owner.work !== 'specdev/prototype') fail('bootstrap requires the owning prototype Work and its evidence');
+  }
+  if (mode === 'promotion') {
+    if (change.facts.outcome !== 'completed') fail('design promotion requires completed change evidence');
+    const { validateChange } = await import('./validate-specdev.mjs');
+    const result = validateChange(change.root, 'complete', context.projectRoot, null, null, {context});
+    if (result.errors.length) fail(`design promotion requires complete acceptance evidence: ${result.errors.join('; ')}`);
+  }
+}
+
+async function verifyApproval(context, sourceChange, candidate, digest, approval, expectedCurrent) {
+  if (!approval.record || !HASH.test(approval.record.sha256 ?? '')) fail('design approval requires a locatable confirmation record and digest');
+  const recordPath = await localFile(context, approval.record.path, approval.record);
+  const commandReports = join(dirname(context.state), 'commands', 'archive-and-consolidate');
+  if (!within(sourceChange.root, recordPath) && !within(commandReports, recordPath) && !within(join(context.state,'maintenance'), recordPath)) fail('design confirmation record is outside the owning change/report');
+  const bytes = await readFile(recordPath), text = bytes.toString('utf8');
+  if (sha256(bytes) !== approval.record.sha256) fail('design confirmation record digest drift');
+  const bindings = [approval.source, approval.confirmed_at, digest, expectedCurrent ?? 'absent'];
+  if (approval.preview) bindings.push(approval.preview.sha256, approval.preview.prototype_digest);
+  if (bindings.some(value => !text.includes(value))) fail('design confirmation record does not bind the approved content');
+  const rootDesign = join(context.projectRoot, 'DESIGN.md');
+  await safe(context.projectRoot, rootDesign);
+  const existing = await present(rootDesign);
+  if (!existing) {
+    if (approval.project_design) fail('approved user DESIGN is missing');
+    return;
+  }
+  if (!existing.isFile()) fail('user DESIGN is not a regular file');
+  const rootHash = await fileHash(rootDesign), decision = approval.project_design;
+  if (!decision || typeof decision.owner !== 'string' || !decision.owner.trim() || /^(?:unknown|unresolved|unspecified|none|n\/a|未知|未解析)/i.test(decision.owner.trim()) || decision.disposition !== 'derived-readonly') fail('user DESIGN owner and derived-readonly authority must be explicit');
+  if (decision.sha256 !== rootHash) fail('user DESIGN digest drift');
+  if (!candidate.meta.sources.some(source => ['DESIGN.md', '<Path>DESIGN.md</Path>'].includes(source.locator) && source.digest === rootHash)) fail('candidate must cite the existing user DESIGN and its byte digest');
+  if ([decision.owner, decision.disposition, rootHash].some(value => !text.includes(value))) fail('confirmation record must bind the preserved user DESIGN authority');
+}
+
+async function verifySources(context, meta, mode, alreadyPublished = false) {
+  for (const rule of meta.rules) {
+    if (mode === 'bootstrap' && rule.verification !== 'approved-intent') fail('bootstrap rules must be approved-intent');
+    for (const source of rule.sources) {
+      if (isAbsolute(source.locator) || source.locator.includes('\\') || source.locator.split('/').includes('..')) fail('unsafe design evidence locator');
+      const change = await changeFor(context, source.change);
+      if(rule.verification === 'implemented' && change.facts.readonly && !alreadyPublished) fail(`implemented rule ${rule.id}: legacy archive alone does not prove completed acceptance; preserve its historical snapshot and obtain a current completion chain`);
+      if (rule.verification === 'implemented' && !(change.facts.readonly ? change.facts.status.change_status === 'archived' : change.facts.outcome === 'completed')) fail(`implemented rule ${rule.id} requires a completed source change`);
+      if (rule.verification === 'implemented' && !change.facts.readonly) {
+        const {validateChange} = await import('./validate-specdev.mjs');
+        const completed = validateChange(change.root,'complete',context.projectRoot,null,null,{context});
+        if (completed.errors.length) fail(`implemented rule ${rule.id} source completion is unverified: ${completed.errors.join('; ')}`);
+      }
+      // A change-relative locator survives archival without rewriting immutable baselines.
+      const projectRelative = source.locator.startsWith('<Path>') || source.locator.startsWith('{roots.') || source.locator.startsWith('.agents/');
+      const path = projectRelative ? await localFile(context, source.locator) : runtime.safeWorkPathSync(change.root, source.locator, {mustExist:true,type:'file'});
+      if (rule.verification === 'implemented') {
+        const rel = portable(relative(change.root, path));
+        if (!rel.startsWith('evidence/') || rel.includes('/../')) fail(`implemented rule ${rule.id} requires change Evidence`);
+      }
+      if (await fileHash(path) !== source.digest) fail(`design evidence digest drift: ${rule.id}`);
+    }
+  }
+}
+
+async function indexContent(context, current) {
+  const lines = ['# Project design revisions', '', '当前规范：`DESIGN.md`。本索引是可重建投影，历史快照不可变。', '', '| Revision | Current | SHA-256 | Supersedes |', '|---|---|---|---|'];
+  let currentRecord;
+  for (const name of (await readdir(context.revisions)).filter(name => /^DESIGN-\d{4,}\.md$/.test(name)).sort()) {
+    const path = await safe(context.projectRoot, join(context.revisions, name));
+    const record = await validateProjectDesign(path);
+    if (name !== `${record.meta.revision}.md`) fail('design revision filename mismatch');
+    if (record.meta.revision === current) currentRecord = record;
+    lines.push(`| [${record.meta.revision}](revisions/${name}) | ${record.meta.revision === current ? 'yes' : ''} | ${await fileHash(path)} | ${record.meta.supersedes ?? 'none'} |`);
+  }
+  const cell = value => String(value).replaceAll('|', '\\|').replace(/[\r\n]+/g, ' ');
+  lines.push('', '## Current rule lookup', '', '| Rule ID | Scope | Verification | Locator |', '|---|---|---|---|');
+  for (const rule of currentRecord?.meta.rules ?? []) lines.push(`| ${cell(rule.id)} | ${cell(rule.scope.join(', '))} | ${rule.verification} | [DESIGN.md](DESIGN.md) |`);
+  return `${lines.join('\n')}\n`;
+}
+
+/** Caller owns user authorization and persistence of this bounded publication receipt. */
+export async function publishDesign({ repoRoot, methodRoot, stateRoot, context: suppliedContext, candidatePath, approval, mode = 'bootstrap', expectedCurrent = null, apply = false, resume = false }) {
+  const receipt = { owner: OWNER, mode, applied: false, checkpoints: [], paths: {}, recovery: null };
+  let release;
+  try {
+    if (!['bootstrap', 'promotion'].includes(mode)) fail('invalid design publication mode');
+    if (expectedCurrent !== null && !HASH.test(expectedCurrent)) fail('invalid expected current digest');
+    const workContext = designContext(candidatePath, {repoRoot,methodRoot,stateRoot,context:suppliedContext});
+    const context = {...workContext, state:workContext.specdevRoot};
+    context.store = join(context.state, 'design');
+    context.revisions = join(context.store, 'revisions');
+    const currentPath = join(context.store, 'DESIGN.md'), indexPath = join(context.store, 'INDEX.md');
+    const candidate = await safe(context.projectRoot, canonicalToolPath(context, candidatePath));
+    const rel = portable(relative(context.state, candidate));
+    const matched = /^(?:changes(?:\/archive)?|archive\/\d{4}-\d{2})\/(\d{4}-\d{2}-\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*)\/.+\.md$/.exec(rel);
+    if (!matched) fail('design candidate must belong to a SpecDev change');
+    const sourceChange = await changeFor(context, matched[1]);
+    const withinChange = relative(sourceChange.root, candidate);
+    if (withinChange === '..' || withinChange.startsWith(`..${sep}`) || isAbsolute(withinChange)) fail('candidate does not belong to the resolved source change');
+    context.sourceName = matched[1];
+    const record = await validateProjectDesign(candidate), bytes = await readFile(candidate), digest = sha256(bytes);
+    if (!approval || approval.approved !== true || typeof approval.source !== 'string' || !approval.source.trim() || !/^\d{4}-\d{2}-\d{2}T/.test(approval.confirmed_at ?? '') || Number.isNaN(Date.parse(approval.confirmed_at))) fail('explicit design approval record is required');
+    if (approval.candidate_sha256 !== digest || approval.current_sha256 !== expectedCurrent) fail('design approval digest does not match candidate/current');
+    if (approval.locator_version !== undefined && approval.locator_version !== 2) fail('unknown approval locator version');
+    if (approval.locator_version !== 2 && [approval.record,approval.preview].some(value => value && ('base' in value || 'change' in value))) fail('relative locator bases require approval locator_version: 2');
+    if (approval.locator_version === 2) for (const [kind,locator] of [['record',approval.record],['preview',approval.preview]]) {
+      if (!locator && kind === 'preview') continue;
+      const keys = new Set(kind === 'record' ? ['base','change','path','sha256'] : ['base','change','path','sha256','package_path','prototype_digest']);
+      if (!locator || !['project','change'].includes(locator.base) || Object.keys(locator).some(key=>!keys.has(key)) || (locator.base === 'change' ? locator.change !== context.sourceName : locator.change !== undefined)) fail('v2 approval locator must declare its exact project/change base and owner');
+    }
+    const preview = approval.preview;
+    if (mode === 'bootstrap' && (!preview || !HASH.test(preview.sha256 ?? '') || !HASH.test(preview.prototype_digest ?? '') || typeof preview.package_path !== 'string')) fail('bootstrap approval must include the displayed HTML preview and complete package digest');
+    async function verifyPreview() {
+      if (!preview) return;
+      const previewPath = await localFile(context, preview.path, preview);
+      if (!/\.html?$/i.test(previewPath) || await fileHash(previewPath) !== preview.sha256) fail('design preview digest drift');
+      const packagePath = await localFile(context, preview.package_path, preview);
+      const packageRelative = portable(relative(sourceChange.root, packagePath));
+      if (!/^prototypes\/UI-\d{3,}\/design-system\.md$/.test(packageRelative) || previewPath !== join(dirname(packagePath), 'final', 'index.html')) fail('design approval preview must belong to its change prototype package');
+      if (await prototypeDigest(packagePath) !== preview.prototype_digest) fail('design prototype package digest drift');
+      if (mode === 'bootstrap') {
+        const { validate } = await import('../../specdev-p-prototype/scripts/validate-design-package.mjs');
+        await validate(packagePath, {checkPreview:true,context});
+        const { readDesign } = await import('./design-artifacts.mjs');
+        const changeDesign = await readDesign(join(sourceChange.root,'DESIGN.md'));
+        if (changeDesign.meta.baseline.revision !== record.meta.revision || changeDesign.meta.baseline.digest !== record.digest) fail('bootstrap change DESIGN must bind the approved candidate baseline revision/digest');
+      }
+    }
+    await verifyPreview();
+    await verifyApproval(context, sourceChange, record, digest, approval, expectedCurrent);
+    const snapshot = join(context.revisions, `${record.meta.revision}.md`);
+    for (const path of [context.state, context.store, context.revisions, currentPath, indexPath, snapshot]) await safe(context.projectRoot, path);
+    receipt.paths = Object.fromEntries(Object.entries({ current: currentPath, revision: snapshot, index: indexPath }).map(([key, path]) => [key, portable(relative(context.projectRoot, path))]));
+    receipt.revision = record.meta.revision;
+    receipt.candidate_sha256 = digest;
+    receipt.design_digest = record.digest;
+    const operation = sha256(JSON.stringify({ mode, digest, expectedCurrent, source: approval.source, confirmed_at: approval.confirmed_at, record: approval.record, project_design: approval.project_design, preview }));
+    receipt.operation = operation;
+    async function verifyCurrent() {
+      const existing = await present(currentPath);
+      if (!existing) {
+        if (expectedCurrent !== null || mode !== 'bootstrap' || record.meta.revision !== 'DESIGN-0001' || record.meta.supersedes !== null) fail('design current is missing or bootstrap revision is invalid');
+        return false;
+      }
+      await safe(context.projectRoot, currentPath);
+      const current = await validateProjectDesign(currentPath), currentHash = await fileHash(currentPath);
+      const oldSnapshot = await safe(context.projectRoot, join(context.revisions, `${current.meta.revision}.md`));
+      if (!await present(oldSnapshot) || await fileHash(oldSnapshot) !== currentHash) fail('current DESIGN differs from its immutable revision');
+      if (currentHash === digest) return true;
+      if (currentHash !== expectedCurrent || mode !== 'promotion') fail('design current digest drift; rebase the candidate');
+      const next = Number(REVISION.exec(current.meta.revision)?.[1]) + 1;
+      if (!Number.isSafeInteger(next) || record.meta.revision !== `DESIGN-${String(next).padStart(4, '0')}` || record.meta.supersedes !== current.meta.revision) fail('design revision must be the next revision and supersede current');
+      return false;
+    }
+    let alreadyPublished = await verifyCurrent();
+    await verifySources(context, record.meta, mode, alreadyPublished);
+    await assertWriterState(context, sourceChange, mode, alreadyPublished);
+    if (await present(snapshot) && await fileHash(snapshot) !== digest) fail('immutable design revision conflict');
+    receipt.checkpoints.push('validated');
+    receipt.already_published = alreadyPublished;
+    if (!apply) {
+      if (await present(join(context.store, '.publish-lock')) || await present(join(context.store, '.publish-resume'))) fail('design publication is locked');
+      return receipt;
+    }
+    await mkdir(context.store, { recursive: true });
+    await safe(context.projectRoot, context.store);
+    release = await acquire(context, operation, approval.source, resume);
+    await mkdir(context.revisions, { recursive: true });
+    await safe(context.projectRoot, context.revisions);
+    await assertWriterState(context, await changeFor(context, matched[1]), mode, await verifyCurrent());
+    if (await fileHash(candidate) !== digest) fail('design candidate changed after approval');
+    await verifyPreview();
+    await verifyApproval(context, sourceChange, record, digest, approval, expectedCurrent);
+    alreadyPublished = await verifyCurrent();
+    await verifySources(context, record.meta, mode, alreadyPublished);
+    if (await present(snapshot)) {
+      if (await fileHash(snapshot) !== digest) fail('immutable design revision conflict');
+    } else await atomicFile(context, snapshot, bytes, true);
+    if (await fileHash(snapshot) !== digest) fail('design revision readback failed');
+    receipt.checkpoints.push('revision-written');
+    if (!alreadyPublished) await atomicFile(context, currentPath, bytes, mode === 'bootstrap');
+    if (await fileHash(currentPath) !== digest) fail('design current readback failed');
+    receipt.applied = true;
+    receipt.checkpoints.push('current-published');
+    const index = await indexContent(context, record.meta.revision);
+    await atomicFile(context, indexPath, index);
+    if (await readFile(indexPath, 'utf8') !== index) fail('design index readback failed');
+    receipt.checkpoints.push('index-written');
+    return receipt;
+  } catch (error) {
+    receipt.recovery = 'Read the original approval/report and actual current/revision; retry the identical operation only after resolving its blocker.';
+    error.receipt = receipt;
+    throw error;
+  } finally {
+    if (release) {
+      try { await release(); }
+      catch (error) { error.receipt = receipt; throw error; }
+    }
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2), options = {};
+  for (let i = 0; i < args.length; i++) {
+    const key = args[i];
+    if (['--apply', '--resume', '--expect-absent'].includes(key)) { options[key.slice(2)] = true; continue; }
+    if (!['--candidate', '--state-root', '--repo', '--method-root', '--approval', '--mode', '--expected-current'].includes(key) || !args[i + 1] || args[i + 1].startsWith('--')) fail(`unknown or incomplete argument: ${key}`);
+    options[key.slice(2)] = args[++i];
+  }
+  if (!options.candidate || !options['state-root'] || !options.approval || Boolean(options['expect-absent']) === Boolean(options['expected-current'])) fail('provide --candidate, --state-root, --approval and exactly one expected-current option');
+  const context = designContext(options.candidate, {repoRoot:options.repo,methodRoot:options['method-root'],stateRoot:options['state-root']});
+  const approvalPath = await safe(context.projectRoot, resolve(context.projectRoot,options.approval));
+  const approval = JSON.parse(await readFile(approvalPath, 'utf8'));
+  return publishDesign({ context, stateRoot: options['state-root'], candidatePath: options.candidate, approval, mode: options.mode, expectedCurrent: options['expected-current'] ?? null, apply: Boolean(options.apply), resume: Boolean(options.resume) });
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().then(result => process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)).catch(error => {
+    process.stderr.write(`${JSON.stringify({ error: error.message, receipt: error.receipt ?? null }, null, 2)}\n`);
+    process.exitCode = 1;
+  });
+}

package/template/workflows/specdev/common/tools/review-scope.mjs

@@ -1,8 +1,48 @@
-/** Read-only Git review selection. Resolves refs once; never fetches or writes state. */
+/** Read-only review selection. Freezes local files or Git refs; never fetches or writes state. */
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
+import { closeSync, constants, fstatSync, openSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
 
-const modes = new Set(['baseline', 'range', 'commit', 'pr']);
+const modes = new Set(['baseline', 'range', 'commit', 'pr', 'source-files']);
+function contained(root, path) {
+  const rel = relative(root, path);
+  if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw new Error('review-scope: each source file must remain within the explicit project root');
+  }
+  return rel.split(sep).join('/');
+}
+function sourceFiles(options) {
+  if (['base', 'head', 'commit', 'parent'].some(key => options[key] !== undefined)) {
+    throw new Error('review-scope: source-files does not accept Git comparison options');
+  }
+  if (!Array.isArray(options.files) || !options.files.length) throw new Error('review-scope: source-files requires at least one --file');
+  const root = realpathSync(resolve(options.repo));
+  if (!statSync(root).isDirectory()) throw new Error('review-scope: repo must be a project directory');
+  const seen = new Set(), source_snapshot = [];
+  for (const path of options.files) {
+    if (typeof path !== 'string' || !path || isAbsolute(path) || /[\\:\x00-\x1f]/.test(path) || path.split('/').some(part => !part || part === '.' || part === '..')) {
+      throw new Error('review-scope: --file must be an explicit portable project-relative file path');
+    }
+    const requested = resolve(root, path), actual = realpathSync(requested);
+    const resolved_path = contained(root, actual);
+    if (seen.has(actual)) throw new Error('review-scope: duplicate source file or alias');
+    seen.add(actual);
+    if (!statSync(actual).isFile()) throw new Error('review-scope: --file must select a regular file');
+    const descriptor = openSync(actual, constants.O_RDONLY | constants.O_NONBLOCK | (constants.O_NOFOLLOW ?? 0));
+    try {
+      const before = fstatSync(descriptor, { bigint: true });
+      if (!before.isFile()) throw new Error('review-scope: --file must select a regular file');
+      const bytes = readFileSync(descriptor);
+      const after = fstatSync(descriptor, { bigint: true });
+      const current = statSync(actual, { bigint: true });
+      const stable = ['dev', 'ino', 'size', 'mtimeNs', 'ctimeNs'].every(key => before[key] === after[key] && after[key] === current[key]);
+      if (!stable || realpathSync(requested) !== actual) throw new Error('review-scope: source file changed while freezing inputs; retry from current evidence');
+      source_snapshot.push({ path, sha256: createHash('sha256').update(bytes).digest('hex'), bytes: bytes.length, ...(resolved_path === path ? {} : { resolved_path }) });
+    } finally { closeSync(descriptor); }
+  }
+  return { version: 1, mode: 'source-files', review_mode: 'source-files', outcome: 'source-snapshot', source_snapshot };
+}
 function git(repo, args, encoding = 'utf8') {
   return execFileSync('git', ['-C', repo, ...args], {
     encoding, maxBuffer: 32 * 1024 * 1024, timeout: 30000,
@@ -25,8 +65,10 @@ function commit(repo, ref, field) {
 export function resolveReviewScope(options) {
   const { repo, mode } = options;
   if (typeof repo !== 'string' || !repo || !modes.has(mode)) {
-    throw new Error('review-scope: --repo and --mode baseline|range|commit|pr are required');
+    throw new Error('review-scope: --repo and --mode baseline|range|commit|pr|source-files are required');
   }
+  if (mode === 'source-files') return sourceFiles(options);
+  if (options.files !== undefined) throw new Error('review-scope: --file requires source-files mode');
   git(repo, ['rev-parse', '--git-dir']);
   let base, head;
   let selectedParent = null;
@@ -69,13 +111,14 @@ export function resolveReviewScope(options) {
 /** Strict argv admission; inputs are passed to Git as argv, never as shell text. */
 export function reviewScopeCLI(argv) {
   const options = {};
-  const allowed = new Set(['repo', 'mode', 'base', 'head', 'commit', 'parent']);
+  const allowed = new Set(['repo', 'mode', 'base', 'head', 'commit', 'parent', 'file']);
   for (let i = 0; i < argv.length; i++) {
     const key = argv[i].startsWith('--') ? argv[i].slice(2) : '';
-    if (!allowed.has(key) || Object.hasOwn(options, key)) throw new Error(`review-scope: invalid or duplicate option ${argv[i]}`);
+    if (!allowed.has(key) || key !== 'file' && Object.hasOwn(options, key)) throw new Error(`review-scope: invalid or duplicate option ${argv[i]}`);
     const value = argv[++i];
     if (!value || value.startsWith('--')) throw new Error(`review-scope: missing ${key}`);
-    options[key] = value;
+    if (key === 'file') (options.files ??= []).push(value);
+    else options[key] = value;
   }
   console.log(JSON.stringify(resolveReviewScope(options), null, 2));
   return 0;

package/template/workflows/specdev/common/tools/tests/engineering.test.mjs

@@ -22,13 +22,12 @@ const performance = () => ({ version: 1, kind: 'performance', checkpoint: 'basel
 const documentation = () => ({ version: 1, kind: 'documentation', checkpoint: 'documentation-revision', evidence: ['observed command output'], owner_paths: ['README owner'], outcome: 'verified', visible_behavior_changed: false, behavior_verification: 'not-applicable', claims: [{ subject: 'example runs', method: 'command', state: 'verified', evidence: ['example stdout'], command: 'node example.mjs', executed: true, exit_code: 0, output: ['actual expected output'] }] });
 const incident = () => ({ version: 1, kind: 'incident', checkpoint: 'incident-revision', evidence: ['sanitized incident log'], facts: ['request timed out'], unknowns: ['remote effect unknown'], next_checks: ['read remote marker'], feedback_loop_ready: false, root_cause_confirmed: false });
 function change(t) {
-  const root = join(temporary(t), '2026-10-11-engineering');
-  mkdirSync(root);
-  const status = JSON.parse(readFileSync(join(workflow, 'I-init-setup/change-status-template.json'), 'utf8'));
-  status.change = '2026-10-11-engineering';
-  status.created_at = status.updated_at = status.leadership.assigned_at = '2026-10-11T00:00:00Z';
-  status.leadership.current = 'test-owner';
-  writeFileSync(join(root, '.status.json'), JSON.stringify(status, null, 2) + '\n');
+  const project=temporary(t), state=join(project,'.agents/speculo/.speculo');
+  const root = join(state,'specdev/changes/2026-10-11-engineering');
+  mkdirSync(root,{recursive:true});
+  writeFileSync(join(state,'workspace.json'),readFileSync(join(workflow,'../../.speculo/workspace.json')));
+  writeFileSync(join(state,'specdev/config.json'),readFileSync(join(workflow,'specdev-i-init-setup/assets/config-template.json')));
+  writeFileSync(join(root, 'README.md'), '# Engineering investigation\nOutcome: active\n');
   return root;
 }
 function run(args) {
@@ -142,13 +141,13 @@ test('all specialized branches are discoverable from their unchanged owner entri
   assert.deepEqual(validateEngineeringPackage(workflow), []);
 });
 test('real validator accepts measurements and rejects the controlled regression', t => {
-  const root = change(t), status = readFileSync(join(root, '.status.json'));
+  const root = change(t), status = readFileSync(join(root, 'README.md'));
   const file = join(root, 'architecture-review.md'), record = performance();
   writeFileSync(file, '# Measurement\n' + fence(record));
   const good = run(['--engineering', 'performance', root]); assert.equal(good.status, 0, good.output);
   record.baseline.samples = []; writeFileSync(file, '# Measurement\n' + fence(record));
   const bad = run(['--engineering', 'performance', root]); assert.equal(bad.status, 1, bad.output); assert.match(bad.output, /samples/);
-  assert.deepEqual(readFileSync(join(root, '.status.json')), status);
+  assert.deepEqual(readFileSync(join(root, 'README.md')), status);
 });
 test('ordinary real validation also rejects malformed marked observations', t => {
   const root = change(t); writeFileSync(join(root, 'architecture-review.md'), '```json specdev-engineering-evidence\n{\n```');
@@ -159,7 +158,7 @@ test('specialist CLI admission requires its existing artifact and exclusive flag
   for (const args of [ ['--engineering', 'performance', root], ['--engineering', 'wrong', root], ['--engineering', 'performance', '--self-check'], ['--engineering', 'performance', '--engineering', 'performance', root] ]) {
     const r = run(args); assert.notEqual(r.status, 0, JSON.stringify(args));
   }
-  assert.deepEqual(readdirSync(root), ['.status.json']);
+  assert.deepEqual(readdirSync(root), ['README.md']);
 });
 test('real documentation validation does not accept an unexecuted command', t => {
   const root = change(t); mkdirSync(join(root, 'evidence'));
@@ -171,7 +170,7 @@ test('real documentation validation does not accept an unexecuted command', t =>
 });
 test('incident stage cannot advance a diagnosis without its actual red feedback contract', t => {
   const root = change(t), file = join(root, 'diagnosis.md');
-  let body = readFileSync(join(workflow, 'D-diagnose-bugs/diagnosis-template.md'), 'utf8')
+  let body = readFileSync(join(workflow, 'specdev-d-diagnose-bugs/assets/diagnosis-template.md'), 'utf8')
     .replace('change: <YYYY-MM-DD-topic>', 'change: 2026-10-11-engineering')
     .replace('status: reproducing', 'status: blocked').replace('cleanup_status: pending', 'cleanup_status: clean')
     .replace('updated_at: <ISO-8601>', 'updated_at: 2026-10-11T00:00:00Z')
@@ -225,10 +224,10 @@ test('range comparison and merge-base comparison have distinct semantics', t =>
   assert.deepEqual(baseline.changed_paths, ['side.txt']); assert.deepEqual(range.changed_paths, ['b.txt', 'c.txt', 'side.txt']);
 });
 test('fifteen Work IDs and persisted schema versions remain unchanged', () => {
-  const entries = readdirSync(workflow).filter(name => /^[A-Z]-/.test(name)); assert.equal(entries.length, 15);
-  const ids = entries.map(name => /^id: (.+)$/m.exec(readFileSync(join(workflow, name, `${name}.md`), 'utf8'))?.[1]);
+  const entries = readdirSync(workflow).filter(name => /^specdev-[a-z]-/.test(name)); assert.equal(entries.length, 15);
+  const ids = entries.map(name => /speculo-id: (.+)$/m.exec(readFileSync(join(workflow, name, 'SKILL.md'), 'utf8'))?.[1]);
   assert.deepEqual(ids.sort(), ['archive-and-consolidate','code-review','diagnose-bugs','goal-plan','grill-with-docs','implement','init-setup','learn-change','prototype','retro','review-architecture','spec','tickets','triage','wayfinder'].map(id => 'specdev/' + id).sort());
-  for (const [file, version] of [['config', 6], ['status', 5], ['change-status', 6], ['goal-plan', 6]]) {
+  for (const [file, version] of [['config', 7], ['status', 5], ['change-status', 6], ['goal-plan', 7]]) {
     const schema = JSON.parse(readFileSync(join(workflow, 'common/schemas', `${file}.schema.json`), 'utf8'));
     assert.equal(schema.properties.schema_version.const, version);
   }
@@ -243,12 +242,11 @@ test('review scope ignores configured external diff and forced color', t => {
   assert.equal(scope.diff_sha256, plain.diff_sha256); assert.equal(existsSync(sentinel), false);
 });
 test('specialist validation errors do not create remote ledgers or reopen completed states', t => {
-  const root = change(t), statusPath = join(root, '.status.json');
-  const status = JSON.parse(readFileSync(statusPath, 'utf8'));
-  status.change_status = 'completed'; status.completed_at = '2026-10-11T00:00:00Z';
-  writeFileSync(statusPath, JSON.stringify(status)); const before = readFileSync(statusPath);
+  const root = change(t), statusPath = join(root, 'README.md');
+  const status = readFileSync(statusPath, 'utf8').replace('Outcome: active', 'Outcome: completed');
+  writeFileSync(statusPath, status); const before = readFileSync(statusPath);
   const r = run(['--engineering', 'performance', root]); assert.notEqual(r.status, 0);
-  assert.deepEqual(readFileSync(statusPath), before); assert.deepEqual(readdirSync(root), ['.status.json']);
+  assert.deepEqual(readFileSync(statusPath), before); assert.deepEqual(readdirSync(root), ['README.md']);
 });
 test('correcting a candidate preserves historical incident observation bytes', t => {
   const root = change(t), original = fence(incident()), file = join(root, 'diagnosis.md');

package/template/workflows/specdev/common/tools/tests/review-source-files.test.mjs

@@ -0,0 +1,74 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { mkdtempSync, mkdirSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { resolveReviewScope } from '../review-scope.mjs';
+
+const tool = fileURLToPath(new URL('../review-scope.mjs', import.meta.url));
+function fixture(t) {
+  const parent = mkdtempSync(join(tmpdir(), 'specdev-source-review-'));
+  t.after(() => rmSync(parent, { recursive: true, force: true }));
+  const root = join(parent, 'project'); mkdirSync(root);
+  mkdirSync(join(root, 'src')); writeFileSync(join(root, 'src/shipping.mjs'), 'export const fee = 500;\n');
+  return { root, parent };
+}
+function manifest(root, relative = '') {
+  return readdirSync(join(root, relative), { withFileTypes: true }).flatMap(entry => {
+    const path = relative ? `${relative}/${entry.name}` : entry.name;
+    return entry.isDirectory() ? manifest(root, path) : [[path, createHash('sha256').update(readFileSync(join(root, path))).digest('hex')]];
+  });
+}
+function cli(root, args) {
+  return spawnSync(process.execPath, ['--input-type=module', '-e', `import { reviewScopeCLI } from ${JSON.stringify(new URL('../review-scope.mjs', import.meta.url).href)}; reviewScopeCLI(process.argv.slice(1));`, '--', '--repo', root, ...args], {
+    encoding: 'utf8', env: { ...process.env, PATH: '' }, cwd: dirname(tool), timeout: 10000,
+  });
+}
+test('file snapshot works without Git or workspace and leaves the full project unchanged', t => {
+  const {root, parent} = fixture(t);
+  // An outer repository marker must not be consulted or inherited.
+  mkdirSync(join(parent, '.git')); writeFileSync(join(parent, '.git/HEAD'), 'synthetic outer marker\n');
+  const before = manifest(parent);
+  const result = cli(root, ['--mode', 'source-files', '--file', 'src/shipping.mjs']);
+  assert.equal(result.status, 0, result.stderr);
+  const scope = JSON.parse(result.stdout);
+  assert.deepEqual(scope.source_snapshot, [{path:'src/shipping.mjs', sha256:createHash('sha256').update(readFileSync(join(root, 'src/shipping.mjs'))).digest('hex'), bytes:24}]);
+  assert.equal(scope.outcome, 'source-snapshot');
+  for (const key of ['fixed_point','head_sha','base_sha','commit_log','approved']) assert.equal(Object.hasOwn(scope, key), false);
+  assert.deepEqual(manifest(parent), before);
+});
+test('source-file paths are literal and changed bytes invalidate their digest', t => {
+  const {root} = fixture(t), path = 'src/[literal] $(touch injected).mjs';
+  writeFileSync(join(root, path), 'first\n');
+  const first = cli(root, ['--mode','source-files','--file',path,'--file','src/shipping.mjs']);
+  assert.equal(first.status, 0, first.stderr); assert.equal(JSON.parse(first.stdout).source_snapshot.length, 2);
+  writeFileSync(join(root, path), 'second\n');
+  const next = resolveReviewScope({repo:root, mode:'source-files', files:[path]});
+  assert.notEqual(JSON.parse(first.stdout).source_snapshot[0].sha256, next.source_snapshot[0].sha256);
+  assert.deepEqual(readdirSync(root), ['src']);
+});
+test('empty, ambiguous, duplicate, directory and escaping source scopes fail without writes', t => {
+  const {root, parent} = fixture(t); writeFileSync(join(parent,'outside'), 'outside\n');
+  symlinkSync(join(parent,'outside'), join(root,'escape'));
+  symlinkSync('src/shipping.mjs', join(root,'alias'));
+  const before = manifest(parent);
+  for (const files of [[], [''], ['../outside'], ['/outside'], ['src/../src/shipping.mjs'], ['src\\shipping.mjs'], ['src'], ['missing'], ['escape'], ['src/shipping.mjs','src/shipping.mjs'], ['alias','src/shipping.mjs']]) {
+    assert.throws(() => resolveReviewScope({repo:root, mode:'source-files', files}), `accepted ${JSON.stringify(files)}`);
+  }
+  const alias = resolveReviewScope({repo:root, mode:'source-files', files:['alias']});
+  assert.equal(alias.source_snapshot[0].resolved_path, 'src/shipping.mjs');
+  assert.deepEqual(manifest(parent), before);
+});
+test('source-files does not weaken Git-mode input admission or silently change modes', t => {
+  const {root} = fixture(t);
+  for (const extra of [{base:'HEAD'}, {head:'HEAD'}, {commit:'HEAD'}, {parent:1}]) assert.throws(() => resolveReviewScope({repo:root,mode:'source-files',files:['src/shipping.mjs'],...extra}), /does not accept Git/);
+  assert.throws(() => resolveReviewScope({repo:root,mode:'range',files:['src/shipping.mjs'],base:'HEAD',head:'HEAD'}), /requires source-files/);
+  for (const args of [
+    ['--mode','source-files'], ['--mode','source-files','--file','src/shipping.mjs','--repo',root],
+    ['--mode','source-files','--file','src/shipping.mjs','--file','src/shipping.mjs'],
+    ['--mode','source-files','--unknown','x'], ['--mode','range','--base','HEAD','--head','HEAD'],
+  ]) assert.notEqual(cli(root,args).status,0,JSON.stringify(args));
+});