@planu/cli 4.11.7 → 4.11.9

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/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/session-safeguard/checkpoint-runner.js

@@ -1,6 +1,5 @@
 import { detectUnpushedCommits } from './unpushed-detector.js';
 import { flushBuffer } from './learnings-buffer.js';
-import { checkSessionContextFreshness } from './session-context-freshness.js';
 import { safeAutopush } from './autopush.js';
 const WARN_UNPUSHED_HOURS = 2;
 /** Regenerate session-context.md (fire-and-forget, best-effort). */
@@ -44,12 +43,9 @@ function buildHumanSummary(sessionContextRefreshed, learningsFlushed, unpushed,
 /** Run a full session checkpoint: regen context, flush buffer, detect/push unpushed. */
 export async function runCheckpoint(options) {
     const { projectPath, dryRun = false, autopush = false, autopushBranches } = options;
-    // Check freshness and regenerate if stale (or always refresh on explicit call)
-    const freshness = await checkSessionContextFreshness(projectPath);
-    let sessionContextRefreshed = false;
-    if (freshness.stale && !dryRun) {
-        sessionContextRefreshed = await regenerateSessionContext(projectPath);
-    }
+    // This runner backs the explicit checkpoint tool, so refresh even when the
+    // file mtime is recent: package releases can change semantic state instantly.
+    const sessionContextRefreshed = dryRun ? false : await regenerateSessionContext(projectPath);
     // Flush learnings buffer
     let learningsFlushed = 0;
     if (!dryRun) {

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 {};

package/dist/engine/triagier/classifier.js

@@ -1,8 +1,7 @@
-// engine/triagier/classifier.ts — SPEC-726: Haiku-backed intent classifier
+// engine/triagier/classifier.ts — SPEC-726: intent classifier
 //
-// If an LLM provider is available, calls Haiku for classification.
-// Falls back to a deterministic heuristic classifier on timeout, error, or
-// when no provider is configured.
+// Uses deterministic classification today.
+// A model-backed classifier may be wired later without changing the public interface.
 import { runWithGuard } from './cost-guard.js';
 import { routeToNextStep } from './router.js';
 /**
@@ -67,16 +66,16 @@ export function heuristicClassify(description) {
 const GUARD_FALLBACK_RESULT = {
     kind: 'feature-spec',
     confidence: 0.5,
-    rationale: 'GUARD_FALLBACK',
+    rationale: 'Deterministic fallback classification used because the guarded classifier path did not complete in time.',
     nextStep: { tool: 'elicit_requirements', mode: 'interactive' },
 };
 // ---------------------------------------------------------------------------
-// LLM-backed classifier (stub — uses heuristic until Haiku adapter is wired)
+// Guarded classifier path (currently deterministic)
 // ---------------------------------------------------------------------------
 /**
- * Try to classify using an LLM provider (Haiku-class).
- * Currently implemented as a deterministic heuristic because no Haiku API
- * adapter is wired in src/engine/llm-providers/. When a Haiku transport is
+ * Try to classify through the guarded classifier path.
+ * Currently implemented as a deterministic heuristic because no model transport
+ * is wired in src/engine/llm-providers/. When a model-backed transport is
  * available, replace this stub with a real call. The interface is unchanged.
  *
  * Architectural note: the spec says "If LLM provider unavailable, use
@@ -85,9 +84,7 @@ const GUARD_FALLBACK_RESULT = {
  * correctly when a real LLM call is wired in.
  */
 // eslint-disable-next-line @typescript-eslint/require-await -- async signature required by cost-guard interface
-async function tryLlmClassify(input) {
-    // TODO: Wire real Haiku call here when llm-providers has a text-generation adapter.
-    // For now: deterministic heuristic (same result, no API cost).
+async function tryGuardedClassify(input) {
     return heuristicClassify(input.description);
 }
 // ---------------------------------------------------------------------------
@@ -95,8 +92,8 @@ async function tryLlmClassify(input) {
 // ---------------------------------------------------------------------------
 /**
  * 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 async function classifyIntent(input) {
     // Respect any hint provided by the caller
@@ -109,7 +106,7 @@ export async function classifyIntent(input) {
             nextStep: routeToNextStep(hintKind),
         };
     }
-    const guardResult = await runWithGuard(() => tryLlmClassify(input), {
+    const guardResult = await runWithGuard(() => tryGuardedClassify(input), {
         wallClockMs: 5_000,
         maxOutputTokens: 1_500,
     });