musubix3 0.1.19 → 0.1.21

package/dist/packages/cli/src/main.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import { Command, CommanderError, InvalidArgumentError } from 'commander';
+import { realpathSync } from 'node:fs';
 import { basename, relative, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { c4Diagram, validateConstitution, validateDesign, validateRequirements, } from '../../domain/src/index.js';
-import { buildKnowledge, buildTrace, changedFiles, checkTrace, configLint, cycles, exists, files, formalCheck, graphGate, graphImpact, indexGraph, loadConfig, loadGraph, loadTrace, portable, projectStatus, queryKnowledge, formalDoctor, generateFormalArtifacts, readText, runGate, traceImpact, changePhases, recordChangePhase, recordWorkflow, runTddPhase, sanitizeWorkflowLogFile, validateTddEvidence, verifyWorkflowLogFile, migrateTddFingerprint, voidTddCycle, attestationSigningPayload, createUnsignedAttestation, githubOidcAudience, verifyEvidenceAttestation, mutationDoctor, mutationIdentity, validateMutationEvidence, validateModelCorrespondenceEvidence, within, approvalManifest, approvalStages, recordApproval, requireApproval, requireDomainOption, requireValidateDomainOption, resolveDesignFileDomain, resolveNamedDomain, validateApprovals, validateApprovalsForDomain, scaffoldCommands, scaffoldRequirements, scaffoldDesign, recordChangeWaiver, recordWorkflowWaiver, recordAllWorkflowWaivers, } from '../../analysis/src/index.js';
+import { buildKnowledge, buildTrace, changedFiles, checkTrace, configLint, cycles, exists, files, formalCheck, graphGate, graphImpact, indexGraph, loadConfig, loadGraph, loadTrace, portable, projectStatus, queryKnowledge, formalDoctor, generateFormalArtifacts, readText, runGate, traceImpact, changePhases, recordChangePhase, recordWorkflow, runTddPhase, sanitizeWorkflowLogFile, validateTddEvidence, verifyWorkflowLogFile, migrateTddFingerprint, migrateTddIdentifier, voidTddCycle, archiveTddCycle, mergeEvidenceHistories, recoverEvidenceMerge, recoverQualityRefresh, attestationSigningPayload, createUnsignedAttestation, githubOidcAudience, verifyEvidenceAttestation, mutationDoctor, mutationIdentity, validateMutationEvidence, validateModelCorrespondenceEvidence, within, approvalManifest, approvalStages, diffOnlyChangedFiles, loadApproval, recordApproval, requireApproval, requireDomainOption, requireValidateDomainOption, resolveDesignFileDomain, resolveNamedDomain, validateApprovals, validateApprovalsForDomain, scaffoldCommands, scaffoldRequirements, scaffoldDesign, recordChangeWaiver, recordWorkflowWaiver, recordAllWorkflowWaivers, assertCoordinatedEvidenceRead, EvidenceProtectedOutputError, EvidenceWriterLockError, recoverEvidenceWriterLock, withEvidenceWriterLock, } from '../../analysis/src/index.js';
 import { install, pluginInstall, upgradeSkills } from './install.js';
 const packageRoot = fileURLToPath(new URL('../../../../', import.meta.url));
 function output(value, json, summary) {
@@ -23,8 +24,12 @@ function common(command) {
 function pathQuery(root, query) {
     return portable(relative(root, resolve(root, query)));
 }
+async function coordinatedReader(root, operation) {
+    await assertCoordinatedEvidenceRead(root);
+    return operation();
+}
 export function createProgram() {
-    const program = new Command().name('musubix3').description('Evidence-driven SDD for GitHub Copilot CLI / 根拠に基づく仕様駆動開発').version('0.1.19');
+    const program = new Command().name('musubix3').description('Evidence-driven SDD for GitHub Copilot CLI / 根拠に基づく仕様駆動開発').version('0.1.21');
     program.exitOverride();
     common(program.command('init').alias('install').description('Install repository skills and SDD artifacts (preserves existing files)'))
         .option('--dry-run', 'Preview without writing').option('--force', 'Replace bundled, managed paths only')
@@ -85,27 +90,31 @@ export function createProgram() {
     }
     common(design.command('validate <file>')).action(async (file, options) => {
         const root = resolve(options.root);
-        if (await exists(within(root, '.musubix/config.json'))) {
-            const config = await loadConfig(root);
-            const domain = await resolveDesignFileDomain(root, config.approval, portable(relative(root, resolve(root, file))));
-            await requireApproval(root, 'requirements', config.approval, domain);
-        }
-        result(await designResult(file, root), !!options.json);
+        await coordinatedReader(root, async () => {
+            if (await exists(within(root, '.musubix/config.json'))) {
+                const config = await loadConfig(root);
+                const domain = await resolveDesignFileDomain(root, config.approval, portable(relative(root, resolve(root, file))));
+                await requireApproval(root, 'requirements', config.approval, domain);
+            }
+            result(await designResult(file, root), !!options.json);
+        });
     });
     common(design.command('c4 <file>')).action(async (file, options) => {
         const root = resolve(options.root);
-        if (await exists(within(root, '.musubix/config.json'))) {
-            const config = await loadConfig(root);
-            const domain = await resolveDesignFileDomain(root, config.approval, portable(relative(root, resolve(root, file))));
-            await requireApproval(root, 'requirements', config.approval, domain);
-        }
-        const report = await designResult(file, root);
-        if (!report.valid) {
-            result(report, !!options.json);
-            return;
-        }
-        const diagram = c4Diagram(report.value);
-        output({ diagram }, !!options.json, diagram);
+        await coordinatedReader(root, async () => {
+            if (await exists(within(root, '.musubix/config.json'))) {
+                const config = await loadConfig(root);
+                const domain = await resolveDesignFileDomain(root, config.approval, portable(relative(root, resolve(root, file))));
+                await requireApproval(root, 'requirements', config.approval, domain);
+            }
+            const report = await designResult(file, root);
+            if (!report.valid) {
+                result(report, !!options.json);
+                return;
+            }
+            const diagram = c4Diagram(report.value);
+            output({ diagram }, !!options.json, diagram);
+        });
     });
     common(design.command('scaffold <slug>')).action(async (slug, options) => {
         const path = await scaffoldDesign(resolve(options.root), slug);
@@ -121,10 +130,12 @@ export function createProgram() {
     common(trace.command('check')).option('--strict', 'Fail missing mandatory coverage')
         .action(async (options) => {
         const root = resolve(options.root);
+        await assertCoordinatedEvidenceRead(root);
         result(await checkTrace(root, await loadTrace(root), !!options.strict), !!options.json);
     });
     common(trace.command('impact <id-or-path>')).action(async (query, options) => {
         const root = resolve(options.root);
+        await assertCoordinatedEvidenceRead(root);
         const graph = await loadTrace(root);
         const freshness = await checkTrace(root, graph);
         const stale = freshness.diagnostics.some((d) => d.code.startsWith('TRACE_STALE'));
@@ -144,28 +155,35 @@ export function createProgram() {
     common(graph.command('index')).option('--changed', 'Report changed files; conservatively refresh full graph')
         .action(async (options) => {
         const root = resolve(options.root);
-        const changed = options.changed ? await changedFiles(root) : null;
-        const indexed = await indexGraph(root);
-        output({ ...indexed, changed }, !!options.json, `Graph: ${indexed.files.length} files, ${indexed.imports.length} imports, ${indexed.symbols.length} symbols.`);
-        if (indexed.diagnostics.some((d) => d.severity === 'error'))
-            process.exitCode = 1;
+        await withEvidenceWriterLock(root, 'graph index', async () => {
+            const changed = options.changed ? await changedFiles(root) : null;
+            const indexed = await indexGraph(root);
+            output({ ...indexed, changed }, !!options.json, `Graph: ${indexed.files.length} files, ${indexed.imports.length} imports, ${indexed.symbols.length} symbols.`);
+            if (indexed.diagnostics.some((d) => d.severity === 'error'))
+                process.exitCode = 1;
+        });
     });
     common(graph.command('impact <symbol-or-path>')).action(async (query, options) => {
         const root = resolve(options.root);
+        await assertCoordinatedEvidenceRead(root);
         const indexed = await loadGraph(root);
         const normalized = indexed.files.includes(pathQuery(root, query)) ? pathQuery(root, query) : query;
         output(graphImpact(indexed, normalized), !!options.json);
     });
     common(graph.command('cycles')).action(async (options) => {
-        const found = cycles(await loadGraph(resolve(options.root)));
+        const root = resolve(options.root);
+        await assertCoordinatedEvidenceRead(root);
+        const found = cycles(await loadGraph(root));
         output({ cycles: found }, !!options.json);
         if (found.length)
             process.exitCode = 1;
     });
     common(graph.command('gate')).action(async (options) => {
         const root = resolve(options.root);
-        const config = await loadConfig(root);
-        result(graphGate(await indexGraph(root), config.architecture, config.codeGraph), !!options.json);
+        await withEvidenceWriterLock(root, 'graph gate', async () => {
+            const config = await loadConfig(root);
+            result(graphGate(await indexGraph(root), config.architecture, config.codeGraph), !!options.json);
+        });
     });
     const knowledge = program.command('knowledge').description('Local artifact and Git evidence retrieval (TF-IDF, not GraphRAG)');
     common(knowledge.command('build')).action(async (options) => {
@@ -177,7 +195,9 @@ export function createProgram() {
         const limit = Number(options.limit);
         if (!Number.isInteger(limit) || limit < 1 || limit > 100)
             throw new Error('--limit must be 1..100.');
-        output(await queryKnowledge(resolve(options.root), query.join(' '), limit), !!options.json);
+        const root = resolve(options.root);
+        await assertCoordinatedEvidenceRead(root);
+        output(await queryKnowledge(root, query.join(' '), limit), !!options.json);
     });
     const formal = program.command('formal').description('Honest consistency checking of an explicit abstraction');
     common(formal.command('check <file>'))
@@ -192,12 +212,12 @@ export function createProgram() {
         if (!Number.isInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 300_000)
             throw new Error('--timeout must be 100..300000 milliseconds.');
         const root = resolve(options.root);
-        const report = await formalCheck(await readText(root, file), root, {
+        const report = await withEvidenceWriterLock(root, 'formal check', async () => formalCheck(await readText(root, file), root, {
             solver: options.solver,
             timeoutMs,
             ...(options.z3Command ? { z3Command: options.z3Command } : {}),
             ...(options.leanCommand ? { leanCommand: options.leanCommand } : {}),
-        });
+        }));
         output(report, !!options.json);
         if (!report.valid)
             process.exitCode = 1;
@@ -209,7 +229,7 @@ export function createProgram() {
             throw new Error('Unknown format; use both, smt2, or lean.');
         const root = resolve(options.root);
         const formats = options.format === 'both' ? ['smt2', 'lean'] : [options.format];
-        const report = await generateFormalArtifacts(await readText(root, file), root, [...formats]);
+        const report = await withEvidenceWriterLock(root, 'formal generate', async () => generateFormalArtifacts(await readText(root, file), root, [...formats]));
         output(report, !!options.json, report.artifacts.map((entry) => `${entry.format}: ${entry.path}`).join('\n'));
         if (!report.valid)
             process.exitCode = 1;
@@ -258,6 +278,61 @@ export function createProgram() {
     common(evidence.command('refresh'))
         .option('--changed', 'Preserve changed-file impact context while refreshing all checks')
         .action(executeGate);
+    common(evidence.command('unlock')
+        .description('Inspect and recover an abandoned project evidence-writer lock')
+        .requiredOption('--recover', 'Recover only a demonstrably dead same-host owner')
+        .addHelpText('after', `
+Recovery never steals a live, remote, malformed, PID-reused, or indeterminate
+lock. Inspect the reported owner and exact lock path before any targeted manual
+removal. If a merge journal is also pending, recover this writer lock first,
+then run evidence merge --recover.
+
+Windows directory synchronization may be unavailable after atomic publication
+or verified release. Automatic recovery remains inspection-only on Windows and
+macOS.`))
+        .action(async (options) => {
+        if (!options.recover)
+            throw new Error('--recover is required.');
+        const report = await recoverEvidenceWriterLock(resolve(options.root));
+        output(report, !!options.json, report.action);
+    });
+    common(evidence.command('merge')
+        .description('Deterministically merge another valid append-only evidence history into the current root')
+        .option('--incoming <directory>', 'Project directory containing the incoming .musubix/evidence history')
+        .option('--dry-run', 'Validate and preview the merge without writing evidence')
+        .option('--recover', 'Recover an interrupted merge without requiring --incoming')
+        .addHelpText('after', `
+Both roots must contain individually valid order, TDD, and change evidence. The
+incoming root must be path-disjoint and is never modified. Merge uses canonical
+duplicate comparison and stable base-first ordering; recordedAt warnings may
+remain. The current worktree must already contain incoming change documents.
+Merge only handles order.json, tdd.json, changes.json, and change-waivers.json.
+Run gate/status afterward and explicitly re-approve stale waivers. If base
+Quality precedes incoming batch evidence, merge before recording Quality.
+Use --recover for interrupted transactions; unsafe recovery requires backing up
+the evidence directory, restoring/verifying all four targets from a trusted
+source, quarantining merge files, and rerunning structural validation.`))
+        .action(async (options) => {
+        const root = resolve(options.root);
+        if (options.recover) {
+            if (options.incoming || options.dryRun)
+                throw new Error('--recover cannot be combined with --incoming or --dry-run.');
+            const report = await recoverEvidenceMerge(root);
+            output(report, !!options.json, report.action);
+            return;
+        }
+        if (!options.incoming)
+            throw new Error('--incoming <directory> is required unless --recover is used.');
+        const report = await mergeEvidenceHistories(root, resolve(options.incoming), { ...(options.dryRun ? { dryRun: true } : {}) });
+        output(report, !!options.json, `${report.valid ? (options.dryRun ? 'DRY-RUN' : 'MERGED') : 'FAILED'}`
+            + ` preserved=${report.preserved} deduplicated=${report.deduplicated} appended=${report.appended}`
+            + `${report.diagnostics.length ? `\n${report.diagnostics.map((item) => `${item.code}${item.file ? ` ${item.file}` : ''}${item.identity ? ` ${item.identity}` : ''}: ${item.message}`).join('\n')}` : ''}`
+            + `${report.followUpDiagnostics.length ? `\n${report.followUpDiagnostics.map((item) => `${item.code}${item.path ? ` ${item.path}` : ''}: ${item.message}`).join('\n')}` : ''}`
+            + `${report.supersededScopes.length ? `\nWaiver supersession changed for ${report.supersededScopes.length} scope(s).` : ''}`
+            + `${report.revalidationRequired ? '\nEVIDENCE_MERGE_REVALIDATION_REQUIRED: rerun gate and status; re-approve stale waivers.' : ''}`);
+        if (!report.valid)
+            process.exitCode = 1;
+    });
     const mutation = program.command('mutation').description('Inspect and validate requirement-scoped mutation evidence');
     common(mutation.command('doctor')).action(async (options) => {
         const report = await mutationDoctor(resolve(options.root));
@@ -268,7 +343,9 @@ export function createProgram() {
             : 'No supported project ecosystem was detected.');
     });
     common(mutation.command('validate')).action(async (options) => {
-        const report = await validateMutationEvidence(resolve(options.root));
+        const root = resolve(options.root);
+        await assertCoordinatedEvidenceRead(root);
+        const report = await validateMutationEvidence(root);
         if (!options.json && !report.present) {
             console.log('No mutation evidence at .musubix/evidence/mutation.json; the gate converts a configured mutationReport into that file. Compatible mode does not require it.');
         }
@@ -289,7 +366,9 @@ export function createProgram() {
     common(correspondence.command('validate')
         /* @id CODE-MODEL-CORRESPONDENCE-EVIDENCE-GUIDANCE-002 */
         .description('Validate model correspondence evidence (run `npx musubix3 evidence refresh` first to generate .musubix/evidence/model-correspondence.json)')).action(async (options) => {
-        const report = await validateModelCorrespondenceEvidence(resolve(options.root));
+        const root = resolve(options.root);
+        await assertCoordinatedEvidenceRead(root);
+        const report = await validateModelCorrespondenceEvidence(root);
         result(report, !!options.json);
     });
     common(program.command('workflow-record <skill> <phase>').description('Record a self-reported workflow declaration'))
@@ -313,28 +392,30 @@ export function createProgram() {
         .option('--session-id <uuid>', 'Require the terminal result to identify this Copilot session')
         .action(async (logs, options) => {
         const root = resolve(options.root);
-        const paths = logs.map((log) => resolve(log));
-        for (const path of paths) {
-            const info = await stat(path);
-            if (!info.isFile())
-                throw new Error('Workflow log must be a file.');
-        }
-        const configured = (await loadConfig(root)).workflow;
-        const mode = options.strict || options.sessionId ? 'strict' : configured.mode;
-        const expectedSessionId = options.sessionId ?? configured.expectedSessionId;
-        const manifest = await verifyWorkflowLogFile(root, paths.length === 1 ? paths[0] : paths, {
-            mode,
-            ...(expectedSessionId ? { expectedSessionId } : {}),
-            ...(configured.maxAgeSeconds === undefined ? {} : { maxAgeSeconds: configured.maxAgeSeconds }),
-            ...(configured.maxFutureSkewSeconds === undefined
-                ? {}
-                : { maxFutureSkewSeconds: configured.maxFutureSkewSeconds }),
-            ...(configured.maxEventSkewMs === undefined ? {} : { maxEventSkewMs: configured.maxEventSkewMs }),
-            ...(configured.maxTranscriptBytes === undefined ? {} : { maxBytes: configured.maxTranscriptBytes }),
-            ...(configured.maxTranscriptLineBytes === undefined ? {} : { maxLineBytes: configured.maxTranscriptLineBytes }),
+        await withEvidenceWriterLock(root, 'workflow-verify', async () => {
+            const paths = logs.map((log) => resolve(log));
+            for (const path of paths) {
+                const info = await stat(path);
+                if (!info.isFile())
+                    throw new Error('Workflow log must be a file.');
+            }
+            const configured = (await loadConfig(root)).workflow;
+            const mode = options.strict || options.sessionId ? 'strict' : configured.mode;
+            const expectedSessionId = options.sessionId ?? configured.expectedSessionId;
+            const manifest = await verifyWorkflowLogFile(root, paths.length === 1 ? paths[0] : paths, {
+                mode,
+                ...(expectedSessionId ? { expectedSessionId } : {}),
+                ...(configured.maxAgeSeconds === undefined ? {} : { maxAgeSeconds: configured.maxAgeSeconds }),
+                ...(configured.maxFutureSkewSeconds === undefined
+                    ? {}
+                    : { maxFutureSkewSeconds: configured.maxFutureSkewSeconds }),
+                ...(configured.maxEventSkewMs === undefined ? {} : { maxEventSkewMs: configured.maxEventSkewMs }),
+                ...(configured.maxTranscriptBytes === undefined ? {} : { maxBytes: configured.maxTranscriptBytes }),
+                ...(configured.maxTranscriptLineBytes === undefined ? {} : { maxLineBytes: configured.maxTranscriptLineBytes }),
+            });
+            output(manifest, !!options.json, `Verified ${manifest.verification?.invocations.length ?? 0} Copilot Skill invocation event(s)`
+                + `${manifest.verification?.sessionId ? ` in session ${manifest.verification.sessionId}` : ''}.`);
         });
-        output(manifest, !!options.json, `Verified ${manifest.verification?.invocations.length ?? 0} Copilot Skill invocation event(s)`
-            + `${manifest.verification?.sessionId ? ` in session ${manifest.verification.sessionId}` : ''}.`);
     });
     common(program.command('workflow-sanitize <log> <output-file>').description('Write a privacy-minimized Skill lifecycle transcript'))
         .option('--session-id <uuid>', 'Replace the terminal session ID with a review-safe UUID')
@@ -416,6 +497,7 @@ export function createProgram() {
         if (!['github', 'azure-pipelines', 'generic'].includes(options.provider))
             throw new Error('Unknown attestation provider.');
         const root = resolve(options.root);
+        await assertCoordinatedEvidenceRead(root);
         const configured = (await loadConfig(root)).attestation.githubOidc;
         if (configured?.mode === 'strict' && options.provider !== 'github') {
             throw new Error('Strict GitHub OIDC attestation requires --provider github.');
@@ -448,6 +530,7 @@ export function createProgram() {
     });
     common(attestation.command('verify')).action(async (options) => {
         const root = resolve(options.root);
+        await assertCoordinatedEvidenceRead(root);
         const report = await verifyEvidenceAttestation(root, (await loadConfig(root)).attestation);
         output(report, !!options.json, `${report.status}: ${report.valid ? 'valid' : 'invalid'}`);
         if (!report.valid)
@@ -481,6 +564,16 @@ export function createProgram() {
         output(evidence, !!options.json, options.dryRun ? `Would record ${changeId}:${phase}.` : `Recorded ${changeId}:${phase}.`);
     });
     const change = program.command('change').description('Change chronology and waiver evidence');
+    /** @id CODE-CHANGE-QUALITY-REFRESH-005
+     * @implements REQ-CHANGE-QUALITY-REFRESH-003
+     * @design DES-CHANGE-QUALITY-REFRESH-002
+     */
+    common(change.command('quality-recover')
+        .description('Recover an interrupted two-file Quality refresh transaction'))
+        .action(async (options) => {
+        const report = await recoverQualityRefresh(resolve(options.root));
+        output(report, !!options.json, report.recovered ? `Quality refresh ${report.action}.` : 'No Quality refresh to recover.');
+    });
     const waiver = change.command('waiver').description('Record an audited, bounded downgrade of a recording-order-debt diagnostic');
     common(waiver.command('record <change-id> <code>')
         .description('Downgrade one currently-present waivable diagnostic from error to warning, as an appended, hash-chained record'))
@@ -496,17 +589,41 @@ export function createProgram() {
         output(result, !!options.json, `WAIVER: PASS (${changeId}:${code}${options.requirement ? `:${options.requirement}` : ''}${options.detail ? `:${options.detail}` : ''})`);
     });
     const approval = program.command('approval').description('Prepare, record and validate explicit artifact-bound human approvals');
+    /** @id CODE-APPROVAL-PREPARE-DIFF-ONLY-003
+     * @implements REQ-APPROVAL-PREPARE-DIFF-ONLY-001 REQ-APPROVAL-PREPARE-DIFF-ONLY-002 REQ-APPROVAL-PREPARE-DIFF-ONLY-004
+     * @implements REQ-APPROVAL-PREPARE-DIFF-ONLY-005 REQ-APPROVAL-PREPARE-DIFF-ONLY-006 REQ-APPROVAL-PREPARE-DIFF-ONLY-007
+     * @design DES-APPROVAL-PREPARE-DIFF-ONLY-002 DES-APPROVAL-PREPARE-DIFF-ONLY-003
+     */
     common(approval.command('prepare <stage>').description('Show the exact artifact manifest a human must review'))
         .option('--domain <name>', 'Approval domain (required when approval.domains is configured, except for release)')
+        .option('--diff-only', 'Additionally report only the file paths whose content changed since the last recorded approval for this stage')
         .action(async (stage, options) => {
         if (!approvalStages.includes(stage))
             throw new Error(`stage must be one of: ${approvalStages.join(', ')}`);
         const root = resolve(options.root);
+        await assertCoordinatedEvidenceRead(root);
         const config = await loadConfig(root);
         requireDomainOption(config.approval, stage, options.domain);
         const domain = options.domain ? await resolveNamedDomain(root, config.approval, options.domain) : undefined;
         const manifest = await approvalManifest(root, stage, domain);
-        output(manifest, !!options.json, `${stage} artifact manifest: ${manifest.artifactSha256}\n${Object.keys(manifest.artifacts).join('\n')}`);
+        if (!options.diffOnly) {
+            output(manifest, !!options.json, `${stage} artifact manifest: ${manifest.artifactSha256}\n${Object.keys(manifest.artifacts).join('\n')}`);
+            return;
+        }
+        // REQ-APPROVAL-PREPARE-DIFF-ONLY-007: no try/catch here — a corrupted prior
+        // approval file must abort the command via loadApproval's thrown error,
+        // never be silently treated as "no prior approval".
+        const previous = await loadApproval(root, stage, domain?.name);
+        const { changedFiles: changed, diffOnlyBaseline } = diffOnlyChangedFiles(manifest, previous);
+        const withDiff = { ...manifest, changedFiles: changed, diffOnlyBaseline };
+        // REQ-APPROVAL-PREPARE-DIFF-ONLY-006: the non-JSON summary shows only the
+        // changed paths (plus the full hash and an explicit baseline note), never
+        // the complete artifact listing; --json output above is unaffected.
+        const baselineNote = diffOnlyBaseline === 'none'
+            ? 'no prior approval found; showing all current artifacts'
+            : 'compared against the previously recorded approval';
+        const diffSummary = `${stage} artifact manifest: ${manifest.artifactSha256}\n(diff-only: ${baselineNote})\n${changed.join('\n')}`;
+        output(withDiff, !!options.json, diffSummary);
     });
     common(approval.command('record <stage>'))
         .requiredOption('--approver <name>', 'Human approver name')
@@ -520,14 +637,17 @@ export function createProgram() {
         if (options.confirm !== true)
             throw new Error('--confirm is required to record human approval.');
         const root = resolve(options.root);
-        const config = await loadConfig(root);
-        const evidence = await recordApproval(root, stage, options.approver, options.artifactSha256, config.approval, options.domain);
-        output(evidence, !!options.json, `Recorded explicit ${stage} approval by ${evidence.approver} for ${evidence.artifactSha256}.`);
+        await withEvidenceWriterLock(root, 'approval record', async () => {
+            const config = await loadConfig(root);
+            const evidence = await recordApproval(root, stage, options.approver, options.artifactSha256, config.approval, options.domain);
+            output(evidence, !!options.json, `Recorded explicit ${stage} approval by ${evidence.approver} for ${evidence.artifactSha256}.`);
+        });
     });
     common(approval.command('validate'))
         .option('--domain <name>', 'Limit the report to one approval domain')
         .action(async (options) => {
         const root = resolve(options.root);
+        await assertCoordinatedEvidenceRead(root);
         const config = await loadConfig(root);
         requireValidateDomainOption(config.approval, options.domain);
         const report = options.domain
@@ -544,7 +664,9 @@ export function createProgram() {
         + "name suffix for go-test/cargo, an additional @Tag for junit, DisplayName for dotnet). "
         + 'See README.md "Adapter test-ID declaration reference" for the full table and worked examples.');
     common(tdd.command('validate')).action(async (options) => {
-        const report = await validateTddEvidence(resolve(options.root));
+        const root = resolve(options.root);
+        await assertCoordinatedEvidenceRead(root);
+        const report = await validateTddEvidence(root);
         result(report, !!options.json);
     });
     for (const phase of ['red', 'green', 'refactor']) {
@@ -559,13 +681,14 @@ export function createProgram() {
         // onto `green`/`refactor` via the shared loop.
         if (phase === 'red') {
             phaseCommand.description('Record a failing (Red) test as TDD evidence for a requirement. Persisting the '
-                + "project's first cycle here makes gate's tdd check required project-wide for "
-                + 'every mandatory requirement (each uncovered one surfaced as '
-                + 'TDD_REQUIREMENT_UNCOVERED); "approval record release" always runs the full '
-                + '(non-\'--changed\') gate, so it is blocked by any resulting '
-                + 'TDD_REQUIREMENT_UNCOVERED diagnostics. "tdd migrate" cannot bulk-onboard '
-                + 'previously-uncovered requirements: it only re-fingerprints a requirement that '
-                + 'already has a valid Green cycle.');
+                + "project's first cycle here activates gate's tdd coverage evaluation project-wide "
+                + 'for every mandatory requirement (each uncovered one surfaced as '
+                + 'TDD_REQUIREMENT_UNCOVERED); if tdd was not already required for another '
+                + 'configured reason, that same first cycle is what makes the check required. '
+                + '"approval record release" always runs the full (non-\'--changed\') gate, so '
+                + 'it is blocked by any resulting TDD_REQUIREMENT_UNCOVERED diagnostics. '
+                + '"tdd migrate" cannot bulk-onboard previously-uncovered requirements: it only '
+                + 'reuses already-covered valid Green-backed evidence.');
         }
         phaseCommand
             .requiredOption('--requirement <id>', 'Requirement ID verified by the test')
@@ -580,17 +703,23 @@ export function createProgram() {
                 process.exitCode = 1;
         });
     }
-    common(tdd.command('migrate <test-id>'))
-        .requiredOption('--approver <name>', 'Human approver recording this fingerprint migration')
+    common(tdd.command('migrate [ids...]'))
+        .description('Relink existing covered evidence: `tdd migrate <test-id>` re-fingerprints one covered test; `tdd migrate <old-id> <new-id>` relinks a pure identifier rename.')
+        .requiredOption('--approver <name>', 'Human approver recording this migrate operation')
         .option('--confirm', 'Confirm the migration is reviewed and intended', false)
-        .action(async (testId, options) => {
+        .action(async (ids, options) => {
         if (!options.confirm)
-            throw new Error('Fingerprint migration requires --confirm.');
+            throw new Error('TDD migration requires --confirm.');
+        if (ids.length < 1 || ids.length > 2)
+            throw new InvalidArgumentError('tdd migrate accepts either <test-id> or <old-id> <new-id>.');
         const root = resolve(options.root);
-        const migration = await migrateTddFingerprint(root, testId, options.approver);
+        const migration = ids.length === 1
+            ? await migrateTddFingerprint(root, ids[0], options.approver)
+            : await migrateTddIdentifier(root, ids[0], ids[1], options.approver);
+        const target = ids.join(' -> ');
         output(migration, !!options.json, migration.migrated
-            ? `MIGRATE: PASS (${testId}) ${migration.fromFingerprint} -> ${migration.toFingerprint}`
-            : `MIGRATE: FAIL (${testId}) ${migration.reason}`);
+            ? `MIGRATE: PASS (${target}) ${migration.fromFingerprint} -> ${migration.toFingerprint}`
+            : `MIGRATE: FAIL (${target}) ${migration.reason}`);
         if (!migration.migrated)
             process.exitCode = 1;
     });
@@ -609,9 +738,26 @@ export function createProgram() {
         if (!voidResult.voided)
             process.exitCode = 1;
     });
+    common(tdd.command('archive <test-id>'))
+        .requiredOption('--approver <name>', 'Human approver recording this archive')
+        .requiredOption('--reason <text>', 'Reason this TDD cycle is being archived')
+        .option('--confirm', 'Confirm the archive is reviewed and intended', false)
+        .action(async (testId, options) => {
+        if (!options.confirm)
+            throw new Error('Archiving a TDD cycle requires --confirm.');
+        const root = resolve(options.root);
+        const archiveResult = await archiveTddCycle(root, testId, options.approver, options.reason);
+        output(archiveResult, !!options.json, archiveResult.archived
+            ? `ARCHIVE: PASS (${testId}) cycle=${archiveResult.cycleId}`
+            : `ARCHIVE: FAIL (${testId}) ${archiveResult.reason}`);
+        if (!archiveResult.archived)
+            process.exitCode = 1;
+    });
     common(program.command('status').description('One-shot artifact and gate readiness summary'))
         .action(async (options) => {
-        const status = await projectStatus(resolve(options.root));
+        const root = resolve(options.root);
+        await assertCoordinatedEvidenceRead(root);
+        const status = await projectStatus(root);
         const approvalSummary = status.approvals
             ? status.approvals.stages.map((stage) => `${stage.stage}=${stage.status}`).join(', ')
             : 'unconfigured';
@@ -627,13 +773,40 @@ async function main() {
         if (cause instanceof CommanderError && cause.exitCode === 0)
             return;
         const message = cause instanceof Error ? cause.message : String(cause);
-        if (process.argv.includes('--json'))
-            console.log(JSON.stringify({ error: { code: 'CLI_ERROR', message } }));
+        if (process.argv.includes('--json')) {
+            if (cause instanceof EvidenceWriterLockError) {
+                const underlying = cause.cause instanceof Error
+                    ? {
+                        name: cause.cause.name,
+                        message: cause.cause.message,
+                        ...('code' in cause.cause ? { code: String(cause.cause.code) } : {}),
+                    }
+                    : cause.cause === undefined ? undefined : { message: String(cause.cause) };
+                console.log(JSON.stringify({
+                    error: {
+                        code: cause.code,
+                        message,
+                        lockPath: cause.lockPath,
+                        ...(cause.owner === undefined ? {} : { owner: cause.owner }),
+                        ...(underlying === undefined ? {} : { cause: underlying }),
+                        ...(cause.guidance === undefined ? {} : { guidance: cause.guidance }),
+                    },
+                }));
+            }
+            else if (cause instanceof EvidenceProtectedOutputError) {
+                console.log(JSON.stringify({ error: { code: cause.code, message, path: cause.path } }));
+            }
+            else {
+                console.log(JSON.stringify({ error: { code: 'CLI_ERROR', message } }));
+            }
+        }
         else
             console.error(`musubix3: ${message}`);
         process.exitCode = 2;
     }
 }
-await main();
+if (process.argv[1] !== undefined && pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url) {
+    await main();
+}
 import { readFile, stat } from 'node:fs/promises';
 //# sourceMappingURL=main.js.map