@namewta/speculo 1.0.22 → 2.0.1

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

@@ -0,0 +1,125 @@
+/** 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', '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,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0' },
+  });
+}
+function commit(repo, ref, field) {
+  if (typeof ref !== 'string' || !ref || ref.startsWith('-') || ref.includes('\0')) {
+    throw new Error(`review-scope: ${field} must be an explicit Git ref`);
+  }
+  try {
+    return git(repo, ['rev-parse', '--verify', '--end-of-options', `${ref}^{commit}`]).trim();
+  } catch {
+    throw new Error(`review-scope: ${field} cannot resolve to a local commit; read/fetch the authorized object first`);
+  }
+}
+
+/** Resolve the exact comparison and return bounded metadata, not the entire diff. */
+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|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;
+  if (mode === 'commit') {
+    if (options.base !== undefined || options.head !== undefined) throw new Error('review-scope: commit mode does not accept base/head');
+    head = commit(repo, options.commit, 'commit');
+    const parents = git(repo, ['rev-list', '--parents', '-n', '1', head]).trim().split(/\s+/).slice(1);
+    if (!parents.length) throw new Error('review-scope: root commit has no committed baseline; do not fabricate a CR fixed_point');
+    if (parents.length > 1 && options.parent === undefined) throw new Error('review-scope: merge commit requires explicit --parent');
+    selectedParent = options.parent === undefined ? 1 : Number(options.parent);
+    if (!Number.isSafeInteger(selectedParent) || selectedParent < 1 || selectedParent > parents.length) throw new Error('review-scope: invalid parent number');
+    base = parents[selectedParent - 1];
+  } else {
+    if (options.commit !== undefined || options.parent !== undefined) throw new Error('review-scope: commit/parent require commit mode');
+    base = commit(repo, options.base, 'base');
+    head = commit(repo, options.head, 'head');
+    if (mode === 'pr' && (![options.base, options.head].every(value => /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/i.test(value)))) {
+      throw new Error('review-scope: PR mode requires exact remotely observed base/head SHAs, not moving names');
+    }
+  }
+  let comparisonBase = base;
+  if (mode === 'baseline' || mode === 'pr') {
+    const bases = git(repo, ['merge-base', '--all', base, head]).trim().split(/\s+/).filter(Boolean);
+    if (bases.length !== 1) throw new Error('review-scope: comparison requires one unambiguous merge base');
+    comparisonBase = bases[0];
+  }
+  const diffArgs = ['diff', '--no-color', '--no-ext-diff', '--no-textconv', '--binary', '--no-renames', comparisonBase, head, '--'];
+  const diff = git(repo, diffArgs, null);
+  const names = git(repo, ['diff', '--no-color', '--no-ext-diff', '--no-textconv', '--no-renames', '--name-only', '-z', comparisonBase, head, '--'])
+    .split('\0').filter(Boolean);
+  return {
+    version: 1, mode, outcome: names.length ? 'changes' : 'no-diff',
+    base_sha: base, head_sha: head, fixed_point: comparisonBase,
+    parent: selectedParent, diff_sha256: createHash('sha256').update(diff).digest('hex'),
+    diff_bytes: diff.length, changed_paths: names, diff_command: ['git', ...diffArgs],
+    log_command: ['git', 'log', `${comparisonBase}..${head}`, '--oneline', '--'],
+  };
+}
+
+/** 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', 'file']);
+  for (let i = 0; i < argv.length; i++) {
+    const key = argv[i].startsWith('--') ? argv[i].slice(2) : '';
+    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}`);
+    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

@@ -0,0 +1,265 @@
+/** Read-only admission and real-entry regressions; no network or user state. */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync, rmSync, readdirSync, symlinkSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { engineeringRecords, validateEngineeringRecord, validateEngineeringArtifacts, validateEngineeringPackage } from '../engineering-evidence.mjs';
+import { resolveReviewScope } from '../review-scope.mjs';
+
+const workflow = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
+const cli = join(workflow, 'common/tools/validate-specdev.mjs');
+function temporary(t) {
+  const root = mkdtempSync(join(tmpdir(), 'specdev-engineering-'));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  return root;
+}
+const fence = record => '\n```json specdev-engineering-evidence\n' + JSON.stringify(record, null, 2) + '\n```\n';
+const measurement = () => ({ checkpoint: 'baseline-revision', entrypoint: 'node public-cli.mjs', environment: 'isolated test host', clock: 'process start to ready', workload: 'deterministic fixture', workload_digest: 'a'.repeat(64), unit: 'ms', direction: 'lower', cache: 'cold', excluded_costs: ['external model network'], samples: [20, 22, 21] });
+const performance = () => ({ version: 1, kind: 'performance', checkpoint: 'baseline-revision', evidence: ['observed measurement output'], operation: 'open project', outcome: 'baseline', uncertainty: 'Synthetic workload; no live model latency measured.', baseline: measurement() });
+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 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) {
+  const result = spawnSync(process.execPath, [cli, ...args], { encoding: 'utf8', timeout: 30000 });
+  assert.equal(result.error, undefined);
+  return { ...result, output: result.stdout + result.stderr };
+}
+function git(repo, ...args) {
+  return execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 10000, env: { ...process.env, GIT_CONFIG_NOSYSTEM: '1' } }).trim();
+}
+function repository(t) {
+  const root = temporary(t);
+  git(root, 'init', '-b', 'main');
+  git(root, 'config', 'user.name', 'SpecDev fixture');
+  git(root, 'config', 'user.email', 'fixture@example.invalid');
+  git(root, 'config', 'commit.gpgsign', 'false');
+  function commit(name) {
+    writeFileSync(join(root, name + '.txt'), name + '\n');
+    git(root, 'add', '--', name + '.txt');
+    git(root, 'commit', '-m', name);
+    return git(root, 'rev-parse', 'HEAD');
+  }
+  return { root, a: commit('a'), b: commit('b'), c: commit('c'), commit };
+}
+
+for (const factory of [performance, documentation, incident]) {
+  test(`accepts a consistent ${factory().kind} observation`, () => assert.deepEqual(validateEngineeringRecord(factory()), []));
+}
+for (const [name, mutate] of [
+  ['unknown version', r => r.version = 2],
+  ['empty evidence', r => r.evidence = []],
+  ['empty samples', r => r.baseline.samples = []],
+  ['string samples', r => r.baseline.samples = ['20']],
+  ['negative samples', r => r.baseline.samples = [-1]],
+  ['infinite samples', r => r.baseline.samples = [Infinity]],
+  ['missing endpoint', r => r.baseline.entrypoint = ''],
+  ['unknown cache', r => r.baseline.cache = 'automatic'],
+  ['placeholder digest', r => r.baseline.workload_digest = 'replace-me'],
+]) test(`performance rejects ${name}`, () => {
+  const record = performance(); mutate(record);
+  assert.ok(validateEngineeringRecord(record).length);
+});
+test('inconclusive performance can honestly record missing measurements', () => {
+  const record = performance(); record.outcome = 'inconclusive'; delete record.baseline;
+  assert.deepEqual(validateEngineeringRecord(record), []);
+});
+test('an improvement requires comparable samples and behavior verification', () => {
+  const record = performance(); record.outcome = 'improved'; record.behavior_verification = 'passed';
+  record.candidate = { ...measurement(), checkpoint: 'candidate-revision', samples: [10, 12, 11] };
+  assert.deepEqual(validateEngineeringRecord(record), []);
+  record.candidate.samples = [30, 32, 31];
+  assert.match(validateEngineeringRecord(record).join('\n'), /arithmetic means/);
+  record.candidate.samples = [10, 12, 11]; record.behavior_verification = 'not-run';
+  assert.match(validateEngineeringRecord(record).join('\n'), /behavior verification/);
+});
+for (const field of ['entrypoint', 'environment', 'clock', 'workload_digest', 'unit', 'direction', 'cache', 'excluded_costs']) {
+  test(`performance comparison cannot silently change ${field}`, () => {
+    const r = performance(); r.outcome = 'improved'; r.behavior_verification = 'passed';
+    r.candidate = { ...measurement(), checkpoint: 'candidate', samples: [1], [field]: field === 'excluded_costs' ? [] : 'different' };
+    assert.match(validateEngineeringRecord(r).join('\n'), new RegExp(`comparison changes ${field}`));
+  });
+}
+for (const [name, mutate] of [
+  ['unexecuted command', r => r.claims[0].executed = false],
+  ['nonzero exit', r => r.claims[0].exit_code = 1],
+  ['missing output', r => r.claims[0].output = []],
+  ['unverified aggregate', r => { r.claims[0].state = 'unverified'; r.claims[0].reason = 'no access'; }],
+  ['visible behavior without evidence', r => r.visible_behavior_changed = true],
+]) test(`documentation rejects ${name}`, () => {
+  const r = documentation(); mutate(r); assert.ok(validateEngineeringRecord(r).length);
+});
+test('documentation permits honest partial verification', () => {
+  const r = documentation(); r.outcome = 'partial'; r.claims[0].state = 'unverified'; r.claims[0].reason = 'environment unavailable';
+  assert.deepEqual(validateEngineeringRecord(r), []);
+});
+test('incident observation cannot assert readiness or confirmed cause', () => {
+  for (const field of ['feedback_loop_ready', 'root_cause_confirmed']) {
+    const r = incident(); r[field] = true; assert.match(validateEngineeringRecord(r).join('\n'), /must not assert/);
+  }
+});
+test('fence parser ignores nested examples and checks torn or malformed selected records', () => {
+  assert.deepEqual(engineeringRecords('````markdown\n' + fence(performance()) + '````\n'), { records: [], errors: [] });
+  assert.equal(engineeringRecords(fence(performance())).records.length, 1);
+  assert.ok(engineeringRecords('```json specdev-engineering-evidence\n{\n```\n').errors.length);
+  assert.ok(engineeringRecords('```json specdev-engineering-evidence\n{}').errors.length);
+  assert.ok(validateEngineeringRecord(null).length);
+  assert.ok(validateEngineeringRecord([]).length);
+});
+test('legacy unmarked reports remain unchanged and require no new record', t => {
+  const root = change(t), file = join(root, 'architecture-review.md');
+  writeFileSync(file, '# Historical report\nUnstructured, retained bytes.\n');
+  const before = readFileSync(file);
+  assert.deepEqual(validateEngineeringArtifacts(root), []);
+  assert.deepEqual(readFileSync(file), before);
+});
+test('record ownership is checked without creating absent artifacts', t => {
+  const root = change(t); const before = readdirSync(root);
+  assert.match(validateEngineeringArtifacts(root, 'performance').join('\n'), /missing evidence/);
+  assert.deepEqual(readdirSync(root), before);
+  writeFileSync(join(root, 'architecture-review.md'), fence(documentation()));
+  assert.match(validateEngineeringArtifacts(root).join('\n'), /engineering\/owner/);
+});
+test('symlinked observation owners cannot read outside a change', t => {
+  const root = change(t), outside = join(dirname(root), 'outside.md');
+  writeFileSync(outside, fence(performance()));
+  try { symlinkSync(outside, join(root, 'architecture-review.md')); }
+  catch (e) { if (e.code === 'EPERM') return t.skip('host does not permit fixture symlinks'); throw e; }
+  assert.match(validateEngineeringArtifacts(root).join('\n'), /symlinked evidence owners/);
+});
+test('all specialized branches are discoverable from their unchanged owner entries', () => {
+  assert.deepEqual(validateEngineeringPackage(workflow), []);
+});
+test('real validator accepts measurements and rejects the controlled regression', t => {
+  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, '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```');
+  const result = run([root]); assert.equal(result.status, 1); assert.match(result.output, /engineering\/fence/);
+});
+test('specialist CLI admission requires its existing artifact and exclusive flags', t => {
+  const root = change(t);
+  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), ['README.md']);
+});
+test('real documentation validation does not accept an unexecuted command', t => {
+  const root = change(t); mkdirSync(join(root, 'evidence'));
+  const file = join(root, 'evidence/direct-spec.md'), record = documentation();
+  writeFileSync(file, '# Document checks\n' + fence(record));
+  const good = run(['--engineering', 'documentation', root]); assert.equal(good.status, 0, good.output);
+  record.claims[0].executed = false; writeFileSync(file, fence(record));
+  const bad = run(['--engineering', 'documentation', root]); assert.equal(bad.status, 1); assert.match(bad.output, /verified command/);
+});
+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, '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')
+    .replace(/<Path>[^\n]+?<\/Path>/g, 'not-applicable') + fence(incident());
+  writeFileSync(file, body);
+  const good = run(['--stage', 'diagnosis', '--engineering', 'incident', root]); assert.equal(good.status, 0, good.output);
+  body = body.replace('status: blocked', 'status: root-cause-confirmed'); writeFileSync(file, body);
+  const bad = run(['--stage', 'diagnosis', root]); assert.equal(bad.status, 1); assert.match(bad.output, /requires ready feedback loop/);
+});
+test('single commit selection excludes later HEAD work', t => {
+  const r = repository(t), scope = resolveReviewScope({ repo: r.root, mode: 'commit', commit: r.b });
+  assert.equal(scope.head_sha, r.b); assert.equal(scope.fixed_point, r.a); assert.deepEqual(scope.changed_paths, ['b.txt']);
+});
+test('no-diff is a read-only outcome, not an approval or failed reference', t => {
+  const r = repository(t), before = git(r.root, 'status', '--porcelain');
+  const result = run(['--review-scope', '--repo', r.root, '--mode', 'range', '--base', r.c, '--head', r.c]);
+  assert.equal(result.status, 0, result.output);
+  const scope = JSON.parse(result.stdout); assert.equal(scope.outcome, 'no-diff'); assert.equal(scope.diff_bytes, 0); assert.deepEqual(scope.changed_paths, []);
+  assert.equal(Object.hasOwn(scope, 'approved'), false); assert.equal(git(r.root, 'status', '--porcelain'), before);
+});
+test('new HEAD invalidates a frozen review digest', t => {
+  const r = repository(t), first = resolveReviewScope({ repo: r.root, mode: 'baseline', base: r.a, head: 'HEAD' });
+  r.commit('d'); const next = resolveReviewScope({ repo: r.root, mode: 'baseline', base: r.a, head: 'HEAD' });
+  assert.notEqual(first.head_sha, next.head_sha); assert.notEqual(first.diff_sha256, next.diff_sha256);
+});
+test('PR selection requires both exact observed remote SHAs', t => {
+  const r = repository(t);
+  assert.equal(resolveReviewScope({ repo: r.root, mode: 'pr', base: r.a, head: r.c }).head_sha, r.c);
+  assert.throws(() => resolveReviewScope({ repo: r.root, mode: 'pr', base: r.a, head: 'HEAD' }), /exact remotely observed/);
+});
+test('invalid refs and ambiguous comparison options are refused', t => {
+  const r = repository(t);
+  for (const options of [
+    { mode: 'range', base: 'not-a-ref', head: r.c }, { mode: 'range', base: '--all', head: r.c },
+    { mode: 'commit', commit: r.a }, { mode: 'commit', commit: r.b, head: r.c },
+    { mode: 'commit', commit: r.b, parent: 3 }, { mode: 'range', base: r.a, head: r.c, parent: 1 },
+  ]) assert.throws(() => resolveReviewScope({ repo: r.root, ...options }));
+  assert.notEqual(run(['--review-scope', '--repo', r.root, '--repo', r.root]).status, 0);
+});
+test('merge commit requires an explicit parent', t => {
+  const r = repository(t); git(r.root, 'checkout', '-b', 'side', r.a); const side = r.commit('side');
+  git(r.root, 'checkout', 'main'); git(r.root, 'merge', '--no-ff', 'side', '-m', 'merge'); const merge = git(r.root, 'rev-parse', 'HEAD');
+  assert.throws(() => resolveReviewScope({ repo: r.root, mode: 'commit', commit: merge }), /explicit --parent/);
+  assert.equal(resolveReviewScope({ repo: r.root, mode: 'commit', commit: merge, parent: 2 }).fixed_point, side);
+  assert.equal(resolveReviewScope({ repo: r.root, mode: 'commit', commit: merge, parent: 1 }).fixed_point, r.c);
+});
+test('range comparison and merge-base comparison have distinct semantics', t => {
+  const r = repository(t); git(r.root, 'checkout', '-b', 'side', r.a); const side = r.commit('side');
+  const baseline = resolveReviewScope({ repo: r.root, mode: 'baseline', base: r.c, head: side });
+  const range = resolveReviewScope({ repo: r.root, mode: 'range', base: r.c, head: side });
+  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 => /^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', 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);
+  }
+});
+
+test('review scope ignores configured external diff and forced color', t => {
+  const r = repository(t), sentinel = join(r.root, 'unexpected-diff-effect');
+  const plain = resolveReviewScope({ repo: r.root, mode: 'range', base: r.a, head: r.c });
+  git(r.root, 'config', 'color.ui', 'always');
+  git(r.root, 'config', 'diff.external', `node -e "require('fs').writeFileSync('${sentinel.replaceAll('\\', '/')}', 'bad')"`);
+  const scope = resolveReviewScope({ repo: r.root, mode: 'range', base: r.a, head: r.c });
+  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, '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), ['README.md']);
+});
+test('correcting a candidate preserves historical incident observation bytes', t => {
+  const root = change(t), original = fence(incident()), file = join(root, 'diagnosis.md');
+  writeFileSync(file, original);
+  assert.deepEqual(validateEngineeringArtifacts(root, 'incident'), []);
+  const subsequent = { ...incident(), checkpoint: 'later-source', facts: ['new read-only evidence'] };
+  writeFileSync(file, original + fence(subsequent));
+  assert.deepEqual(validateEngineeringArtifacts(root, 'incident'), []);
+  assert.ok(readFileSync(file, 'utf8').startsWith(original));
+});
+test('a valid-looking measurement in another owner does not satisfy requested performance', t => {
+  const root = change(t); mkdirSync(join(root, 'evidence'));
+  writeFileSync(join(root, 'evidence/direct-spec.md'), fence(performance()));
+  const r = run(['--engineering', 'performance', root]); assert.equal(r.status, 1);
+  assert.match(r.output, /engineering\/owner/); assert.match(r.output, /missing evidence/);
+});

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));
+});

package/template/workflows/specdev/common/tools/ticket-control.mjs

@@ -4,7 +4,8 @@ import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseFrontmatter, validateChange, pathsOverlap } from './validate-specdev.mjs';
-import { CHANGE_ID, digest, findGraphCycle, resolveProjectSource, validateGoalMap } from './plan-contract.mjs';
+import { CHANGE_ID, digest, findGraphCycle, resolveProjectSource, validateGoalMap, resolveToolContext, validateExecutionPolicy, canonicalToolPath } from './plan-contract.mjs';
+import * as runtime from '../../../../lib/speculo-runtime.mjs';
 
 const terminal = new Set(['done','cancelled']);
 const inFlight = new Set(['in_progress','review']);
@@ -12,19 +13,6 @@ function readArtifact(file) {
   if (!existsSync(file) || lstatSync(file).isSymbolicLink() || !lstatSync(file).isFile()) throw new Error(`missing or noncanonical artifact: ${file}`);
   return { path: file, ...parseFrontmatter(file) };
 }
-function readStatus(root) {
-  const file = join(root,'.status.json');
-  if (!existsSync(file) || lstatSync(file).isSymbolicLink()) throw new Error(`missing real change status: ${file}`);
-  return JSON.parse(readFileSync(file,'utf8'));
-}
-function findConfig(root) {
-  let here = resolve(root);
-  while (true) {
-    const candidate = join(here,'.speculo','specdev','config.json');
-    if (existsSync(candidate)) return JSON.parse(readFileSync(candidate,'utf8'));
-    const parent = dirname(here);if (parent === here) return null;here = parent;
-  }
-}
 function resourceOverlap(left, right) {
   if (left === right) return true;
   const prefix = value => value.endsWith('*') ? value.slice(0,-1) : null;
@@ -58,10 +46,14 @@ function contractHash(node) {
   return digest(JSON.stringify({ meta, body: node.artifact.body, spec: node.specDigest, goal: node.goalDigest, dependencies: node.dependencies, serializations: node.serializations, sources }));
 }
 
-export function analyzeMap({ mapPath, repoRoot, previous = null }) {
+export function analyzeMap({ mapPath, repoRoot, methodRoot, stateRoot, context: suppliedContext, previous = null }) {
   if (!mapPath || !repoRoot) throw new Error('--map and --repo are required');
   mapPath = resolve(mapPath);repoRoot = resolve(repoRoot);
-  const root = dirname(mapPath);
+  let root = dirname(mapPath);
+  const context = resolveToolContext(root, { repoRoot, methodRoot, stateRoot, context: suppliedContext });
+  root = canonicalToolPath(context, root);
+  mapPath = canonicalToolPath(context, mapPath);
+  runtime.readChangeFactsSync(context, basename(root));
   let entry = readArtifact(mapPath);
   const errors = [], warnings = [], nodes = new Map(), memberRoots = new Map(), serializations = new Set();
   let parent = false;
@@ -77,17 +69,19 @@ export function analyzeMap({ mapPath, repoRoot, previous = null }) {
   const planFile = join(root,parent ? 'implementation-plan.md' : 'goal-plan.md');
   const plan = existsSync(planFile) ? readArtifact(planFile) : null;
   const strategy = plan?.meta.ticket_workspace_policy ?? 'current';
-  let limit = strategy === 'current' ? 1 : plan?.meta.implementation_agent_limit;
+  let limit = strategy === 'current' ? 1 : plan?.meta.concurrent_implementation_limit;
   if (!['current','required'].includes(strategy) || !Number.isInteger(limit) || limit < 1) errors.push('invalid workspace strategy or implementation limit');
-  const config = findConfig(root);
-  if (plan && (!config || !Number.isInteger(config.execution?.max_implementation_agents) || plan.meta.implementation_agent_limit > config.execution.max_implementation_agents)) errors.push('plan implementation limit is not backed by existing config');
+  const configPath = join(context.specdevRoot, 'config.json');
+  const config = existsSync(configPath) ? JSON.parse(readFileSync(runtime.safeWorkPathSync(context.specdevRoot, 'config.json', {mustExist:true,type:'file'}), 'utf8')) : null;
+  if (plan) errors.push(...validateExecutionPolicy(plan, config));
 
   for (const member of members) {
     const memberRoot = parent ? join(dirname(root),member) : root;
     if (memberRoot === root && parent) { errors.push('parent cannot include itself'); continue; }
     if (!existsSync(memberRoot) || lstatSync(memberRoot).isSymbolicLink() || !lstatSync(memberRoot).isDirectory()) { errors.push(`member must be a real change directory: ${member}`); continue; }
     memberRoots.set(member,memberRoot);
-    const status = readStatus(memberRoot);
+    const facts = runtime.readChangeFactsSync(context, member);
+    if (facts.location.root !== memberRoot) { errors.push(`member is not an active change: ${member}`); continue; }
     const specFile = join(memberRoot,'spec.md');
     const spec = readArtifact(specFile);
     const specDigest = digest(readFileSync(specFile));
@@ -99,7 +93,7 @@ export function analyzeMap({ mapPath, repoRoot, previous = null }) {
       const id = parent ? `${member}::${artifact.meta.id}` : artifact.meta.id;
       if (nodes.has(id)) { errors.push(`duplicate Ticket ${id}`); continue; }
       if (!Array.isArray(artifact.meta.blocked_by) || artifact.meta.blocked_by.some(value => !/^T-\d{2,}$/.test(value))) { errors.push(`invalid dependencies: ${id}`); continue; }
-      nodes.set(id, { id, member, repoRoot, artifact, specDigest, status, dependencies: artifact.meta.blocked_by.map(value => parent ? `${member}::${value}` : value), reasons: [], validationErrors: [] });
+      nodes.set(id, { id, member, repoRoot, artifact, specDigest, facts, dependencies: artifact.meta.blocked_by.map(value => parent ? `${member}::${value}` : value), reasons: [], validationErrors: [] });
       if (spec.meta.ready_for_tickets !== true) nodes.get(id).reasons.push('source Spec is not Ready');
     }
   }
@@ -123,7 +117,7 @@ export function analyzeMap({ mapPath, repoRoot, previous = null }) {
   const cycle = findGraphCycle(graph);if (cycle) errors.push(`dependency cycle: ${cycle.join(' -> ')}`);
 
   // Reuse existing stage gates. Local diagnostics block their owner, structural ones block dispatch.
-  const validation = validateChange(root,parent ? 'goal-plan' : 'tickets',repoRoot);
+  const validation = validateChange(root,parent ? 'goal-plan' : 'tickets',repoRoot,null,null,{context});
   warnings.push(...validation.warnings);
   for (const error of validation.errors) {
     let assigned = false;
@@ -153,7 +147,7 @@ export function analyzeMap({ mapPath, repoRoot, previous = null }) {
   for (const node of nodes.values()) {
     node.reasons.push(...node.validationErrors);
     if (!terminal.has(node.artifact.meta.status) && (!plan || plan.meta.ready_for_execution !== true)) node.reasons.push('Goal planning gate is not ready for execution');
-    if (!terminal.has(node.artifact.meta.status) && node.artifact.meta.plan_contract_version !== 1) node.reasons.push('legacy Ticket needs explicit Plan-contract upgrade before dispatch');
+    if (node.artifact.meta.plan_contract_version !== 1) node.reasons.push('Ticket requires current plan_contract_version: 1');
   }
   const goalDigest = stableGoalContract(plan,entry);
   for (const node of nodes.values()) {
@@ -238,10 +232,10 @@ function main(args) {
   const options = {};
   for (let i=0;i<args.length;i++) {
     const key = args[i];
-    if (!['--map','--repo','--previous'].includes(key) || !args[i+1] || args[i+1].startsWith('--') || key in options) throw new Error('Usage: ticket-control.mjs --map <map-file> --repo <project-root> [--previous <checkpoint-json>]');
+    if (!['--map','--repo','--previous','--method-root','--state-root'].includes(key) || !args[i+1] || args[i+1].startsWith('--') || key in options) throw new Error('Usage: ticket-control.mjs --map <map-file> --repo <project-root> [--previous <checkpoint-json>]');
     options[key]=args[++i];
   }
-  const result = analyzeMap({mapPath:options['--map'],repoRoot:options['--repo'],previous:options['--previous'] ? JSON.parse(readFileSync(options['--previous'],'utf8')) : null});
+  const result = analyzeMap({mapPath:options['--map'],repoRoot:options['--repo'],methodRoot:options['--method-root'],stateRoot:options['--state-root'],previous:options['--previous'] ? JSON.parse(readFileSync(options['--previous'],'utf8')) : null});
   console.log(JSON.stringify(result,null,2));
   return result.errors.length || result.validation_errors.length ? 1 : 0;
 }