@namewta/speculo 2.0.4 → 2.0.6

package/template/workflows/specdev/common/tools/ticket-control.mjs

@@ -5,6 +5,7 @@ import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseFrontmatter, validateChange, pathsOverlap } from './validate-specdev.mjs';
 import { CHANGE_ID, digest, findGraphCycle, resolveProjectSource, validateGoalMap, resolveToolContext, validateExecutionPolicy, canonicalToolPath } from './plan-contract.mjs';
+import { readExecutionContext, ticketPolicy } from './execution-context.mjs';
 import * as runtime from '../../../../lib/speculo-runtime.mjs';
 
 const terminal = new Set(['done','cancelled']);
@@ -43,7 +44,7 @@ function contractHash(node) {
       }
     }
   }
-  return digest(JSON.stringify({ meta, body: node.artifact.body, spec: node.specDigest, goal: node.goalDigest, dependencies: node.dependencies, serializations: node.serializations, sources }));
+  return digest(JSON.stringify({ meta, body: node.artifact.body, spec: node.specDigest, goal: node.goalDigest, scheduling:node.policy, workspace:readExecutionContext(dirname(dirname(node.artifact.path))), dependencies: node.dependencies, serializations: node.serializations, sources }));
 }
 
 export function analyzeMap({ mapPath, repoRoot, methodRoot, stateRoot, context: suppliedContext, previous = null }) {
@@ -68,9 +69,9 @@ export function analyzeMap({ mapPath, repoRoot, methodRoot, stateRoot, context:
   if (!Array.isArray(members) || !members.length || (parent && members.length < 2) || new Set(members).size !== members.length || members.some(id => !CHANGE_ID.test(id))) return failure(['invalid/duplicate member change IDs']);
   const planFile = join(root,parent ? 'implementation-plan.md' : 'goal-plan.md');
   const plan = existsSync(planFile) ? readArtifact(planFile) : null;
-  const strategy = plan?.meta.ticket_workspace_policy ?? 'current';
-  let limit = strategy === 'current' ? 1 : plan?.meta.concurrent_implementation_limit;
-  if (!['current','required'].includes(strategy) || !Number.isInteger(limit) || limit < 1) errors.push('invalid workspace strategy or implementation limit');
+  const scopeContext = readExecutionContext(root);
+  const policy = ticketPolicy(plan?.meta,scopeContext);
+  const limit = policy.max_parallel_tickets;
   const configPath = join(context.specdevRoot, 'config.json');
   const config = existsSync(configPath) ? JSON.parse(readFileSync(runtime.safeWorkPathSync(context.specdevRoot, 'config.json', {mustExist:true,type:'file'}), 'utf8')) : null;
   if (plan) errors.push(...validateExecutionPolicy(plan, config));
@@ -81,6 +82,9 @@ export function analyzeMap({ mapPath, repoRoot, methodRoot, stateRoot, context:
     if (!existsSync(memberRoot) || lstatSync(memberRoot).isSymbolicLink() || !lstatSync(memberRoot).isDirectory()) { errors.push(`member must be a real change directory: ${member}`); continue; }
     memberRoots.set(member,memberRoot);
     const facts = runtime.readChangeFactsSync(context, member);
+    const childPlanPath = join(memberRoot,'goal-plan.md');
+    const childPlan = parent && existsSync(childPlanPath) ? readArtifact(childPlanPath) : null;
+    const memberPolicy = ticketPolicy(plan?.meta,childPlan?.meta,readExecutionContext(memberRoot));
     if (facts.location.root !== memberRoot) { errors.push(`member is not an active change: ${member}`); continue; }
     const specFile = join(memberRoot,'spec.md');
     const spec = readArtifact(specFile);
@@ -93,7 +97,7 @@ export function analyzeMap({ mapPath, repoRoot, methodRoot, stateRoot, context:
       const id = parent ? `${member}::${artifact.meta.id}` : artifact.meta.id;
       if (nodes.has(id)) { errors.push(`duplicate Ticket ${id}`); continue; }
       if (!Array.isArray(artifact.meta.blocked_by) || artifact.meta.blocked_by.some(value => !/^T-\d{2,}$/.test(value))) { errors.push(`invalid dependencies: ${id}`); continue; }
-      nodes.set(id, { id, member, repoRoot, artifact, specDigest, facts, dependencies: artifact.meta.blocked_by.map(value => parent ? `${member}::${value}` : value), reasons: [], validationErrors: [] });
+      nodes.set(id, { id, member, repoRoot, policy:memberPolicy, artifact, specDigest, facts, dependencies: artifact.meta.blocked_by.map(value => parent ? `${member}::${value}` : value), reasons: [], validationErrors: [] });
       if (spec.meta.ready_for_tickets !== true) nodes.get(id).reasons.push('source Spec is not Ready');
     }
   }
@@ -146,7 +150,7 @@ export function analyzeMap({ mapPath, repoRoot, methodRoot, stateRoot, context:
   }
   for (const node of nodes.values()) {
     node.reasons.push(...node.validationErrors);
-    if (!terminal.has(node.artifact.meta.status) && (!plan || plan.meta.ready_for_execution !== true)) node.reasons.push('Goal planning gate is not ready for execution');
+    if (!terminal.has(node.artifact.meta.status) && (plan && plan.meta.ready_for_execution !== true)) node.reasons.push('Goal planning gate is not ready for execution');
     if (node.artifact.meta.plan_contract_version !== 1) node.reasons.push('Ticket requires current plan_contract_version: 1');
   }
   const goalDigest = stableGoalContract(plan,entry);
@@ -157,7 +161,7 @@ export function analyzeMap({ mapPath, repoRoot, methodRoot, stateRoot, context:
   const contractDigests = Object.fromEntries([...nodes].map(([id,node]) => [id,contractHash(node)]));
   const invalidated = new Set();
   if (previous !== null) {
-    if (previous.schema_version !== 1 || !previous.contract_digests || typeof previous.contract_digests !== 'object' || Array.isArray(previous.contract_digests) || previous.scope !== basename(root)) errors.push('previous checkpoint schema/scope does not match this Goal');
+    if (previous.schema_version !== 2 || !previous.contract_digests || typeof previous.contract_digests !== 'object' || Array.isArray(previous.contract_digests) || previous.scope !== basename(root)) errors.push('previous checkpoint schema/scope does not match this Goal');
     else {
       for (const [id,value] of Object.entries(contractDigests)) if (previous.contract_digests[id] !== value) invalidated.add(id);
       for (const id of Object.keys(previous.contract_digests)) if (!nodes.has(id)) warnings.push(`previous node removed; check coverage before accepting replan: ${id}`);
@@ -183,7 +187,7 @@ export function analyzeMap({ mapPath, repoRoot, methodRoot, stateRoot, context:
       if (!prerequisite || prerequisite.artifact.meta.status !== 'done' || prerequisite.reasons.length) node.reasons.push(`dependency not successfully satisfied: ${dependency}`);
     }
     for (const other of active) {
-      const issue = strategy === 'current' ? 'current workspace already has an implementation writer' : conflicts(node,other,serializations);
+      const issue = conflicts(node,other,serializations);
       if (issue) node.reasons.push(`in-flight owner ${other.artifact.meta.owner ?? 'unknown'} (${other.id}): ${issue}`);
     }
     if (!node.reasons.length) candidates.push(node);
@@ -206,15 +210,16 @@ export function analyzeMap({ mapPath, repoRoot, methodRoot, stateRoot, context:
   for (const node of candidates.sort((a,b) => a.id.localeCompare(b.id))) {
     if (node.reasons.length) continue;
     const conflict = frontier.map(id => conflicts(node,nodes.get(id),serializations)).find(Boolean);
-    if (conflict || frontier.length >= Math.max(0,limit-active.length)) { deferred.push({id:node.id, reason:conflict ?? 'workspace/config concurrency limit'});continue; }
+    const memberActive = active.filter(other=>other.member === node.member).length + frontier.filter(id=>nodes.get(id).member === node.member).length;
+    if (conflict || limit !== null && frontier.length >= Math.max(0,limit-active.length) || node.policy.max_parallel_tickets !== null && memberActive >= node.policy.max_parallel_tickets) { deferred.push({id:node.id, reason:conflict ?? 'Ticket scheduling concurrency limit'});continue; }
     frontier.push(node.id);
   }
   const blocked = [...nodes.values()].filter(node => node.reasons.length).map(node => ({id:node.id,reasons:[...new Set(node.reasons)]}));
   const nodeErrors = [...nodes.values()].flatMap(node => node.validationErrors.map(message => ({id:node.id,message})));
   const result = {
-    schema_version:1, scope:basename(root), mode:'read-only-analysis',
+    schema_version:2, scope:basename(root), mode:'read-only-analysis',
     authorization_checked:false, transaction_gateway_checked:false,
-    workspace_policy:strategy, implementation_limit:limit,
+    ticket_execution:policy.ticket_execution, max_parallel_tickets:limit,
     input_digest:digest(JSON.stringify({entry:entry.meta,contracts:contractDigests})),
     goal_contract_digest:goalDigest, contract_digests:contractDigests, frontier:errors.length ? [] : frontier,
     deferred, in_flight:active.map(node => ({id:node.id,owner:node.artifact.meta.owner})),
@@ -226,7 +231,7 @@ export function analyzeMap({ mapPath, repoRoot, methodRoot, stateRoot, context:
   return result;
 }
 function failure(errors) {
-  return {schema_version:1,mode:'read-only-analysis',frontier:[],errors,validation_errors:[],eligible_for_final_verification:false};
+  return {schema_version:2,mode:'read-only-analysis',frontier:[],errors,validation_errors:[],eligible_for_final_verification:false};
 }
 function main(args) {
   const options = {};

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

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/** Read-only handoff checks. Never discovers, opens or authenticates external transcripts. */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { posix, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  markdownBodyLines, parseFrontmatter, readChangeFactsSync, readUtf8ArtifactSync,
+  resolveWorkContextSync, safeWorkPathSync,
+} from '../../../../lib/speculo-runtime.mjs';
+import { checkSchema } from './delivery-artifacts.mjs';
+
+const schema = JSON.parse(readFileSync(new URL('../schemas/session-locator.schema.json', import.meta.url), 'utf8'));
+const requireThat = (condition, message) => { if (!condition) throw new Error(message); };
+const real = value => typeof value === 'string' && value.trim() === value && value.length > 0 && !/^(?:unknown|unassigned|pending|todo|tbd|\.\.\.)$/i.test(value) && !/[<>\x00-\x1f]|\{[^}]*\}/.test(value);
+const readFile = (root, path) => readUtf8ArtifactSync(safeWorkPathSync(root, path, {mustExist:true, type:'file'}));
+const readJson = path => JSON.parse(readUtf8ArtifactSync(path));
+
+function utc(value) {
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/.test(value)) return false;
+  const time = Date.parse(value);
+  return Number.isFinite(time) && new Date(time).toISOString() === value.replace(/(?:\.(\d{1,3}))?Z$/, (_, fraction = '') => `.${fraction.padEnd(3, '0')}Z`);
+}
+function identity(session, task) {
+  const match = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z(?:-(\d{2,}))?$/.exec(session ?? '');
+  requireThat(match && utc(`${match[1]}-${match[2]}-${match[3]}T${match[4]}:${match[5]}:${match[6]}Z`) && (!match[7] || Number(match[7]) > 0 && String(Number(match[7])).padStart(2,'0') === match[7]), 'invalid orchestration session');
+  const number = /^(\d{3,})-[a-z0-9]+(?:-[a-z0-9]+)*$/.exec(task ?? '')?.[1];
+  requireThat(number && Number.isSafeInteger(Number(number)) && Number(number) > 0 && String(Number(number)).padStart(3,'0') === number, 'invalid task sequence/topic');
+}
+function headings(text, names) {
+  const lines = markdownBodyLines(text);
+  for (const name of names) {
+    const matches = lines.filter(line => line.text === `## ${name}`);
+    requireThat(matches.length === 1, `expected one ${name} section`);
+    const end = lines.find(line => line.line > matches[0].line && /^#{1,2} /.test(line.text))?.line ?? Infinity;
+    requireThat(lines.some(line => line.line > matches[0].line && line.line < end && line.text.trim() && !/^#+\s/.test(line.text)), `empty ${name} section`);
+  }
+}
+
+/** Only a log path is stored; correspondence to this task is checked before writing. */
+export function validateSessionLocator(value) {
+  const errors = [];
+  checkSchema(value, schema, 'session-locator', errors);
+  if (errors.length) return errors;
+  const path = value.path;
+  if (!real(path) || /(?:^|[\\/])(?:\.\.\.|unknown|todo|tbd)(?:[\\/]|$)/i.test(path)) errors.push('path: placeholder or empty locator');
+  // Accept source paths on either platform; do not access the external file here.
+  if (!(posix.isAbsolute(path) || /^[A-Za-z]:[\\/]/.test(path) || /^\\\\[^\\/]+[\\/][^\\/]+[\\/]/.test(path))) errors.push('path must be an absolute file path');
+  return errors;
+}
+
+export function validateHandoff(input) {
+  const errors = [], warnings = [];
+  try {
+    requireThat(['dispatch','return'].includes(input.stage), 'expected dispatch or return stage');
+    identity(input.session,input.task);
+    const context = resolveWorkContextSync(input);
+    const facts = readChangeFactsSync(context,input.change);
+    requireThat(facts.location.kind === 'active', 'archived handoffs are frozen; use the original archive integrity checks');
+    if (input.stage === 'dispatch') requireThat(facts.outcome === 'active', 'dispatch requires an active change');
+    const round = safeWorkPathSync(facts.location.root,`sessions/${input.session}`,{mustExist:true,type:'directory'});
+    const prefix = input.task.split('-')[0];
+    requireThat(readdirSync(round).filter(name => name.split('-')[0] === prefix).length === 1, 'task sequence is missing or occupied more than once');
+    const root = safeWorkPathSync(round,input.task,{mustExist:true,type:'directory'});
+    const {fields:meta,body} = parseFrontmatter(readFile(root,'TASK.md'));
+    requireThat(meta.schema_version === 1, 'TASK requires schema_version 1; retain legacy handoffs under their original contract');
+    requireThat(Object.keys(meta).every(key => ['schema_version','session','task','kind','change','ticket'].includes(key)), 'TASK: unknown metadata field');
+    requireThat(meta.session === input.session && meta.task === input.task, 'TASK identity mismatch');
+    requireThat(['implementation','review','research','test-observation'].includes(meta.kind), 'TASK: invalid kind');
+    if (meta.change !== undefined) requireThat(meta.change === input.change, 'TASK change mismatch');
+    if (meta.ticket !== undefined) requireThat(real(meta.ticket), 'TASK: invalid ticket');
+    headings(body,['Goal','Inputs','Workspace and Scope','Acceptance','Return']);
+    const report = safeWorkPathSync(root,'REPORT.md',{type:'file'});
+    if (input.stage === 'dispatch') requireThat(!existsSync(report), 'already delivered; create a new task instead of redispatch');
+    else {
+      const text = readFile(root,'REPORT.md'), lines = markdownBodyLines(text);
+      const headerEnd = lines.find(line => /^## /.test(line.text))?.line ?? Infinity;
+      const fields = {};
+      for (const line of lines.filter(line => line.line < headerEnd)) {
+        const match = /^(Session|Task|Status):\s*(.*?)\s*$/.exec(line.text);
+        if (!match) continue;
+        requireThat(!Object.hasOwn(fields,match[1]), `REPORT: duplicate ${match[1]}`); fields[match[1]]=match[2];
+      }
+      requireThat(fields.Session === input.session && fields.Task === input.task, 'REPORT identity mismatch');
+      requireThat(['completed','blocked','failed','cancelled'].includes(fields.Status), 'REPORT: invalid terminal status');
+      headings(text,['聚焦交接','产物与验证','问题与下一步']);
+    }
+    const path = safeWorkPathSync(root,'session-locator.json',{type:'file'});
+    if (existsSync(path)) errors.push(...validateSessionLocator(readJson(path)));
+  } catch (error) { errors.push(String(error.message ?? error)); }
+  return {errors,warnings,caveat:'Read-only structure checks do not authenticate tool identity, transcript content, authorization or completion; external histories are never opened.'};
+}
+
+export function handoffCLI(argv) {
+  const names = {'--repo':'projectRoot','--method-root':'methodRoot','--state-root':'stateRoot','--change':'change','--session':'session','--task':'task','--stage':'stage'}, input = {};
+  if (argv.length === 1 && argv[0] === '--help') {
+    console.log('Usage: node validate-handoff.mjs --repo <project> [--method-root <methods> --state-root <data-parent>] --change <id> --session <round> --task <id> --stage dispatch|return\nDirect use requires all three roots. Read-only; no log discovery or external transcript access.'); return 0;
+  }
+  try {
+    for (let i=0;i<argv.length;i++) {
+      const key = Object.hasOwn(names,argv[i]) ? names[argv[i]] : undefined, value = argv[++i];
+      requireThat(key && !Object.hasOwn(input,key) && value && !value.startsWith('--'), 'unknown, duplicate or incomplete option'); input[key] = value;
+    }
+    requireThat(['projectRoot','change','session','task','stage'].every(key => input[key]), 'missing required arguments');
+    requireThat(['dispatch','return'].includes(input.stage), 'invalid stage');
+  } catch (error) { console.error(String(error.message ?? error)); return 2; }
+  const result = validateHandoff(input); console.log(JSON.stringify(result,null,2)); return result.errors.length ? 1 : 0;
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = handoffCLI(process.argv.slice(2));

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

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+/** Read-only checks. Approval records document authority; they cannot grant it. */
+import { existsSync, lstatSync, readFileSync, readdirSync, readlinkSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  assertChangeName, markdownBodyLines, parseFrontmatter, readUtf8ArtifactSync,
+  resolveChangeSync, resolveWorkContextSync, safeWorkPathSync, validateSkill,
+} from '../../../../lib/speculo-runtime.mjs';
+import { checkSchema } from './delivery-artifacts.mjs';
+
+const schemaRoot = fileURLToPath(new URL('../schemas/', import.meta.url));
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+const fail = message => { throw new Error(message); };
+const requireThat = (condition, message) => { if (!condition) fail(message); };
+const portable = path => path.split(sep).join('/');
+const unique = (values, label) => requireThat(new Set(values).size === values.length, `${label}: duplicate entry`);
+const file = (root, path) => safeWorkPathSync(root, path, { mustExist: true, type: 'file' });
+const digestFile = path => hash(readFileSync(path));
+
+function schema(value, name) {
+  const errors = [];
+  checkSchema(value, JSON.parse(readFileSync(join(schemaRoot, `${name}.schema.json`), 'utf8')), name, errors);
+  requireThat(!errors.length, errors.join('\n'));
+  return value;
+}
+function json(root, path, name) {
+  return schema(JSON.parse(readUtf8ArtifactSync(file(root, path))), name);
+}
+function headings(body, names) {
+  const lines = markdownBodyLines(body, 'retro record');
+  for (const name of names) {
+    const found = lines.filter(line => line.text === `## ${name}`);
+    requireThat(found.length === 1, `expected one ${name} section`);
+    const end = lines.find(line => line.line > found[0].line && /^#{1,2} /.test(line.text))?.line;
+    requireThat(body.split(/\r?\n/).slice(found[0].line, end ? end - 1 : undefined).join('\n').trim(), `empty ${name} section`);
+  }
+}
+function object(context, id, kind) {
+  assertChangeName(id);
+  const active = safeWorkPathSync(context.specdevRoot, `retro/${id}`, { type: 'directory' });
+  const archived = safeWorkPathSync(context.specdevRoot, `retro/archive/${id}`, { type: 'directory' });
+  const present = [active, archived].filter(existsSync);
+  requireThat(present.length === 1, `${id}: missing or duplicate retro identity`);
+  const root = present[0], filename = kind === 'report' ? 'RETRO.md' : 'PLAN.md';
+  requireThat(!existsSync(join(root, kind === 'report' ? 'PLAN.md' : 'RETRO.md')), `${id}: conflicting object kinds`);
+  const path = file(root, filename), { fields: meta, body } = parseFrontmatter(readUtf8ArtifactSync(path));
+  schema(meta, kind === 'report' ? 'retrospective' : 'retro-upgrade');
+  requireThat(meta.id === id, `${id}: record identity mismatch`);
+  headings(body, kind === 'report' ? ['Scope', 'Evidence', 'Findings', 'Acceptance', 'Routes'] : ['Scope', 'Decisions', 'Changes', 'Validation', 'Archive']);
+  return { id, root, path, meta, body, archived: root === archived, sha256: digestFile(path) };
+}
+function snapshot(root, entry, prefix) {
+  requireThat(entry.snapshot.startsWith(`${prefix}/`), `${entry.snapshot}: snapshot must be under ${prefix}/`);
+  const path = file(root, entry.snapshot);
+  requireThat(digestFile(path) === entry.sha256, `${entry.snapshot}: snapshot digest drift`);
+  requireThat(readUtf8ArtifactSync(path).includes(entry.quote), `${entry.snapshot}: quote is not verbatim in snapshot`);
+}
+function report(context, id, warnings) {
+  const record = object(context, id, 'report'), { meta, root } = record;
+  unique(meta.sources.map(s => s.id), 'sources');
+  unique(meta.findings.map(f => f.id), 'findings');
+  requireThat(meta.sources.length || meta.outcome === 'insufficient-evidence', `${id}: evidence is required`);
+  requireThat((meta.outcome === 'findings') === (meta.findings.length > 0), `${id}: outcome/findings mismatch`);
+  const sourceIds = new Set(meta.sources.map(s => s.id));
+  for (const source of meta.sources) {
+    snapshot(root, source, 'sources');
+    const visibleQuote = record.body.replace(/^> ?/gm, '');
+    requireThat(visibleQuote.includes(source.quote) && record.body.includes(source.id), `${source.id}: body must display the original quote and source ID`);
+    if (source.change !== null) requireThat(record.body.includes(source.change), `${source.id}: body must identify its source change`);
+    requireThat(!/[\x00-\x1f]/.test(source.locator), `${source.id}: unsafe source locator`);
+    if (source.kind === 'change') {
+      requireThat(source.change !== null, `${source.id}: missing source change`);
+      // A snapshot preserves historical bytes; current originals may legitimately evolve.
+      const location = resolveChangeSync(context, source.change, { includeArchived: true });
+      const original = safeWorkPathSync(location.root, source.locator.split('#')[0], { type: 'file' });
+      if (!existsSync(original)) warnings.push(`${source.id}: original unavailable; only captured evidence was checked`);
+    } else if (source.kind === 'project') {
+      const original = safeWorkPathSync(context.projectRoot, source.locator.split('#')[0], { type: 'file' });
+      if (!existsSync(original)) warnings.push(`${source.id}: original unavailable; recheck current project facts before adoption`);
+    } else {
+      requireThat(source.locator.startsWith('session:'), `${source.id}: expected actual session locator`);
+      warnings.push(`${source.id}: session provenance requires observation; snapshot integrity alone is not proof`);
+    }
+    if (source.change !== null) assertChangeName(source.change);
+  }
+  for (const finding of meta.findings) {
+    requireThat(finding.evidence.every(id => sourceIds.has(id)), `${finding.id}: unknown evidence`);
+    headings(record.body, [finding.id]);
+  }
+  return record;
+}
+function builderPaths(value) {
+  requireThat(value?.schema_version === 1 && value.generator === 'engineering-standards-builder' && Array.isArray(value.skills), 'invalid Builder ownership manifest');
+  requireThat(Object.keys(value).every(k => ['schema_version', 'generator', 'skills'].includes(k)), 'unknown Builder ownership fields');
+  unique(value.skills.map(s => s.path), 'Builder paths');
+  requireThat(value.skills.filter(s => s.role === 'router').length === 1 && value.skills.some(s => s.role === 'router' && s.name === 'engineering-standards'), 'invalid Builder router');
+  for (const skill of value.skills) requireThat(Object.keys(skill).every(k => ['name', 'path', 'role'].includes(k)) && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(skill.name) && skill.path === `.agents/skills/${skill.name}` && ['router', 'domain'].includes(skill.role), 'invalid Builder owned path');
+  return new Set(value.skills.map(s => s.path));
+}
+function owners(context, record) {
+  const projected = new Set();
+  const projection = safeWorkPathSync(context.stateRoot, 'projections.json', { type: 'file' });
+  if (existsSync(projection)) {
+    const value = JSON.parse(readUtf8ArtifactSync(projection));
+    const businessId = /^[a-z0-9]+(?:-[a-z0-9]+)*\/[a-z0-9]+(?:-[a-z0-9]+)*$/;
+    requireThat(value?.schema_version === 3 && typeof value.package_version === 'string' && Array.isArray(value.files) && Array.isArray(value.targets) && value.targets.every(h => ['agents', 'claude'].includes(h)) && Array.isArray(value.asset_ids) && value.asset_ids.every(id => typeof id === 'string' && businessId.test(id)) && (value.targets.length || !value.asset_ids.length), 'invalid Speculo projection manifest');
+    unique(value.targets, 'projection hosts'); unique(value.asset_ids, 'projection assets');
+    unique(value.files.map(f => f?.path), 'projection paths');
+    for (const entry of value.files) {
+      requireThat(entry && typeof entry.path === 'string' && /^\.(?:agents|claude)\/skills\/[a-z0-9-]+\/(?:SKILL\.md|agents\/openai\.yaml)$/.test(entry.path) && typeof entry.asset_id === 'string' && businessId.test(entry.asset_id) && typeof entry.sha256 === 'string' && /^[a-f0-9]{64}$/.test(entry.sha256), 'invalid projection record');
+      projected.add(entry.path.split('/').slice(0, 3).join('/'));
+    }
+  }
+  const manifest = '.agents/skills/engineering-standards/generated-skill-set.json';
+  const original = safeWorkPathSync(context.projectRoot, manifest, { type: 'file' });
+  const before = existsSync(original) ? builderPaths(JSON.parse(readUtf8ArtifactSync(original))) : new Set();
+  const candidate = record.meta.changes.find(c => c.path === manifest);
+  const after = candidate ? builderPaths(JSON.parse(readUtf8ArtifactSync(file(record.root, candidate.candidate)))) : before;
+  for (const path of before) requireThat(after.has(path), 'Skill deletion/renaming needs a separate explicit maintenance plan');
+  return { projected, before, after };
+}
+function candidateLinks(context, record, change, candidates) {
+  if (!change.path.endsWith('.md')) return;
+  const text = readUtf8ArtifactSync(file(record.root, change.candidate));
+  for (const match of text.matchAll(/\]\(([^\s)]+)(?:\s+"[^"]*")?\)/g)) {
+    const link = match[1].replace(/^<|>$/g, '');
+    if (/^(?:[a-z][a-z0-9+.-]*:|#)/i.test(link)) continue;
+    const part = decodeURIComponent(link.split('#')[0]);
+    requireThat(part && !part.startsWith('/') && !part.includes('\\'), `${change.path}: invalid local link ${link}`);
+    const target = portable(relative(context.projectRoot, resolve(context.projectRoot, dirname(change.path), part)));
+    safeWorkPathSync(context.projectRoot, target);
+    requireThat(candidates.has(target) || existsSync(safeWorkPathSync(context.projectRoot, target)), `${change.path}: broken local link ${link}`);
+  }
+}
+function readExecution(record, targets) {
+  const receipt = json(record.root, 'execution.json', 'retro-execution');
+  requireThat(receipt.plan_sha256 === record.sha256 && receipt.approval_sha256 === record.approvalHash, 'execution is not bound to approved plan');
+  unique(receipt.results.map(r => r.path), 'execution targets');
+  requireThat(receipt.results.every(r => targets.has(r.path)), 'execution target set mismatch');
+  return receipt;
+}
+function passedResult(record, result, change) {
+  requireThat(result?.result === 'passed' && result.sha256 === change.after_sha256, `${change.path}: unverified upgrade`);
+  requireThat(result.evidence.startsWith('evidence/'), `${change.path}: evidence must be under evidence/`);
+  requireThat(digestFile(file(record.root, result.evidence)) === result.evidence_sha256, `${change.path}: verification evidence drift`);
+  requireThat(result.command === null ? result.exit === null : result.exit === 0, `${change.path}: verification command failed`);
+}
+function upgrade(context, id, warnings, { live = true, execution = false, approved = false } = {}) {
+  const record = object(context, id, 'upgrade'), { meta, root } = record;
+  unique(meta.inputs.map(i => i.report), 'input reports');
+  unique(meta.changes.map(c => c.path), 'change targets');
+  unique(meta.decisions.map(d => `${d.report}/${d.finding}`), 'decisions');
+  const reports = new Map();
+  for (const input of meta.inputs) {
+    const source = report(context, input.report, warnings);
+    requireThat(source.meta.status === 'completed', `${input.report}: incomplete report`);
+    requireThat(source.sha256 === input.sha256, `${input.report}: input report digest drift`);
+    requireThat(execution || approved || !source.archived, `${input.report}: new plans use unarchived reports`);
+    reports.set(input.report, source);
+  }
+  const targets = new Set(meta.changes.map(c => c.path));
+  for (const decision of meta.decisions) {
+    requireThat(reports.get(decision.report)?.meta.findings.some(f => f.id === decision.finding), `${decision.report}/${decision.finding}: unknown finding`);
+    requireThat(decision.disposition === 'adopt' ? decision.targets.length > 0 && decision.targets.every(p => targets.has(p)) : decision.targets.length === 0, `${decision.finding}: invalid disposition targets`);
+  }
+  for (const source of reports.values()) for (const finding of source.meta.findings) {
+    requireThat(meta.decisions.some(d => d.report === source.id && d.finding === finding.id), `${source.id}/${finding.id}: missing disposition`);
+  }
+  for (const id of meta.archive_reports) {
+    requireThat(reports.has(id), `${id}: archive report not in frozen inputs`);
+    requireThat(!meta.decisions.some(d => d.report === id && d.disposition === 'defer'), `${id}: deferred findings cannot be archived`);
+  }
+  if (approved || execution) {
+    const approval = json(root, 'approval.json', 'retro-approval');
+    snapshot(root, approval, 'approval');
+    requireThat(approval.plan_sha256 === record.sha256, 'approved plan digest drift');
+    record.approval = approval;
+    record.approvalHash = digestFile(file(root, 'approval.json'));
+  }
+  const previous = approved && existsSync(join(root, 'execution.json')) ? readExecution(record, targets) : null;
+  const ownership = live ? owners(context, record) : null;
+  const candidates = new Map(meta.changes.map(c => [c.path, c]));
+  for (const change of meta.changes) {
+    requireThat(meta.decisions.some(d => d.disposition === 'adopt' && d.targets.includes(change.path)), `${change.path}: target has no adopted finding`);
+    requireThat(/^\.agents\/skills\/[a-z0-9]+(?:-[a-z0-9]+)*\/.+/.test(change.path), `${change.path}: target must be a project Skill file`);
+    const target = live ? safeWorkPathSync(context.projectRoot, change.path, { type: 'file' }) : null;
+    requireThat(change.candidate.startsWith('candidates/'), `${change.path}: candidate must be under candidates/`);
+    const candidate = file(root, change.candidate);
+    requireThat(digestFile(candidate) === change.after_sha256, `${change.path}: candidate digest drift`);
+    requireThat((change.action === 'create') === (change.before_sha256 === null), `${change.path}: create/before mismatch`);
+    if (change.action === 'retain') requireThat(change.before_sha256 === change.after_sha256, `${change.path}: retain must not change bytes`);
+    if (change.action === 'update') requireThat(change.before_sha256 !== change.after_sha256, `${change.path}: unchanged target should be retain`);
+    if (live) {
+      const skill = change.path.split('/').slice(0, 3).join('/');
+      requireThat(!ownership.projected.has(skill), `${skill}: managed Speculo projection; edit its source through its owner`);
+      const owned = ownership.before.has(skill) || ownership.after.has(skill);
+      requireThat(owned === (change.owner === 'engineering-standards-builder'), `${skill}: ownership mismatch`);
+      const current = existsSync(target) ? digestFile(target) : null;
+      if (approved && current === change.after_sha256 && current !== change.before_sha256) {
+        requireThat(previous, `${change.path}: landed target requires original execution evidence before resuming`);
+        passedResult(record, previous.results.find(r => r.path === change.path), change);
+      } else requireThat(current === (execution ? change.after_sha256 : change.before_sha256), `${change.path}: target digest drift`);
+      candidateLinks(context, record, change, candidates);
+    }
+    if (basename(change.path) === 'SKILL.md') {
+      // Existing host-specific extensions remain owned by the project; never strip them to pass a check.
+      const prior = live && existsSync(target) ? parseFrontmatter(readFileSync(target)).fields : {};
+      const fields = parseFrontmatter(readFileSync(candidate)).fields;
+      const errors = validateSkill(readFileSync(candidate), dirname(change.path)).filter(error => {
+        if (!error.startsWith('unsupported top-level field: ')) return true;
+        const key = error.slice('unsupported top-level field: '.length);
+        return live && JSON.stringify(prior[key]) !== JSON.stringify(fields[key]);
+      });
+      requireThat(!errors.length, `${change.path}: ${errors.join('; ')}`);
+    }
+    const skillRoot = change.path.split('/').slice(0, 3).join('/');
+    if (live) requireThat(candidates.has(`${skillRoot}/SKILL.md`) || existsSync(safeWorkPathSync(context.projectRoot, `${skillRoot}/SKILL.md`, { type: 'file' })), `${skillRoot}: missing Skill entry`);
+  }
+  if (execution) {
+    const receipt = readExecution(record, targets);
+    requireThat(receipt.status === 'verified', 'upgrade execution is not verified');
+    requireThat(receipt.results.length === targets.size, 'execution target set mismatch');
+    for (const result of receipt.results) {
+      passedResult(record, result, candidates.get(result.path));
+    }
+    record.execution = receipt;
+  }
+  return record;
+}
+
+/** Snapshot without following symlinks. The sole mutable move receipt is excluded. */
+export function retroInventory(root) {
+  const entries = [];
+  function walk(directory, prefix = '') {
+    for (const name of readdirSync(directory).sort()) {
+      const path = prefix ? `${prefix}/${name}` : name;
+      if (path === 'archive.json') continue;
+      const full = join(directory, name), stat = lstatSync(full), entry = { path, mode: stat.mode & 0o7777 };
+      if (stat.isSymbolicLink()) entries.push({ ...entry, type: 'symlink', target: readlinkSync(full) });
+      else if (stat.isDirectory()) { entries.push({ ...entry, type: 'directory' }); walk(full, path); }
+      else { requireThat(stat.isFile(), `${path}: unsupported archive entry`); entries.push({ ...entry, type: 'file', sha256: digestFile(full) }); }
+    }
+  }
+  walk(root);
+  return entries;
+}
+function archive(context, record, plan, sealed) {
+  requireThat(record.archived, `${record.id}: not in retro/archive`);
+  const receipt = json(record.root, 'archive.json', 'retro-archive');
+  requireThat(receipt.id === record.id && receipt.owner === record.meta.owner && receipt.upgrade === plan.id, 'archive identity/owner mismatch');
+  requireThat(receipt.source === `retro/${record.id}` && receipt.target === `retro/archive/${record.id}`, 'archive source/target mismatch');
+  requireThat(receipt.plan_sha256 === plan.sha256 && receipt.approval_sha256 === plan.approvalHash, 'archive approval mismatch');
+  if (sealed) requireThat(receipt.result === 'verified', 'archive has not been sealed');
+  unique(receipt.entries.map(e => e.path), 'archive inventory');
+  const actual = new Map(retroInventory(record.root).map(e => [e.path, e]));
+  requireThat(actual.size === receipt.entries.length, 'archive inventory coverage mismatch');
+  for (const entry of receipt.entries) {
+    const observed = actual.get(entry.path);
+    requireThat(observed && entry.type === observed.type && entry.mode === observed.mode && entry.sha256 === observed.sha256 && entry.target === observed.target, `${entry.path}: archive integrity drift`);
+  }
+}
+export function listRetroReports(input) {
+  const context = resolveWorkContextSync(input), root = safeWorkPathSync(context.specdevRoot, 'retro', { type: 'directory' });
+  const result = { reports: [], issues: [] };
+  if (!existsSync(root)) return result;
+  for (const name of readdirSync(root).filter(name => name !== 'archive').sort()) {
+    try {
+      const path = safeWorkPathSync(root, name, { mustExist: true, type: 'directory' });
+      if (!existsSync(join(path, 'RETRO.md'))) continue;
+      object(context, name, 'report');
+      result.reports.push(name);
+    } catch (error) { result.issues.push({ id: name, error: String(error.message ?? error) }); }
+  }
+  return result;
+}
+export function validateRetro(input) {
+  const errors = [], warnings = [];
+  try {
+    const context = resolveWorkContextSync(input), stage = input.stage ?? 'record';
+    requireThat(['report', 'upgrade'].includes(input.kind), 'expected report or upgrade kind');
+    requireThat(['record', 'apply', 'verified', 'archive-ready', 'archived'].includes(stage), 'invalid retro stage');
+    requireThat(!input.sealed || stage === 'archived', '--sealed requires archived stage');
+    requireThat(input.kind === 'upgrade' || !['apply', 'verified'].includes(stage), 'apply/verified stages require upgrade');
+    const historical = stage === 'archived';
+    const record = input.kind === 'report' ? report(context, input.id, warnings) : upgrade(context, input.id, warnings, { live: !historical, approved: stage === 'apply', execution: ['verified', 'archive-ready', 'archived'].includes(stage) });
+    requireThat(historical === record.archived, historical ? 'object has not moved' : 'archived objects are read-only; use archived validation');
+    if (stage === 'archive-ready' || historical) {
+      const plan = input.kind === 'upgrade' ? record : upgrade(context, input.upgrade, warnings, { live: !historical, execution: true });
+      if (input.kind === 'report') requireThat(plan.meta.archive_reports.includes(input.id), `${input.id}: not approved for archive`);
+      if (input.kind === 'upgrade') for (const id of plan.meta.archive_reports) {
+        const source = report(context, id, warnings);
+        requireThat(source.archived, `${id}: report must be sealed before archiving its upgrade`);
+        archive(context, source, plan, true);
+      }
+      if (historical) archive(context, record, plan, Boolean(input.sealed));
+    }
+  } catch (error) { errors.push(String(error.message ?? error)); }
+  return { errors, warnings: [...new Set(warnings)], caveat: 'Read-only integrity checks do not authenticate approval, provenance, semantic quality or host invocation.' };
+}
+export function retroCLI(argv) {
+  const options = {}, names = { '--repo': 'projectRoot', '--method-root': 'methodRoot', '--state-root': 'stateRoot', '--stage': 'stage', '--upgrade-plan': 'upgrade' };
+  if (argv.includes('--help')) {
+    console.log('Usage: node validate-retro.mjs (--list | --report <id> | --upgrade <id>) --repo <project> [--method-root <methods> --state-root <data-parent>] [--stage record|apply|verified|archive-ready|archived] [--upgrade-plan <id>] [--sealed]\nDefault record checks are read-only. Direct use requires all three roots. Example: --report 2026-10-15-ci --repo . --method-root ./template --state-root ./data');
+    return 0;
+  }
+  try {
+    let mode;
+    for (let i = 0; i < argv.length; i++) {
+      const arg = argv[i];
+      if (['--list', '--report', '--upgrade'].includes(arg)) {
+        requireThat(!mode, 'choose exactly one mode'); mode = arg;
+        if (arg !== '--list') { options.kind = arg.slice(2); options.id = argv[++i]; requireThat(options.id && !options.id.startsWith('--'), 'missing object ID'); }
+      } else if (arg === '--sealed') { requireThat(!options.sealed, 'duplicate --sealed'); options.sealed = true; }
+      else {
+        const key = names[arg]; requireThat(key && !(key in options), `invalid or duplicate option: ${arg}`);
+        const value = argv[++i]; requireThat(value && !value.startsWith('--'), `missing value: ${arg}`); options[key] = value;
+      }
+    }
+    requireThat(mode, 'choose --list, --report or --upgrade');
+    if (mode === '--list') {
+      requireThat(!options.stage && !options.upgrade && !options.sealed, 'list does not accept validation stage options');
+      const result = listRetroReports(options);
+      console.log(JSON.stringify(result, null, 2)); return result.issues.length ? 1 : 0;
+    }
+    requireThat(!options.upgrade || options.kind === 'report' && ['archive-ready', 'archived'].includes(options.stage), '--upgrade-plan is for report archive validation');
+    const result = validateRetro(options); console.log(JSON.stringify(result, null, 2)); return result.errors.length ? 1 : 0;
+  } catch (error) { console.error(String(error.message ?? error)); return 2; }
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = retroCLI(process.argv.slice(2));