@planu/cli 5.7.5 → 5.7.7

package/dist/tools/tool-registry/group-quality-compliance.js

@@ -3,8 +3,6 @@ import { z } from 'zod';
 import { safeGoverned, safeTracked } from '../safe-handler.js';
 import { projectIdSchema, withProject } from '../tool-registry-helpers.js';
 import { t } from '../../i18n/index.js';
-import { makeDeprecationStub } from './deprecated-stubs.js';
-import { registerFromEntries } from '../tool-entry.js';
 // ── Compliance (register-compliance-tools.ts) ─────────────────────────────────
 import { handleCheckComplianceUnified, handleCheckComplianceLegacyShim, handleComplianceScoreReportShim, handleComplianceGapAnalysisShim, handleVerifySpecComplianceShim, } from '../compliance-unified-handler.js';
 import { handleConfigureCompliance } from '../compliance-handler.js';
@@ -42,7 +40,7 @@ import { handleDefineLintRule, handleListLintRules, handleRunSpecLint, handleDel
 // ── Readiness (register-readiness-tools.ts) ───────────────────────────────────
 import { handleCheckReadiness } from '../check-readiness.js';
 import { handlePackageHandoff } from '../package-handoff.js';
-import { CheckReadinessOutputSchema, SpecIdSchema } from '../schemas/index.js';
+import { CheckReadinessOutputSchema, SpecIdSchema, PackageHandoffOutputSchema, } from '../schemas/index.js';
 // ── Approval (register-approval-tools.ts) ────────────────────────────────────
 import { handleConfigureApprovalPolicy, handleApproveSpec, handleRequestChanges, handleApprovalStatus, handleIssueReviewerToken, } from '../approval-handler.js';
 // ── SPEC-961: Architecture lint ─────────────────────────────────────────────
@@ -831,7 +829,7 @@ export function registerQualityComplianceGroupTools(s) {
         description: t('tools.check_readiness.description'),
         inputSchema: {
             ...projectIdSchema,
-            specId: SpecIdSchema.describe('Spec ID to evaluate'),
+            specId: SpecIdSchema.describe('Spec ID to evaluate. Must match pattern ^SPEC-\\d+$, max 50 characters.'),
             mode: z
                 .enum(['strict', 'lenient'])
                 .optional()
@@ -952,7 +950,15 @@ export function registerQualityComplianceGroupTools(s) {
         description: t('tools.package_handoff.description'),
         inputSchema: {
             ...projectIdSchema,
-            specId: SpecIdSchema.describe('Spec ID to generate handoff package for'),
+            specId: SpecIdSchema.describe('Spec ID to generate handoff package for. Must match pattern ^SPEC-\\d+$, max 50 characters.'),
+        },
+        outputSchema: PackageHandoffOutputSchema,
+        annotations: {
+            title: 'Submit Durable Handoff Packaging',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
         },
     }, safeGoverned('package_handoff', withProject((args) => handlePackageHandoff(args))));
     // ── Approval ─────────────────────────────────────────────────────────────────
@@ -1041,31 +1047,35 @@ export function registerQualityComplianceGroupTools(s) {
         description: 'Request changes on a spec. The spec is moved back to draft and prior approvals are cleared. ' +
             'A comment explaining the required changes is mandatory.',
         inputSchema: {
-            projectPath: z.string().min(1).max(4096).describe('Absolute path to the project root.'),
+            projectPath: z
+                .string()
+                .min(1)
+                .max(4096)
+                .describe('Absolute path to the project root. Max 4096 characters.'),
             specId: z
                 .string()
                 .min(1)
                 .max(500)
-                .describe('Spec ID to request changes on (e.g. SPEC-042).'),
+                .describe('Spec ID to request changes on (e.g. SPEC-042). Max 500 characters.'),
             reviewer: z
                 .string()
                 .trim()
                 .min(1)
                 .max(500)
-                .describe('Name, email, or username of the reviewer requesting changes.'),
+                .describe('Name, email, or username of the reviewer requesting changes. Max 500 characters.'),
             comment: z
                 .string()
                 .trim()
                 .min(1)
                 .max(10_000)
-                .describe('Required explanation of what needs to change before re-approval.'),
+                .describe('Required explanation of what needs to change before re-approval. Max 10000 characters.'),
             role: z
                 .string()
                 .trim()
                 .min(1)
                 .max(500)
                 .optional()
-                .describe('Role of the reviewer (e.g. "tech-lead", "qa").'),
+                .describe('Role of the reviewer (e.g. "tech-lead", "qa"). Max 500 characters.'),
         },
         annotations: { title: 'Request Changes', destructiveHint: true },
     }, safeGoverned('request_changes', (args) => handleRequestChanges(args)));
@@ -1188,10 +1198,5 @@ export function registerQualityComplianceGroupTools(s) {
                 .describe('Absolute path to the project root. Used to detect language and test framework.'),
         },
     }, safeTracked('run_mutation_hints', async (args) => handleRunMutationHints({ projectPath: args.projectPath })));
-    // ── SPEC-331: Multi-Agent Orchestration Plan (migrated to skill, SPEC-658) ────
-    // Tool stays registered for backward compat; callers receive a deprecation notice.
-    registerFromEntries(s, [
-        makeDeprecationStub('generate_orchestration_plan', '.claude/skills/parallel-safe.md', 'parallel-safe'),
-    ]);
 }
 //# sourceMappingURL=group-quality-compliance.js.map

package/dist/tools/tool-registry-helpers.js

@@ -5,12 +5,16 @@ import { resolveProjectId, missingProjectIdError } from './resolve-project-id.js
 // ── Shared schema fragments ──────────────────────────────────────────────────
 /** Standard dual projectId/projectPath optional Zod fields. Spread into inputSchema. */
 export const projectIdSchema = {
-    projectId: z.string().max(500).optional().describe('Project ID hash. Prefer projectPath.'),
+    projectId: z
+        .string()
+        .max(500)
+        .optional()
+        .describe('Project ID hash. Prefer projectPath. Max 500 characters.'),
     projectPath: z
         .string()
         .max(4096)
         .optional()
-        .describe('Absolute path to project root. Derives projectId automatically.'),
+        .describe('Absolute path to project root. Derives projectId automatically. Max 4096 characters.'),
 };
 /**
  * Wraps a handler that requires a resolved projectId.

package/dist/tools/update-status/batch.js

@@ -90,6 +90,22 @@ export async function handleUpdateStatusBatch(input) {
             },
         };
     }
+    if (input.status === 'approved' || input.status === 'implementing') {
+        const missingIds = uniqueSpecIds.filter((specId) => input.evidence?.[specId] === undefined);
+        if (missingIds.length > 0) {
+            const fixHint = `Supply an evidence entry for each of: ${missingIds.join(', ')}.`;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `BATCH_EVIDENCE_REQUIRED: Missing model-routing evidence for: ${missingIds.join(', ')}.\nFix: ${fixHint}`,
+                    },
+                ],
+                isError: true,
+                structuredContent: { error: 'BATCH_EVIDENCE_REQUIRED', code: 422, missingIds, fixHint },
+            };
+        }
+    }
     const updated = [];
     const skipped = [];
     const failed = [];
@@ -98,6 +114,7 @@ export async function handleUpdateStatusBatch(input) {
     try {
         for (const specId of uniqueSpecIds) {
             const result = await handleUpdateStatus({
+                ...input.evidence?.[specId],
                 specId,
                 status: input.status,
                 projectId: resolved.projectId,

package/dist/tools/update-status/dod-gates.js

@@ -48,6 +48,7 @@ export const implementationReviewTemplate = lazyTemplate(() => renderSchemaSkele
         schema_version: HANDOFF_ARTIFACT_TEMPLATE_SCHEMA_VERSION,
         reviewedAt: HANDOFF_ARTIFACT_TEMPLATE_TIMESTAMP,
         'reviewer.agent': 'planu-implementation-reviewer',
+        'reviewer.sessionId': '<your-session-id>',
     },
 }));
 export const validationReportTemplate = lazyTemplate(() => renderSchemaSkeleton(ValidationReportV1Schema, {
@@ -738,9 +739,21 @@ export async function checkImplementationReviewGate(specId, projectId, _force) {
                 specId,
                 error: 'implementation_review_self_review',
                 message: 'The implementation reviewer must be a different identity from the implementer. Self-review is blocked.',
-                blockers: [`Implementer and reviewer share the identity "${verified.implementingActor}".`],
+                blockers: [
+                    `Implementer and reviewer share the session identity "${verified.implementingActor}" (verified.implementingActor).`,
+                ],
                 fixHint: 'Have a different, independent agent write the implementation review evidence, then retry done.',
             });
+        case 'identity_unverifiable':
+            return implementationReviewGateError({
+                specId,
+                error: 'implementation_review_identity_unverifiable',
+                message: 'Reviewer independence is unverifiable. reviewer.sessionId is missing, blank, or a placeholder, or the implementing actor could not be resolved from the transition log.',
+                blockers: [
+                    `reviewer.sessionId was ${JSON.stringify(verified.review?.reviewer.sessionId ?? null)}. implementingActor was ${JSON.stringify(verified.implementingActor ?? null)}.`,
+                ],
+                fixHint: 'Have planu-implementation-reviewer record its real session identity in reviewer.sessionId, and have the orchestrator pass a real actor on update_status(implementing), then retry done.',
+            });
         case 'unreadable':
             return implementationReviewGateError({
                 specId,

package/dist/tools/update-status/done-receipt-verifier.d.ts

@@ -1,6 +1,28 @@
+import { RuntimeDatabase } from '../../storage/runtime-db.js';
 import type { DurableJobRecord } from '../../types/durable-job.js';
+import type { ValidationReceipt, ValidationReceiptBindings, ValidationReceiptVerification } from '../../types/validation-receipt.js';
+import { ValidationReceiptStore } from '../../engine/validation/validation-receipt.js';
 import { type ValidationFreshnessLease } from '../../engine/validation/validation-freshness.js';
 export { doneReceiptBindingsDifferOnlyInEvidence } from '../../engine/validation/durable-validation.js';
+export type CurrentBindingsResolution = {
+    ok: true;
+    currentBindings: ValidationReceiptBindings;
+    verification: ValidationReceiptVerification;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function resolveVerifiedCurrentBindings(args: {
+    database: RuntimeDatabase;
+    store: ValidationReceiptStore;
+    identity: {
+        projectId: string;
+        specId: string;
+        projectPath?: string;
+        specPath?: string;
+    };
+    receipt: ValidationReceipt;
+}): Promise<CurrentBindingsResolution>;
 export type DoneReceiptVerifier = (identity: {
     projectId: string;
     specId: string;

package/dist/tools/update-status/done-receipt-verifier.js

@@ -59,6 +59,58 @@ import { ValidationReceiptStore, LOCAL_VALIDATION_RECEIPT_ISSUER, createValidati
 import { beginValidationFreshnessBarrier, bindValidationFreshnessLease, captureValidationFreshnessLease, closeValidationFreshnessLease, } from '../../engine/validation/validation-freshness.js';
 import { computeDurableValidationBindings, doneReceiptBindingsDifferOnlyInEvidence, toValidationReceiptBindings, } from '../../engine/validation/durable-validation.js';
 export { doneReceiptBindingsDifferOnlyInEvidence } from '../../engine/validation/durable-validation.js';
+export async function resolveVerifiedCurrentBindings(args) {
+    const { database, store, identity, receipt } = args;
+    let currentBindings = await store.readCurrentBindings(identity.projectId, identity.specId);
+    if (!currentBindings) {
+        if (!identity.projectPath || !identity.specPath) {
+            return { ok: false, reason: 'stale-bindings' };
+        }
+        const projectPath = identity.projectPath;
+        const specPath = isAbsolute(identity.specPath)
+            ? identity.specPath
+            : join(projectPath, identity.specPath);
+        const observed = await computeDurableValidationBindings({
+            canonicalProjectId: identity.projectId,
+            specId: identity.specId,
+            projectPath,
+            specPath,
+        });
+        const observedBindings = toValidationReceiptBindings(observed.bindings, observed.artifactDigests);
+        const isExactMatch = Boolean(receipt.bindings) &&
+            JSON.stringify(observedBindings) === JSON.stringify(receipt.bindings);
+        if (!isExactMatch &&
+            !doneReceiptBindingsDifferOnlyInEvidence(observedBindings, receipt.bindings)) {
+            return { ok: false, reason: 'stale-bindings' };
+        }
+        await store.projectCurrentBindings(observedBindings);
+        currentBindings = observedBindings;
+    }
+    const { authority } = createValidationReceiptAuthority({
+        database,
+        workspaceId: 'global',
+        projectId: identity.projectId,
+        issuerId: LOCAL_VALIDATION_RECEIPT_ISSUER,
+    });
+    let verification = await authority.verifyCurrent({
+        ...currentBindings,
+        projectId: identity.projectId,
+        specId: identity.specId,
+    });
+    const evidenceOnlyDrift = verification.reason === 'stale-bindings' &&
+        doneReceiptBindingsDifferOnlyInEvidence(currentBindings, receipt.bindings);
+    if (evidenceOnlyDrift) {
+        verification = await authority.verifyCurrent({
+            ...receipt.bindings,
+            projectId: identity.projectId,
+            specId: identity.specId,
+        });
+    }
+    if (!verification.valid) {
+        return { ok: false, reason: verification.reason ?? 'invalid-receipt' };
+    }
+    return { ok: true, currentBindings, verification };
+}
 export function completedJobPublishesReceipt(job, receiptId) {
     if (job?.state !== 'completed' || !job.result || typeof job.result !== 'object') {
         return false;
@@ -83,33 +135,11 @@ export async function verifyCurrentDoneReceipt(identity) {
         if (receipt.issuer !== LOCAL_VALIDATION_RECEIPT_ISSUER) {
             return { valid: false, reason: 'unknown-issuer' };
         }
-        const currentBindings = await store.readCurrentBindings(identity.projectId, identity.specId);
-        if (!currentBindings) {
-            return { valid: false, reason: 'stale-bindings' };
-        }
-        const { authority } = createValidationReceiptAuthority({
-            database,
-            workspaceId: 'global',
-            projectId: identity.projectId,
-            issuerId: LOCAL_VALIDATION_RECEIPT_ISSUER,
-        });
-        let verification = await authority.verifyCurrent({
-            ...currentBindings,
-            projectId: identity.projectId,
-            specId: identity.specId,
-        });
-        const evidenceOnlyDrift = verification.reason === 'stale-bindings' &&
-            doneReceiptBindingsDifferOnlyInEvidence(currentBindings, receipt.bindings);
-        if (evidenceOnlyDrift) {
-            verification = await authority.verifyCurrent({
-                ...receipt.bindings,
-                projectId: identity.projectId,
-                specId: identity.specId,
-            });
-        }
-        if (!verification.valid) {
-            return verification;
+        const resolution = await resolveVerifiedCurrentBindings({ database, store, identity, receipt });
+        if (!resolution.ok) {
+            return { valid: false, reason: resolution.reason };
         }
+        const { currentBindings, verification } = resolution;
         const receiptJobExists = database
             .listJobs(identity.projectId, 'global')
             .some((job) => completedJobPublishesReceipt(job, receipt.receiptId));

package/dist/tools/update-status/evidence-gate.js

@@ -63,12 +63,12 @@ import { extractAcceptanceCriteriaTexts } from '../../engine/spec-format/accepta
 import { formatKeyValue } from '../output-formatter.js';
 import { RuntimeDatabase } from '../../storage/runtime-db.js';
 import { resolveStorageLayout } from '../../storage/storage-layout.js';
-import { ValidationReceiptStore, LOCAL_VALIDATION_RECEIPT_ISSUER, createValidationReceiptAuthority, readCurrentValidationReceipt, } from '../../engine/validation/validation-receipt.js';
+import { ValidationReceiptStore, LOCAL_VALIDATION_RECEIPT_ISSUER, readCurrentValidationReceipt, } from '../../engine/validation/validation-receipt.js';
 import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
 import { captureValidationFreshnessLease } from '../../engine/validation/validation-freshness.js';
 import { computeDurableValidationBindings, toValidationReceiptBindings, } from '../../engine/validation/durable-validation.js';
 import { checkReconciliationFreshness } from '../../engine/evidence-gates/reconciliation-freshness.js';
-import { doneReceiptBindingsDifferOnlyInEvidence } from './done-receipt-verifier.js';
+import { doneReceiptBindingsDifferOnlyInEvidence, resolveVerifiedCurrentBindings, } from './done-receipt-verifier.js';
 import { extractCanonicalFileOwnership } from '../../engine/handoff-packager.js';
 import { generateTaskPlanSkeleton, writeEvidenceSkeleton, } from '../../engine/evidence-gates/evidence-skeletons.js';
 import { extractSection } from '../../engine/spec-format/markdown-sections.js';
@@ -127,10 +127,13 @@ export async function checkLifecycleEvidenceTransitionGate(args) {
         })
         : null;
     if (receiptResult && !receiptResult.ok) {
+        const message = receiptResult.reason === 'stale-bindings'
+            ? 'stale-bindings: validation inputs changed after the receipt was issued. Re-run validate, then retry done.'
+            : receiptResult.reason;
         return evidenceGateError({
             specId: args.specId,
             transition: args.transition,
-            issues: [{ code: 'evidence_provenance_invalid', message: receiptResult.reason }],
+            issues: [{ code: 'evidence_provenance_invalid', message }],
             requiredContractKinds: [],
         });
     }
@@ -244,25 +247,11 @@ async function readVerifiedCurrentReceipt(identity) {
             if (receipt.issuer !== LOCAL_VALIDATION_RECEIPT_ISSUER) {
                 return { ok: false, reason: 'unknown-issuer' };
             }
-            const currentBindings = await store.readCurrentBindings(identity.projectId, identity.specId);
-            if (!currentBindings) {
-                return { ok: false, reason: 'stale-bindings' };
-            }
-            const { authority } = createValidationReceiptAuthority({
-                database,
-                workspaceId: 'global',
-                projectId: identity.projectId,
-                issuerId: LOCAL_VALIDATION_RECEIPT_ISSUER,
-            });
-            const verification = await authority.verifyCurrent({
-                ...currentBindings,
-                projectId: identity.projectId,
-                specId: identity.specId,
-            });
-            if (!verification.valid) {
-                return { ok: false, reason: verification.reason ?? 'invalid-receipt' };
+            const resolution = await resolveVerifiedCurrentBindings({ database, store, identity, receipt });
+            if (!resolution.ok) {
+                return { ok: false, reason: resolution.reason };
             }
-            if (!(await currentBindingsAreFresh(identity, currentBindings))) {
+            if (!(await currentBindingsAreFresh(identity, resolution.currentBindings))) {
                 return { ok: false, reason: 'stale-bindings' };
             }
             return { ok: true, receipt };

package/dist/tools/update-status/file-sync.d.ts

@@ -13,6 +13,7 @@ export interface FrontmatterSyncWarning {
 export declare function syncSpecFiles(updatedSpec: Spec, _currentStatus: SpecStatus, newStatus: SpecStatus, projectPath?: string, qualityWarnings?: readonly string[]): Promise<{
     warning?: FrontmatterSyncWarning;
     title?: string;
+    driftReconciled?: boolean;
 }>;
 export declare function tryReconcile(newStatus: string, specId: string, projectId: string): Promise<string | null>;
 /**

package/dist/tools/update-status/file-sync.js

@@ -131,6 +131,7 @@ function assertSpecBodyIntegrity(args) {
         throw new Error(`SPEC_INTEGRITY_WRITE_FAILED: refusing to write ${args.specId} because update_status(${args.newStatus}) would shrink spec.md body by ${String(lost)} characters without an explicit migration marker.`);
     }
 }
+const FROZEN_TERMINAL_STATUSES = ['done', 'discarded'];
 export async function syncSpecFiles(updatedSpec, _currentStatus, newStatus, projectPath, qualityWarnings = []) {
     let warning;
     let refreshedTitle;
@@ -148,6 +149,11 @@ export async function syncSpecFiles(updatedSpec, _currentStatus, newStatus, proj
                 parsedMetadata.title !== updatedSpec.title) {
                 refreshedTitle = parsedMetadata.title;
             }
+            if (FROZEN_TERMINAL_STATUSES.includes(newStatus) && parsedMetadata.status === newStatus) {
+                return refreshedTitle
+                    ? { title: refreshedTitle, driftReconciled: true }
+                    : { driftReconciled: true };
+            }
             const { updateFrontmatterField } = await import('../../engine/frontmatter-parser.js');
             let updatedContent = updateFrontmatterField(specContent, 'status', newStatus);
             if (qualityWarnings.length > 0) {

package/dist/tools/update-status/index.d.ts

@@ -1,5 +1,6 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { UpdateStatusInput, ToolResult, Actuals, Spec, ReconciliationInvocationContext } from '../../types/index.js';
+import { type FrontmatterSyncWarning } from './file-sync.js';
 import { type GapScore } from '../../engine/code-scanner/index.js';
 type LifecycleAuthorityRoute = {
     route: 'ordinary';
@@ -27,6 +28,11 @@ export declare function synthesizeActuals(actuals: Partial<Actuals> | undefined,
 export declare function computeTransitionRootBinding(projectPath: string): string;
 /** Recover durable post-commit work for every registered project after server startup. */
 export declare function recoverPendingPostCommitTasksAtStartup(): Promise<void>;
+export declare function resolveTransitionEventAudit(driftReconciled: boolean, baseReason: string | undefined, baseMeta: Record<string, unknown>): {
+    reason: string | undefined;
+    meta: Record<string, unknown>;
+};
+export declare function buildDriftAppendFailureWarning(specId: string, specPath: string | null, error: unknown): FrontmatterSyncWarning;
 export declare function handleUpdateStatus(params: UpdateStatusInput, server?: McpServer): Promise<ToolResult>;
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/tools/update-status/index.js

@@ -140,17 +140,6 @@ function buildAutoAdvancePlan(currentStatus, targetStatus) {
         stepsExecuted,
     };
 }
-/**
- * SPEC-1356 (T-A3): auto-generate traceability-matrix.json when it is missing,
- * BEFORE the evidence gate reads it for a 'done' transition. Never overwrites an
- * existing artifact. Tolerates every internal failure (falls through to the
- * ordinary evidence gate, which will report the real missing-evidence error).
- *
- * When autofill actually writes a fresh file, the newly-created evidence has not
- * been bound by validate's durable receipt yet, so this blocks once with a clear
- * "re-run validate" message instead of letting a stale-relative-to-receipt
- * traceability matrix slide through the done gates silently.
- */
 async function runTraceabilityAutofillGate(args) {
     try {
         const specPath = isAbsolute(args.spec.specPath) || !args.projectPath
@@ -158,7 +147,7 @@ async function runTraceabilityAutofillGate(args) {
             : join(args.projectPath, args.spec.specPath);
         const specBody = await readSpecContent(specPath);
         if (specBody === null) {
-            return null;
+            return { warning: null };
         }
         const result = await autofillTraceabilityMatrix({
             projectId: args.projectId,
@@ -168,29 +157,16 @@ async function runTraceabilityAutofillGate(args) {
             ownSpecMdPath: toRepoRelativePath(args.spec.specPath, args.projectPath),
         });
         if (!result.written) {
-            return null;
+            return { warning: null };
         }
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `traceability-matrix.json was auto-generated at ${result.path} (${String(result.rowCount)} rows). ` +
-                        'Run validate to bind this evidence, then retry update_status(done).',
-                },
-            ],
-            isError: true,
-            structuredContent: {
-                error: 'traceability_matrix_autofilled',
-                code: 422,
-                context: { specId: args.specId, path: result.path, rowCount: result.rowCount },
-                fixHint: 'Run validate so the new traceability-matrix.json is bound, then retry done.',
-            },
+            warning: `traceability-matrix.json auto-generated (${String(result.rowCount)} rows) and bound via evidence-only rebind`,
         };
     }
     catch (error) {
         // reliability-optional: EVIDENCE_AUTOFILL_GATE — falls through to the ordinary evidence gate
         reportClassifiedDegradation('EVIDENCE_AUTOFILL_GATE', error);
-        return null;
+        return { warning: null };
     }
 }
 /**
@@ -603,6 +579,18 @@ function buildPersistenceFailureResponse(args) {
         },
     };
 }
+export function resolveTransitionEventAudit(driftReconciled, baseReason, baseMeta) {
+    return driftReconciled
+        ? { reason: 'drift-reconciliation', meta: { ...baseMeta, driftReconciled: true } }
+        : { reason: baseReason, meta: baseMeta };
+}
+export function buildDriftAppendFailureWarning(specId, specPath, error) {
+    return {
+        specId,
+        specPath,
+        reason: `drift-reconciliation audit marker not recorded: ${error instanceof Error ? error.message : String(error)}`,
+    };
+}
 async function commitTransitionWithNarrowLock(args) {
     return withApprovalSpecLock(args.projectPath, args.specId, async () => {
         const lock = await acquireLock(args.projectPath, args.specId, {
@@ -671,7 +659,12 @@ async function commitTransitionWithNarrowLock(args) {
                     updatedSpec.title = syncResult.title;
                     await specStore.updateSpec(args.projectId, args.specId, { title: syncResult.title });
                 }
-                return { ok: true, transitionRecord, updatedSpec };
+                return {
+                    ok: true,
+                    transitionRecord,
+                    updatedSpec,
+                    driftReconciled: syncResult.driftReconciled === true,
+                };
             }
             try {
                 await rollbackTransitionSpec(transitionRecord);
@@ -1011,14 +1004,7 @@ export async function handleUpdateStatus(params, server) {
                             sddRoutingGate.gateResults.sddModelRouting = 'forced';
                         }
                     }
-                    // SPEC-1356 (T-A3): auto-generate traceability-matrix.json before the
-                    // evidence gate below reads it, so a spec never fails 'done' purely
-                    // because nobody hand-wrote the traceability artifact. Never overwrites
-                    // an existing file. Freshness caveat: when autofill actually writes a
-                    // new file, its evidence has not yet been bound by validate's durable
-                    // receipt, so we block once and ask the caller to re-run validate
-                    // rather than risk certifying stale bindings. See evidence-autofill.ts
-                    // for the full rationale.
+                    let traceabilityAutofillWarning = null;
                     if (plannedStatuses.includes('done') &&
                         !shouldSkipGateForExplicitLegacyHarness('evidence')) {
                         const autofillGate = await runTraceabilityAutofillGate({
@@ -1027,9 +1013,7 @@ export async function handleUpdateStatus(params, server) {
                             projectId,
                             projectPath: effectiveGatePath,
                         });
-                        if (autofillGate) {
-                            return autofillGate;
-                        }
+                        traceabilityAutofillWarning = autofillGate.warning;
                     }
                     // SPEC-1054: BDD/SDD evidence gates. Non-trivial specs must carry
                     // Discovery before approval, task-plan before implementation, and
@@ -1327,7 +1311,9 @@ export async function handleUpdateStatus(params, server) {
                         : undefined;
                     const qualityWarningsToWrite = newStatus === 'approved'
                         ? [...readinessGate.qualityWarnings, ...formatGate.qualityWarnings]
-                        : [];
+                        : newStatus === 'done' && traceabilityAutofillWarning
+                            ? [...new Set([...(spec.qualityWarnings ?? []), traceabilityAutofillWarning])]
+                            : [];
                     const persistence = await commitTransitionWithNarrowLock({
                         projectPath: effectiveGatePath ?? projectId,
                         projectId,
@@ -1351,7 +1337,7 @@ export async function handleUpdateStatus(params, server) {
                     if (!persistence.ok) {
                         return persistence.error;
                     }
-                    const { transitionRecord, updatedSpec } = persistence;
+                    const { transitionRecord, updatedSpec, driftReconciled } = persistence;
                     if (updatedSpec.title && updatedSpec.title !== spec.title) {
                         spec.title = updatedSpec.title;
                     }
@@ -1361,6 +1347,11 @@ export async function handleUpdateStatus(params, server) {
                     if (newStatus === 'done') {
                         await runTransitionMaintenance(transitionProjectPath);
                     }
+                    const transitionEventAudit = resolveTransitionEventAudit(driftReconciled, params.reason, {
+                        ...transitionEvidenceMeta,
+                        transitionId,
+                        committedAt,
+                    });
                     await appendTransitionEvent({
                         projectId,
                         specId,
@@ -1368,14 +1359,17 @@ export async function handleUpdateStatus(params, server) {
                         from: originalStatus,
                         to: newStatus,
                         actor,
-                        reason: params.reason,
+                        reason: transitionEventAudit.reason,
                         sessionId: params.sessionId,
                         modelId: params.modelId,
                         gateResults: sddRoutingGate.gateResults,
-                        meta: { ...transitionEvidenceMeta, transitionId, committedAt },
+                        meta: transitionEventAudit.meta,
                     }).catch((error) => {
                         /* reliability-optional: SDD_ROUTING_REPORT — never block committed acknowledgement */
                         reportClassifiedDegradation('SDD_ROUTING_REPORT', error);
+                        if (driftReconciled) {
+                            frontmatterSyncWarnings.push(buildDriftAppendFailureWarning(specId, updatedSpec.specPath, error));
+                        }
                     });
                     if (reverseTransition && params.reason) {
                         await appendTransitionEvent({
@@ -1536,6 +1530,7 @@ export async function handleUpdateStatus(params, server) {
                         depGuard: depGuardResult,
                         // SPEC-698: surface frontmatter sync failures in the response
                         frontmatterSyncWarnings: frontmatterSyncWarnings.length > 0 ? frontmatterSyncWarnings : null,
+                        qualityWarnings: qualityWarningsToWrite.length > 0 ? qualityWarningsToWrite : null,
                         updatedAt: updatedSpec.updatedAt,
                         message: ti('tools.update_status.success', { specId, status: newStatus }),
                         ...(collector.hasEntries() ? { autopilotSummary: collector.getMessages() } : {}),

package/dist/tools/update-status-actions.js

@@ -71,13 +71,8 @@ export async function runImplementingSideEffects(projectId, specId, transitionPr
             });
         }
         if (!branchResult.isError) {
-            try {
-                const branchData = JSON.parse(branchResult.content[0]?.text ?? '{}');
-                autoBranch = branchData.branchName;
-            }
-            catch {
-                // ignore parse error
-            }
+            const branchName = branchResult.structuredContent?.branchName;
+            autoBranch = typeof branchName === 'string' ? branchName : undefined;
         }
     }
     // -------------------------------------------------------------------------