@namewta/speculo 1.0.22 → 2.0.1

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

@@ -0,0 +1,170 @@
+/** Read-only completion preflight. Artifact text never authenticates user authority. */
+import { existsSync, readdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { basename, join } from 'node:path';
+import {
+  readChangeFactsSync, readArtifactSectionSync, readUtf8ArtifactSync,
+  safeWorkPathSync, markdownBodyLines, parseFrontmatter,
+} from '../../../../lib/speculo-runtime.mjs';
+
+const meaningful = value => typeof value === 'string' && value.trim() && !/^(?:unknown|unassigned|pending|tbd|todo|\.\.\.|<.*>)$/i.test(value.trim());
+function error(code, path, message) { throw new Error(`${code}: ${path}: ${message}`); }
+function section(path, heading) {
+  const text = readUtf8ArtifactSync(path), lines = markdownBodyLines(text, path);
+  const matches = lines.filter(line => line.text === `## ${heading}`);
+  if (matches.length !== 1) error('closure-evidence-missing', path, `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 fields(text, path) {
+  const result = {};
+  for (const {text: line} of markdownBodyLines(text, path)) {
+    const m = /^([A-Za-z][A-Za-z-]*): (.+)$/.exec(line);
+    if (!m) continue;
+    if (m[1] in result) error('closure-evidence-missing', path, `duplicate ${m[1]}`);
+    result[m[1]] = m[2].trim();
+  }
+  return result;
+}
+function evidence(root, locator) {
+  if (!meaningful(locator)) error('closure-evidence-missing', root, 'missing evidence locator');
+  const pieces = locator.split('#');
+  if (pieces.length > 2) error('closure-evidence-missing', root, 'ambiguous evidence locator');
+  const path = safeWorkPathSync(root, pieces[0] || 'README.md', { mustExist: true, type: 'file' });
+  const text = pieces.length === 2 ? readArtifactSectionSync(path, pieces[1]).text : readUtf8ArtifactSync(path);
+  if (!meaningful(text)) error('closure-evidence-missing', path, 'empty evidence');
+  return { path, text };
+}
+export function readChangeOwner(context, change) {
+  const facts = readChangeFactsSync(context, change), root = facts.location.root;
+  for (const name of ['implementation-plan.md', 'goal-plan.md']) {
+    const path = safeWorkPathSync(root, name, { type: 'file' });
+    if (!existsSync(path)) continue;
+    const {fields: meta} = parseFrontmatter(readUtf8ArtifactSync(path));
+    if (meta.change !== facts.location.name || !meaningful(meta.lead)) error('owner-unresolved', path, 'plan must identify this change and its actual Lead');
+    return { owner: meta.lead, path, evidencePath: path, kind: name === 'implementation-plan.md' ? 'parent-lead' : 'goal-lead' };
+  }
+  const data = fields(section(facts.readmePath, 'Ownership'), facts.readmePath);
+  if (!meaningful(data.Owner)) error('owner-unresolved', facts.readmePath, 'no actual owner/session locator');
+  const source = evidence(root, data.Evidence);
+  if (source.path === facts.readmePath && !data.Evidence.includes('#')) error('owner-unresolved', source.path, 'Ownership must point to a separate session/handoff section');
+  const sourceFields = fields(source.text, source.path);
+  if (![sourceFields.Owner, sourceFields.Session].includes(data.Owner)) error('owner-unresolved', source.path, 'owner differs from original session/handoff evidence');
+  if (data.Work && sourceFields.Work !== data.Work) error('owner-unresolved', source.path, 'Work differs from original ownership evidence');
+  return { owner: data.Owner, path: facts.readmePath, evidencePath: source.path, work: data.Work, kind: 'direct-owner' };
+}
+export function readLightweightSpec(changeRoot) {
+  const readme = safeWorkPathSync(changeRoot, 'README.md', { mustExist: true, type: 'file' });
+  const hasSpec = existsSync(join(changeRoot, 'spec.md'));
+  const visible = markdownBodyLines(readUtf8ArtifactSync(readme), readme);
+  const readmeOwns = visible.some(line => line.text === '<a id="scope"></a>');
+  if (hasSpec && readmeOwns) error('identity-conflict', readme, 'README and spec.md both claim specification ownership; replace the migrated README scope with navigation');
+  if (hasSpec) return { path: join(changeRoot, 'spec.md'), kind: 'independent' };
+  const scope = readArtifactSectionSync(readme, 'scope');
+  const acceptance = readArtifactSectionSync(readme, 'acceptance');
+  const verification = readArtifactSectionSync(readme, 'verification');
+  const ids = [...new Set(acceptance.text.match(/\bAC-\d+\b/g) ?? [])];
+  if (!ids.length) error('closure-evidence-missing', readme, 'lightweight acceptance must identify observable AC-n contracts');
+  return { path: readme, kind: 'lightweight', scope, acceptance, verification, ids };
+}
+function validateLightweightCompletion(root, errors) {
+  const spec = readLightweightSpec(root);
+  if (spec.kind !== 'lightweight') return;
+  const rows = spec.verification.text.split(/\r?\n/).filter(line => /^\|\s*AC-\d+\s*\|/.test(line)).map(line => line.split('|').slice(1,-1).map(cell => cell.trim()));
+  for (const id of spec.ids) {
+    const matches = rows.filter(row => row[0] === id);
+    if (matches.length !== 1) { errors.push(`closure-evidence-missing: ${spec.path}: ${id} needs one verification row (AC | Result | Evidence [| SHA256])`); continue; }
+    const row = matches[0];
+    if (![3,4].includes(row.length) || row[1] !== 'passed' || (row[3] && !/^[a-f0-9]{64}$/.test(row[3]))) { errors.push(`closure-evidence-missing: ${spec.path}: ${id} needs a passed result and valid optional evidence digest`); continue; }
+    try {
+      const record = evidence(root, row[2]);
+      if (record.path === spec.path && (!row[2].includes('#') || row[2].split('#')[1] === 'verification')) error('closure-evidence-missing', record.path, 'verification must cite a separate actual evidence section');
+      const actual = createHash('sha256').update(readUtf8ArtifactSync(record.path)).digest('hex');
+      if (row[3] && row[3] !== actual) error('source-drift', record.path, `${id} evidence digest changed`);
+      const data = fields(record.text, record.path);
+      if (data.Result !== 'passed' || !meaningful(data.Method) || !meaningful(data.Observed) || !meaningful(data.Source)) error('closure-evidence-missing', record.path, 'verification record needs Method, Source, Observed and Result: passed');
+      if (data.Command && data.Exit !== '0') error('closure-evidence-missing', record.path, 'command verification requires Exit: 0');
+    } catch (e) { errors.push(String(e)); }
+  }
+  for (const row of rows) if (!spec.ids.includes(row[0])) errors.push(`closure-evidence-missing: ${spec.path}: verification references undeclared ${row[0]}`);
+  if (/^\s*[-*] \[ \]/m.test(spec.acceptance.text)) errors.push(`closure-evidence-missing: ${spec.path}: acceptance remains unchecked`);
+}
+function validateCancellation(facts, owner, errors) {
+  const root = facts.location.root, content = readArtifactSectionSync(facts.readmePath, 'cancellation');
+  const data = fields(content.text, facts.readmePath);
+  for (const key of ['Source','Scope','Time','Confirmed-By','Undelivered','Landed','Writers','Dependencies','Checkpoints','External','Next']) if (!meaningful(data[key])) errors.push(`closure-evidence-missing: ${facts.readmePath}: cancellation needs ${key}`);
+  if (data['Confirmed-By'] !== owner?.owner) errors.push(`owner-unresolved: ${facts.readmePath}: cancellation was not confirmed by original completion owner`);
+  if (!/^\d{4}-\d\d-\d\dT/.test(data.Time ?? '') || !Number.isFinite(Date.parse(data.Time))) errors.push(`closure-evidence-missing: ${facts.readmePath}: cancellation needs actual decision time`);
+  const source = evidence(root, data.Source);
+  if (source.path === facts.readmePath && (!data.Source.includes('#') || data.Source.split('#')[1] === 'cancellation')) error('closure-evidence-missing', source.path, 'cancellation must point to a separate actual request section');
+  if (!/^none: \S/.test(data.Writers ?? '')) {
+    if (!/^stopped: \S/.test(data.Writers ?? '')) errors.push(`writer-active: ${facts.readmePath}: need none with rationale or stopped with termination/handoff evidence; timeout is not termination`);
+    else {
+      const stopped = evidence(root, data.Writers.slice(9)), stoppedFields = fields(stopped.text, stopped.path);
+      if (stoppedFields.Writers !== 'stopped' || !meaningful(stoppedFields.Observed)) errors.push(`writer-active: ${stopped.path}: missing observed termination/handoff`);
+    }
+  }
+  for (const key of ['Dependencies','Checkpoints','External']) if (!/^(?:none|resolved|transferred|waived): \S/.test(data[key] ?? '')) errors.push(`closure-evidence-missing: ${facts.readmePath}: unresolved ${key}`);
+  const tickets = safeWorkPathSync(root, 'evidence', { type: 'directory' });
+  if (existsSync(tickets)) for (const file of readdirSync(tickets).filter(n => /^T-\d+\.md$/.test(n))) {
+    const path = safeWorkPathSync(tickets, file, { type: 'file', mustExist: true }), text = readUtf8ArtifactSync(path);
+    const blocks = [...text.matchAll(/^## Workspace Execution Record\r?\n([\s\S]*?)(?=^## |$(?![\s\S]))/gm)];
+    for (const block of blocks) {
+      const json = /```json\s*\n([\s\S]*?)\n```/.exec(block[1]);
+      if (!json) error('closure-evidence-missing', path, 'invalid workspace execution record');
+      const record = JSON.parse(json[1]);
+      if (['active','review','integrating','blocked'].includes(record.status)) errors.push(`writer-active: ${path}: cancellation does not end an execution owner or candidate`);
+    }
+  }
+}
+export function validateArchiveDelivery(changeRoot) {
+  const errors = [];
+  for (const name of ['triage.md','publish.md']) {
+    const path = safeWorkPathSync(changeRoot, name, { type: 'file' }); if (!existsSync(path)) continue;
+    try {
+      const {fields: meta} = parseFrontmatter(readUtf8ArtifactSync(path));
+      if (meta.change !== basename(changeRoot)) errors.push(`${path}: change identity mismatch`);
+      if (name === 'triage.md' && !['closed','waived','not-applicable'].includes(meta.external_action)) errors.push(`${path}: external delivery is not closed`);
+      if (meta.publish_action !== undefined && !['not-requested','published','waived'].includes(meta.publish_action)) errors.push(`${path}: publish delivery is not closed`);
+    } catch (e) { errors.push(String(e)); }
+  }
+  const prs = safeWorkPathSync(changeRoot, 'pull-requests', { type: 'directory' });
+  if (existsSync(prs)) for (const name of readdirSync(prs)) {
+    try {
+      const path = safeWorkPathSync(prs, name, { type: 'file', mustExist: true });
+      const {fields: meta} = parseFrontmatter(readUtf8ArtifactSync(path));
+      if (meta.change !== basename(changeRoot)) errors.push(`${path}: change identity mismatch`);
+      if (meta.requested === true && !(meta.status === 'waived' || meta.status === 'ready' || (meta.delivery_target === 'draft' && meta.status === 'draft'))) errors.push(`${path}: requested PR delivery is unresolved`);
+    } catch (e) { errors.push(String(e)); }
+  }
+  return errors;
+}
+/** complex-preflight is deliberately not a completion certificate; the full validator must follow. */
+export function validateChangeClosure({context, change, forArchive = false}) {
+  const errors = []; let facts, owner, scope;
+  try {
+    facts = readChangeFactsSync(context, change);
+    owner = readChangeOwner(context, change);
+    if (facts.outcome === 'active') errors.push(`closure-evidence-missing: ${facts.readmePath}: change is still active`);
+    const root = facts.location.root;
+    if (facts.outcome === 'cancelled') { scope = 'cancellation'; validateCancellation(facts, owner, errors); }
+    else {
+      const goalPath = safeWorkPathSync(root, 'goal-plan.md', {type:'file'});
+      const lightweightGoal = existsSync(goalPath) && parseFrontmatter(readUtf8ArtifactSync(goalPath)).fields.artifact === 'lightweight-goal-plan';
+      const independent = ['spec.md','ticket','tickets-map.md','implementation-plan.md','implementation-map.md','retro',...(!lightweightGoal ? ['goal-plan.md'] : [])].some(name => existsSync(join(root, name)));
+      const complex = independent || ['DESIGN.md','prototypes'].some(name => existsSync(join(root,name)));
+      scope = complex ? 'complex-preflight' : 'lightweight';
+      if (!independent && facts.outcome === 'completed') {
+        validateLightweightCompletion(root, errors);
+        if (lightweightGoal) {
+          const tasks = section(goalPath, 'Tasks');
+          if (!/^\s*[-*] \[x\]/m.test(tasks) || /^\s*[-*] \[ \]/m.test(tasks)) errors.push(`closure-evidence-missing: ${goalPath}: Goal tasks must be actually delivered`);
+          for (const heading of ['Integration and Verification','Next Steps']) if (!meaningful(section(goalPath,heading))) errors.push(`closure-evidence-missing: ${goalPath}: ${heading} is empty`);
+          if (/^\s*[-*] \[[ x]\]/m.test(readUtf8ArtifactSync(facts.readmePath))) errors.push(`identity-conflict: ${facts.readmePath}: Goal owns task progress; README must not mirror it`);
+        }
+      }
+    }
+    if (forArchive) errors.push(...validateArchiveDelivery(root));
+  } catch (e) { errors.push(String(e)); }
+  return { valid: errors.length === 0, complete: errors.length === 0 && scope !== 'complex-preflight', scope, errors, facts, owner };
+}

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

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