musubix3 0.1.20 → 0.1.21

package/dist/packages/analysis/src/tdd.js

@@ -8,7 +8,108 @@ import { buildTrace } from './trace.js';
 import { adapterInvocation, clearAdapterOutput, mergeAdapterArgs, normalizeAdapterReport, readAdapterOutput } from './adapters.js';
 import { appendEvidenceOrder, evidenceOrderRecord, inspectEvidenceOrder } from './order.js';
 import { requireApproval, resolveRequirementDomain } from './approval.js';
+import { batchFor, changeRecordPhasePrecondition, currentTddOrderWindow, effectiveBatches, loadChangeEvidence, } from './change-evidence.js';
 import { withEvidenceWriterLock } from './evidence-writer-lock.js';
+// TDD cycle-validity re-derivations. Relocated here (unchanged bodies) from
+// change-evidence.ts: they need TddCycle/TddEvidence, which are defined in
+// this file, and change-evidence.ts must stay free of any dependency on
+// this file so that this file's own (new, CHANGE-0049) runtime dependency
+// on change-evidence.ts (for changeRecordPhasePrecondition/loadChangeEvidence)
+// does not create a module-dependency cycle between the two files.
+/** @id CODE-CHANGE-REQUIREMENT-BATCHES-004
+ * @implements REQ-CHANGE-REQUIREMENT-BATCHES-005
+ * @design DES-CHANGE-REQUIREMENT-BATCHES-002
+ */
+export function voidedCycleOrdersInCurrentWindow(change, requirementId, tdd, validlyVoided) {
+    const window = currentTddOrderWindow(change, requirementId);
+    if (!window)
+        return [];
+    return (tdd?.cycles ?? [])
+        .filter((cycle) => cycle.requirementId === requirementId
+        && validlyVoided.has(cycle)
+        && Number.isInteger(cycle.red.order)
+        && cycle.red.order > window.after
+        && cycle.red.order <= window.through
+        && Number.isInteger(cycle.void?.order))
+        .map((cycle) => cycle.void.order)
+        .sort((a, b) => a - b);
+}
+/** @id CODE-CHANGE-EVIDENCE-WAIVER-029
+ * @implements REQ-CHANGE-EVIDENCE-WAIVER-018
+ * @design DES-CHANGE-EVIDENCE-WAIVER-006
+ * Excludes validly archived cycles from the order window alongside validly
+ * voided ones (Issue #64): a cleaned-up dangling cycle (e.g. one `tdd
+ * archive`d because the forced-failing Red it required never applied) must
+ * never be selected as the "current" cycle for a requirement.
+ */
+function currentTddCycle(change, requirementId, tdd, validlyVoided, validlyArchived = new Set()) {
+    const window = currentTddOrderWindow(change, requirementId);
+    if (!window)
+        return undefined;
+    return (tdd?.cycles ?? [])
+        .filter((cycle) => cycle.requirementId === requirementId
+        && !validlyVoided.has(cycle)
+        && !validlyArchived.has(cycle)
+        && Number.isInteger(cycle.red.order)
+        && cycle.red.order > window.after
+        && cycle.red.order <= window.through)
+        .reduce((selected, cycle) => !selected || cycle.red.order >= selected.red.order ? cycle : selected, undefined);
+}
+function tddCyclesInCurrentWindow(change, requirementId, tdd, validlyVoided) {
+    const window = currentTddOrderWindow(change, requirementId);
+    if (!window)
+        return [];
+    return (tdd?.cycles ?? []).filter((cycle) => cycle.requirementId === requirementId
+        && !validlyVoided.has(cycle)
+        && Number.isInteger(cycle.red.order)
+        && cycle.red.order > window.after
+        && cycle.red.order <= window.through);
+}
+export function hasValidTddCycle(change, requirementId, tdd, validlyVoided = new Set()) {
+    const batch = batchFor(effectiveBatches(change), requirementId);
+    const implementation = batch?.implementation;
+    const green = batch?.green;
+    return tddCyclesInCurrentWindow(change, requirementId, tdd, validlyVoided).some((cycle) => !!implementation
+        && green
+        && Number.isInteger(implementation.order)
+        && Number.isInteger(green.order)
+        && Number.isInteger(cycle.green?.order)
+        && cycle.red.valid
+        && cycle.green?.valid
+        && cycle.green.order > implementation.order
+        && cycle.green.order <= green.order);
+}
+export function redUnprovenCondition(change, requirementId, tdd, validlyVoided = new Set()) {
+    const batch = batchFor(effectiveBatches(change), requirementId);
+    return !!batch?.red && !hasValidTddCycle(change, requirementId, tdd, validlyVoided);
+}
+export function greenUnprovenCondition(change, requirementId, tdd, validlyVoided = new Set()) {
+    const batch = batchFor(effectiveBatches(change), requirementId);
+    return !!batch?.green && !hasValidTddCycle(change, requirementId, tdd, validlyVoided);
+}
+export function completenessTddUnsatisfiedCondition(change, requirementId, tdd, validlyVoided = new Set()) {
+    return !hasValidTddCycle(change, requirementId, tdd, validlyVoided);
+}
+/** @id CODE-CHANGE-EVIDENCE-WAIVER-028
+ * @implements REQ-CHANGE-EVIDENCE-WAIVER-018
+ * @design DES-CHANGE-EVIDENCE-WAIVER-006
+ * Accepts an optional `validlyArchived` set, mirroring `validlyVoided`, so
+ * archived TDD cycles are excluded from both the "lacks order evidence" scan
+ * and `currentTddCycle`'s window selection (Issue #64).
+ */
+export function orderMigrationRequiredRequirementCondition(change, requirementId, tdd, validlyVoided = new Set(), validlyArchived = new Set()) {
+    const batch = batchFor(effectiveBatches(change), requirementId);
+    if (!batch?.red)
+        return false;
+    const cycles = (tdd?.cycles ?? []).filter((cycle) => cycle.requirementId === requirementId && !validlyVoided.has(cycle) && !validlyArchived.has(cycle));
+    if (cycles.some((cycle) => !Number.isInteger(cycle.red.order)))
+        return true;
+    const window = currentTddOrderWindow(change, requirementId);
+    if (!window)
+        return false;
+    const current = currentTddCycle(change, requirementId, tdd, validlyVoided, validlyArchived);
+    return !!current && !Number.isInteger(current.green?.order);
+}
 function render(value, testId, testPath, reportPath) {
     return value.replaceAll('{testId}', testId).replaceAll('{testPath}', testPath).replaceAll('{reportPath}', reportPath);
 }
@@ -31,6 +132,57 @@ export function parseMusubixTestReport(text) {
 function chainRecordSha256(record) {
     return digest(JSON.stringify(record));
 }
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function migrationMode(record) {
+    return record.mode ?? 'fingerprint';
+}
+function migrationScope(record) {
+    return migrationMode(record) === 'identifier'
+        ? {
+            ...(record.oldTestId !== undefined ? { oldTestId: record.oldTestId } : {}),
+            ...(record.newTestId !== undefined ? { newTestId: record.newTestId } : {}),
+        }
+        : undefined;
+}
+function migrationRecords(cycle) {
+    if (cycle.migrateHistory?.length)
+        return cycle.migrateHistory;
+    return cycle.migrate ? [cycle.migrate] : [];
+}
+function latestMigration(cycle) {
+    return migrationRecords(cycle).at(-1);
+}
+function currentEffectiveTestId(cycle) {
+    const identifierMigration = [...migrationRecords(cycle)].reverse().find((record) => migrationMode(record) === 'identifier');
+    return identifierMigration?.newTestId ?? cycle.testId;
+}
+function currentEffectiveFingerprint(cycle) {
+    const migrate = latestMigration(cycle);
+    if (migrate)
+        return migrate.toFingerprint;
+    if (cycle.refactor?.valid)
+        return cycle.refactor.testFingerprint;
+    return cycle.green?.testFingerprint;
+}
+function currentEffectiveSourceFingerprint(cycle) {
+    if (cycle.refactor?.valid)
+        return cycle.refactor.sourceFingerprint;
+    return cycle.green?.sourceFingerprint;
+}
+function chainIdentity(record) {
+    if (record.phase === 'migrate') {
+        return JSON.stringify([
+            record.cycleId,
+            record.phase,
+            record.mode ?? 'fingerprint',
+            record.oldTestId ?? null,
+            record.newTestId ?? null,
+        ]);
+    }
+    return JSON.stringify([record.cycleId, record.phase]);
+}
 function appendChainRecord(evidence, cycle, phase, phaseEvidence) {
     if (!cycle.cycleId)
         throw new Error('TDD cycle ID is required for append-only evidence.');
@@ -49,6 +201,13 @@ function appendChainRecord(evidence, cycle, phase, phaseEvidence) {
         testPath: cycle.testPath,
         commandName: cycle.commandName,
         phase,
+        ...(phase === 'migrate' && phaseEvidence && typeof phaseEvidence === 'object'
+            ? {
+                mode: phaseEvidence.mode,
+                oldTestId: phaseEvidence.oldTestId,
+                newTestId: phaseEvidence.newTestId,
+            }
+            : {}),
         phaseEvidenceSha256: digest(JSON.stringify(phaseEvidence)),
         previousSha256: previous?.recordSha256 ?? null,
     };
@@ -75,7 +234,7 @@ function collectStatements(node, out) {
         out.push(node);
     ts.forEachChild(node, (child) => collectStatements(child, out));
 }
-async function testFingerprint(root, test) {
+async function testDeclarationText(root, test) {
     const text = await readText(root, test.path);
     const lines = text.split(/\r?\n/);
     const start = lines.slice(0, Math.max(0, test.line - 1)).join('\n').length + (test.line > 1 ? 1 : 0);
@@ -85,12 +244,15 @@ async function testFingerprint(root, test) {
         collectStatements(source, statements);
         const declaration = statements.find((statement) => statement.getStart(source) >= start);
         if (declaration)
-            return digest(text.slice(start, declaration.end).trim());
+            return text.slice(start, declaration.end).trim();
     }
     const lineEnd = text.indexOf('\n', start);
     const searchFrom = lineEnd < 0 ? text.length : lineEnd + 1;
     const next = text.slice(searchFrom).search(/^[ \t]*(?:\/\*+|\/\/|#).*?@id\s+TEST-/m);
-    return digest(text.slice(start, next < 0 ? text.length : searchFrom + next).trim());
+    return text.slice(start, next < 0 ? text.length : searchFrom + next).trim();
+}
+async function testFingerprint(root, test) {
+    return digest(await testDeclarationText(root, test));
 }
 // The pre-REQ-TDD-FINGERPRINT-SCOPING-001 algorithm (top-level statements
 // only). Retained solely so `migrateTddFingerprint` can prove a stored
@@ -116,6 +278,43 @@ export async function legacyTestFingerprint(root, test) {
     const next = text.slice(searchFrom).search(/^[ \t]*(?:\/\*+|\/\/|#).*?@id\s+TEST-/m);
     return digest(text.slice(start, next < 0 ? text.length : searchFrom + next).trim());
 }
+/** @id CODE-TDD-IDENTIFIER-MIGRATION-002
+ * @implements REQ-TDD-IDENTIFIER-MIGRATION-002 REQ-TDD-IDENTIFIER-MIGRATION-003
+ * @design DES-TDD-IDENTIFIER-MIGRATION-002
+ */
+async function normalizedIdentifierMigrationFingerprint(root, test, oldTestId, newTestId) {
+    let declaration = await testDeclarationText(root, test);
+    const idPattern = new RegExp(`@id\\s+${escapeRegExp(newTestId)}\\b`, 'g');
+    const idMatches = declaration.match(idPattern) ?? [];
+    if (idMatches.length !== 1) {
+        throw new Error(`${newTestId} must contain exactly one authoritative @id annotation in its declaration.`);
+    }
+    declaration = declaration.replace(idPattern, `@id ${oldTestId}`);
+    if (!isSource(test.path))
+        return digest(declaration);
+    const source = ts.createSourceFile(test.path, declaration, ts.ScriptTarget.Latest, true);
+    const literals = [];
+    const visit = (node) => {
+        if ((ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) && node.text.includes(newTestId)) {
+            literals.push({ start: node.getStart(source), end: node.end, text: node.text });
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    if (literals.length !== 1) {
+        throw new Error(`${newTestId} must differ from ${oldTestId} only in its @id annotation and one adapter-matched identity string.`);
+    }
+    const [literal] = literals;
+    if (!literal)
+        throw new Error('Missing adapter identity literal.');
+    const replacement = declaration.slice(literal.start, literal.end).replace(new RegExp(escapeRegExp(newTestId), 'g'), oldTestId);
+    declaration = `${declaration.slice(0, literal.start)}${replacement}${declaration.slice(literal.end)}`;
+    return digest(declaration.trim());
+}
+/** @id CODE-TDD-CYCLE-ARCHIVE-006
+ * @implements REQ-TDD-CYCLE-ARCHIVE-012
+ * @design DES-TDD-CYCLE-ARCHIVE-005
+ */
 export async function migrateTddFingerprint(root, testId, approver) {
     return withEvidenceWriterLock(root, 'tdd migrate', () => migrateTddFingerprintUnlocked(root, testId, approver));
 }
@@ -129,13 +328,21 @@ async function migrateTddFingerprintUnlocked(root, testId, approver) {
     if (!cycle)
         throw new Error(`No TDD cycle found for ${testId}.`);
     const order = await inspectEvidenceOrder(root);
+    /** @id CODE-TDD-CYCLE-ARCHIVE-005
+     * @implements REQ-TDD-CYCLE-ARCHIVE-012
+     * @design DES-TDD-CYCLE-ARCHIVE-005
+     */
+    if (archiveLinkage(evidence, order, cycle).valid) {
+        throw new Error(`${testId}'s latest cycle is archived and cannot be migrated; record a fresh Red-Green cycle instead.`);
+    }
     /** @id CODE-TDD-CYCLE-VOID-006
-     * @implements REQ-TDD-CYCLE-VOID-012
-     * @design DES-TDD-CYCLE-VOID-006
+     * @implements REQ-TDD-CYCLE-VOID-012 REQ-TDD-CYCLE-ARCHIVE-012
+     * @design DES-TDD-CYCLE-VOID-006 DES-TDD-CYCLE-ARCHIVE-005
      */
     if (voidLinkage(evidence, order, cycle).valid) {
         const validlyVoided = new Set(evidence.cycles.filter((entry) => voidLinkage(evidence, order, entry).valid));
-        const effective = effectiveLatestCycle(evidence, order, validlyVoided, testId, cycle);
+        const validlyArchived = new Set(evidence.cycles.filter((entry) => archiveLinkage(evidence, order, entry).valid));
+        const effective = effectiveLatestCycle(evidence, order, validlyVoided, validlyArchived, testId, cycle);
         if (effective)
             cycle = effective;
     }
@@ -143,14 +350,15 @@ async function migrateTddFingerprintUnlocked(root, testId, approver) {
         throw new Error(`${testId} lacks a cycle ID; regenerate its evidence before migrating.`);
     if (!cycle.green?.valid)
         throw new Error(`${testId} has no valid Green phase to migrate.`);
-    if (cycle.migrate)
+    if (migrationRecords(cycle).length > 0)
         throw new Error(`${testId} has already been migrated.`);
     const trace = await buildTrace(root);
     const test = trace.nodes.find((node) => node.kind === 'test' && node.id === testId);
     if (!test)
         throw new Error(`Annotated test ID not found: ${testId}`);
-    const latestPhase = cycle.refactor?.valid ? cycle.refactor : cycle.green;
-    const storedFingerprint = latestPhase.testFingerprint;
+    const storedFingerprint = currentEffectiveFingerprint(cycle);
+    if (!storedFingerprint)
+        throw new Error(`${testId} has no effective fingerprint to migrate.`);
     const legacyCurrent = await legacyTestFingerprint(root, test);
     if (legacyCurrent !== storedFingerprint) {
         return {
@@ -165,6 +373,7 @@ async function migrateTddFingerprintUnlocked(root, testId, approver) {
         fromFingerprint: storedFingerprint,
         toFingerprint,
         approver,
+        mode: 'fingerprint',
         recordedAt: new Date().toISOString(),
     };
     record.order = (await appendEvidenceOrder(root, { kind: 'tdd', entityId: cycle.cycleId, phase: 'migrate' })).sequence;
@@ -173,6 +382,105 @@ async function migrateTddFingerprintUnlocked(root, testId, approver) {
     await writeJson(root, '.musubix/evidence/tdd.json', evidence);
     return { migrated: true, testId, fromFingerprint: storedFingerprint, toFingerprint };
 }
+/** @id CODE-TDD-IDENTIFIER-MIGRATION-001
+ * @implements REQ-TDD-IDENTIFIER-MIGRATION-001 REQ-TDD-IDENTIFIER-MIGRATION-002 REQ-TDD-IDENTIFIER-MIGRATION-003 REQ-TDD-IDENTIFIER-MIGRATION-004
+ * @design DES-TDD-IDENTIFIER-MIGRATION-001 DES-TDD-IDENTIFIER-MIGRATION-002 DES-TDD-IDENTIFIER-MIGRATION-003
+ */
+export async function migrateTddIdentifier(root, oldTestId, newTestId, approver) {
+    return withEvidenceWriterLock(root, 'tdd migrate', () => migrateTddIdentifierUnlocked(root, oldTestId, newTestId, approver));
+}
+async function migrateTddIdentifierUnlocked(root, oldTestId, newTestId, approver) {
+    if (!approver?.trim())
+        throw new Error('An approver is required to migrate TDD identifier evidence.');
+    if (oldTestId === newTestId)
+        throw new Error('Identifier migration requires old and new test IDs that must differ.');
+    const evidence = await loadTddEvidence(root);
+    if (!evidence)
+        throw new Error('No TDD evidence found.');
+    let cycle = evidence.cycles.filter((entry) => entry.testId === oldTestId).at(-1);
+    if (!cycle)
+        throw new Error(`No TDD cycle found for ${oldTestId}.`);
+    const order = await inspectEvidenceOrder(root);
+    if (archiveLinkage(evidence, order, cycle).valid) {
+        throw new Error(`${oldTestId}'s latest cycle is archived and cannot be migrated; record a fresh Red-Green cycle instead.`);
+    }
+    if (voidLinkage(evidence, order, cycle).valid) {
+        const validlyVoided = new Set(evidence.cycles.filter((entry) => voidLinkage(evidence, order, entry).valid));
+        const validlyArchived = new Set(evidence.cycles.filter((entry) => archiveLinkage(evidence, order, entry).valid));
+        const effective = effectiveLatestCycle(evidence, order, validlyVoided, validlyArchived, oldTestId, cycle);
+        if (effective)
+            cycle = effective;
+    }
+    if (!cycle.cycleId)
+        throw new Error(`${oldTestId} lacks a cycle ID; regenerate its evidence before migrating.`);
+    if (!cycle.green?.valid)
+        throw new Error(`${oldTestId} has no valid Green phase to migrate.`);
+    const previousIdentifierMigration = [...migrationRecords(cycle)].reverse().find((record) => migrationMode(record) === 'identifier');
+    if (previousIdentifierMigration?.newTestId === newTestId) {
+        throw new Error(`${oldTestId} is already relinked to ${newTestId}.`);
+    }
+    if (previousIdentifierMigration) {
+        throw new Error(`${oldTestId} is already relinked to ${previousIdentifierMigration.newTestId}; conflicting relinks are not allowed.`);
+    }
+    if (evidence.cycles.some((entry) => entry !== cycle && currentEffectiveTestId(entry) === newTestId)) {
+        throw new Error(`${newTestId} already has a recorded cycle history.`);
+    }
+    const trace = await buildTrace(root);
+    if (trace.nodes.some((node) => node.kind === 'test' && node.id === oldTestId)) {
+        throw new Error(`${oldTestId} still has a surviving authoritative declaration in the current trace.`);
+    }
+    const matches = trace.nodes.filter((node) => node.kind === 'test' && node.id === newTestId);
+    if (matches.length !== 1)
+        throw new Error(`${newTestId} must have exactly one surviving authoritative declaration.`);
+    const [test] = matches;
+    if (!test)
+        throw new Error(`Annotated test ID not found: ${newTestId}`);
+    if (test.path !== cycle.testPath)
+        throw new Error(`${newTestId} must remain in the same test file path as ${oldTestId}.`);
+    const expectedSourceFingerprint = currentEffectiveSourceFingerprint(cycle);
+    const currentSource = await sourceFingerprint(root, test.path);
+    if (expectedSourceFingerprint !== currentSource) {
+        throw new Error(`${oldTestId}'s non-test sourceFingerprint changed after Green; record a fresh Red-Green cycle instead.`);
+    }
+    const baselineFingerprint = currentEffectiveFingerprint(cycle);
+    if (!baselineFingerprint)
+        throw new Error(`${oldTestId} has no effective fingerprint to relink.`);
+    const normalizedFingerprint = await normalizedIdentifierMigrationFingerprint(root, test, oldTestId, newTestId);
+    if (normalizedFingerprint !== baselineFingerprint) {
+        throw new Error(`${newTestId} is not a pure rename of ${oldTestId}; declaration fingerprint changed beyond rename-only tokens.`);
+    }
+    const toFingerprint = await testFingerprint(root, test);
+    const record = {
+        phase: 'migrate',
+        mode: 'identifier',
+        fromFingerprint: baselineFingerprint,
+        toFingerprint,
+        oldTestId,
+        newTestId,
+        approver,
+        recordedAt: new Date().toISOString(),
+    };
+    record.order = (await appendEvidenceOrder(root, {
+        kind: 'tdd',
+        entityId: cycle.cycleId,
+        phase: 'migrate',
+        oldTestId,
+        newTestId,
+    })).sequence;
+    cycle.migrateHistory = [...migrationRecords(cycle), record];
+    if (!cycle.migrate)
+        cycle.migrate = record;
+    appendChainRecord(evidence, cycle, 'migrate', record);
+    await writeJson(root, '.musubix/evidence/tdd.json', evidence);
+    return {
+        migrated: true,
+        testId: oldTestId,
+        oldTestId,
+        newTestId,
+        fromFingerprint: baselineFingerprint,
+        toFingerprint,
+    };
+}
 export async function loadTddEvidence(root) {
     const path = '.musubix/evidence/tdd.json';
     if (!await exists(within(root, path)))
@@ -190,13 +498,19 @@ export async function loadTddEvidence(root) {
 function phaseLinkageValid(order, chain, cycle, phase, phaseEvidence) {
     if (!order.valid || !cycle.cycleId || !chain)
         return false;
-    const phaseOrder = phase === 'void' ? cycle.void?.order : phase === 'migrate' ? cycle.migrate?.order : cycle[phase]?.order;
+    const phaseOrder = phase === 'void'
+        ? cycle.void?.order
+        : phase === 'archive'
+            ? cycle.archive?.order
+            : phase === 'migrate'
+                ? cycle.migrate?.order
+                : cycle[phase]?.order;
     if (phaseOrder === undefined)
         return false;
     const orderRecord = evidenceOrderRecord(order.records, 'tdd', cycle.cycleId, phase);
     if (!orderRecord || orderRecord.sequence !== phaseOrder)
         return false;
-    if (phase === 'void' && orderRecord.testId !== cycle.testId)
+    if ((phase === 'void' || phase === 'archive') && orderRecord.testId !== cycle.testId)
         return false;
     const matches = chain.filter((record) => record.phase === phase && record.cycleId === cycle.cycleId && record.testId === cycle.testId);
     if (matches.length !== 1)
@@ -209,6 +523,32 @@ function phaseLinkageValid(order, chain, cycle, phase, phaseEvidence) {
         && record.previousSha256 === expectedPrevious
         && record.phaseEvidenceSha256 === digest(JSON.stringify(phaseEvidence));
 }
+function migrationLinkageValid(order, chain, cycle, record) {
+    if (!order.valid || !cycle.cycleId || record.order === undefined || !chain)
+        return false;
+    const orderRecord = evidenceOrderRecord(order.records, 'tdd', cycle.cycleId, 'migrate', migrationScope(record));
+    if (!orderRecord || orderRecord.sequence !== record.order)
+        return false;
+    if (migrationMode(record) === 'identifier'
+        && (orderRecord.oldTestId !== record.oldTestId || orderRecord.newTestId !== record.newTestId)) {
+        return false;
+    }
+    const matches = chain.filter((entry) => entry.phase === 'migrate'
+        && entry.cycleId === cycle.cycleId
+        && entry.testId === cycle.testId
+        && (entry.mode ?? 'fingerprint') === migrationMode(record)
+        && (entry.oldTestId ?? null) === (record.oldTestId ?? null)
+        && (entry.newTestId ?? null) === (record.newTestId ?? null));
+    if (matches.length !== 1)
+        return false;
+    const chainRecord = matches[0];
+    const index = chain.indexOf(chainRecord);
+    const expectedPrevious = index === 0 ? null : chain[index - 1].recordSha256;
+    const { recordSha256, ...payload } = chainRecord;
+    return recordSha256 === chainRecordSha256(payload)
+        && chainRecord.previousSha256 === expectedPrevious
+        && chainRecord.phaseEvidenceSha256 === digest(JSON.stringify(record));
+}
 /** @id CODE-TDD-CYCLE-VOID-002
  * @implements REQ-TDD-CYCLE-VOID-005, REQ-TDD-CYCLE-VOID-006, REQ-TDD-CYCLE-VOID-007
  * @design DES-TDD-CYCLE-VOID-002
@@ -243,9 +583,77 @@ function voidLinkage(evidence, order, cycle) {
     }
     return { valid: false, reason: `${cycle.testId}'s void evidence is malformed: ${reason}.` };
 }
+/** @id CODE-TDD-CYCLE-ARCHIVE-002
+ * @implements REQ-TDD-CYCLE-ARCHIVE-006 REQ-TDD-CYCLE-ARCHIVE-007 REQ-TDD-CYCLE-ARCHIVE-013
+ * @design DES-TDD-CYCLE-ARCHIVE-003
+ */
+function archiveLinkage(evidence, order, cycle) {
+    if (!cycle.archive)
+        return { valid: false };
+    const matchingOrderRecords = !cycle.cycleId
+        ? []
+        : [...order.records.values()].filter((record) => record.kind === 'tdd' && record.entityId === cycle.cycleId && record.phase === 'archive');
+    // Chain records sharing this cycle's (cycleId, phase) identity regardless of
+    // testId: a conflicting record for a different testId must not be masked by
+    // phaseLinkageValid's testId-scoped match (REQ-TDD-CYCLE-ARCHIVE-007).
+    const identityChainRecords = (evidence.chain ?? []).filter((record) => record.phase === 'archive' && record.cycleId === cycle.cycleId);
+    if (cycle.archive.testId === cycle.testId
+        && cycle.archive.cycleId === cycle.cycleId
+        && matchingOrderRecords.length === 1
+        && identityChainRecords.length === 1
+        && phaseLinkageValid(order, evidence.chain, cycle, 'archive', cycle.archive)) {
+        return { valid: true };
+    }
+    let reason = 'an invalid monotonic evidence order log';
+    if (order.valid) {
+        if (cycle.archive.testId !== cycle.testId || cycle.archive.cycleId !== cycle.cycleId) {
+            reason = 'a payload identity mismatch';
+        }
+        else if (!cycle.cycleId || cycle.archive.order === undefined) {
+            reason = 'a missing order record reference';
+        }
+        else if (matchingOrderRecords.length === 0) {
+            reason = 'a missing or mismatched order record';
+        }
+        else if (matchingOrderRecords.length > 1) {
+            reason = 'a duplicate order record';
+        }
+        else if (matchingOrderRecords[0].sequence !== cycle.archive.order) {
+            reason = 'a missing or mismatched order record';
+        }
+        else if (matchingOrderRecords[0].testId !== cycle.testId) {
+            reason = 'an order record testId mismatch';
+        }
+        else if (!evidence.chain) {
+            reason = 'a missing hash chain';
+        }
+        else if (identityChainRecords.length > 1) {
+            reason = 'a conflicting chain record';
+        }
+        else {
+            const matches = evidence.chain.filter((record) => record.phase === 'archive' && record.cycleId === cycle.cycleId && record.testId === cycle.testId);
+            reason = matches.length === 0
+                ? 'a missing chain record'
+                : matches.length > 1
+                    ? 'a duplicate chain record'
+                    : 'a broken predecessor or payload hash link';
+        }
+    }
+    return { valid: false, reason: `${cycle.testId}'s archive evidence is malformed: ${reason}.` };
+}
 export function validlyVoidedTddCycles(evidence, order) {
     return new Set((evidence?.cycles ?? []).filter((cycle) => voidLinkage(evidence, order, cycle).valid));
 }
+/** @id CODE-CHANGE-EVIDENCE-WAIVER-027
+ * @implements REQ-CHANGE-EVIDENCE-WAIVER-018
+ * @design DES-CHANGE-EVIDENCE-WAIVER-006
+ * Mirrors `validlyVoidedTddCycles` for archived cycles so callers can exclude
+ * validly archived evidence from change order-window checks the same way
+ * validly voided evidence is already excluded (Issue #64).
+ */
+export function validlyArchivedTddCycles(evidence, order) {
+    return new Set((evidence?.cycles ?? []).filter((cycle) => archiveLinkage(evidence, order, cycle).valid));
+}
 /** Resolves the effective latest cycle for `testId` when its actual latest
  * cycle (`voidedCycle`) is validly voided, per REQ-TDD-CYCLE-VOID-010: the
  * eligible, non-voided candidate with the greatest verified Green order
@@ -255,7 +663,7 @@ export function validlyVoidedTddCycles(evidence, order) {
  * @implements REQ-TDD-CYCLE-VOID-010
  * @design DES-TDD-CYCLE-VOID-004
  */
-function effectiveLatestCycle(evidence, order, validlyVoidedCycles, testId, voidedCycle) {
+function effectiveLatestCycle(evidence, order, validlyVoidedCycles, validlyArchivedCycles, testId, voidedCycle) {
     if (!voidedCycle.cycleId)
         return undefined;
     const voidRecord = evidenceOrderRecord(order.records, 'tdd', voidedCycle.cycleId, 'void');
@@ -269,6 +677,8 @@ function effectiveLatestCycle(evidence, order, validlyVoidedCycles, testId, void
             continue;
         if (validlyVoidedCycles.has(candidate))
             continue;
+        if (validlyArchivedCycles.has(candidate))
+            continue;
         if (!candidate.cycleId)
             continue;
         if (!phaseLinkageValid(order, evidence.chain, candidate, 'green', candidate.green))
@@ -282,12 +692,19 @@ function effectiveLatestCycle(evidence, order, validlyVoidedCycles, testId, void
     return best?.cycle;
 }
 /** @id CODE-TDD-CYCLE-VOID-001
- * @implements REQ-TDD-CYCLE-VOID-001, REQ-TDD-CYCLE-VOID-002, REQ-TDD-CYCLE-VOID-003, REQ-TDD-CYCLE-VOID-004, REQ-TDD-CYCLE-VOID-011
- * @design DES-TDD-CYCLE-VOID-001, DES-TDD-CYCLE-VOID-005
+ * @implements REQ-TDD-CYCLE-VOID-001, REQ-TDD-CYCLE-VOID-002, REQ-TDD-CYCLE-VOID-003, REQ-TDD-CYCLE-VOID-004, REQ-TDD-CYCLE-VOID-011, REQ-TDD-CYCLE-ARCHIVE-004
+ * @design DES-TDD-CYCLE-VOID-001, DES-TDD-CYCLE-VOID-005, DES-TDD-CYCLE-ARCHIVE-002
  */
 export async function voidTddCycle(root, testId, approver, reason) {
     return withEvidenceWriterLock(root, 'tdd void', () => voidTddCycleUnlocked(root, testId, approver, reason));
 }
+/** @id CODE-TDD-CYCLE-ARCHIVE-001
+ * @implements REQ-TDD-CYCLE-ARCHIVE-001 REQ-TDD-CYCLE-ARCHIVE-002 REQ-TDD-CYCLE-ARCHIVE-003 REQ-TDD-CYCLE-ARCHIVE-004 REQ-TDD-CYCLE-ARCHIVE-005
+ * @design DES-TDD-CYCLE-ARCHIVE-001 DES-TDD-CYCLE-ARCHIVE-002
+ */
+export async function archiveTddCycle(root, testId, approver, reason) {
+    return withEvidenceWriterLock(root, 'tdd archive', () => archiveTddCycleUnlocked(root, testId, approver, reason));
+}
 async function voidTddCycleUnlocked(root, testId, approver, reason) {
     if (!approver?.trim())
         throw new Error('An approver is required to void a TDD cycle.');
@@ -299,10 +716,12 @@ async function voidTddCycleUnlocked(root, testId, approver, reason) {
     const cycle = evidence.cycles.filter((entry) => entry.testId === testId).at(-1);
     if (!cycle)
         throw new Error(`No TDD cycle found for ${testId}.`);
-    if (cycle.green?.valid)
-        throw new Error(`${testId}'s latest cycle has a valid Green phase; only a dangling cycle can be voided.`);
     if (cycle.void)
         throw new Error(`${testId}'s latest cycle is already voided.`);
+    if (cycle.archive)
+        throw new Error(`${testId}'s latest cycle already carries a void or archive marker.`);
+    if (cycle.green?.valid)
+        throw new Error(`${testId}'s latest cycle has a valid Green phase; only a dangling cycle can be voided.`);
     if (!cycle.cycleId)
         throw new Error(`${testId} lacks a cycle ID; regenerate its evidence before voiding.`);
     if (!evidence.chain && evidence.cycles.some((entry) => entry !== cycle)) {
@@ -310,7 +729,7 @@ async function voidTddCycleUnlocked(root, testId, approver, reason) {
     }
     const order = await inspectEvidenceOrder(root);
     const earlierCycles = evidence.cycles.slice(0, evidence.cycles.indexOf(cycle)).filter((entry) => entry.testId === testId);
-    const eligibleFallback = earlierCycles.some((entry) => entry.red.valid && entry.green?.valid && !voidLinkage(evidence, order, entry).valid);
+    const eligibleFallback = earlierCycles.some((entry) => entry.red.valid && entry.green?.valid && !entry.void && !entry.archive);
     if (!eligibleFallback) {
         return {
             voided: false,
@@ -325,11 +744,72 @@ async function voidTddCycleUnlocked(root, testId, approver, reason) {
     await writeJson(root, '.musubix/evidence/tdd.json', evidence);
     return { voided: true, testId, cycleId: cycle.cycleId };
 }
+async function archiveTddCycleUnlocked(root, testId, approver, reason) {
+    if (!approver?.trim())
+        throw new Error('An approver is required to archive a TDD cycle.');
+    if (!reason?.trim())
+        throw new Error('A reason is required to archive a TDD cycle.');
+    const evidence = await loadTddEvidence(root);
+    if (!evidence)
+        throw new Error('No TDD evidence found.');
+    const cycle = evidence.cycles.filter((entry) => entry.testId === testId).at(-1);
+    if (!cycle)
+        throw new Error(`No TDD cycle found for ${testId}.`);
+    if (cycle.void || cycle.archive)
+        throw new Error(`${testId}'s latest cycle already carries a void or archive marker.`);
+    if (!cycle.cycleId)
+        throw new Error(`${testId} lacks a cycle ID; regenerate its evidence before archiving.`);
+    if (!evidence.chain && evidence.cycles.some((entry) => entry !== cycle)) {
+        throw new Error('Existing TDD evidence lacks an append-only hash chain; regenerate it before recording new phases.');
+    }
+    const record = {
+        phase: 'archive',
+        approver,
+        reason,
+        testId: cycle.testId,
+        cycleId: cycle.cycleId,
+        recordedAt: new Date().toISOString(),
+    };
+    record.order = (await appendEvidenceOrder(root, {
+        kind: 'tdd',
+        entityId: cycle.cycleId,
+        phase: 'archive',
+        testId: cycle.testId,
+    })).sequence;
+    cycle.archive = record;
+    appendChainRecord(evidence, cycle, 'archive', record);
+    await writeJson(root, '.musubix/evidence/tdd.json', evidence);
+    return { archived: true, testId, cycleId: cycle.cycleId };
+}
 export async function runTddPhase(root, phase, testId, requirementId, commandName, runner = runProcess) {
     return withEvidenceWriterLock(root, `tdd ${phase}`, () => runTddPhaseUnlocked(root, phase, testId, requirementId, commandName, runner));
 }
 async function runTddPhaseUnlocked(root, phase, testId, requirementId, commandName, runner) {
     const config = await loadConfig(root);
+    // Hoisted so both this check and the TDD_ADOPTION_PROJECT_WIDE warning
+    // logic below share one computation (same `.musubix/changes/CHANGE-\d+\.md`
+    // existence check gate.ts's own `hasChangeDocuments` formula uses).
+    const hasChangeDocuments = (await files(root)).some((path) => /^\.musubix\/changes\/CHANGE-\d+\.md$/.test(path));
+    /** @id CODE-TDD-GREEN-REQUIREMENT-SCOPING-003
+     * @implements REQ-TDD-GREEN-REQUIREMENT-SCOPING-003
+     * @design DES-TDD-GREEN-REQUIREMENT-SCOPING-002
+     * Runs strictly before every other existing `tdd red`/`tdd green`
+     * validation (the `red`-only design-approval check immediately below and
+     * REQ-002's cycle-matching check after `buildTrace`), and before any
+     * preflight command, test-command execution, or evidence/order-log write,
+     * so a staged-change phase-ordering mistake is rejected before it can
+     * corrupt the append-only TDD evidence chain (Issue #67).
+     */
+    if (hasChangeDocuments && (phase === 'red' || phase === 'green')) {
+        const changeEvidence = await loadChangeEvidence(root);
+        const precondition = changeRecordPhasePrecondition(changeEvidence, phase, requirementId);
+        if (!precondition.satisfied) {
+            const instruction = precondition.changeId
+                ? `change-record ${precondition.changeId} ${precondition.missingPhase} --requirement ${requirementId}`
+                : `a staged change must record design --requirement ${requirementId} first`;
+            throw new Error(`CHANGE_RECORD_PHASE_PRECONDITION: tdd ${phase} for ${requirementId} requires ${instruction} before it can be recorded.`);
+        }
+    }
     if (phase === 'red') {
         const domain = await resolveRequirementDomain(root, config.approval, requirementId);
         await requireApproval(root, 'design', config.approval, domain);
@@ -474,12 +954,11 @@ async function runTddPhaseUnlocked(root, phase, testId, requirementId, commandNa
                 .filter((edge) => edge.relation === 'verifies' && edge.to === requirement.id)
                 .map((edge) => edge.from);
             return !evidence.cycles.some((cycle) => cycle.requirementId === requirement.id
-                && verifiedTests.includes(cycle.testId)
+                && verifiedTests.includes(currentEffectiveTestId(cycle))
                 && cycle.red.valid
                 && cycle.green?.valid);
         })
             .map((requirement) => requirement.id);
-        const hasChangeDocuments = (await files(root)).some((path) => /^\.musubix\/changes\/CHANGE-\d+\.md$/.test(path));
         const alreadyRequired = config.requiredChecks.includes('tdd') || hasChangeDocuments;
         const uncoveredText = uncoveredIds.length
             ? `Other uncovered mandatory requirements: ${uncoveredIds.join(', ')}.`
@@ -528,10 +1007,14 @@ async function runTddPhaseUnlocked(root, phase, testId, requirementId, commandNa
     await writeJson(root, '.musubix/evidence/tdd.json', evidence);
     return result;
 }
+/** @id CODE-TDD-CYCLE-ARCHIVE-004
+ * @implements REQ-TDD-CYCLE-ARCHIVE-006 REQ-TDD-CYCLE-ARCHIVE-007 REQ-TDD-CYCLE-ARCHIVE-008 REQ-TDD-CYCLE-ARCHIVE-009 REQ-TDD-CYCLE-ARCHIVE-010 REQ-TDD-CYCLE-ARCHIVE-013
+ * @design DES-TDD-CYCLE-ARCHIVE-003 DES-TDD-CYCLE-ARCHIVE-004 DES-TDD-CYCLE-ARCHIVE-005
+ */
 export async function validateTddEvidence(root) {
     const evidence = await loadTddEvidence(root);
     if (!evidence?.cycles.length)
-        return { present: false, valid: false, diagnostics: [], cycles: 0, voided: [] };
+        return { present: false, valid: false, diagnostics: [], cycles: 0, voided: [], archived: [] };
     const diagnostics = [];
     const order = await inspectEvidenceOrder(root);
     diagnostics.push(...order.diagnostics);
@@ -553,17 +1036,17 @@ export async function validateTddEvidence(root) {
             if (recordSha256 !== chainRecordSha256(payload)) {
                 diagnostics.push(error('TDD_CHAIN_HASH_MISMATCH', `TDD chain record ${record.sequence} has an invalid SHA-256.`));
             }
-            const key = `${record.cycleId}:${record.phase}`;
+            const key = chainIdentity(record);
             if (records.has(key))
                 diagnostics.push(error('TDD_CHAIN_PHASE_DUPLICATE', `${key} appears more than once in the TDD chain.`));
             records.set(key, record);
         }
         for (const cycle of evidence.cycles) {
-            for (const phase of ['red', 'green', 'refactor', 'migrate', 'void']) {
+            for (const phase of ['red', 'green', 'refactor', 'void', 'archive']) {
                 const phaseEvidence = cycle[phase];
                 if (!phaseEvidence)
                     continue;
-                const key = `${cycle.cycleId ?? 'missing'}:${phase}`;
+                const key = chainIdentity({ cycleId: cycle.cycleId ?? 'missing', phase });
                 const record = records.get(key);
                 if (!record) {
                     diagnostics.push(error('TDD_CHAIN_PHASE_MISSING', `${cycle.testId}:${phase} is absent from the TDD hash chain.`, cycle.testPath));
@@ -578,6 +1061,28 @@ export async function validateTddEvidence(root) {
                 }
                 records.delete(key);
             }
+            for (const migration of migrationRecords(cycle)) {
+                const key = chainIdentity({
+                    cycleId: cycle.cycleId ?? 'missing',
+                    phase: 'migrate',
+                    mode: migrationMode(migration),
+                    ...(migration.oldTestId !== undefined ? { oldTestId: migration.oldTestId } : {}),
+                    ...(migration.newTestId !== undefined ? { newTestId: migration.newTestId } : {}),
+                });
+                const record = records.get(key);
+                if (!record) {
+                    diagnostics.push(error('TDD_CHAIN_PHASE_MISSING', `${cycle.testId}:migrate is absent from the TDD hash chain.`, cycle.testPath));
+                    continue;
+                }
+                if (record.requirementId !== cycle.requirementId
+                    || record.testId !== cycle.testId
+                    || record.testPath !== cycle.testPath
+                    || record.commandName !== cycle.commandName
+                    || record.phaseEvidenceSha256 !== digest(JSON.stringify(migration))) {
+                    diagnostics.push(error('TDD_CHAIN_PAYLOAD_MISMATCH', `${cycle.testId}:migrate does not match its immutable TDD chain record.`, cycle.testPath));
+                }
+                records.delete(key);
+            }
         }
         for (const record of records.values()) {
             diagnostics.push(error('TDD_CHAIN_ORPHAN', `TDD chain record ${record.sequence} has no matching cycle phase.`));
@@ -585,7 +1090,7 @@ export async function validateTddEvidence(root) {
     }
     const latestCycles = new Map();
     for (const cycle of evidence.cycles)
-        latestCycles.set(cycle.testId, cycle);
+        latestCycles.set(currentEffectiveTestId(cycle), cycle);
     /** @id CODE-TDD-SUPERSEDED-CYCLE-SCOPING-001
      * @implements REQ-TDD-SUPERSEDED-CYCLE-SCOPING-001
      */
@@ -593,11 +1098,12 @@ export async function validateTddEvidence(root) {
     {
         const cyclesByTest = new Map();
         for (const cycle of evidence.cycles) {
-            const list = cyclesByTest.get(cycle.testId);
+            const identity = currentEffectiveTestId(cycle);
+            const list = cyclesByTest.get(identity);
             if (list)
                 list.push(cycle);
             else
-                cyclesByTest.set(cycle.testId, [cycle]);
+                cyclesByTest.set(identity, [cycle]);
         }
         for (const cycles of cyclesByTest.values()) {
             for (let index = 0; index < cycles.length; index++) {
@@ -613,6 +1119,8 @@ export async function validateTddEvidence(root) {
      */
     const validlyVoidedCycles = new Set();
     const voided = [];
+    const validlyArchivedCycles = new Set();
+    const archived = [];
     for (const cycle of evidence.cycles) {
         if (!cycle.void)
             continue;
@@ -635,13 +1143,29 @@ export async function validateTddEvidence(root) {
             diagnostics.push(error('TDD_VOID_EVIDENCE_MALFORMED', linkage.reason, cycle.testPath));
         }
     }
+    for (const cycle of evidence.cycles) {
+        if (!cycle.archive)
+            continue;
+        const linkage = archiveLinkage(evidence, order, cycle);
+        if (linkage.valid) {
+            validlyArchivedCycles.add(cycle);
+            archived.push({
+                testId: cycle.testId,
+                cycleId: cycle.cycleId,
+                archive: { approver: cycle.archive.approver, reason: cycle.archive.reason, recordedAt: cycle.archive.recordedAt },
+            });
+        }
+        else {
+            diagnostics.push(error('TDD_ARCHIVE_EVIDENCE_MALFORMED', linkage.reason, cycle.testPath));
+        }
+    }
     const trace = await buildTrace(root, false);
     for (const requirement of trace.nodes.filter((node) => node.kind === 'requirement' && node.mandatory)) {
         const verifiedTests = trace.edges
             .filter((edge) => edge.relation === 'verifies' && edge.to === requirement.id)
             .map((edge) => edge.from);
         const covered = evidence.cycles.some((cycle) => cycle.requirementId === requirement.id
-            && verifiedTests.includes(cycle.testId)
+            && verifiedTests.includes(currentEffectiveTestId(cycle))
             && cycle.red.valid
             && cycle.green?.valid);
         if (!covered) {
@@ -671,45 +1195,57 @@ export async function validateTddEvidence(root) {
         if (cycle.refactor?.order !== undefined && cycle.green?.order !== undefined && cycle.refactor.order <= cycle.green.order) {
             diagnostics.push(error('TDD_ORDER_SEQUENCE', `${cycle.testId}:refactor is not after Green in monotonic evidence order.`, cycle.testPath));
         }
-        if (cycle.migrate) {
-            if (!cycle.cycleId || !Number.isInteger(cycle.migrate.order)) {
+        const migrations = migrationRecords(cycle);
+        for (const migration of migrations) {
+            if (!cycle.cycleId || !Number.isInteger(migration.order)) {
                 diagnostics.push(error('TDD_ORDER_MIGRATION_REQUIRED', `${cycle.testId}:migrate lacks monotonic order evidence; archive legacy evidence and regenerate the complete cycle instead of editing append-only records.`, cycle.testPath));
+                continue;
             }
-            else {
-                const record = evidenceOrderRecord(order.records, 'tdd', cycle.cycleId, 'migrate');
-                if (!record || record.sequence !== cycle.migrate.order) {
+            if (!migrationLinkageValid(order, evidence.chain, cycle, migration)) {
+                const orderRecord = evidenceOrderRecord(order.records, 'tdd', cycle.cycleId, 'migrate', migrationScope(migration));
+                if (!orderRecord || orderRecord.sequence !== migration.order) {
                     diagnostics.push(error('TDD_ORDER_MISMATCH', `${cycle.testId}:migrate does not match the monotonic evidence order log.`, cycle.testPath));
                 }
+                else {
+                    diagnostics.push(error('TDD_CHAIN_PAYLOAD_MISMATCH', `${cycle.testId}:migrate does not match its immutable TDD chain record.`, cycle.testPath));
+                }
             }
             const latestNonMigrateOrder = cycle.refactor?.valid ? cycle.refactor.order : cycle.green?.order;
-            if (cycle.migrate.order !== undefined && latestNonMigrateOrder !== undefined && cycle.migrate.order <= latestNonMigrateOrder) {
+            if (migration.order !== undefined && latestNonMigrateOrder !== undefined && migration.order <= latestNonMigrateOrder) {
                 diagnostics.push(error('TDD_ORDER_SEQUENCE', `${cycle.testId}:migrate is not after Green/Refactor in monotonic evidence order.`, cycle.testPath));
             }
-            if (!cycle.migrate.approver) {
+            if (!validlyArchivedCycles.has(cycle) && !migration.approver) {
                 diagnostics.push(error('TDD_LEGACY_OR_UNSCOPED_EVIDENCE', `${cycle.testId}:migrate lacks a recorded human approver.`, cycle.testPath));
             }
+            if (migrationMode(migration) === 'identifier' && (!migration.oldTestId || !migration.newTestId)) {
+                diagnostics.push(error('TDD_MIGRATE_EVIDENCE_MALFORMED', `${cycle.testId}:migrate lacks old/new test ID linkage.`, cycle.testPath));
+            }
         }
-        if (!supersededCycles.has(cycle) && !validlyVoidedCycles.has(cycle)
+        if (!supersededCycles.has(cycle) && !validlyVoidedCycles.has(cycle) && !validlyArchivedCycles.has(cycle)
             && (!cycle.red.scoped || !cycle.red.resultObserved || cycle.red.testStatus !== 'failed' || !cycle.red.reportSha256 || !cycle.red.sourceFingerprint || !cycle.red.executionId)) {
             diagnostics.push(error('TDD_LEGACY_OR_UNSCOPED_EVIDENCE', `${cycle.testId} lacks test-scoped execution provenance; archive the legacy cycle and regenerate it from a clean Red baseline: move .musubix/evidence/tdd.json aside and re-record every cycle with tdd red/green/refactor. There is no partial prune command; hand-editing the evidence is not supported.`, cycle.testPath));
         }
-        if (!supersededCycles.has(cycle) && !validlyVoidedCycles.has(cycle) && !cycle.red.valid)
+        if (!supersededCycles.has(cycle) && !validlyVoidedCycles.has(cycle) && !validlyArchivedCycles.has(cycle) && !cycle.red.valid)
             diagnostics.push(error('TDD_RED_MISSING', `${cycle.testId} has no valid failing Red phase; archive it and regenerate the complete cycle by moving .musubix/evidence/tdd.json aside and re-recording every cycle.`, cycle.testPath));
-        if (!supersededCycles.has(cycle) && !validlyVoidedCycles.has(cycle) && !cycle.green?.valid)
+        if (!supersededCycles.has(cycle) && !validlyVoidedCycles.has(cycle) && !validlyArchivedCycles.has(cycle) && !cycle.green?.valid)
             diagnostics.push(error('TDD_GREEN_MISSING', `${cycle.testId} has no valid passing Green phase; archive it and regenerate the complete cycle by moving .musubix/evidence/tdd.json aside and re-recording every cycle.`, cycle.testPath));
         if (cycle.green?.valid) {
-            if (!cycle.green.scoped || !cycle.green.resultObserved || cycle.green.testStatus !== 'passed' || !cycle.green.reportSha256 || !cycle.green.sourceFingerprint || !cycle.green.executionId) {
+            if (!validlyArchivedCycles.has(cycle)
+                && (!cycle.green.scoped || !cycle.green.resultObserved || cycle.green.testStatus !== 'passed' || !cycle.green.reportSha256 || !cycle.green.sourceFingerprint || !cycle.green.executionId)) {
                 diagnostics.push(error('TDD_LEGACY_OR_UNSCOPED_EVIDENCE', `${cycle.testId} Green lacks test-scoped execution provenance.`, cycle.testPath));
             }
-            const actualLatest = latestCycles.get(cycle.testId);
+            const effectiveTestId = currentEffectiveTestId(cycle);
+            const actualLatest = latestCycles.get(effectiveTestId);
             // Effective-latest resolution for TDD_TEST_STALE (REQ-TDD-CYCLE-VOID-010)
             // is implemented by the shared `effectiveLatestCycle` helper, annotated
             // as CODE-TDD-CYCLE-VOID-004 above.
             const isStaleTarget = actualLatest === cycle
-                || (actualLatest !== undefined && validlyVoidedCycles.has(actualLatest)
-                    && effectiveLatestCycle(evidence, order, validlyVoidedCycles, cycle.testId, actualLatest) === cycle);
+                ? !validlyArchivedCycles.has(cycle)
+                : (actualLatest !== undefined && validlyVoidedCycles.has(actualLatest)
+                    && effectiveLatestCycle(evidence, order, validlyVoidedCycles, validlyArchivedCycles, effectiveTestId, actualLatest) === cycle
+                    && !validlyArchivedCycles.has(cycle));
             if (isStaleTarget) {
-                const test = trace.nodes.find((node) => node.kind === 'test' && node.id === cycle.testId);
+                const test = trace.nodes.find((node) => node.kind === 'test' && node.id === effectiveTestId);
                 const current = test ? await testFingerprint(root, test) : undefined;
                 const candidates = [];
                 if (cycle.green.order !== undefined)
@@ -717,23 +1253,26 @@ export async function validateTddEvidence(root) {
                 if (cycle.refactor?.valid && cycle.refactor.order !== undefined) {
                     candidates.push({ order: cycle.refactor.order, fingerprint: cycle.refactor.testFingerprint });
                 }
-                if (cycle.migrate?.order !== undefined)
-                    candidates.push({ order: cycle.migrate.order, fingerprint: cycle.migrate.toFingerprint });
+                for (const migration of migrations) {
+                    if (migration.order !== undefined)
+                        candidates.push({ order: migration.order, fingerprint: migration.toFingerprint });
+                }
                 const latest = candidates.sort((a, b) => b.order - a.order)[0];
                 if (latest && current !== latest.fingerprint)
-                    diagnostics.push(error('TDD_TEST_STALE', `${cycle.testId} changed after its latest passing TDD phase.`, cycle.testPath));
+                    diagnostics.push(error('TDD_TEST_STALE', `${effectiveTestId} changed after its latest passing TDD phase.`, cycle.testPath));
             }
-            if (cycle.red.sourceFingerprint === cycle.green.sourceFingerprint) {
+            if (!validlyArchivedCycles.has(cycle) && cycle.red.sourceFingerprint === cycle.green.sourceFingerprint) {
                 diagnostics.push(error('TDD_GREEN_WITHOUT_SOURCE_CHANGE', `${cycle.testId} has no non-test project change between Red and Green.`, cycle.testPath));
             }
         }
-        if (cycle.green && cycle.green.commandSha256 !== cycle.red.commandSha256) {
+        if (!validlyArchivedCycles.has(cycle) && cycle.green && cycle.green.commandSha256 !== cycle.red.commandSha256) {
             diagnostics.push(error('TDD_COMMAND_CHANGED', `${cycle.testId} used a different command between Red and Green.`, cycle.testPath));
         }
-        if (cycle.refactor && cycle.refactor.commandSha256 !== cycle.red.commandSha256) {
+        if (!validlyArchivedCycles.has(cycle) && cycle.refactor && cycle.refactor.commandSha256 !== cycle.red.commandSha256) {
             diagnostics.push(error('TDD_COMMAND_CHANGED', `${cycle.testId} used a different command during Refactor.`, cycle.testPath));
         }
-        if (cycle.refactor?.valid && (!cycle.refactor.scoped || !cycle.refactor.resultObserved || cycle.refactor.testStatus !== 'passed' || !cycle.refactor.reportSha256 || !cycle.refactor.sourceFingerprint || !cycle.refactor.executionId)) {
+        if (cycle.refactor?.valid && !validlyArchivedCycles.has(cycle)
+            && (!cycle.refactor.scoped || !cycle.refactor.resultObserved || cycle.refactor.testStatus !== 'passed' || !cycle.refactor.reportSha256 || !cycle.refactor.sourceFingerprint || !cycle.refactor.executionId)) {
             diagnostics.push(error('TDD_LEGACY_OR_UNSCOPED_EVIDENCE', `${cycle.testId} Refactor lacks test-scoped execution provenance.`, cycle.testPath));
         }
     }
@@ -754,6 +1293,6 @@ export async function validateTddEvidence(root) {
                 hashes.set(key, cycle);
         }
     }
-    return { present: true, valid: !diagnostics.length, diagnostics, cycles: evidence.cycles.length, voided };
+    return { present: true, valid: !diagnostics.length, diagnostics, cycles: evidence.cycles.length, voided, archived };
 }
 //# sourceMappingURL=tdd.js.map