@planu/cli 4.11.6 → 4.11.8

package/dist/engine/dogfooding/runtime-gap-detector.js

@@ -0,0 +1,386 @@
+import { constants } from 'node:fs';
+import { open, realpath, stat } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+const REPEATED_SIGNAL_THRESHOLD = 2;
+const GIT_TIMEOUT_MS = 1_500;
+const GIT_MAX_BUFFER_BYTES = 64 * 1024;
+const ARTIFACTS = [
+    { label: 'package.json', relativePath: 'package.json', maxBytes: 64 * 1024, json: true },
+    {
+        label: 'session-context',
+        relativePath: join('planu', 'session-context.md'),
+        maxBytes: 256 * 1024,
+        json: false,
+    },
+    {
+        label: 'session',
+        relativePath: join('planu', 'session.json'),
+        maxBytes: 256 * 1024,
+        json: true,
+    },
+];
+const SIGNAL_RULES = [
+    {
+        signature: 'forced-lifecycle:force-status',
+        title: 'Repeated forceStatus lifecycle bypasses',
+        severity: 'high',
+        nextAction: 'create_spec',
+        patterns: [
+            /^\s*(?:[-*]\s*)?(?:tool|action|event|call)(?:\s+|\s*:\s*)update_status\b[^\n]{0,160}\bforceStatus\b\s*[:=]\s*true\b/gim,
+            /^\s*(?:[-*]\s*)?(?:tool|action|event|call)(?:\s+|\s*:\s*)forceStatus\b\s*[:=]\s*true\b[^\n]{0,160}\bupdate_status\b/gim,
+            /^\s*(?:[-*]\s*)?(?:tool|action|event|call)(?:\s+|\s*:\s*)forced status transition\b/gim,
+        ],
+        structuredBooleanKey: 'forceStatus',
+    },
+    {
+        signature: 'forced-lifecycle:force-approve',
+        title: 'Repeated forceApprove lifecycle bypasses',
+        severity: 'high',
+        nextAction: 'create_spec',
+        patterns: [
+            /^\s*(?:[-*]\s*)?(?:tool|action|event|call)(?:\s+|\s*:\s*)approve_spec\b[^\n]{0,160}\bforceApprove\b\s*[:=]\s*true\b/gim,
+            /^\s*(?:[-*]\s*)?(?:tool|action|event|call)(?:\s+|\s*:\s*)forceApprove\b\s*[:=]\s*true\b[^\n]{0,160}\bapprove_spec\b/gim,
+            /^\s*(?:[-*]\s*)?(?:tool|action|event|call)(?:\s+|\s*:\s*)force-approved lifecycle transition\b/gim,
+        ],
+        structuredBooleanKey: 'forceApprove',
+    },
+    {
+        signature: 'guard-fallback-visible',
+        title: 'Repeated guarded fallback behavior',
+        severity: 'medium',
+        nextAction: 'create_spec',
+        patterns: [/\bGUARD_FALLBACK\b/gi, /\bguard(?:ed)? fallback\b/gi],
+    },
+    {
+        signature: 'placeholder-output-visible',
+        title: 'Repeated placeholder-facing output',
+        severity: 'medium',
+        nextAction: 'create_spec',
+        patterns: [
+            /\/\/\s*TO[D]O\b/gi,
+            /\braw TO[D]O placeholder\b/gi,
+            /\bplaceholder(?:-facing)? output\b/gi,
+            /\bempty placeholder comparison\b/gi,
+        ],
+    },
+    {
+        signature: 'validate-runtime-mismatch',
+        title: 'Repeated validation and runtime mismatch',
+        severity: 'high',
+        nextAction: 'create_spec',
+        patterns: [
+            /\bvalidat(?:e|ed|ion)[^\n]{0,80}\bruntime (?:mismatch|failed|failure|error|timeout)\b/gi,
+            /\bruntime mismatch[^\n]{0,80}\bvalidat(?:e|ed|ion)\b/gi,
+        ],
+    },
+    {
+        signature: 'manual-recovery-loop',
+        title: 'Repeated manual recovery steps',
+        severity: 'medium',
+        nextAction: 'submit_feedback',
+        patterns: [
+            /\bmanual recovery\b/gi,
+            /\brepair_frontmatter_drift\b/gi,
+            /\breconcile_spec\b/gi,
+            /\bretry(?:ing)? update_status\b/gi,
+            /\brecoveryRequired\b/gi,
+        ],
+    },
+];
+function isWithin(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+async function loadArtifact(projectRoot, artifact) {
+    const candidate = resolve(projectRoot, artifact.relativePath);
+    if (!isWithin(projectRoot, candidate)) {
+        return null;
+    }
+    let handle;
+    try {
+        const canonicalBeforeOpen = await realpath(candidate);
+        if (!isWithin(projectRoot, canonicalBeforeOpen)) {
+            return null;
+        }
+        handle = await open(candidate, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const handleStat = await handle.stat();
+        if (!handleStat.isFile() || handleStat.size > artifact.maxBytes) {
+            return null;
+        }
+        // Re-resolve after opening and verify the path still names the opened inode.
+        // This closes parent-symlink traversal and path-swap races without trusting
+        // the lexical project-relative path alone.
+        const canonicalAfterOpen = await realpath(candidate);
+        if (!isWithin(projectRoot, canonicalAfterOpen)) {
+            return null;
+        }
+        const pathStat = await stat(canonicalAfterOpen);
+        if (pathStat.dev !== handleStat.dev || pathStat.ino !== handleStat.ino) {
+            return null;
+        }
+        const content = await handle.readFile({ encoding: 'utf8' });
+        if (!artifact.json) {
+            return { label: artifact.label, content, json: null };
+        }
+        try {
+            return { label: artifact.label, content, json: JSON.parse(content) };
+        }
+        catch {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+function countMatches(content, patterns) {
+    let count = 0;
+    for (const pattern of patterns) {
+        pattern.lastIndex = 0;
+        count += [...content.matchAll(pattern)].length;
+    }
+    return count;
+}
+function countStructuredBoolean(value, key) {
+    if (Array.isArray(value)) {
+        return value.reduce((total, item) => total + countStructuredBoolean(item, key), 0);
+    }
+    if (typeof value !== 'object' || value === null) {
+        return 0;
+    }
+    let count = 0;
+    for (const [entryKey, entryValue] of Object.entries(value)) {
+        if (/^(?:docs?|documentation|examples?|schema|inputSchema)$/i.test(entryKey)) {
+            continue;
+        }
+        if (entryKey === key && entryValue === true) {
+            count += 1;
+        }
+        count += countStructuredBoolean(entryValue, key);
+    }
+    return count;
+}
+function addRepeatedSignals(runtimeArtifacts, findings) {
+    for (const rule of SIGNAL_RULES) {
+        const sourceCounts = runtimeArtifacts
+            .map((artifact) => ({
+            label: artifact.label,
+            count: countMatches(artifact.content, rule.patterns) +
+                (rule.structuredBooleanKey
+                    ? countStructuredBoolean(artifact.json, rule.structuredBooleanKey)
+                    : 0),
+        }))
+            .filter((entry) => entry.count > 0);
+        const occurrences = sourceCounts.reduce((total, entry) => total + entry.count, 0);
+        if (occurrences < REPEATED_SIGNAL_THRESHOLD) {
+            continue;
+        }
+        findings.set(rule.signature, {
+            signature: rule.signature,
+            title: rule.title,
+            severity: rule.severity,
+            nextAction: rule.nextAction,
+            occurrences,
+            evidence: [
+                `${String(occurrences)} occurrence(s) across ${String(sourceCounts.length)} allowlisted runtime artifact(s)`,
+            ],
+        });
+    }
+}
+function addRepeatedToolFailures(runtimeArtifacts, findings) {
+    const counts = new Map();
+    for (const artifact of runtimeArtifacts) {
+        for (const match of artifact.content.matchAll(/(?:^|[^a-z0-9_-])-\s*[✗x]\s+([a-z0-9_-]+)/gi)) {
+            const tool = match[1];
+            if (!tool) {
+                continue;
+            }
+            const current = counts.get(tool) ?? { occurrences: 0, sources: new Set() };
+            current.occurrences += 1;
+            current.sources.add(artifact.label);
+            counts.set(tool, current);
+        }
+    }
+    for (const [tool, aggregate] of counts) {
+        if (aggregate.occurrences < REPEATED_SIGNAL_THRESHOLD) {
+            continue;
+        }
+        findings.set(`repeated-tool-failure:${tool}`, {
+            signature: `repeated-tool-failure:${tool}`,
+            title: `Repeated ${tool} failures during dogfooding`,
+            severity: 'high',
+            nextAction: 'create_spec',
+            occurrences: aggregate.occurrences,
+            evidence: [
+                `${tool} failed ${String(aggregate.occurrences)} time(s) across ${String(aggregate.sources.size)} allowlisted runtime artifact(s)`,
+            ],
+        });
+    }
+}
+function packageVersion(artifact) {
+    if (!artifact || typeof artifact.json !== 'object' || artifact.json === null) {
+        return null;
+    }
+    const version = artifact.json.version;
+    return typeof version === 'string' ? version : null;
+}
+function sessionVersion(runtimeArtifacts) {
+    for (const artifact of runtimeArtifacts) {
+        const match = /\*\*Version\*\*:\s*([0-9]+\.[0-9]+\.[0-9]+)/.exec(artifact.content);
+        if (match?.[1]) {
+            return match[1];
+        }
+        if (typeof artifact.json === 'object' && artifact.json !== null) {
+            const version = artifact.json.version;
+            if (typeof version === 'string') {
+                return version;
+            }
+        }
+    }
+    return null;
+}
+function runGit(projectRoot, args) {
+    return new Promise((resolveResult) => {
+        execFile('git', [...args], {
+            cwd: projectRoot,
+            encoding: 'utf8',
+            timeout: GIT_TIMEOUT_MS,
+            maxBuffer: GIT_MAX_BUFFER_BYTES,
+            windowsHide: true,
+        }, (error, stdout) => {
+            resolveResult(error ? null : stdout.trim());
+        });
+    });
+}
+async function detectBranchDrift(projectRoot, findings) {
+    const refs = [
+        'refs/heads/main',
+        'refs/remotes/origin/main',
+        'refs/heads/develop',
+        'refs/remotes/origin/develop',
+        'refs/heads/release',
+        'refs/remotes/origin/release',
+    ];
+    const values = await Promise.all(refs.map((ref) => runGit(projectRoot, ['rev-parse', '--verify', ref])));
+    const resolved = new Map(refs.map((ref, index) => [ref, values[index] ?? null]));
+    const remoteMainSha = resolved.get('refs/remotes/origin/main');
+    const localMainSha = resolved.get('refs/heads/main');
+    const mainSha = remoteMainSha ?? localMainSha;
+    if (!mainSha) {
+        return false;
+    }
+    for (const branch of ['develop', 'release']) {
+        const local = resolved.get(`refs/heads/${branch}`);
+        const remote = resolved.get(`refs/remotes/origin/${branch}`);
+        if (remoteMainSha && remote && remote !== remoteMainSha) {
+            const signature = `remote-mirror-stale:${branch}`;
+            findings.set(signature, {
+                signature,
+                title: `Remote ${branch} mirror is stale`,
+                severity: 'high',
+                nextAction: 'create_spec',
+                occurrences: 1,
+                evidence: [`origin/${branch} does not match authoritative origin/main`],
+            });
+        }
+        if (local && local !== mainSha) {
+            const signature = `local-mirror-stale:${branch}`;
+            findings.set(signature, {
+                signature,
+                title: `Local ${branch} mirror is stale`,
+                severity: 'medium',
+                nextAction: 'create_spec',
+                occurrences: 1,
+                evidence: [
+                    `Local ${branch} does not match ${remoteMainSha ? 'authoritative origin/main' : 'local main'}`,
+                ],
+            });
+        }
+        else if (!local && remote) {
+            const signature = `local-mirror-missing:${branch}`;
+            findings.set(signature, {
+                signature,
+                title: `Local ${branch} mirror is missing`,
+                severity: 'medium',
+                nextAction: 'create_spec',
+                occurrences: 1,
+                evidence: [`Local ${branch} is missing while origin/${branch} exists`],
+            });
+        }
+    }
+    return true;
+}
+export async function analyzeRuntimeDogfooding(projectPath) {
+    let projectRoot;
+    try {
+        projectRoot = await realpath(resolve(projectPath));
+    }
+    catch {
+        return {
+            status: 'insufficient_evidence',
+            findings: [],
+            analyzedSources: [],
+            unavailableSources: ARTIFACTS.map((artifact) => artifact.label),
+        };
+    }
+    const loaded = await Promise.all(ARTIFACTS.map((artifact) => loadArtifact(projectRoot, artifact)));
+    const artifacts = loaded.filter((artifact) => artifact !== null);
+    const analyzedSources = artifacts.map((artifact) => artifact.label);
+    const unavailableSources = ARTIFACTS.filter((_, index) => loaded[index] === null).map((artifact) => artifact.label);
+    const runtimeArtifacts = artifacts.filter((artifact) => artifact.label === 'session-context' || artifact.label === 'session');
+    const findings = new Map();
+    addRepeatedSignals(runtimeArtifacts, findings);
+    addRepeatedToolFailures(runtimeArtifacts, findings);
+    const currentVersion = packageVersion(artifacts.find((item) => item.label === 'package.json'));
+    const persistedVersion = sessionVersion(runtimeArtifacts);
+    if (currentVersion && persistedVersion && currentVersion !== persistedVersion) {
+        findings.set('session-version-drift', {
+            signature: 'session-version-drift',
+            title: 'Persisted session version drifted from the current package version',
+            severity: 'medium',
+            nextAction: 'submit_feedback',
+            occurrences: 1,
+            evidence: ['Persisted session version does not match package.json'],
+        });
+    }
+    const gitEvidenceAvailable = await detectBranchDrift(projectRoot, findings);
+    if (gitEvidenceAvailable) {
+        analyzedSources.push('git-local-refs');
+    }
+    else {
+        unavailableSources.push('git-local-refs');
+    }
+    const normalizedFindings = [...findings.values()].sort((a, b) => {
+        const rank = { high: 0, medium: 1, low: 2 };
+        return rank[a.severity] - rank[b.severity] || a.title.localeCompare(b.title);
+    });
+    if (normalizedFindings.length > 0) {
+        return {
+            status: 'findings',
+            findings: normalizedFindings,
+            analyzedSources,
+            unavailableSources,
+        };
+    }
+    const hasCompleteRuntimeEvidence = runtimeArtifacts.some((artifact) => artifact.label === 'session-context') &&
+        runtimeArtifacts.some((artifact) => artifact.label === 'session');
+    if (!hasCompleteRuntimeEvidence || !gitEvidenceAvailable) {
+        return {
+            status: 'insufficient_evidence',
+            findings: [],
+            analyzedSources,
+            unavailableSources,
+        };
+    }
+    return {
+        status: 'no_actionable_gaps',
+        findings: [],
+        analyzedSources,
+        unavailableSources,
+    };
+}
+//# sourceMappingURL=runtime-gap-detector.js.map

package/dist/engine/figma/visual-qa.d.ts

@@ -12,6 +12,7 @@ export interface VisualQAResult {
     figmaImageUrl: string;
     screenshotUrl: string;
     comparedAt: string;
+    comparisonMode: 'pixel-diff' | 'evidence-only';
     diffs: VisualDiffEntry[];
     criticalCount: number;
     warningCount: number;
@@ -26,7 +27,7 @@ export interface VisualQASummary {
     validatedAt: string;
 }
 export declare function exportFigmaFrameImage(fileKey: string, nodeId: string, accessToken: string): Promise<string>;
-export declare function createVisualQAResult(specId: string, nodeId: string, figmaImageUrl: string, screenshotUrl: string, diffs: VisualDiffEntry[]): VisualQAResult;
+export declare function createVisualQAResult(specId: string, nodeId: string, figmaImageUrl: string, screenshotUrl: string, diffs: VisualDiffEntry[], comparisonMode?: 'pixel-diff' | 'evidence-only'): VisualQAResult;
 export declare function buildPlaceholderDiff(_screenshotUrl: string, _figmaImageUrl: string): VisualDiffEntry[];
 export declare function formatVisualQAReport(results: VisualQAResult[]): string;
 export declare function buildSummary(results: VisualQAResult[], totalSpecs: number): VisualQASummary;

package/dist/engine/figma/visual-qa.js

@@ -21,7 +21,7 @@ export async function exportFigmaFrameImage(fileKey, nodeId, accessToken) {
 // ---------------------------------------------------------------------------
 // createVisualQAResult — build a VisualQAResult from diffs
 // ---------------------------------------------------------------------------
-export function createVisualQAResult(specId, nodeId, figmaImageUrl, screenshotUrl, diffs) {
+export function createVisualQAResult(specId, nodeId, figmaImageUrl, screenshotUrl, diffs, comparisonMode = 'pixel-diff') {
     const criticalCount = diffs.filter((d) => d.severity === 'critical').length;
     const warningCount = diffs.filter((d) => d.severity === 'warning').length;
     const infoCount = diffs.filter((d) => d.severity === 'info').length;
@@ -31,18 +31,18 @@ export function createVisualQAResult(specId, nodeId, figmaImageUrl, screenshotUr
         figmaImageUrl,
         screenshotUrl,
         comparedAt: new Date().toISOString(),
+        comparisonMode,
         diffs,
         criticalCount,
         warningCount,
         infoCount,
-        passed: criticalCount === 0,
+        passed: comparisonMode === 'pixel-diff' && criticalCount === 0,
     };
 }
 // ---------------------------------------------------------------------------
 // buildPlaceholderDiff — placeholder for pixel-level image comparison
 // ---------------------------------------------------------------------------
 export function buildPlaceholderDiff(_screenshotUrl, _figmaImageUrl) {
-    // TODO: Integrate with canvas/Playwright for pixel-level comparison
     return [];
 }
 // ---------------------------------------------------------------------------
@@ -55,7 +55,7 @@ export function formatVisualQAReport(results) {
     const header = '| Spec | Status | Critical | Warnings | Compared At |';
     const separator = '|------|--------|---------|---------|------------|';
     const rows = results.map((r) => {
-        const status = r.passed ? '✅ Pass' : '❌ Fail';
+        const status = r.comparisonMode === 'evidence-only' ? '⚠ Evidence only' : r.passed ? '✅ Pass' : '❌ Fail';
         const date = r.comparedAt.slice(0, 10);
         return `| ${r.specId} | ${status} | ${r.criticalCount} | ${r.warningCount} | ${date} |`;
     });
@@ -65,11 +65,12 @@ export function formatVisualQAReport(results) {
 // buildSummary — aggregate summary across all results
 // ---------------------------------------------------------------------------
 export function buildSummary(results, totalSpecs) {
+    const validatedResults = results.filter((result) => result.comparisonMode === 'pixel-diff');
     return {
         totalSpecs,
-        specsValidated: results.length,
-        specsWithCritical: results.filter((r) => r.criticalCount > 0).length,
-        specsNeverValidated: totalSpecs - results.length,
+        specsValidated: validatedResults.length,
+        specsWithCritical: validatedResults.filter((r) => r.criticalCount > 0).length,
+        specsNeverValidated: Math.max(0, totalSpecs - validatedResults.length),
         validatedAt: new Date().toISOString(),
     };
 }

package/dist/engine/git-safe-input.d.ts

@@ -0,0 +1,6 @@
+export declare function isSafeGitRef(value: string): boolean;
+export declare function assertSafeGitRef(value: string, label?: string): void;
+export declare function isSafeGitDiffRange(value: string): boolean;
+export declare function assertSafeGitDiffRange(value: string): void;
+export declare function assertPositivePrNumber(value: number): void;
+//# sourceMappingURL=git-safe-input.d.ts.map

package/dist/engine/git-safe-input.js

@@ -0,0 +1,41 @@
+const SAFE_GIT_REF_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._/@{}:+~-]{0,200}$/;
+function hasShellMetacharacters(value) {
+    return /[\s`$;&|<>\\\n\r]/.test(value);
+}
+export function isSafeGitRef(value) {
+    return (value.length > 0 &&
+        SAFE_GIT_REF_PATTERN.test(value) &&
+        !value.startsWith('-') &&
+        !value.includes('..') &&
+        !hasShellMetacharacters(value));
+}
+export function assertSafeGitRef(value, label = 'git ref') {
+    if (!isSafeGitRef(value)) {
+        throw new Error(`Invalid ${label}. Use a canonical commit hash or git ref without whitespace or shell metacharacters.`);
+    }
+}
+export function isSafeGitDiffRange(value) {
+    if (value.length === 0 || hasShellMetacharacters(value)) {
+        return false;
+    }
+    if (value.includes('...')) {
+        const parts = value.split('...');
+        return parts.length === 2 && parts.every((part) => part !== '' && isSafeGitRef(part));
+    }
+    if (value.includes('..')) {
+        const parts = value.split('..');
+        return parts.length === 2 && parts.every((part) => part !== '' && isSafeGitRef(part));
+    }
+    return isSafeGitRef(value);
+}
+export function assertSafeGitDiffRange(value) {
+    if (!isSafeGitDiffRange(value)) {
+        throw new Error('Invalid commitRange. Use a canonical git ref or a safe range like base..head or base...head.');
+    }
+}
+export function assertPositivePrNumber(value) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error('Invalid prNumber. Use a positive integer pull request number.');
+    }
+}
+//# sourceMappingURL=git-safe-input.js.map

package/dist/engine/qa-gate.js

@@ -5,6 +5,7 @@ import { readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { resolveProjectCommandPlan } from '../tools/validate-runtime.js';
 const TIMEOUT_MS = 120_000;
+const MAX_OUTPUT_BUFFER_BYTES = 64 * 1024 * 1024;
 const QA_FINGERPRINT_FILES = [
     'package.json',
     'pnpm-lock.yaml',
@@ -30,7 +31,7 @@ function runCheck(name, command, args, cwd) {
         cwd,
         timeout: TIMEOUT_MS,
         encoding: 'utf-8',
-        maxBuffer: 2 * 1024 * 1024,
+        maxBuffer: MAX_OUTPUT_BUFFER_BYTES,
     });
     const durationMs = Date.now() - start;
     const passed = result.status === 0 && !result.error;

package/dist/engine/spec-state-machine/transition-spec.d.ts

@@ -12,9 +12,19 @@ export interface TransitionContext {
     viaSync?: boolean;
     /** Optional reason supplied by the LLM (forceStatus / reverse transition). */
     reason?: string;
+    /** Non-status fields committed atomically with the status mutation. */
+    updates?: Omit<Partial<Spec>, 'status'>;
+    /** Optional work scheduled after the durable transition boundary. */
+    pendingBackgroundActions?: readonly string[];
+    /** Snapshot used by lifecycle gates; the store rejects intervening mutations. */
+    expectedSpec?: Spec;
 }
 export interface TransitionRecord {
+    projectId: string;
+    specId: string;
     spec: Spec;
+    previousSpec: Spec;
+    transitionId: string;
     fromStatus: SpecStatus;
     toStatus: SpecStatus;
     trigger: TransitionTrigger;
@@ -29,7 +39,12 @@ export interface TransitionRecord {
  * is responsible for running all gates (DoD, validate, QA, security, etc.) BEFORE
  * invoking transitionSpec. transitionSpec never runs gates itself.
  *
- * Callable ONLY from `src/tools/update-status/index.ts`.
+ * Callable only from the lifecycle status orchestrator.
  */
 export declare function transitionSpec(projectId: string, specId: string, newStatus: SpecStatus, ctx: TransitionContext): Promise<TransitionRecord>;
+/**
+ * Restore the exact pre-transition snapshot after paired persistence fails.
+ * The update_status caller must still hold the per-spec cross-process lock.
+ */
+export declare function rollbackTransitionSpec(record: TransitionRecord): Promise<Spec>;
 //# sourceMappingURL=transition-spec.d.ts.map

package/dist/engine/spec-state-machine/transition-spec.js

@@ -12,23 +12,38 @@ import { specStore } from '../../storage/index.js';
  * is responsible for running all gates (DoD, validate, QA, security, etc.) BEFORE
  * invoking transitionSpec. transitionSpec never runs gates itself.
  *
- * Callable ONLY from `src/tools/update-status/index.ts`.
+ * Callable only from the lifecycle status orchestrator.
  */
 export async function transitionSpec(projectId, specId, newStatus, ctx) {
-    const before = await specStore.getSpec(projectId, specId);
+    const before = ctx.expectedSpec ?? (await specStore.getSpecFresh(projectId, specId));
     if (!before) {
         throw new Error(`Spec ${specId} not found in project ${projectId}`);
     }
     // Use the internal-only write path that bypasses the status guard
-    const after = await specStore.__internalSetStatus(projectId, specId, newStatus);
+    const after = await specStore.__internalSetStatus(projectId, specId, newStatus, ctx.updates, ctx.pendingBackgroundActions, { status: before.status, updatedAt: before.updatedAt });
+    const receipt = after.statusHistory?.at(-1);
+    if (!receipt?.transitionId) {
+        throw new Error(`Transition receipt was not persisted for ${specId}`);
+    }
     return {
+        projectId,
+        specId,
         spec: after,
+        previousSpec: before,
+        transitionId: receipt.transitionId,
         fromStatus: before.status,
         toStatus: newStatus,
         trigger: ctx.trigger,
         actor: ctx.actor,
         viaSync: ctx.viaSync ?? false,
-        timestamp: new Date().toISOString(),
+        timestamp: receipt.changedAt,
     };
 }
+/**
+ * Restore the exact pre-transition snapshot after paired persistence fails.
+ * The update_status caller must still hold the per-spec cross-process lock.
+ */
+export async function rollbackTransitionSpec(record) {
+    return specStore.__internalRestoreSpecSnapshot(record.projectId, record.specId, record.previousSpec, record.spec);
+}
 //# sourceMappingURL=transition-spec.js.map

package/dist/engine/triagier/classifier.d.ts

@@ -19,8 +19,8 @@ interface HeuristicResult {
 export declare function heuristicClassify(description: string): HeuristicResult;
 /**
  * Classify the intent of a user request into a TriageKind.
- * Wraps the LLM call (or heuristic) in a cost guard (5s wall-clock).
- * On guard trip, returns a safe fallback (feature-spec, confidence 0.5, rationale GUARD_FALLBACK).
+ * Wraps the guarded classifier path in a cost guard (5s wall-clock).
+ * On guard trip, returns a safe deterministic fallback.
  */
 export declare function classifyIntent(input: TriageRequestInput): Promise<TriageResult>;
 export {};