@namewta/speculo 1.0.22 → 1.0.24

package/template/workflows/specdev/common/tools/engineering-evidence.mjs

@@ -0,0 +1,150 @@
+/** Optional, versioned observations in existing artifacts; not a second task state. */
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { join, relative, isAbsolute } from 'node:path';
+
+export const ENGINEERING_KINDS = new Set(['performance', 'documentation', 'incident']);
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const text = value => typeof value === 'string' && value.trim().length > 0;
+const strings = value => Array.isArray(value) && value.length > 0 && value.every(text);
+const digest = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const samples = value => Array.isArray(value) && value.length > 0 && value.every(x => typeof x === 'number' && Number.isFinite(x) && x >= 0);
+const mean = values => values.reduce((average, value, i) => average * (i / (i + 1)) + value / (i + 1), 0);
+
+/** Parse only explicitly labelled fences outside other fenced examples. */
+export function engineeringRecords(body) {
+  const records = [], errors = [];
+  let fence = null, lines = [], selected = false;
+  for (const line of body.split(/\r?\n/)) {
+    if (!fence) {
+      const opening = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+      if (!opening) continue;
+      fence = opening[1];
+      selected = opening[2].trim() === 'json specdev-engineering-evidence';
+      lines = [];
+    } else if (new RegExp(`^ {0,3}${fence[0]}{${fence.length},}\\s*$`).test(line)) {
+      if (selected) {
+        try { records.push(JSON.parse(lines.join('\n'))); }
+        catch { errors.push('engineering/fence: expected one valid JSON object'); }
+      }
+      fence = null;
+    } else lines.push(line);
+  }
+  if (fence && selected) errors.push('engineering/fence: unclosed evidence fence');
+  return { records, errors };
+}
+
+/** Reject internally inconsistent claims; cannot authenticate measurements or logs. */
+export function validateEngineeringRecord(record) {
+  const errors = [];
+  const require = (condition, message) => { if (!condition) errors.push(`engineering/${record?.kind ?? 'record'}: ${message}`); };
+  if (!object(record)) return ['engineering/record: expected object'];
+  require(record.version === 1, 'version must be 1');
+  require(ENGINEERING_KINDS.has(record.kind), 'unknown kind');
+  require(text(record.checkpoint), 'checkpoint is required');
+  require(strings(record.evidence), 'nonempty evidence locators are required');
+  if (record.kind === 'performance') {
+    require(['baseline', 'improved', 'no-gain', 'inconclusive'].includes(record.outcome), 'invalid outcome');
+    require(text(record.operation), 'user operation is required');
+    require(text(record.uncertainty), 'measurement uncertainty and exclusions must be explained');
+    if (record.outcome === 'inconclusive' && record.baseline == null && record.candidate == null) return errors;
+    const checkMeasurement = (m, label) => {
+      if (!object(m)) { require(false, `${label} measurement is required`); return false; }
+      for (const field of ['checkpoint', 'entrypoint', 'environment', 'clock', 'workload']) require(text(m[field]), `${label}.${field} is required`);
+      require(digest(m.workload_digest), `${label}.workload_digest must be SHA-256`);
+      require(['ms', 'bytes', 'ops/s'].includes(m.unit), `${label}.unit must be ms, bytes or ops/s`);
+      require(['lower', 'higher'].includes(m.direction), `${label}.direction is required`);
+      require(['cold', 'warm', 'not-applicable'].includes(m.cache), `${label}.cache is required`);
+      require(Array.isArray(m.excluded_costs) && m.excluded_costs.every(text), `${label}.excluded_costs must be a string array`);
+      require(samples(m.samples), `${label}.samples must contain finite nonnegative observed values`);
+      return true;
+    };
+    checkMeasurement(record.baseline, 'baseline');
+    if (record.candidate != null || record.outcome === 'improved' || record.outcome === 'no-gain') {
+      checkMeasurement(record.candidate, 'candidate');
+      if (object(record.baseline) && object(record.candidate)) {
+        for (const field of ['entrypoint', 'environment', 'clock', 'workload_digest', 'unit', 'direction', 'cache', 'excluded_costs']) {
+          require(JSON.stringify(record.baseline[field]) === JSON.stringify(record.candidate[field]), `comparison changes ${field}`);
+        }
+        if (record.outcome === 'improved') {
+          require(record.behavior_verification === 'passed', 'improvement requires behavior verification');
+          if (samples(record.baseline.samples) && samples(record.candidate.samples)) {
+            const a = mean(record.baseline.samples), b = mean(record.candidate.samples);
+            require(record.baseline.direction === 'lower' ? b < a : b > a, 'improvement contradicts observed arithmetic means');
+          }
+        }
+      }
+    }
+  } else if (record.kind === 'documentation') {
+    require(['verified', 'partial', 'blocked'].includes(record.outcome), 'invalid outcome');
+    require(strings(record.owner_paths), 'owning sources are required');
+    require(typeof record.visible_behavior_changed === 'boolean', 'visible_behavior_changed must be boolean');
+    require(['passed', 'failed', 'not-run', 'not-applicable'].includes(record.behavior_verification), 'invalid behavior verification');
+    require(Array.isArray(record.claims) && record.claims.length > 0, 'claims are required');
+    if (Array.isArray(record.claims)) for (const claim of record.claims) {
+      if (!object(claim)) { require(false, 'claim must be an object'); continue; }
+      require(text(claim.subject) && strings(claim.evidence), 'claim needs subject and evidence');
+      require(['command', 'source', 'manual'].includes(claim.method), 'invalid claim method');
+      require(['verified', 'unverified'].includes(claim.state), 'invalid claim state');
+      if (claim.method === 'command' && claim.state === 'verified') {
+        require(text(claim.command) && claim.executed === true && claim.exit_code === 0 && strings(claim.output), 'verified command needs execution, zero exit and observed output');
+      }
+      if (claim.state === 'unverified') require(text(claim.reason), 'unverified claim needs reason');
+      if (record.outcome === 'verified') require(claim.state === 'verified', 'overall verified has an unverified claim');
+    }
+    if (record.visible_behavior_changed && record.outcome === 'verified') require(record.behavior_verification === 'passed', 'visible change requires behavior evidence');
+  } else if (record.kind === 'incident') {
+    require(record.feedback_loop_ready === false && record.root_cause_confirmed === false, 'event triage must not assert feedback readiness or confirmed cause');
+    require(strings(record.facts) && strings(record.next_checks), 'observed facts and next safe checks are required');
+    require(Array.isArray(record.unknowns) && record.unknowns.length > 0 && record.unknowns.every(text), 'missing evidence must stay visible');
+  }
+  return errors;
+}
+
+/** Read existing owners only. Explicit --engineering requires a matching record. */
+export function validateEngineeringArtifacts(change, requiredKind = null) {
+  const errors = [], found = new Set();
+  const root = realpathSync(change);
+  const safe = (file, directory = false) => {
+    if (!existsSync(file)) return false;
+    const stat = lstatSync(file);
+    if (stat.isSymbolicLink()) { errors.push('engineering/path: symlinked evidence owners are not read'); return false; }
+    const rel = relative(root, realpathSync(file));
+    if (isAbsolute(rel) || rel === '..' || rel.startsWith('../') || rel.startsWith('..\\')) { errors.push('engineering/path: evidence escapes change'); return false; }
+    return directory ? stat.isDirectory() : stat.isFile();
+  };
+  const files = [[join(change, 'architecture-review.md'), 'performance'], [join(change, 'diagnosis.md'), 'incident']];
+  const evidenceRoot = join(change, 'evidence');
+  if (safe(evidenceRoot, true)) for (const name of readdirSync(evidenceRoot).filter(n => n.endsWith('.md')).sort()) {
+    files.push([join(evidenceRoot, name), 'documentation']);
+  }
+  for (const [file, ownerKind] of files) {
+    if (!safe(file)) continue;
+    const parsed = engineeringRecords(readFileSync(file, 'utf8'));
+    errors.push(...parsed.errors.map(e => `${relative(change, file)}: ${e}`));
+    for (const record of parsed.records) {
+      if (record?.kind !== ownerKind) errors.push(`${relative(change, file)}: engineering/owner: expected ${ownerKind}`);
+      else found.add(record.kind);
+      errors.push(...validateEngineeringRecord(record).map(e => `${relative(change, file)}: ${e}`));
+    }
+  }
+  if (requiredKind && !found.has(requiredKind)) errors.push(`engineering/${requiredKind}: missing evidence in existing owner artifact`);
+  return errors;
+}
+
+/** Keep optional branches reachable from their owning entry without a new registry. */
+export function validateEngineeringPackage(root) {
+  const errors = [];
+  for (const [entry, target] of [
+    ['R-review-architecture/R-review-architecture.md', 'R-review-architecture/references/performance-review.md'],
+    ['I-implement/I-implement.md', 'I-implement/references/documentation-procedure.md'],
+    ['D-diagnose-bugs/D-diagnose-bugs.md', 'D-diagnose-bugs/references/incident-evidence.md'],
+  ]) {
+    if (!existsSync(join(root, target))) errors.push(`engineering/route: missing ${target}`);
+    const source = join(root, entry);
+    if (!existsSync(source) || !readFileSync(source, 'utf8').includes(`<Path>{roots.workflows}/specdev/${target}</Path>`)) errors.push(`engineering/route: ${entry} does not expose ${target}`);
+  }
+  for (const rule of ['error-handling', 'test-reliability', 'agent-experience', 'documentation-standard', 'engineering-evidence']) {
+    if (!existsSync(join(root, 'common', 'rules', `${rule}.md`))) errors.push(`engineering/rule: missing ${rule}`);
+  }
+  return errors;
+}

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

@@ -0,0 +1,82 @@
+/** Read-only Git review selection. Resolves refs once; never fetches or writes state. */
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+
+const modes = new Set(['baseline', 'range', 'commit', 'pr']);
+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 are required');
+  }
+  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']);
+  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]}`);
+    const value = argv[++i];
+    if (!value || value.startsWith('--')) throw new Error(`review-scope: missing ${key}`);
+    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,267 @@
+/** 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 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');
+  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, '.status.json'));
+  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);
+});
+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), ['.status.json']);
+});
+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, 'D-diagnose-bugs/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 => /^[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]);
+  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]]) {
+    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, '.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 r = run(['--engineering', 'performance', root]); assert.notEqual(r.status, 0);
+  assert.deepEqual(readFileSync(statusPath), before); assert.deepEqual(readdirSync(root), ['.status.json']);
+});
+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/validate-specdev.mjs

@@ -26,6 +26,8 @@ import {
 } from "./plan-contract.mjs";
 
 import { validateRecord, validateRecords } from "./delivery-artifacts.mjs";
+import { reviewScopeCLI } from "./review-scope.mjs";
+import { ENGINEERING_KINDS, validateEngineeringArtifacts, validateEngineeringPackage } from "./engineering-evidence.mjs";
 
 const DOMAIN_SCHEMA_VERSION = 3;
 const CONFIG_SCHEMA_VERSION = 6;
@@ -1077,7 +1079,7 @@ function capabilityChecks(root) {
       "code-review",
       [
         join(root, "C-code-review", "C-code-review.md"),
-        ["git diff <fixed>...<head>", "固定点", "标准轴", "规范轴", "未合并排名", "reviews/CR-###.md"],
+        ["--review-scope", "baseline", "range", "commit", "pr", "no-diff", "固定点", "标准轴", "规范轴", "未合并排名", "reviews/CR-###.md"],
       ],
     ],
     [
@@ -1274,6 +1276,16 @@ function selfCheck(root) {
   errors.push(...references.errors);
   warnings.push(...references.warnings);
   errors.push(...capabilityChecks(root));
+  errors.push(...validateEngineeringPackage(root));
+  // Run real runner regressions; these tests never recursively request self-check.
+  try {
+    execFileSync(process.execPath, ["--test", join(root, "common", "tools", "tests", "engineering.test.mjs")], {
+      encoding: "utf8", timeout: 120000, maxBuffer: 8 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch (error) {
+    errors.push(`engineering regressions failed: ${error.stdout ?? ""}${error.stderr ?? error.message}`);
+  }
 
   const obsolete = [
     "P-goal-plan/input-validation.md",
@@ -1647,6 +1659,9 @@ function validateDiagnosis(path, expectedChange, errors) {
   if (typeof meta.feedback_loop_ready !== "boolean") {
     errors.push("diagnosis.md: feedback_loop_ready must be boolean");
   }
+  if (["minimizing", "testing-hypotheses", "root-cause-confirmed"].includes(meta.status) && meta.feedback_loop_ready !== true) {
+    errors.push("diagnosis.md: advanced diagnosis requires ready feedback loop and real red evidence");
+  }
   if (meta.feedback_loop_ready) {
     if (!String(meta.red_command ?? "").trim() || !String(meta.red_evidence ?? "").trim()) {
       errors.push("diagnosis.md: ready feedback loop requires red_command and red_evidence");
@@ -3285,7 +3300,7 @@ function validateParentImplementation(change, parentStatus, stage, errors, warni
   return { map, plan, members, tasks, memberStatuses, ticketByTask };
 }
 
-function validateChange(change, stage = null, repoRoot = null) {
+function validateChange(change, stage = null, repoRoot = null, engineeringKind = null) {
   const errors = [];
   const warnings = [];
   if (!isDirectory(change)) {
@@ -3635,6 +3650,7 @@ function validateChange(change, stage = null, repoRoot = null) {
     }
   }
 
+  errors.push(...validateEngineeringArtifacts(change, engineeringKind));
   return { errors, warnings };
 }
 
@@ -3646,11 +3662,13 @@ function printResults(errors, warnings) {
 }
 
 function usage() {
-  console.error("Usage: node validate-specdev.mjs [--stage <stage>] [--repo <project-root>] <change-directory> | --self-check | --capture <capture.md> | --triage-run <TRI-NNN.md>");
+  console.error("Usage: node validate-specdev.mjs [--stage <stage>] [--repo <project-root>] [--engineering <performance|documentation|incident>] <change-directory> | --review-scope --repo <project-root> --mode <baseline|range|commit|pr> [comparison options] | --self-check | --capture <capture.md> | --triage-run <TRI-NNN.md>");
   return 2;
 }
 
 function main(argv) {
+  if (argv[0] === "--review-scope") return reviewScopeCLI(argv.slice(1));
+  let engineeringKind = null;
   let selfCheckRequested = false;
   let stage = null;
   let repoRoot = null;
@@ -3659,7 +3677,10 @@ function main(argv) {
   const positional = [];
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
-    if (arg === "--self-check") {
+    if (arg === "--engineering") {
+      if (engineeringKind !== null || !ENGINEERING_KINDS.has(argv[index + 1])) return usage();
+      engineeringKind = argv[++index];
+    } else if (arg === "--self-check") {
       selfCheckRequested = true;
     } else if (arg === "--stage") {
       stage = argv[index + 1] ?? null;
@@ -3685,6 +3706,7 @@ function main(argv) {
     }
   }
   if (stage !== null && !VALID_STAGES.has(stage)) return usage();
+  if (engineeringKind !== null && (selfCheckRequested || capturePath || triageRunPath || positional.length !== 1)) return usage();
   if (triageRunPath) {
     if (selfCheckRequested || positional.length || stage !== null || capturePath || repoRoot) return usage();
     return printResults(validateRecord(resolve(triageRunPath), "triage-run", parseFrontmatter).errors, []);
@@ -3703,7 +3725,7 @@ function main(argv) {
     return printResults(errors, []);
   }
   if (positional.length === 1) {
-    const result = validateChange(resolve(positional[0]), stage, repoRoot);
+    const result = validateChange(resolve(positional[0]), stage, repoRoot, engineeringKind);
     return printResults(result.errors, result.warnings);
   }
   return usage();