@namewta/speculo 2.0.1 → 2.0.3

package/template/workflows/specdev/common/tools/plan-contract.mjs

@@ -123,9 +123,8 @@ export function validateTicketPlan(artifact, { repoRoot = null, requirePlan = fa
   if (meta.plan_contract_version !== 1) errors.push('unsupported plan_contract_version');
   errors.push(...validateBindings(meta, repoRoot));
   if (!strings(meta.resource_claims) || new Set(meta.resource_claims).size !== meta.resource_claims.length) errors.push('resource_claims must be a unique string array');
-  if (meta.ready === true || ['in_progress','review','done'].includes(meta.status)) {
-    for (const heading of ['## 11. SKILL 调用计划', '## 12. 停止、检查点与交付']) if (!body.includes(heading)) errors.push(`ready Plan Ticket missing '${heading}'`);
-  }
+  // Skill invocation is enforced by the structured bindings and real completion
+  // records below, not by repeating generic instructions in every Ticket body.
   if (checkEvidence && meta.status === 'done' && meta.skill_bindings?.some(binding => binding?.required === true)) {
     try {
       const evidencePath = join(dirname(dirname(path)), 'evidence', `${meta.id}.md`);
@@ -262,13 +261,13 @@ export function validateInitiative(directory) {
   return errors;
 }
 
-/** Read actual per-Ticket integration records; never creates empty execution slots. */
+/** Read actual Ticket or Direct Spec records; never creates empty execution slots. */
 export function readChangeExecution(changeRoot) {
   const root = join(changeRoot, 'evidence');
   if (!existsSync(root)) return [];
   if (lstatSync(root).isSymbolicLink() || !lstatSync(root).isDirectory()) throw new Error('Evidence must be a real directory');
   const records = [];
-  for (const file of readdirSync(root).filter(name => /^T-\d{2,}\.md$/.test(name)).sort()) {
+  for (const file of readdirSync(root).filter(name => /^T-\d{2,}\.md$/.test(name) || name === 'direct-spec.md').sort()) {
     const path = join(root, file);
     if (lstatSync(path).isSymbolicLink() || !lstatSync(path).isFile()) throw new Error(`${path}: Evidence must be a regular file`);
     const text = readFileSync(path, 'utf8').replaceAll('\r\n', '\n');
@@ -276,9 +275,17 @@ export function readChangeExecution(changeRoot) {
     if (!sections.length) continue;
     if (sections.length !== 1) throw new Error(`${path}: duplicate Workspace Execution Record`);
     const record = readEvidenceValue(text,'## Workspace Execution Record');
-    if (!plainObject(record) || record.ticket_id !== file.slice(0, -3)) throw new Error(`${path}: execution record identity differs from Evidence Ticket`);
+    const direct = file === 'direct-spec.md';
+    if (!plainObject(record) || (direct
+      ? record.purpose !== 'direct-spec' || record.change !== basename(changeRoot) || 'ticket_id' in record
+      : record.ticket_id !== file.slice(0, -3) || 'purpose' in record || 'change' in record)) {
+      throw new Error(`${path}: execution record identity differs from Evidence ${direct ? 'Direct Spec/change' : 'Ticket'}`);
+    }
     records.push(record);
   }
+  if (records.some(record => record.purpose === 'direct-spec') && records.some(record => record.ticket_id)) {
+    throw new Error('Direct Spec and Ticket execution records cannot coexist; reconcile the original execution before changing modes');
+  }
   return records;
 }
 

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,94 @@
 /** 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');
+  const root = realpathSync(resolve(options.repo));
+  if (realpathSync(git(root, ['rev-parse','--show-toplevel']).trim()) !== root) 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 +149,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/engineering.test.mjs

@@ -223,10 +223,10 @@ test('range comparison and merge-base comparison have distinct semantics', t =>
   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', () => {
+test('fifteen Work IDs match the current registry 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());
+  assert.deepEqual(ids.sort(), ['archive-and-consolidate','code-review','diagnose-bugs','goal-plan','grill-with-docs','implement','init-setup','learn','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);

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,59 @@
+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');
+  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,'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 [*] $(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'));
+  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/);
+});