@namewta/speculo 1.0.24 → 2.0.1

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

@@ -0,0 +1,277 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile, readdir, readlink } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseFrontmatter } from '../../../../lib/speculo-runtime.mjs';
+import * as runtime from '../../../../lib/speculo-runtime.mjs';
+import { resolveToolContext, canonicalToolPath, resolveSnapshotContext } from './plan-contract.mjs';
+import * as schemas from '../../../../lib/design-validators.mjs';
+
+export const sha256 = value => createHash('sha256').update(value).digest('hex');
+const stable = value => Array.isArray(value) ? value.map(stable) : value && typeof value === 'object'
+  ? Object.fromEntries(Object.keys(value).sort().map(key => [key, stable(value[key])])) : value;
+
+/** Hash normative content, never its own receipt or mutable workflow timestamps. */
+export function designDigest(markdown) {
+  const { fields, body } = parseFrontmatter(markdown);
+  const { confirmation, status, updated_at, ...normative } = fields;
+  return sha256(JSON.stringify(stable(normative)) + '\n' + body.replaceAll('\r\n', '\n').trim());
+}
+
+export function assertSchema(name, value) {
+  const validate = schemas[name];
+  if (!validate || !validate(value)) throw new Error(`${name}: ${JSON.stringify(validate?.errors ?? 'unknown schema')}`);
+}
+
+export async function safePath(root, locator) {
+  if (typeof locator !== 'string' || !locator || isAbsolute(locator) || locator.includes('\\') || locator.split('/').some(x => !x || x === '.' || x === '..')) throw new Error(`unsafe design locator: ${locator}`);
+  return runtime.safeWorkPathSync(root, locator, { mustExist:true });
+}
+
+export async function readDesign(path) {
+  if ((await lstat(path)).isSymbolicLink()) throw new Error('design document must not be a symlink');
+  const text = await readFile(path, 'utf8');
+  const { fields: meta, body } = parseFrontmatter(text);
+  return { meta, body, text, digest: designDigest(text) };
+}
+
+function unique(items, label) {
+  if (new Set(items).size !== items.length) throw new Error(`duplicate ${label}`);
+}
+
+function assertBody(body) {
+  if (!body.trim() || /\bTODO\b|<YYYY-MM-DD|<ISO-8601>|\[待补充\]/.test(body)) throw new Error('design normative body is incomplete');
+  if (/(?:[A-Za-z]:[\\/]|\/(?:Users|home|tmp)\/)/.test(body)) throw new Error('design contains machine-specific absolute path');
+}
+
+export async function validateProjectDesign(path) {
+  const record = await readDesign(path);
+  assertSchema('projectDesign', record.meta);
+  assertBody(record.body);
+  unique(record.meta.rules.map(rule => rule.id), 'design rule id');
+  unique(record.meta.sources.map(source => source.id), 'design source id');
+  for (const rule of record.meta.rules) {
+    if (rule.verification === 'implemented' && !rule.sources.length) throw new Error(`implemented rule ${rule.id} requires implementation evidence`);
+  }
+  validateTokens(record.meta.tokens);
+  return record;
+}
+
+/** Tokens remain project-named; references must resolve and cannot form cycles. */
+export function validateTokens(tokens) {
+  const visit = (value, trail = []) => {
+    if (typeof value === 'string') for (const match of value.matchAll(/\{([\w.-]+)\}/g)) {
+      const key = match[1].replace(/^tokens\./, '');
+      if (trail.includes(key)) throw new Error(`cyclic design token: ${key}`);
+      let target = tokens;
+      for (const part of key.split('.')) target = target?.[part];
+      if (target === undefined) throw new Error(`unresolved design token: ${key}`);
+      visit(target, [...trail, key]);
+    }
+    else if (value && typeof value === 'object') for (const child of Object.values(value)) visit(child, trail);
+  };
+  visit(tokens);
+}
+
+export function designContext(path, options = {}) {
+  if (options.readOnlySnapshot) return resolveSnapshotContext(options.readOnlySnapshot);
+  if (options.snapshotSpecdev) return resolveSnapshotContext({sourceContext:designContext(path,{...options,snapshotSpecdev:undefined}),specdevRoot:options.snapshotSpecdev});
+  if (options.context) return resolveToolContext(path, {context:options.context});
+  const stateParameter = options.stateRoot ? (isAbsolute(options.stateRoot) && options.repoRoot ? relative(resolve(options.repoRoot),options.stateRoot) : options.stateRoot) : undefined;
+  const context = resolveToolContext(path, {repoRoot:options.repoRoot, methodRoot:options.methodRoot, stateRoot:stateParameter ? dirname(stateParameter) : undefined});
+  if (stateParameter && resolve(context.projectRoot, stateParameter) !== context.specdevRoot) throw new Error('state-root must identify the declared SpecDev root');
+  return context;
+}
+export function designStateRoot(path, options = {}) { return designContext(path, options).specdevRoot; }
+
+export async function validateChangeDesign(path, options = {}) {
+  const { requireApproved = true } = options;
+  const record = await readDesign(path);
+  assertSchema('changeDesign', record.meta);
+  assertBody(record.body);
+  validateTokens(record.meta.tokens);
+  unique(record.meta.pages.map(page => page.id), 'design page id');
+  if (basename(dirname(path)) !== record.meta.change) throw new Error('DESIGN change does not match owning directory');
+  if (requireApproved && record.meta.status !== 'approved') throw new Error('change DESIGN requires approved status');
+  if (record.meta.status === 'approved') {
+    if (record.meta.confirmation.digest !== record.digest) throw new Error('change DESIGN confirmation digest is stale');
+    const receipt = await safePath(dirname(path), record.meta.confirmation.record);
+    const receiptBytes = await readFile(receipt);
+    if (sha256(receiptBytes) !== record.meta.confirmation.record_digest) throw new Error('user confirmation record digest is stale');
+    const receiptText = receiptBytes.toString('utf8');
+    for (const digest of [record.digest, record.meta.prototype_ref.digest, record.meta.baseline.digest]) if (!receiptText.includes(digest)) throw new Error('user confirmation record does not bind the design, prototype and baseline scope');
+    const state = designStateRoot(path, options);
+    const snapshot = await validateProjectDesign(await safePath(state, `design/revisions/${record.meta.baseline.revision}.md`));
+    if (snapshot.meta.revision !== record.meta.baseline.revision || snapshot.digest !== record.meta.baseline.digest) throw new Error('baseline revision/digest mismatch');
+  }
+  return record;
+}
+
+export async function prototypeDigest(path) {
+  const { meta } = await readDesign(path), root = dirname(path), files = [];
+  async function collect(folder) {
+    const absolute = await safePath(root, folder);
+    for (const entry of (await readdir(absolute, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+      const locator = `${folder}/${entry.name}`;
+      if (entry.isSymbolicLink()) throw new Error(`prototype resource symlink: ${locator}`);
+      if (entry.isDirectory()) await collect(locator);
+      else if (entry.isFile()) files.push([locator, sha256(await readFile(await safePath(root, locator)))]);
+      else throw new Error(`unsupported prototype resource: ${locator}`);
+    }
+  }
+  await collect('final');
+  await collect('comparison');
+  files.sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+  return sha256(JSON.stringify(stable({ candidates: meta.candidates, selected_candidate: meta.selected_candidate, files })));
+}
+
+export const DESIGN_LIBRARY = fileURLToPath(new URL('../../specdev-p-prototype/design-library/', import.meta.url));
+
+function archiveLocator(context, location, value) {
+  const match = /^(change|project):([^#]+)(?:#([a-z][a-z0-9-]*))?$/.exec(value ?? '');
+  if (!match) throw new Error('archive receipt locator must declare change: or project:');
+  const root = match[1] === 'change' ? location.root : context.projectRoot;
+  return {path:runtime.safeWorkPathSync(root,match[2],{mustExist:true,type:'file'}),anchor:match[3]};
+}
+
+/** Read the owning A receipt and its actual moved bytes, without writing a projection. */
+async function validateArchiveReceipt(context, location, sealed) {
+  const readme = runtime.readChangeFactsSync(context,location).readmePath;
+  const lines = runtime.markdownBodyLines(runtime.readUtf8ArtifactSync(readme),readme);
+  const headings = lines.filter(line=>line.text === '## Archive Receipt');
+  if (headings.length > 1) throw new Error('duplicate Archive Receipt navigation');
+  let locator = `change:archive-receipt.md#archive-${location.name}`;
+  if (headings.length) {
+    const start=headings[0].line,end=lines.find(line=>line.line > start && /^#{1,2} /.test(line.text))?.line ?? Infinity;
+    const values=lines.filter(line=>line.line > start && line.line < end && /^Receipt: /.test(line.text));
+    if(values.length !== 1) throw new Error('Archive Receipt navigation requires one Receipt locator');
+    locator=values[0].text.slice('Receipt: '.length);
+  }
+  const receipt=archiveLocator(context,location,locator);
+  const commandRoot=join(context.stateRoot,'commands/archive-and-consolidate');
+  const within=(root,path)=>{const rel=relative(root,path);return rel && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);};
+  if (!within(location.root,receipt.path) && !within(commandRoot,receipt.path)) throw new Error('archive receipt is outside the owning change/Command report');
+  if (receipt.path !== join(location.root,'archive-receipt.md') && await lstat(join(location.root,'archive-receipt.md')).catch(()=>null)) throw new Error('archive has two receipt authorities');
+  if (!receipt.anchor) throw new Error('archive receipt requires an explicit object anchor');
+  const fields={};
+  for(const line of runtime.markdownBodyLines(runtime.readArtifactSectionSync(receipt.path,receipt.anchor).text,receipt.path)) {
+    const field=/^([A-Z][A-Za-z0-9-]*): (.+)$/.exec(line.text);
+    if(!field) continue;
+    if(field[1] in fields) throw new Error(`archive receipt duplicates ${field[1]}`);
+    fields[field[1]]=field[2];
+  }
+  for(const key of ['Change','Owner','Operation','Approval','Approval-SHA256','Source','Target','Result','Integrity','Integrity-SHA256','Time']) {
+    if(typeof fields[key] !== 'string' || /^(?:unknown|pending|tbd|todo|\.\.\.|<.*>)$/i.test(fields[key])) throw new Error(`archive receipt requires actual ${key}`);
+  }
+  const {readChangeOwner}=await import('./change-artifacts.mjs');
+  if(fields.Change !== location.name || fields.Source !== `changes/${location.name}` || fields.Target !== `changes/archive/${location.name}`) throw new Error('archive receipt has a foreign change/source/target');
+  if(fields.Owner !== readChangeOwner(context,location.name).owner) throw new Error('archive receipt owner differs from the current handoff evidence');
+  if(!['moved','verified'].includes(fields.Result) || Number.isNaN(Date.parse(fields.Time))) throw new Error('archive receipt has an invalid result/time');
+  if(sealed && fields.Result !== 'verified') throw new Error('archive receipt is moved but not sealed; finish the original A8 receipt');
+  const approval=archiveLocator(context,location,fields.Approval);
+  const approvalText=approval.anchor ? runtime.readArtifactSectionSync(approval.path,approval.anchor).text : runtime.readUtf8ArtifactSync(approval.path);
+  if(approval.path === receipt.path || !/^[a-f0-9]{64}$/.test(fields['Approval-SHA256']) || sha256(await readFile(approval.path)) !== fields['Approval-SHA256']) throw new Error('archive approval snapshot is missing, mutable or has digest drift');
+  if([location.name,fields.Operation,fields.Owner].some(value=>!approvalText.includes(value))) throw new Error('archive approval snapshot does not bind the original operation/change/owner');
+  const manifest=archiveLocator(context,location,fields.Integrity);
+  if(manifest.anchor || !within(location.root,manifest.path) || manifest.path === receipt.path || !/^[a-f0-9]{64}$/.test(fields['Integrity-SHA256']) || sha256(await readFile(manifest.path)) !== fields['Integrity-SHA256']) throw new Error('archive integrity manifest has an invalid locator or digest drift');
+  const data=JSON.parse(await readFile(manifest.path,'utf8'));
+  if(!data || Object.keys(data).join(',') !== 'entries' || !Array.isArray(data.entries) || !data.entries.length) throw new Error('archive integrity manifest requires nonempty entries');
+  const excluded=new Set([receipt.path,manifest.path]),seen=new Set(),actual=new Set();
+  const scan=async root=>{for(const name of await readdir(root)){const path=join(root,name);if(excluded.has(path))continue;actual.add(relative(location.root,path).split(sep).join('/'));if((await lstat(path)).isDirectory())await scan(path);}};
+  await scan(location.root);
+  for(const entry of data.entries) {
+    if(!entry || typeof entry.path !== 'string' || isAbsolute(entry.path) || /[\\:\x00-\x1f]/.test(entry.path) || entry.path.split('/').some(part=>!part || part === '.' || part === '..') || !['file','directory','symlink'].includes(entry.type) || !Number.isInteger(entry.mode) || entry.mode < 0 || entry.mode > 0o7777) throw new Error('archive integrity entry has invalid path/type/mode');
+    const allowed=new Set(['path','type','mode',...(entry.type === 'file' ? ['sha256'] : entry.type === 'symlink' ? ['target'] : [])]);
+    if(Object.keys(entry).some(key=>!allowed.has(key)) || seen.has(entry.path.toLowerCase())) throw new Error('archive integrity entry is duplicate or has unknown fields');
+    seen.add(entry.path.toLowerCase());
+    const parentRelative=dirname(entry.path) === '.' ? '' : dirname(entry.path).split(sep).join('/');
+    const parent=runtime.safeWorkPathSync(location.root,parentRelative,{mustExist:true,type:'directory',allowRoot:true});
+    const path=join(parent,basename(entry.path));
+    if(!actual.delete(entry.path) || excluded.has(path)) throw new Error(`archive integrity manifest has an extra or excluded entry: ${entry.path}`);
+    const stat=await lstat(path);
+    if((stat.mode & 0o7777) !== entry.mode || (entry.type === 'file' ? !stat.isFile() : entry.type === 'directory' ? !stat.isDirectory() : !stat.isSymbolicLink())) throw new Error(`archive integrity type/mode drift: ${entry.path}`);
+    if(entry.type === 'file' && (!/^[a-f0-9]{64}$/.test(entry.sha256 ?? '') || sha256(await readFile(path)) !== entry.sha256)) throw new Error(`archive integrity byte drift: ${entry.path}`);
+    if(entry.type === 'symlink' && (typeof entry.target !== 'string' || await readlink(path) !== entry.target)) throw new Error(`archive integrity link drift: ${entry.path}`);
+  }
+  if(actual.size) throw new Error(`archive integrity manifest omits paths: ${[...actual].join(', ')}`);
+  return {archive_state:fields.Result,sealed:fields.Result === 'verified',receipt:receipt.path,operation:fields.Operation};
+}
+
+export async function validateArchived(path, options = {}) {
+  const context = designContext(path, options), state = context.specdevRoot, name = basename(path);
+  const location = runtime.resolveChangeSync(context, name, {includeArchived:true});
+  if (location.root !== canonicalToolPath(context,path) || location.kind === 'active') throw new Error('archived change must resolve to its unique archive location');
+  let receipt={archive_state:'legacy-readonly',readonly:true};
+  if (location.kind === 'legacy-archive') {
+    // Historical evidence is never normalized, upgraded or written by this reader.
+    runtime.readLegacyChangeEvidenceSync(context, location);
+  } else {
+    receipt=await validateArchiveReceipt(context,location,options.sealed === true);
+    const { validateChangeClosure } = await import('./change-artifacts.mjs');
+    const closure = validateChangeClosure({context,change:name,forArchive:true});
+    if (closure.errors.length) throw new Error(closure.errors.join('\n'));
+    if (closure.scope === 'complex-preflight') {
+      const {validateChange} = await import('./validate-specdev.mjs');
+      const result = validateChange(path,'archive-ready',context.projectRoot,null,null,{context,readOnlySnapshot:context.readOnlySnapshot});
+      if (result.errors.length) throw new Error(result.errors.join('\n'));
+    }
+  }
+  const cancelled = location.kind !== 'legacy-archive' && runtime.readChangeFactsSync(context,location).outcome === 'cancelled';
+  if (await lstat(join(path, 'DESIGN.md')).catch(() => null)) {
+    const design = await validateChangeDesign(join(path, 'DESIGN.md'), {context,readOnlySnapshot:context.readOnlySnapshot,requireApproved:!cancelled});
+    const packagePath = await safePath(path, `prototypes/${design.meta.prototype_ref.id}/design-system.md`);
+    if (!cancelled && (await readDesign(packagePath)).meta.status !== 'ready') throw new Error('archived design references a prototype that is not ready');
+    const { validate } = await import('../../specdev-p-prototype/scripts/validate-design-package.mjs');
+    await validate(packagePath, { checkReady: !cancelled, allowDraft:cancelled, context, readOnlySnapshot:context.readOnlySnapshot });
+  }
+  const current = join(state, 'design/DESIGN.md');
+  if (await lstat(current).catch(() => null)) {
+    const record = await validateProjectDesign(current);
+    const snapshot = await validateProjectDesign(await safePath(state, `design/revisions/${record.meta.revision}.md`));
+    if (snapshot.text !== record.text) throw new Error('current project DESIGN differs from immutable revision');
+    const designIndex = await readFile(await safePath(state, 'design/INDEX.md'), 'utf8');
+    if (!designIndex.includes(record.meta.revision)) throw new Error('design index needs rebuilding from published revision');
+  }
+  return receipt;
+}
+
+export async function validateDesignHandoff(changeRoot, options = {}) {
+  const ticketRoot = join(changeRoot, 'ticket');
+  const files = await readdir(ticketRoot).catch(error => { if (error.code === 'ENOENT') return []; throw error; });
+  let design;
+  for (const file of files.filter(file => file.endsWith('.md'))) {
+    const ticket = await readDesign(join(ticketRoot, file));
+    const ui = ticket.meta.ui_change === true || (ticket.meta.expected_changes ?? []).some(path => /\.(?:tsx|jsx|vue|svelte|html|css)(?:<\/Path>)?$/.test(path));
+    if (!ui || ['draft', 'cancelled'].includes(ticket.meta.status)) continue;
+    design ??= await validateChangeDesign(join(changeRoot, 'DESIGN.md'), options);
+    const ref = ticket.meta.design_ref;
+    if (!ref || ref.revision !== design.meta.revision || ref.digest !== design.digest || !Array.isArray(ref.pages) || !ref.pages.length || !Array.isArray(ref.acceptance) || !ref.acceptance.length) throw new Error(`${file}: UI Ticket requires current DESIGN revision/digest/pages/acceptance`);
+    for (const page of ref.pages) if (!design.meta.pages.some(p => p.id === page)) throw new Error(`${file}: unknown DESIGN page ${page}`);
+    for (const ac of ref.acceptance) if (!design.meta.pages.filter(p => ref.pages.includes(p.id)).some(p => p.acceptance.includes(ac))) throw new Error(`${file}: unknown DESIGN acceptance ${ac}`);
+    if (ticket.meta.status === 'done') {
+      const evidence = await readFile(await safePath(changeRoot, `evidence/${ticket.meta.id}.md`), 'utf8');
+      if (!evidence.includes('## Design Conformance') || !evidence.includes(ref.digest) || [...ref.pages, ...ref.acceptance].some(id => !evidence.includes(id))) throw new Error(`${file}: completed UI Ticket needs Design Conformance evidence bound to DESIGN and acceptance IDs`);
+    }
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const [operation, path, ...args] = process.argv.slice(2);
+  const options = {};
+  for (let i=0;i<args.length;i+=2) {
+    if(args[i] === '--sealed' && operation === '--archived' && !options.sealed){options.sealed=true;i--;continue;}
+    const field = {'--repo':'repoRoot','--method-root':'methodRoot','--state-root':'stateRoot','--snapshot-specdev':'snapshotSpecdev'}[args[i]];
+    if (!field || !args[i+1] || args[i+1].startsWith('--') || field in options) throw new Error('invalid explicit design context arguments');
+    options[field] = args[i+1];
+  }
+  const actions = {
+    '--digest': async () => (await readDesign(path)).digest,
+    '--prototype-digest': () => prototypeDigest(path),
+    '--project': () => validateProjectDesign(path),
+    '--change': () => validateChangeDesign(path, options),
+    '--handoff': () => validateDesignHandoff(path, options),
+    '--archived': () => validateArchived(path, options),
+  };
+  if (!path || !actions[operation]) { console.error('usage: design-artifacts.mjs --digest|--prototype-digest|--project|--change|--handoff|--archived <path>'); process.exitCode = 2; }
+  else actions[operation]().then(result => console.log(typeof result === 'string' ? result : result?.archive_state ? JSON.stringify(result) : 'design artifacts: valid')).catch(error => { console.error(error.message); process.exitCode = 1; });
+}

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

@@ -135,9 +135,9 @@ export function validateEngineeringArtifacts(change, requiredKind = null) {
 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'],
+    ['specdev-r-review-architecture/SKILL.md', 'specdev-r-review-architecture/references/performance-review.md'],
+    ['specdev-i-implement/SKILL.md', 'specdev-i-implement/references/documentation-procedure.md'],
+    ['specdev-d-diagnose-bugs/SKILL.md', 'specdev-d-diagnose-bugs/references/incident-evidence.md'],
   ]) {
     if (!existsSync(join(root, target))) errors.push(`engineering/route: missing ${target}`);
     const source = join(root, entry);

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

@@ -1,7 +1,8 @@
 /** Strict, additive Plan contracts. Read-only; no authorization or state writes. */
 import { createHash } from 'node:crypto';
-import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { existsSync, lstatSync, readFileSync, realpathSync, readdirSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import * as runtime from '../../../../lib/speculo-runtime.mjs';
 
 export const CHANGE_ID = /^\d{4}-\d{2}-\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const DIGEST = /^[a-f0-9]{64}$/;
@@ -93,13 +94,24 @@ export function validateBindings(meta, repoRoot) {
   return errors;
 }
 
+function readEvidenceValue(text, heading) {
+  const bodyLines = runtime.markdownBodyLines(text), starts = bodyLines.filter(line=>line.text === heading);
+  if (starts.length !== 1) throw new Error(`expected one '${heading}'`);
+  const start = starts[0].line, end=bodyLines.find(line=>line.line > start && /^#{1,2} /.test(line.text))?.line;
+  const tail = text.replaceAll('\r\n','\n').split('\n').slice(start,end ? end-1 : undefined).join('\n');
+  const blocks=[];let fence=null,buffer=[];
+  for(const line of tail.split('\n')) {
+    const marker=/^ {0,3}(`{3,}|~{3,})([^\r\n]*)$/.exec(line);
+    if(!fence && marker){fence={char:marker[1][0],length:marker[1].length,json:marker[2].trim() === 'json'};buffer=[];continue;}
+    if(fence && marker && marker[1][0] === fence.char && marker[1].length >= fence.length && !marker[2].trim()){if(fence.json)blocks.push(buffer.join('\n'));fence=null;continue;}
+    if(fence)buffer.push(line);
+  }
+  if(fence || blocks.length !== 1) throw new Error(`${heading} requires one complete JSON code block`);
+  return JSON.parse(blocks[0]);
+}
+
 export function readEvidenceRecords(text, heading) {
-  const start = text.indexOf(`${heading}\n`);
-  if (start < 0) throw new Error(`missing '${heading}'`);
-  const tail = text.slice(start + heading.length + 1).split(/^## /m)[0];
-  const match = /```json\s*\n([\s\S]*?)\n```/.exec(tail);
-  if (!match) throw new Error(`${heading} requires a JSON array code block`);
-  const value = JSON.parse(match[1]);
+  const value=readEvidenceValue(text,heading);
   if (!Array.isArray(value)) throw new Error(`${heading} must contain an array`);
   return value;
 }
@@ -107,10 +119,7 @@ export function readEvidenceRecords(text, heading) {
 export function validateTicketPlan(artifact, { repoRoot = null, requirePlan = false, checkEvidence = true } = {}) {
   const { meta, body, path } = artifact;
   const errors = [];
-  if (meta.plan_contract_version === undefined) {
-    if (requirePlan && !['done','cancelled'].includes(meta.status)) errors.push('legacy Ticket must be upgraded to plan_contract_version: 1 before implementation');
-    return errors;
-  }
+  if (meta.plan_contract_version === undefined) return ['Ticket requires plan_contract_version: 1'];
   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');
@@ -135,7 +144,7 @@ export function validateTicketPlan(artifact, { repoRoot = null, requirePlan = fa
 
 export function validatePlanMap(artifact, changeDirectory = null) {
   const { meta, body } = artifact;
-  if (meta.plan_contract_version === undefined) return [];
+  if (meta.plan_contract_version === undefined) return ['Tickets Map requires plan_contract_version: 1'];
   const errors = [];
   if (meta.plan_contract_version !== 1) errors.push('unsupported plan_contract_version');
   if (!Number.isInteger(meta.plan_revision) || meta.plan_revision < 1) errors.push('plan_revision must be a positive integer');
@@ -241,11 +250,9 @@ export function validateInitiative(directory) {
       else if (existsSync(join(target,'implementation-map.md'))) errors.push(`${label}: target must not be a parent implementation change`);
       else {
         try {
-          const statusFile = join(target,'.status.json');
-          if (lstatSync(statusFile).isSymbolicLink() || !lstatSync(statusFile).isFile()) throw new Error('status must be a real file');
-          const status = JSON.parse(readFileSync(statusFile,'utf8'));
-          if (status.schema_version !== 6 || status.artifact !== 'change-status' || status.change !== item.target) throw new Error('status identity does not match target change');
-        } catch (error) { errors.push(`${label}: target has no valid owned change status: ${error.message}`); }
+          if (existsSync(join(target, '.status.json'))) throw new Error('legacy-active-needs-conversion');
+          runtime.parseOutcome(readFileSync(join(target, 'README.md'), 'utf8'), join(target, 'README.md'));
+        } catch (error) { errors.push(`${label}: target has no valid Markdown change facts: ${error.message}`); }
       }
     }
   }
@@ -254,3 +261,139 @@ export function validateInitiative(directory) {
   if (cycle) errors.push(`initiative.json: candidate dependency cycle: ${cycle.join(' -> ')}`);
   return errors;
 }
+
+/** Read actual per-Ticket integration 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()) {
+    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');
+    const sections = runtime.markdownBodyLines(text,path).filter(line=>line.text === '## Workspace Execution Record');
+    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`);
+    records.push(record);
+  }
+  return records;
+}
+
+/** A single Spec authority, with explicit lightweight fallback and stable sections. */
+export function readSpecification(changeRoot, { allowLightweight = false, requiredArtifact = null, depth = null } = {}) {
+  const spec = join(changeRoot, 'spec.md'), readme = join(changeRoot, 'README.md');
+  const sections = {};
+  let anchors = false;
+  if (existsSync(readme)) {
+    const text = readFileSync(readme, 'utf8');
+    anchors = runtime.markdownBodyLines(text, readme).some(line => /^<a id="(?:scope|acceptance|verification)"><\/a>$/.test(line.text));
+  }
+  if (existsSync(spec)) {
+    if (lstatSync(spec).isSymbolicLink() || !lstatSync(spec).isFile()) throw new Error('Spec must be a real file');
+    if (anchors) throw new Error('two specification authorities: migrate README scope/acceptance/verification to navigation');
+    return { path: spec, lightweight: false, text: readFileSync(spec, 'utf8') };
+  }
+  const goal = readLightweightGoal(changeRoot);
+  if (!allowLightweight || requiredArtifact || /^deep$/i.test(depth ?? '') || ['ticket','tickets-map.md','implementation-map.md','implementation-plan.md'].some(name => existsSync(join(changeRoot, name))) || (!goal && existsSync(join(changeRoot,'goal-plan.md')))) throw new Error('independent Spec is required for explicit, Deep, Ticket, Goal or parallel work');
+  for (const anchor of ['scope','acceptance','verification']) {
+    sections[anchor] = runtime.readArtifactSectionSync(readme, anchor);
+    if (placeholder(sections[anchor].text) || !sections[anchor].text.trim()) throw new Error(`README ${anchor} must contain substantive facts`);
+  }
+  const acceptance = [...sections.acceptance.text.matchAll(/\bAC-\d+\b/g)].map(match => match[0]);
+  if (!acceptance.length || new Set(acceptance).size !== acceptance.length) throw new Error('README acceptance requires unique AC identifiers and observable criteria');
+  const text = readFileSync(readme, 'utf8');
+  if ((!goal && !/^[-*] \[[ xX]\] \S/m.test(text)) || !/^## (?:下一步|Next Steps?)\s*$/mi.test(text)) throw new Error('lightweight README requires a current checklist and next step');
+  return { path: readme, lightweight: true, text, sections, acceptance };
+}
+
+export function validateExecutionPolicy(plan, config = null) {
+  const errors = [];
+  const meta = plan.meta;
+  if (!Number.isInteger(meta.concurrent_implementation_limit) || meta.concurrent_implementation_limit < 1 || !Number.isInteger(meta.integration_attempt_limit) || meta.integration_attempt_limit < 1) return ['plan must declare positive execution limits'];
+  if (config) {
+    if (config.schema_version !== 7 || !Number.isInteger(config.execution?.max_concurrent_implementations) || !Number.isInteger(config.execution?.max_integration_attempts)) return ['existing tool config requires schema v7 and explicit execution limits'];
+    if (meta.concurrent_implementation_limit > config.execution.max_concurrent_implementations) errors.push(`concurrent_implementation_limit ${meta.concurrent_implementation_limit} exceeds config max_concurrent_implementations ${config.execution.max_concurrent_implementations}`);
+    if (meta.integration_attempt_limit > config.execution.max_integration_attempts) errors.push(`integration_attempt_limit ${meta.integration_attempt_limit} exceeds config max_integration_attempts ${config.execution.max_integration_attempts}`);
+  } else {
+    const section = plan.body.split(/^## Execution Policy Source\s*$/m)[1]?.split(/^## /m)[0]?.trim();
+    if (placeholder(section)) errors.push('plan without tool config requires an explicit Execution Policy Source');
+  }
+  return errors;
+}
+
+/** Resolve the same explicit roots for every tool; installed discovery stays strict. */
+export function resolveToolContext(changeRoot, options = {}) {
+  const supplied = options.context ?? options;
+  const projectRoot = supplied.projectRoot ?? supplied.repoRoot ?? runtime.workspaceForPathSync(existsSync(changeRoot) && lstatSync(changeRoot).isFile() ? dirname(changeRoot) : changeRoot).projectRoot;
+  return runtime.resolveWorkContextSync({ projectRoot, methodRoot: supplied.methodRoot, stateRoot: supplied.stateRoot });
+}
+
+/** Canonicalize host ancestor aliases while retaining every project-local link check. */
+export function canonicalToolPath(context, input) {
+  const absolute = resolve(context.projectRoot, input);
+  for (let ancestor = absolute; ; ancestor = dirname(ancestor)) {
+    if (existsSync(ancestor) && realpathSync(ancestor) === context.projectRoot) {
+      if (lstatSync(ancestor).isSymbolicLink()) throw new Error('path-unsafe: linked project boundary');
+      return runtime.safeWorkPathSync(context.projectRoot, relative(ancestor, absolute).split(sep).join('/'), {allowRoot:true});
+    }
+    if (dirname(ancestor) === ancestor) throw new Error(`path-unsafe: artifact escapes confirmed project: ${input}`);
+  }
+}
+
+/** Read-only conversion validation against a contained snapshot, never a write context. */
+export function resolveSnapshotContext(snapshot) {
+  const source = resolveToolContext(snapshot.sourceContext.projectRoot, {context:snapshot.sourceContext});
+  const specdevRoot = canonicalToolPath(source, snapshot.specdevRoot);
+  runtime.safeWorkPathSync(source.projectRoot, relative(source.projectRoot,specdevRoot).split(sep).join('/'), {mustExist:true,type:'directory'});
+  if (specdevRoot === source.specdevRoot) throw new Error('snapshot must be separate from the live SpecDev root');
+  runtime.assertMarkdownProtocolSync(specdevRoot);
+  return {...source,specdevRoot,stateRoot:dirname(specdevRoot),readOnlySnapshot:{sourceContext:source,specdevRoot}};
+}
+
+export function readLightweightGoal(changeRoot) {
+  const path = join(changeRoot, 'goal-plan.md');
+  if (!existsSync(path)) return null;
+  const {fields:meta,body} = runtime.parseFrontmatter(runtime.readUtf8ArtifactSync(path));
+  if (meta.artifact !== 'lightweight-goal-plan') return null;
+  if (Object.keys(meta).some(key => !['artifact','change','lead'].includes(key)) || meta.change !== basename(changeRoot) || placeholder(meta.lead)) throw new Error('lightweight Goal must identify its change and real Lead without duplicate progress fields');
+  if (['ticket','tickets-map.md','implementation-map.md','implementation-plan.md'].some(name=>existsSync(join(changeRoot,name)))) throw new Error('lightweight Goal cannot own Tickets, Maps or multi-change execution');
+  const visible=runtime.markdownBodyLines(body,path);
+  for (const heading of ['Tasks','Integration and Verification','Next Steps']) {
+    const starts=visible.filter(line=>line.text === `## ${heading}`);
+    if (starts.length !== 1) throw new Error(`lightweight Goal requires one substantive ${heading} section`);
+    const end=visible.find(line=>line.line > starts[0].line && /^#{1,2} /.test(line.text))?.line ?? Infinity;
+    const content=visible.filter(line=>line.line > starts[0].line && line.line < end).map(line=>line.text).join('\n').trim();
+    if (placeholder(content)) throw new Error(`lightweight Goal requires one substantive ${heading} section`);
+  }
+  if (!/^[-*] \[\s?[xX]?\] \S/m.test(body)) throw new Error('lightweight Goal requires its own task checklist');
+  const readme = runtime.readUtf8ArtifactSync(join(changeRoot,'README.md'));
+  if (/^[-*] \[[ xX]\] /m.test(readme)) throw new Error('README must navigate to Goal instead of mirroring its task progress');
+  return {path,meta,body};
+}
+
+/** A file's presence is not acceptance. Bind each contract to its actual observation. */
+export function validateAcceptanceEvidence(changeRoot, artifact, contractIds) {
+  const errors = [];
+  try {
+    const path = runtime.safeWorkPathSync(changeRoot, artifact, {mustExist:true,type:'file'});
+    const records = readEvidenceRecords(runtime.readUtf8ArtifactSync(path).replaceAll('\r\n','\n'), '## Acceptance Verification');
+    const allowed = new Set(['id','result','method','source','observed','command','exit','evidence','sha256']);
+    if (!contractIds.length) errors.push(`${artifact}: completion requires explicit AC identifiers`);
+    for (const id of new Set(contractIds)) {
+      const matching = records.filter(record => record?.id === id);
+      if (matching.length !== 1) { errors.push(`${artifact}: ${id} requires exactly one actual acceptance result`); continue; }
+      const record = matching[0];
+      if (!plainObject(record) || Object.keys(record).some(key=>!allowed.has(key)) || record.result !== 'passed' || ['method','source','observed'].some(key=>placeholder(record[key]))) errors.push(`${artifact}: ${id} requires passed Method/Source/Observed evidence`);
+      if (record.command !== undefined && (placeholder(record.command) || record.exit !== 0)) errors.push(`${artifact}: ${id} command must have actual Exit 0`);
+      if (record.evidence !== undefined) {
+        const evidence = runtime.safeWorkPathSync(changeRoot, record.evidence, {mustExist:true,type:'file'});
+        if (evidence === path || !DIGEST.test(record.sha256 ?? '') || digest(readFileSync(evidence)) !== record.sha256) errors.push(`${artifact}: ${id} acceptance evidence digest drift or circular evidence`);
+      } else if (record.sha256 !== undefined) errors.push(`${artifact}: digest without evidence locator`);
+    }
+    for (const record of records) if (!contractIds.includes(record?.id)) errors.push(`${artifact}: unknown acceptance contract ${record?.id}`);
+  } catch(error) { errors.push(`${artifact}: ${error.message}`); }
+  return errors;
+}