@namewta/speculo 2.0.2 → 2.0.4

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

@@ -0,0 +1,117 @@
+/** Read-only checks of review records. Tool receipts still require Lead verification. */
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { relative, resolve } from 'node:path';
+import { markdownBodyLines, readArtifactSectionSync, readUtf8ArtifactSync, safeWorkPathSync } from '../../../../lib/speculo-runtime.mjs';
+import { resolveReviewScope } from './review-scope.mjs';
+
+const hash = value => createHash('sha256').update(value).digest('hex');
+const real = value => typeof value === 'string' && value.trim() && !/^(?:<[^>]*>|unknown|unassigned|pending|todo|tbd|\.\.\.)$/i.test(value.trim());
+const identity = value => real(value) && /^[a-z][a-z0-9-]*:\S+$/i.test(value) && real(value.slice(value.indexOf(':')+1));
+function fields(text) {
+  const result = {};
+  for (const {text:line} of markdownBodyLines(text)) {
+    const match = /^([A-Za-z][A-Za-z0-9-]*):\s*(.*)$/.exec(line);
+    if (!match) continue;
+    if (Object.hasOwn(result, match[1])) throw new Error(`duplicate ${match[1]}`);
+    result[match[1]] = match[2].trim();
+  }
+  return result;
+}
+function section(text, heading) {
+  const lines = markdownBodyLines(text), matches = lines.filter(line => line.text === `## ${heading}`);
+  if (matches.length !== 1) throw new Error(`expected one ${heading} section`);
+  const start = matches[0].line, end = lines.find(line => line.line > start && /^#{1,2} /.test(line.text))?.line;
+  return text.split(/\r?\n/).slice(start, end ? end-1 : undefined).join('\n');
+}
+function readLocator(root, locator) {
+  if (!real(locator)) throw new Error('missing original evidence locator');
+  const parts = locator.split('#');
+  if (parts.length > 2 || parts.length === 2 && !parts[1]) throw new Error('invalid evidence locator');
+  const path = safeWorkPathSync(root, parts[0] || 'README.md', {mustExist:true, type:'file'});
+  return {path, text:parts.length === 2 ? readArtifactSectionSync(path, parts[1]).text : readUtf8ArtifactSync(path)};
+}
+export function reviewInputDigest(input) { return hash(JSON.stringify(input)); }
+
+/** Sources use project-relative locators; an anchor avoids a README hashing itself. */
+export function validateIndependentReview(root, artifact, {repoRoot=null, requirePassed=true, expectedHead=null, expectedBase=null, expectedResults=null, requiredImplementers=[], requiredSpecifications=[], checkCurrent=false, requireDelivery=false, allowSourceFiles=false} = {}) {
+  const errors = [], label = `independent-review: ${artifact}`;
+  try {
+    const path = safeWorkPathSync(root, artifact, {mustExist:true, type:'file'});
+    const text = readUtf8ArtifactSync(path), body = section(text,'Independent Review'), data = fields(body);
+    const implementers = (data.Implementers ?? '').split(',').map(x=>x.trim()).filter(Boolean);
+    if (!implementers.length || implementers.some(id=>!identity(id)) || new Set(implementers).size !== implementers.length) throw new Error('Implementers must contain actual namespaced agent/session IDs');
+    if (requiredImplementers.some(id=>!implementers.includes(id))) throw new Error('implementation owner missing from Implementers');
+    if (!identity(data['Verified-By'])) throw new Error('missing actual Verified-By Lead identity');
+    if (!['native','herdr','orca','cli'].includes(data.Mode)) throw new Error('invalid review Mode');
+    const inputSource = readLocator(root,data.Input);
+    const blocks = [...inputSource.text.matchAll(/```json\s*\n([\s\S]*?)\n```/g)];
+    if (blocks.length !== 1) throw new Error('Input must reference one frozen review JSON object');
+    const input = JSON.parse(blocks[0][1]), scope = input.scope;
+    if (!scope || !Array.isArray(input.sources) || !input.sources.length) throw new Error('Input needs scope and actual standards/specification/instruction sources');
+    if (!repoRoot && checkCurrent) throw new Error('current input checks require explicit project root');
+    const sourceKinds = new Set();
+    for (const source of input.sources) {
+      if (!['standards','specification','instructions'].includes(source.kind) || !real(source.locator) || !/^[a-f0-9]{64}$/.test(source.sha256 ?? '')) throw new Error('invalid review source');
+      sourceKinds.add(source.kind);
+      if (repoRoot && checkCurrent && hash(readLocator(repoRoot,source.locator).text) !== source.sha256) throw new Error(`source drift: ${source.locator}`);
+    }
+    if (!sourceKinds.has('standards') || requirePassed && !sourceKinds.has('specification')) throw new Error('missing required review sources');
+    if (requiredSpecifications.some(locator=>!input.sources.some(source=>source.kind === 'specification' && source.locator === locator))) throw new Error('review omits the authoritative specification/acceptance source');
+    const digest = reviewInputDigest(input);
+    const rows = markdownBodyLines(body).filter(({text:line})=>/^\|\s*(standards|specification)\s*\|/.test(line)).map(({text:line})=>line.split('|').slice(1,-1).map(x=>x.trim()));
+    if (rows.length !== 2 || new Set(rows.map(row=>row[0])).size !== 2) throw new Error('expected exactly one result per axis');
+    for (const [axis,reviewer,result,locator,...extra] of rows) {
+      if (extra.length || !identity(reviewer)) throw new Error('invalid reviewer row');
+      if (implementers.includes(reviewer)) throw new Error('reviewer participated in implementation');
+      if (!['pass','request-changes','skipped'].includes(result) || requirePassed && result !== 'pass' || axis === 'standards' && result === 'skipped') throw new Error(`${axis} has not passed`);
+      if (expectedResults && expectedResults[axis] !== result) throw new Error(`${axis} result differs from the owning report`);
+      const report = readLocator(root,locator), reportFields = fields(report.text);
+      if (report.path === path && !locator.includes('#')) throw new Error('report must reference original output, not its summary');
+      if (reportFields.Reviewer !== reviewer || reportFields.Axis !== axis || reportFields.Result !== result || reportFields['Input-SHA256'] !== digest || !real(reportFields.Observed)) throw new Error(`${axis} original report does not match the review record`);
+    }
+    const receipt = fields(readLocator(root,data.Verification).text);
+    const reviewers = (receipt.Reviewers ?? '').split(',').map(x=>x.trim());
+    if (receipt['Verified-By'] !== data['Verified-By'] || receipt.Mode !== data.Mode || receipt.Result !== 'verified' || receipt['Input-SHA256'] !== digest || !real(receipt.Observed) || rows.some(row=>!reviewers.includes(row[1]))) throw new Error('missing matching Lead verification of actual dispatch/return receipts');
+    if (scope.mode === 'source-files' && !allowSourceFiles) throw new Error('source-files cannot substitute implementation change review');
+    if (!['baseline','range','commit','pr','source-files','working-tree'].includes(scope.mode)) throw new Error('invalid frozen review scope');
+    if (scope.outcome === 'no-diff') throw new Error('no-diff is not an independent approval');
+    if (expectedHead && (scope.mode === 'working-tree' ? scope.observed_head : scope.head_sha) !== expectedHead) throw new Error('review does not cover the expected checkpoint');
+    if (expectedBase && scope.base_sha !== expectedBase) throw new Error('review does not cover the implementation baseline');
+    if (scope.mode === 'working-tree' && scope.excluded_paths?.length && !real(input.exclusions)) throw new Error('excluded changes require an explicit scope/ownership rationale');
+    if (checkCurrent) {
+      const options = {repo:repoRoot,mode:scope.mode};
+      if (scope.mode === 'working-tree') { options.base=scope.base_sha; if(scope.selection === 'explicit-files') options.files=scope.scope_paths; }
+      else if (scope.mode === 'source-files') options.files=scope.source_snapshot?.map(file=>file.path);
+      else if (scope.mode === 'commit') { options.commit=scope.head_sha; if(scope.parent) options.parent=scope.parent; }
+      else { options.base=scope.base_sha; options.head=scope.head_sha; }
+      const current = resolveReviewScope(options);
+      // Re-read all scope metadata, not just the HEAD; dirty files are not commits.
+      const comparable = value => {
+        if (value.mode !== 'working-tree' || value.selection !== 'explicit-files') return value;
+        // New report files outside an explicit review scope are expected. Their
+        // existence must not create a self-referential evidence digest.
+        const {excluded_paths, inventory_sha256, input_sha256, ...selected} = value;
+        return selected;
+      };
+      if (JSON.stringify(comparable(current)) !== JSON.stringify(comparable(scope))) throw new Error('frozen review input drifted; run independent review again');
+      if (requireDelivery && scope.mode !== 'working-tree' && scope.mode !== 'source-files') {
+        // A commit report certifies that tree, not later local edits. Markdown
+        // bookkeeping in the owning change may advance after the code review;
+        // authoritative specification sources are still hashed above.
+        const live = resolveReviewScope({repo:repoRoot,mode:'working-tree',base:scope.head_sha});
+        const recordPath = file => {
+          const local = relative(resolve(root),resolve(repoRoot,file)).split('\\').join('/');
+          return /^(?:README\.md|goal-plan\.md|tickets-map\.md|implementation-(?:plan|map)\.md|(?:evidence|reviews|ticket)\/[^/]+\.md)$/.test(local);
+        };
+        const dirty = live.changed_paths.filter(file=>!recordPath(file));
+        if (dirty.length) throw new Error(`unreviewed working-tree delivery changes: ${dirty.join(', ')}; freeze and review the actual working-tree scope`);
+      }
+    }
+  } catch(error) { errors.push(`${label}: ${error.message}`); }
+  return errors;
+}
+
+export function hasIndependentReview(path) {
+  return existsSync(path) && markdownBodyLines(readUtf8ArtifactSync(path)).some(line=>line.text === '## Independent Review');
+}

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

@@ -1,10 +1,96 @@
 /** 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';
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, readlinkSync, realpathSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
 
-const modes = new Set(['baseline', 'range', 'commit', 'pr', 'source-files']);
+const modes = new Set(['baseline', 'range', 'commit', 'pr', 'source-files', 'working-tree']);
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+function portableFile(path) {
+  if (typeof path !== 'string' || !path || isAbsolute(path) || /[\\:\x00-\x1f]/.test(path) || path.split('/').some(part => !part || part === '.' || part === '..' || part.toLowerCase() === '.git')) {
+    throw new Error('review-scope: file must be an explicit portable project-relative path outside .git');
+  }
+  return path;
+}
+
+// Read a link itself, never its target. Directory links are rejected before any
+// file read; a file replaced by a directory is a deletion plus added children.
+function workingFile(root, path) {
+  portableFile(path);
+  const requested = resolve(root, path);
+  for (let parent = dirname(requested); parent !== root; parent = dirname(parent)) {
+    try { if (lstatSync(parent).isSymbolicLink()) throw new Error('review-scope: symlink directory in working-tree scope'); }
+    catch (error) { if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw error; }
+  }
+  let info;
+  try { info = lstatSync(requested); }
+  catch (error) { if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null; throw error; }
+  if (info.isDirectory()) return null;
+  if (info.isSymbolicLink()) {
+    const bytes = readlinkSync(requested, {encoding:'buffer'});
+    return {kind:'symlink', mode:'120000', sha256:digest(bytes), bytes:bytes.length};
+  }
+  if (!info.isFile()) throw new Error('review-scope: unsupported working-tree file type');
+  const fd = openSync(requested, constants.O_RDONLY | constants.O_NONBLOCK | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const before = fstatSync(fd, {bigint:true});
+    if (!before.isFile()) throw new Error('review-scope: working-tree file type changed');
+    const bytes = readFileSync(fd), after = fstatSync(fd, {bigint:true}), current = lstatSync(requested, {bigint:true});
+    if (!['dev','ino','size','mode','mtimeNs','ctimeNs'].every(key => before[key] === after[key] && after[key] === current[key])) throw new Error('review-scope: working-tree changed while freezing inputs');
+    return {kind:'file', mode:before.mode & 0o111n ? '100755' : '100644', sha256:digest(bytes), bytes:bytes.length};
+  } finally { closeSync(fd); }
+}
+
+function workingTree(options) {
+  if (['head','commit','parent'].some(key => options[key] !== undefined)) throw new Error('review-scope: working-tree accepts base, not head/commit/parent');
+  // Native realpath expands Windows short names; relative also handles drive
+  // casing without admitting a nested directory that borrows its parent's Git.
+  const root = realpathSync.native(resolve(options.repo));
+  if (relative(root,realpathSync.native(git(root, ['rev-parse','--show-toplevel']).trim())) !== '') throw new Error('review-scope: working-tree requires the actual project Git root');
+  const base = commit(root, options.base, 'base');
+  const files = options.files?.map(portableFile);
+  if (files && (!files.length || new Set(files).size !== files.length)) throw new Error('review-scope: empty or duplicate working-tree scope');
+  const capture = () => {
+    if (git(root, ['ls-files','--unmerged','-z'])) throw new Error('review-scope: unresolved index conflicts');
+    const head = commit(root, 'HEAD', 'HEAD');
+    const index = git(root, ['ls-files','--stage','-z']);
+    const inventory = git(root, ['status','--porcelain=v1','-z','--untracked-files=all']);
+    const baseEntries = new Map(git(root, ['ls-tree','-r','-z','--full-tree',base]).split('\0').filter(Boolean).map(row => {
+      const tab = row.indexOf('\t'), [mode,type,oid] = row.slice(0,tab).split(' ');
+      return [row.slice(tab+1), {mode,type,oid}];
+    }));
+    const diffArgs = ['diff','--no-color','--no-ext-diff','--no-textconv','--binary','--no-renames',base,'--'];
+    const changed = [...new Set([
+      ...git(root, ['diff','--no-ext-diff','--no-textconv','--no-renames','--name-only','-z',base,'--']).split('\0'),
+      ...git(root, ['ls-files','--others','--exclude-standard','-z']).split('\0'),
+    ].filter(Boolean))].sort();
+    const selected = files ? [...files].sort() : changed;
+    const snapshot = selected.map(path => {
+      portableFile(path);
+      const entry = baseEntries.get(path);
+      if (entry && entry.type !== 'blob') throw new Error('review-scope: submodules require separate review; working-tree snapshot is unverified');
+      const before = entry ? {mode:entry.mode, oid:entry.oid, sha256:digest(git(root, ['cat-file','blob',entry.oid], null))} : null;
+      const after = workingFile(root, path);
+      if (!before && !after) throw new Error(`review-scope: missing or unsupported working-tree path ${path}`);
+      const change = !before ? 'added' : !after ? 'deleted' : before.mode === after.mode && before.sha256 === after.sha256 ? 'unchanged' : before.mode.slice(0,3) !== after.mode.slice(0,3) ? 'type-changed' : 'modified';
+      return {path, change, before, after};
+    });
+    const args = [...diffArgs, ...selected.map(path => `:(literal)${path}`)];
+    const scope = {
+      version:1, mode:'working-tree', review_mode:'working-tree',
+      outcome:snapshot.some(file => file.change !== 'unchanged') ? 'changes' : 'no-diff',
+      base_sha:base, observed_head:head, selection:files ? 'explicit-files' : 'all-changes', scope_paths:selected,
+      changed_paths:snapshot.filter(file => file.change !== 'unchanged').map(file => file.path),
+      excluded_paths:changed.filter(path => !selected.includes(path)),
+      working_snapshot:snapshot, index_sha256:digest(index), inventory_sha256:digest(inventory),
+      tracked_diff_sha256:digest(git(root,args,null)), tracked_diff_command:['git',...args],
+    };
+    return {...scope, input_sha256:digest(JSON.stringify(scope))};
+  };
+  const first = capture(), second = capture();
+  if (first.input_sha256 !== second.input_sha256) throw new Error('review-scope: working-tree changed while freezing inputs; stop writers and retry');
+  return first;
+}
 function contained(root, path) {
   const rel = relative(root, path);
   if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
@@ -65,10 +151,11 @@ 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|source-files are required');
+    throw new Error('review-scope: --repo and --mode baseline|range|commit|pr|source-files|working-tree are required');
   }
   if (mode === 'source-files') return sourceFiles(options);
-  if (options.files !== undefined) throw new Error('review-scope: --file requires source-files mode');
+  if (mode === 'working-tree') return workingTree(options);
+  if (options.files !== undefined) throw new Error('review-scope: --file requires source-files or working-tree mode');
   git(repo, ['rev-parse', '--git-dir']);
   let base, head;
   let selectedParent = null;

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

@@ -0,0 +1,74 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {execFileSync} from 'node:child_process';
+import {mkdtempSync,mkdirSync,writeFileSync,readFileSync,rmSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {validateIndependentReview} from '../review-evidence.mjs';
+import {appendReviewFixture} from './review-fixture.mjs';
+function fixture(t) {
+ const repo=mkdtempSync(join(tmpdir(),'review-evidence-')),root=join(repo,'data/change');
+ t.after(()=>rmSync(repo,{recursive:true,force:true}));mkdirSync(root,{recursive:true});
+ const git=(...args)=>execFileSync('git',['-C',repo,...args],{encoding:'utf8',stdio:['ignore','pipe','pipe']}).trim();
+ git('init','-b','main');git('config','user.name','Fixture');git('config','user.email','test@example.invalid');
+ writeFileSync(join(repo,'.gitignore'),'data/\n');writeFileSync(join(repo,'value.txt'),'before');git('add','.');git('-c','commit.gpgsign=false','commit','-m','base');
+ const base=git('rev-parse','HEAD');writeFileSync(join(repo,'value.txt'),'after');
+ const save=(options={})=>appendReviewFixture({repo,root,base,...options});
+ const validate=(options={})=>validateIndependentReview(root,'evidence/direct-spec.md',{repoRoot:repo,checkCurrent:true,expectedHead:git('rev-parse','HEAD'),...options});
+ return {repo,root,git,base,save,validate};
+}
+test('one actual independent reviewer may pass both axes in native or explicitly selected modes',t=>{
+ const f=fixture(t);
+ for(const mode of ['native','herdr','orca','cli']) {const r=f.save({mode});const before=readFileSync(r.path);assert.deepEqual(f.validate(),[]);assert.deepEqual(readFileSync(r.path),before);}
+});
+test('self review, unknown identity, mismatched original output and missing dispatch cannot certify completion',t=>{
+ const f=fixture(t),r=f.save();
+ for(const text of [
+  r.text.replace('Implementers: native:implementer','Implementers: native:reviewer'),
+  r.text.replaceAll('native:reviewer','unknown'),
+  r.text.replace('Result: verified','Result: pending'),
+  r.text.replace('Mode: native','Mode: herdr'),
+  r.text.replace('Axis: standards','Axis: specification'),
+  r.text.replace('| standards | native:reviewer | pass |','| standards | native:reviewer | skipped |'),
+  r.text.replace('Verification: evidence/direct-spec.md#review-receipt','Verification: evidence/direct-spec.md#review-input'),
+  r.text.replace('## Independent Review','## Self Review'),
+ ]) {writeFileSync(r.path,text);assert.ok(f.validate().length,text);}
+ writeFileSync(r.path,r.text);assert.ok(f.validate({requiredImplementers:['native:merge-fixer']}).length);
+});
+test('changed code, sources and final HEAD invalidate review, unrelated reports do not',t=>{
+ const f=fixture(t),r=f.save();assert.deepEqual(f.validate(),[]);
+ writeFileSync(join(f.root,'another-report.md'),'New report outside code scope');assert.deepEqual(f.validate(),[]);
+ writeFileSync(join(f.repo,'value.txt'),'new fix');assert.match(f.validate().join('\n'),/drift/);
+ f.save();assert.deepEqual(f.validate(),[]);
+ writeFileSync(join(f.root,'evidence/fixture-standards.md'),'different standards');assert.match(f.validate().join('\n'),/source drift/);
+ f.save();f.git('add','value.txt');f.git('-c','commit.gpgsign=false','commit','-m','new checkpoint');assert.match(f.validate().join('\n'),/checkpoint/);
+ f.save();assert.deepEqual(f.validate(),[]);
+});
+test('valid old record is readable without reusing it for changed current inputs',t=>{
+ const f=fixture(t);f.save();writeFileSync(join(f.repo,'value.txt'),'later work');
+ assert.deepEqual(f.validate({checkCurrent:false}),[]);assert.ok(f.validate().length);
+});
+test('unsafe evidence paths, missing specification and empty change cannot fabricate approval',t=>{
+ const f=fixture(t),r=f.save();
+ writeFileSync(r.path,r.text.replace('Input: evidence/direct-spec.md#review-input','Input: ../outside'));
+ assert.ok(f.validate().length);
+ writeFileSync(r.path,r.text.replace('"kind": "specification"','"kind": "instructions"'));
+ assert.match(f.validate().join('\n'),/required review sources/);
+ writeFileSync(join(f.repo,'value.txt'),'before');f.save();assert.match(f.validate().join('\n'),/no-diff/);
+});
+test('owning results must match original axes and committed delivery rejects later dirty code',t=>{
+ const f=fixture(t);f.git('add','value.txt');f.git('-c','commit.gpgsign=false','commit','-m','reviewed implementation');
+ const head=f.git('rev-parse','HEAD'),r=f.save({head});
+ assert.deepEqual(f.validate({requireDelivery:true}),[]);
+ assert.match(f.validate({expectedResults:{standards:'request-changes',specification:'pass'}}).join('\n'),/differs from the owning report/);
+ writeFileSync(join(f.repo,'value.txt'),'unreviewed repair');
+ assert.deepEqual(f.validate(),[]); // C may inspect the immutable commit itself.
+ assert.match(f.validate({requireDelivery:true}).join('\n'),/unreviewed working-tree delivery/);
+ writeFileSync(join(f.repo,'value.txt'),'after');writeFileSync(join(f.repo,'new-feature.txt'),'unreviewed addition');
+ assert.match(f.validate({requireDelivery:true}).join('\n'),/new-feature/);
+ rmSync(join(f.repo,'new-feature.txt'));writeFileSync(join(f.root,'README.md'),'Outcome: completed\n');
+ assert.deepEqual(f.validate({requireDelivery:true}),[]);
+ const failed=r.text.replace('Axis: standards\nResult: pass','Axis: standards\nResult: request-changes').replace('| standards | native:reviewer | pass |','| standards | native:reviewer | request-changes |');
+ writeFileSync(r.path,failed);
+ assert.match(f.validate({requirePassed:false,expectedResults:{standards:'pass',specification:'pass'}}).join('\n'),/differs from the owning report/);
+});

package/template/workflows/specdev/common/tools/tests/review-fixture.mjs

@@ -0,0 +1,31 @@
+/** Synthetic tool receipts for disposable tests only; never runtime evidence. */
+import {createHash} from 'node:crypto';
+import {mkdirSync,readFileSync,writeFileSync,existsSync} from 'node:fs';
+import {dirname,join,relative} from 'node:path';
+import {resolveReviewScope} from '../review-scope.mjs';
+import {reviewInputDigest} from '../review-evidence.mjs';
+import {readArtifactSectionSync} from '../../../../../lib/speculo-runtime.mjs';
+const hash=text=>createHash('sha256').update(text).digest('hex');
+export function appendReviewFixture({repo,root,artifact='evidence/direct-spec.md',base,head=null,files=['value.txt'],mode='native',reviewer='native:reviewer',implementers=['native:implementer'],spec=null,sourceLocators=null}) {
+  const path=join(root,artifact);mkdirSync(dirname(path),{recursive:true});
+  let prior=existsSync(path)?readFileSync(path,'utf8'):'';
+  prior=prior.split('\n<!-- synthetic-independent-review -->')[0];
+  writeFileSync(path,prior);
+  let sources;
+  if(sourceLocators) sources=sourceLocators.map(({kind,locator})=>{
+    const [file,anchor]=locator.split('#');
+    return {kind,locator,sha256:hash(anchor?readArtifactSectionSync(join(repo,file),anchor).text:readFileSync(join(repo,file),'utf8'))};
+  });
+  else {
+    const standards=join(root,'evidence/fixture-standards.md');mkdirSync(dirname(standards),{recursive:true});writeFileSync(standards,'# Fixture standards\nPreserve existing behavior and test changes.\n');
+    if(!spec) {spec=join(root,'evidence/fixture-spec.md');writeFileSync(spec,'# Fixture Spec\nAC-001: deliver the accepted behavior.\n');}
+    sources=[['standards',standards],['specification',spec]].map(([kind,file])=>({kind,locator:relative(repo,file).split('\\').join('/'),sha256:hash(readFileSync(file,'utf8'))}));
+  }
+  const scope=resolveReviewScope(head?{repo,mode:'range',base,head}:{repo,mode:'working-tree',base,files});
+  const input={scope,sources,exclusions:'Fixture-only records and unrelated inputs are outside the implementation scope.'};
+  const digest=reviewInputDigest(input);
+  const report=axis=>`<a id="${axis}-output"></a>\n## Original ${axis} output\nReviewer: ${reviewer}\nAxis: ${axis}\nResult: pass\nInput-SHA256: ${digest}\nObserved: synthetic fixture reviewer inspected the fixed inputs; no blocking findings.\n`;
+  const text=`\n<!-- synthetic-independent-review -->\n<a id="review-input"></a>\n## Review Input\n\n\x60\x60\x60json\n${JSON.stringify(input,null,2)}\n\x60\x60\x60\n\n${report('standards')}\n${report('specification')}\n<a id="review-receipt"></a>\n## Original dispatch and verification\nVerified-By: native:lead\nMode: ${mode}\nReviewers: ${reviewer}\nInput-SHA256: ${digest}\nResult: verified\nObserved: synthetic fixture dispatch returned the separate reviewer handle and both original outputs.\n\n## Independent Review\nInput: ${artifact}#review-input\nImplementers: ${implementers.join(', ')}\nMode: ${mode}\nVerified-By: native:lead\nVerification: ${artifact}#review-receipt\n\n| Axis | Reviewer | Result | Report |\n|---|---|---|---|\n| standards | ${reviewer} | pass | ${artifact}#standards-output |\n| specification | ${reviewer} | pass | ${artifact}#specification-output |\n`;
+  writeFileSync(path,prior+text);
+  return {input,digest,path,text:prior+text};
+}

package/template/workflows/specdev/common/tools/tests/review-working-tree.test.mjs

@@ -0,0 +1,60 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {execFileSync} from 'node:child_process';
+import {mkdtempSync,mkdirSync,writeFileSync,readFileSync,rmSync,renameSync,chmodSync,symlinkSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {resolveReviewScope} from '../review-scope.mjs';
+
+function fixture(t) {
+  const root=mkdtempSync(join(tmpdir(),'review-working-'));
+  t.after(()=>rmSync(root,{recursive:true,force:true}));
+  const git=(...args)=>execFileSync('git',['-C',root,...args],{encoding:'utf8',stdio:['ignore','pipe','pipe']}).trim();
+  git('init','-b','main');git('config','user.name','Fixture');git('config','user.email','test@example.invalid');
+  git('config','core.autocrlf','false');
+  for(const path of ['one.txt','removed.txt','renamed.txt']) writeFileSync(join(root,path),'original\n');
+  writeFileSync(join(root,'.gitignore'),'ignored/\n');git('add','.');git('-c','commit.gpgsign=false','commit','-m','base');
+  const base=git('rev-parse','HEAD');
+  return {root,git,base,scope:(extra={})=>resolveReviewScope({repo:root,mode:'working-tree',base,...extra})};
+}
+test('working-tree freezes staged, unstaged, added, deleted, renamed and mode changes without writes',t=>{
+  const f=fixture(t);
+  writeFileSync(join(f.root,'one.txt'),'staged\n');f.git('add','one.txt');writeFileSync(join(f.root,'one.txt'),'final\n');
+  rmSync(join(f.root,'removed.txt'));renameSync(join(f.root,'renamed.txt'),join(f.root,'new-name.txt'));
+  writeFileSync(join(f.root,'new.bin'),Buffer.from([0,255,7]));chmodSync(join(f.root,'one.txt'),0o755);
+  mkdirSync(join(f.root,'ignored'));writeFileSync(join(f.root,'ignored/not-selected'),'ignored');
+  const before=readFileSync(join(f.root,'.git/index')), status=f.git('status','--porcelain');
+  const scope=f.scope();
+  assert.equal(scope.outcome,'changes');assert.equal(scope.observed_head,f.base);assert.equal(scope.head_sha,undefined);
+  assert.deepEqual(scope.changed_paths,['new-name.txt','new.bin','one.txt','removed.txt','renamed.txt']);
+  assert.equal(scope.working_snapshot.find(x=>x.path==='one.txt').after.mode,process.platform === 'win32' ? '100644' : '100755');
+  assert.equal(scope.working_snapshot.find(x=>x.path==='removed.txt').after,null);
+  assert.equal(scope.working_snapshot.find(x=>x.path==='new.bin').after.bytes,3);
+  assert.deepEqual(f.scope(),scope);assert.equal(f.git('status','--porcelain'),status);assert.deepEqual(readFileSync(join(f.root,'.git/index')),before);
+  writeFileSync(join(f.root,'new.bin'),Buffer.from([0,255,8]));assert.notEqual(f.scope().input_sha256,scope.input_sha256);
+});
+test('explicit scopes are literal, expose exclusions and retain deleted files',t=>{
+  const f=fixture(t), path='literal [abc] $(touch unsafe).txt';
+  writeFileSync(join(f.root,path),'literal');rmSync(join(f.root,'removed.txt'));writeFileSync(join(f.root,'one.txt'),'changed');
+  const scope=f.scope({files:[path,'removed.txt']});
+  assert.deepEqual(scope.changed_paths,[path,'removed.txt']);assert.deepEqual(scope.excluded_paths,['one.txt']);
+  assert.equal(scope.selection,'explicit-files');
+  for(const files of [[],['../outside'],['.git/config'],['one.txt','one.txt'],['missing']]) assert.throws(()=>f.scope({files}));
+  for(const extra of [{head:'HEAD'},{commit:'HEAD'},{parent:1}]) assert.throws(()=>f.scope(extra));
+  assert.throws(()=>f.scope({base:'missing'}));
+});
+test('links are read as links and directory links never disclose outside bytes',t=>{
+  const f=fixture(t), outside=mkdtempSync(join(tmpdir(),'review-outside-'));
+  t.after(()=>rmSync(outside,{recursive:true,force:true}));writeFileSync(join(outside,'secret'),'sensitive');
+  symlinkSync(join(outside,'secret'),join(f.root,'link'));
+  const scope=f.scope({files:['link']});assert.equal(scope.working_snapshot[0].after.kind,'symlink');
+  symlinkSync(outside,join(f.root,'directory'),process.platform === 'win32' ? 'junction' : 'dir');
+  assert.throws(()=>f.scope({files:['directory/secret']}),/symlink directory/);
+});
+test('unmerged index and borrowed parent repository are rejected',t=>{
+  const f=fixture(t);f.git('checkout','-b','other');writeFileSync(join(f.root,'one.txt'),'other\n');f.git('commit','-am','other');
+  f.git('checkout','main');writeFileSync(join(f.root,'one.txt'),'main\n');f.git('commit','-am','main');
+  assert.throws(()=>f.git('merge','other'));assert.throws(()=>f.scope(),/unresolved index/);
+  f.git('merge','--abort');mkdirSync(join(f.root,'nested'));
+  assert.throws(()=>resolveReviewScope({repo:join(f.root,'nested'),mode:'working-tree',base:f.base}),/actual project Git root/);
+});

package/template/workflows/specdev/common/tools/validate-specdev.mjs

@@ -31,6 +31,7 @@ import {
 import { validateChangeClosure, readChangeOwner } from "./change-artifacts.mjs";
 import { validateRecord, validateRecords } from "./delivery-artifacts.mjs";
 import { reviewScopeCLI } from "./review-scope.mjs";
+import { hasIndependentReview, validateIndependentReview } from "./review-evidence.mjs";
 import { ENGINEERING_KINDS, validateEngineeringArtifacts, validateEngineeringPackage } from "./engineering-evidence.mjs";
 
 const DOMAIN_SCHEMA_VERSION = 3;
@@ -202,15 +203,6 @@ const REQUIRED_TICKET_KEYS = new Set([
   "shared_paths",
   "shared_path_owners",
 ]);
-const REQUIRED_READY_TICKET_SECTIONS = new Set([
-  "## 1. 战略与来源",
-  "## 2. 决策状态",
-  "## 3. 范围边界",
-  "## 4. 要构建什么",
-  "## 7. 路径访问契约",
-  "## 8. 验证矩阵",
-  "## 10. 验收标准",
-]);
 const REQUIRED_GOAL_PLAN_SECTIONS = new Set([
   "## 1. Outcome and Authority",
   "## 2. Execution Graph",
@@ -334,6 +326,20 @@ function sectionBody(body, heading) {
   return (next ? tail.slice(0, next.index) : tail).trim();
 }
 
+// Accept the published long templates and the concise headings without making
+// numbering, repeated instructions or a fixed count of implementation steps a gate.
+function semanticSection(body, names) {
+  const lines = runtime.markdownBodyLines(body);
+  const matches = lines.filter(line => {
+    const match = /^(#{2,3})\s+(?:\d+\.\s*)?(.+)$/.exec(line.text);
+    return match && names.includes(match[2]);
+  });
+  if (matches.length !== 1) return "";
+  const start = matches[0], level = /^#+/.exec(start.text)[0].length;
+  const end = lines.find(line => line.line > start.line && /^#{1,3}\s/.test(line.text) && /^#+/.exec(line.text)[0].length <= level);
+  return body.split(/\r?\n/).slice(start.line, end ? end.line-1 : undefined).join("\n").trim();
+}
+
 function stripPathTag(value) {
   const match = /^<Path>([^<]+)<\/Path>$/.exec(String(value).trim());
   return match ? match[1].trim() : null;
@@ -1460,12 +1466,13 @@ function validateDiagnosis(path, expectedChange, errors) {
   return { path, meta, body };
 }
 
-function validateReviews(change, required, errors) {
+function validateReviews(change, required, errors, repoRoot = null) {
   const root = join(change, "reviews");
   const paths = isDirectory(root)
     ? readdirSync(root).filter((name) => /^CR-\d{3,}\.md$/.test(name)).sort().map((name) => join(root, name))
     : [];
   if (required && !paths.length) errors.push("review stage requires a CR-###.md report");
+  const latest = [...paths].sort((a,b) => Number(basename(a).match(/\d+/)[0])-Number(basename(b).match(/\d+/)[0])).at(-1);
   for (const path of paths) {
     const { meta, body } = parseFrontmatter(path);
     if (meta.schema_version !== 1 || meta.artifact !== "code-review") {
@@ -1483,6 +1490,12 @@ function validateReviews(change, required, errors) {
     for (const heading of ["## Fixed Input", "## 标准", "## 规范", "## Summary"]) {
       if (!body.includes(heading)) errors.push(`${basename(path)}: missing '${heading}'`);
     }
+    // Historical CRs remain readable. Only the current review or an explicitly
+    // supplied new record is checked against the independent execution contract.
+    if (required && path === latest || hasIndependentReview(path)) {
+      errors.push(...validateIndependentReview(change, toPosix(relative(change,path)), {repoRoot,requirePassed:meta.status === 'approved',expectedResults:{standards:meta.standards_result,specification:meta.specification_result},expectedHead:meta.head,checkCurrent:required && path === latest}));
+      if (meta.status === 'approved' && (meta.standards_result !== 'pass' || meta.specification_result !== 'pass')) errors.push(`${basename(path)}: approved requires both review axes to pass`);
+    }
   }
   return paths;
 }
@@ -1692,18 +1705,12 @@ function validateSpec(path, errors, warnings) {
   const sources = requireList(meta, "sources", label, errors);
   if (!sources.length) errors.push(`${label}: sources must contain at least one source`);
   if (meta.ready_for_tickets === true) {
-    const unresolved = sectionBody(body, "### 未决问题");
+    const unresolved = semanticSection(body, ["未决问题"]);
     if (unresolved && !/^无[。.]?$/.test(unresolved.trim())) {
       errors.push(`${label}: ready Spec has unresolved high-impact questions`);
     }
-    for (const heading of [
-      "## 1. 问题与目标",
-      "## 2. 解决方案与外部行为",
-      "## 4. 验收合同",
-      "## 5. 范围",
-      "## 9. 验证策略",
-    ]) {
-      if (!body.includes(heading)) errors.push(`${label}: ready Spec missing '${heading}'`);
+    for (const heading of ["问题与目标", "解决方案与外部行为", "验收合同", "范围", "验证策略"]) {
+      if (!semanticSection(body,[heading])) errors.push(`${label}: ready Spec missing '${heading}' content`);
     }
   }
   return { path, meta, body };
@@ -2181,32 +2188,22 @@ function validateTicket(path, errors) {
     if (!new Set(["ready", "in_progress", "review", "done"]).has(meta.status)) {
       errors.push(`${basename(path)}: ready=true conflicts with status=${meta.status}`);
     }
-    for (const heading of REQUIRED_READY_TICKET_SECTIONS) {
-      if (!body.includes(heading)) errors.push(`${basename(path)}: Ready Ticket missing '${heading}'`);
+    for (const names of [["目标与来源","战略与来源"],["行为与范围","要构建什么"],["验收标准"],["验证方法","验证矩阵"]]) {
+      if (!semanticSection(body,names)) errors.push(`${basename(path)}: Ready Ticket missing '${names[0]}' content`);
     }
-    const unresolved = sectionBody(body, "### 未决问题");
+    const unresolved = semanticSection(body, ["未决问题"]);
     if (unresolved && !/^无[。.]?$/.test(unresolved.trim())) {
       errors.push(`${basename(path)}: Ready Ticket has unresolved questions`);
     }
     if (!lists.writable_paths.length) errors.push(`${basename(path)}: Ready implementation Ticket requires writable_paths`);
-    if (new Set(["standard", "deep"]).has(meta.planning_depth)) {
-      for (const heading of ["## 5. 实现契约", "## 6. 执行路线"]) {
-        if (!body.includes(heading)) {
-          errors.push(`${basename(path)}: ${meta.planning_depth} Ticket missing '${heading}'`);
-        }
-      }
-    }
-    if (meta.planning_depth === "deep" && !body.includes("## 9. 发布、迁移与恢复")) {
-      errors.push(`${basename(path)}: Deep Ticket missing release/migration/recovery`);
-    }
-    const verification = sectionBody(body, "## 8. 验证矩阵");
+    const verification = semanticSection(body, ["验证方法","验证矩阵"]);
     if (!verification || !verification.includes("|")) {
       errors.push(`${basename(path)}: Ready Ticket has no usable verification matrix`);
     }
     if (!verification.includes("E2E disposition") || !/(current-workspace|source-worktree|parent-candidate|direct-parent)/.test(verification)) {
       errors.push(`${basename(path)}: Ready Ticket must define E2E disposition and an explicit execution environment`);
     }
-    const acceptance = sectionBody(body, "## 10. 验收标准").toLowerCase();
+    const acceptance = semanticSection(body, ["验收标准"]).toLowerCase();
     if (!acceptance.includes("- [ ]") && !acceptance.includes("- [x]")) {
       errors.push(`${basename(path)}: Ready Ticket has no acceptance checklist`);
     }
@@ -3099,7 +3096,7 @@ function validateChange(change, stage = null, repoRoot = null, engineeringKind =
     if(archive?.archive_state === 'moved') warnings.push('archive moved and checked, but is not sealed; finish the original A8 receipt');
     return { errors, warnings, ...(archive ? {archive} : {}) };
   }
-  if (isParentImplementation) validateParentImplementation(change, changeStatus, stage, errors, warnings, repoRoot, options);
+  const parentImplementation = isParentImplementation ? validateParentImplementation(change, changeStatus, stage, errors, warnings, repoRoot, options) : null;
   errors.push(...validateInitiative(change));
   if (isFile(join(change, "source-issue.md"))) {
     errors.push("obsolete source-issue.md is forbidden; use source.md without compatibility fallback");
@@ -3127,7 +3124,7 @@ function validateChange(change, stage = null, repoRoot = null, engineeringKind =
   if (isFile(diagnosisPath) || stage === "diagnosis") {
     validateDiagnosis(diagnosisPath, basename(change), errors);
   }
-  validateReviews(change, stage === "review", errors);
+  validateReviews(change, stage === "review", errors, workspace.context.projectRoot);
   validatePrototypes(change, stage === "prototype", errors, prototypeId, new Set(["spec", "tickets", "goal-plan", "implement", "review", "complete"]).has(stage), workspace.context);
   if (new Set(["tickets", "goal-plan", "implement", "review", "complete"]).has(stage)) runDesignCheck("--handoff", change, errors, workspace.context);
   validateChangeLearning(change, stage === "learn", errors);
@@ -3266,6 +3263,43 @@ function validateChange(change, stage = null, repoRoot = null, engineeringKind =
 
   if (stage === "complete" && spec && !ticketMode && !isParentImplementation && !retroOnly) errors.push(...validateAcceptanceEvidence(change,"evidence/direct-spec.md",[...new Set(spec.body.match(/\bAC-\d+\b/g) ?? [])]));
 
+  // New completion/archival consumes actual review evidence. Historical records
+  // remain readable outside these gates; archived validation returned earlier.
+  let nonImplementation = false;
+  if (stage === 'complete' && !spec && !ticketMode && !simpleGoal && !goalPlan && !isParentImplementation && !changeStatus?.worktrees?.length && !isDirectory(join(change,'evidence'))) {
+    try {
+      const owner = readChangeOwner(workspace.context,basename(change));
+      if (owner.work === 'specdev/learn' && isFile(join(change,'learning','index.md'))) {
+        validateChangeLearning(change,true,errors);
+        nonImplementation = true;
+      } else if (owner.work === 'specdev/triage' && source && triage?.meta.ready_for_implementation === false) nonImplementation = true;
+    } catch(error) { errors.push(error.message); }
+  }
+  if (stage === 'complete' && changeStatus?.location.kind === 'active' && changeStatus?.outcome !== 'cancelled' && !retroOnly && !nonImplementation) {
+    const units = [...tickets.values()].filter(ticket => ticket.meta.status !== 'cancelled');
+    const finalArtifact = isParentImplementation ? 'evidence/implementation-orchestration.md'
+      : units.length > 1 ? 'evidence/final-review.md'
+      : units.length === 1 ? `evidence/${units[0].meta.id}.md`
+      : lightweight ? 'README.md' : 'evidence/direct-spec.md';
+    try {
+      const head = execFileSync('git',['-C',workspace.context.projectRoot,'rev-parse','--verify','HEAD^{commit}'],{encoding:'utf8',stdio:['ignore','pipe','pipe']}).trim();
+      const executions = [...(changeStatus.worktrees ?? []), ...[...(parentImplementation?.memberStatuses?.values() ?? [])].flatMap(status=>status.worktrees ?? [])];
+      const owners = executions.flatMap(record => [record.implementation_owner, ...(record.integration?.conflict_paths?.length ? [record.integration_owner] : [])]).filter(value => typeof value === 'string' && /^[a-z][a-z0-9-]*:\S+$/i.test(value));
+      const bases = [...new Set(executions.map(record=>record.base_sha).filter(value=>/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(value ?? '')))];
+      const expectedBase = bases.length > 1 ? execFileSync('git',['-C',workspace.context.projectRoot,'merge-base','--octopus',...bases],{encoding:'utf8',stdio:['ignore','pipe','pipe']}).trim() : bases[0] ?? null;
+      const sourceLocator = path => {
+        const snapshot = workspace.context.readOnlySnapshot;
+        const original = snapshot ? join(snapshot.sourceContext.specdevRoot,relative(workspace.context.specdevRoot,path)) : path;
+        return toPosix(relative(workspace.context.projectRoot,original));
+      };
+      const specLocator = sourceLocator(spec ? spec.path : join(change,'README.md'));
+      const requiredSpecifications = isParentImplementation
+        ? [sourceLocator(join(change,'implementation-plan.md')),sourceLocator(join(change,'implementation-map.md')),...new Set([...(parentImplementation?.ticketByTask?.values() ?? [])].map(unit=>sourceLocator(join(unit.memberRoot,'spec.md'))))]
+        : spec ? [specLocator] : [`${specLocator}#scope`,`${specLocator}#acceptance`];
+      errors.push(...validateIndependentReview(change,finalArtifact,{repoRoot:workspace.context.projectRoot,expectedHead:head,expectedBase,requiredImplementers:owners,requiredSpecifications,checkCurrent:true,requireDelivery:true}));
+    } catch(error) { errors.push(`independent-review: final delivery checkpoint unavailable: ${error.message}`); }
+  }
+
   if (spec && ticketMode) {
     const declaredContracts = new Set(spec.body.match(/\bAC-\d+\b/g) ?? []);
     const coveredContracts = new Set(
@@ -3351,6 +3385,14 @@ function validateChange(change, stage = null, repoRoot = null, engineeringKind =
       continue;
     }
     const text = readText(evidence);
+    if (stage === 'complete' && changeStatus?.location.kind === 'active' || hasIndependentReview(evidence)) {
+      const execution = changeStatus?.worktrees?.find(entry => entry.ticket_id === ticketId);
+      errors.push(...validateIndependentReview(change, `evidence/${ticketId}.md`, {
+        repoRoot:workspace.context.projectRoot,
+        expectedHead:execution?.integration?.result_sha ?? execution?.source_checkpoint ?? null,
+        checkCurrent:false,
+      }));
+    }
     const currentWorkspace = changeStatus?.worktrees?.find(entry => entry.ticket_id === ticketId)?.workspace_ref === "current";
     const requiredHeadings = [
       "## 2. Lead Dispatch And Candidate Return",
@@ -3471,7 +3513,7 @@ function printResults(errors, warnings) {
 }
 
 function usage() {
-  console.error("Usage: node validate-specdev.mjs [--stage <stage>] [--sealed (archived only)] [--prototype-id UI-NNN|LOGIC-NNN] [--repo <project-root>] [--engineering <performance|documentation|incident>] <change-directory> | --review-scope --repo <project-root> --mode <baseline|range|commit|pr|source-files> [comparison options or repeated --file <relative-path>] | --self-check | --capture <capture.md> | --triage-run <TRI-NNN.md>");
+  console.error("Usage: node validate-specdev.mjs [--stage <stage>] [--sealed (archived only)] [--prototype-id UI-NNN|LOGIC-NNN] [--repo <project-root>] [--engineering <performance|documentation|incident>] <change-directory> | --review-scope --repo <project-root> --mode <baseline|range|commit|pr|source-files|working-tree> [comparison options or repeated --file <relative-path>] | --self-check | --capture <capture.md> | --triage-run <TRI-NNN.md>");
   return 2;
 }