@planu/cli 3.9.7 → 3.9.8

package/dist/engine/handoff-packager.js

@@ -1,5 +1,7 @@
 // engine/handoff-packager.ts — Assembles handoff context package for AI agents (SPEC-039)
-import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import { stripFrontmatter } from './frontmatter-parser.js';
 // ── Parsing helpers ──────────────────────────────────────────────────────────
 async function safeReadFile(path) {
@@ -41,11 +43,37 @@ function extractCriteria(huContent) {
     if (!huContent) {
         return [];
     }
+    const bddBlocks = extractBddCriteria(huContent);
+    if (bddBlocks.length > 0) {
+        return bddBlocks;
+    }
     return huContent
         .split('\n')
         .filter((line) => /^- \[[ x]\]/.test(line.trim()))
         .map((line) => line.trim().replace(/^- \[[ x]\]\s*/, ''));
 }
+function extractBddCriteria(content) {
+    const criteria = [];
+    let current = [];
+    for (const rawLine of content.split('\n')) {
+        const trimmed = rawLine.trim().replace(/^-+\s*/, '');
+        if (/^(GIVEN|WHEN|THEN|AND)\b/i.test(trimmed)) {
+            if (/^GIVEN\b/i.test(trimmed) && current.length > 0) {
+                criteria.push(current.join(' / '));
+                current = [];
+            }
+            current.push(trimmed);
+        }
+        else if (current.length > 0 && trimmed === '') {
+            criteria.push(current.join(' / '));
+            current = [];
+        }
+    }
+    if (current.length > 0) {
+        criteria.push(current.join(' / '));
+    }
+    return criteria.filter((criterion) => /GIVEN\b/i.test(criterion) && /WHEN\b/i.test(criterion) && /THEN\b/i.test(criterion));
+}
 function extractFilesFromFicha(fichaContent) {
     if (!fichaContent) {
         return { toModify: [], toCreate: [] };
@@ -88,6 +116,35 @@ function extractFilesFromFicha(fichaContent) {
     }
     return { toModify, toCreate };
 }
+function extractBacktickedFiles(content) {
+    const files = new Set();
+    const matches = content.matchAll(/`([^`\n]+\.(?:ts|tsx|js|jsx|mjs|cjs|json|md|yml|yaml|sh|css|scss|html))`/g);
+    for (const match of matches) {
+        const filePath = match[1]?.trim();
+        if (filePath && !filePath.includes(' ')) {
+            files.add(filePath);
+        }
+    }
+    return [...files];
+}
+function extractLinesByKeywords(content, keywords) {
+    return content
+        .split('\n')
+        .map((line) => line.trim().replace(/^[-*]\s*/, ''))
+        .filter((line) => line.length > 0 && keywords.test(line))
+        .slice(0, 12);
+}
+function extractOperationalSections(content, spec) {
+    return {
+        testPlan: extractLinesByKeywords(content, /\b(test|typecheck|lint|vitest|playwright|verification|validate|pnpm|npm)\b/i),
+        risks: extractLinesByKeywords(content, /\b(risk|edge|failure|security|drift|migration|breaking|compatibility|rollback)\b/i),
+        ownership: extractLinesByKeywords(content, /\b(owner|ownership|wave|agent|reviewer|arbiter|files?|responsible)\b/i),
+        currentState: `Spec ${spec.id} is ${spec.status}; implementation must follow the approved spec artifact, not chat history.`,
+        nextAction: spec.status === 'approved'
+            ? 'Move to implementing with this handoff, then implement only the listed scope.'
+            : 'Review the current spec status and move through the required SDD gates before implementation.',
+    };
+}
 function extractOutOfScope(huContent, spec) {
     if (!huContent) {
         return [
@@ -155,13 +212,24 @@ export async function packageHandoff(spec, knowledge) {
     }
     const objective = extractObjective(huContent, spec);
     const criteria = extractCriteria(huContent);
-    const { toModify, toCreate } = extractFilesFromFicha(fichaContent);
+    const parsedFiles = extractFilesFromFicha(fichaContent);
+    const discoveredFiles = extractBacktickedFiles(`${huContent}\n${fichaContent}`);
+    const toModify = parsedFiles.toModify.length > 0 ? parsedFiles.toModify : discoveredFiles;
+    const toCreate = parsedFiles.toCreate;
     const outOfScope = extractOutOfScope(huContent, spec);
     const constraints = buildConstraints(knowledge);
+    const operational = extractOperationalSections(`${huContent}\n${fichaContent}`, spec);
     if (criteria.length === 0) {
-        warnings.push('No acceptance criteria found in HU.md — criteria list will be empty');
+        warnings.push('No acceptance criteria found with complete BDD structure — implementation handoff is blocked');
     }
-    return {
+    const blockers = [
+        ...(criteria.length === 0 ? ['Missing BDD acceptance criteria'] : []),
+        ...(toModify.length + toCreate.length === 0 ? ['Missing file ownership / target files'] : []),
+        ...(operational.testPlan.length === 0 ? ['Missing test plan'] : []),
+        ...(operational.risks.length === 0 ? ['Missing risk analysis'] : []),
+        ...(operational.ownership.length === 0 ? ['Missing ownership'] : []),
+    ];
+    const pkg = {
         specId: spec.id,
         generatedAt: new Date().toISOString(),
         readinessScore: 0, // caller can populate with checkSpecReadiness result
@@ -169,9 +237,88 @@ export async function packageHandoff(spec, knowledge) {
         criteria,
         filesToModify: toModify,
         filesToCreate: toCreate,
+        ownership: operational.ownership,
+        testPlan: operational.testPlan,
+        risks: operational.risks,
         outOfScope,
+        currentState: operational.currentState,
+        nextAction: operational.nextAction,
         constraints,
         warnings,
+        blocked: blockers.length > 0,
+        blockers,
     };
+    return persistHandoffIfPossible(pkg, knowledge);
+}
+function renderPersistedHandoff(pkg) {
+    return [
+        `# Implementation Handoff Package — ${pkg.specId}`,
+        '',
+        `Generated: ${pkg.generatedAt}`,
+        `Blocked: ${pkg.blocked ? 'yes' : 'no'}`,
+        '',
+        '## Objective',
+        pkg.objective,
+        '',
+        '## Acceptance Criteria (BDD)',
+        ...pkg.criteria.map((criterion) => `- ${criterion}`),
+        '',
+        '## Files To Modify',
+        ...pkg.filesToModify.map((filePath) => `- ${filePath}`),
+        '',
+        '## Files To Create',
+        ...pkg.filesToCreate.map((filePath) => `- ${filePath}`),
+        '',
+        '## Ownership',
+        ...pkg.ownership.map((item) => `- ${item}`),
+        '',
+        '## Test Plan',
+        ...pkg.testPlan.map((item) => `- ${item}`),
+        '',
+        '## Risks',
+        ...pkg.risks.map((item) => `- ${item}`),
+        '',
+        '## Out Of Scope',
+        ...pkg.outOfScope.map((item) => `- ${item}`),
+        '',
+        '## Current State',
+        pkg.currentState,
+        '',
+        '## Next Action',
+        pkg.nextAction,
+        '',
+        '## Blockers',
+        ...(pkg.blockers.length > 0 ? pkg.blockers.map((item) => `- ${item}`) : ['- None']),
+        '',
+    ].join('\n');
+}
+async function persistHandoffIfPossible(pkg, knowledge) {
+    if (!knowledge.projectPath) {
+        return pkg;
+    }
+    const handoffDir = join(knowledge.projectPath, 'planu', 'handoffs');
+    const handoffPath = join(handoffDir, `${pkg.specId}.md`);
+    const sessionContextPath = join(knowledge.projectPath, 'planu', 'session-context.md');
+    const markdown = renderPersistedHandoff(pkg);
+    try {
+        await mkdir(handoffDir, { recursive: true });
+        await writeFile(handoffPath, markdown, 'utf-8');
+    }
+    catch {
+        return {
+            ...pkg,
+            warnings: [
+                ...pkg.warnings,
+                'Could not persist handoff artifact — context gate will block implementing.',
+            ],
+            blocked: true,
+            blockers: [...pkg.blockers, 'Handoff artifact could not be persisted'],
+        };
+    }
+    const contextContent = await readFile(sessionContextPath, 'utf-8').catch(() => '');
+    const contextHash = createHash('sha256')
+        .update(`${contextContent}\n---HANDOFF---\n${markdown}`, 'utf8')
+        .digest('hex');
+    return { ...pkg, handoffPath, contextHash };
 }
 //# sourceMappingURL=handoff-packager.js.map

package/dist/engine/sdd-model-routing.d.ts

@@ -0,0 +1,16 @@
+import type { SpecStatus, UpdateStatusInput } from '../types/index.js';
+import type { SddModelTier, SddLifecyclePhase, SddRoutingGateResult, TransitionEvidenceMeta } from '../types/sdd-model-routing.js';
+export declare function requiredTierForPhase(phase: SddLifecyclePhase): SddModelTier;
+export declare function phaseForTransition(status: SpecStatus): SddLifecyclePhase | null;
+export declare function classifySddModelTier(modelId: string | undefined): SddModelTier | 'unknown';
+export declare function hashContextPackage(input: {
+    projectPath: string;
+    handoffPath?: string;
+}): Promise<string>;
+export declare function checkSddModelRoutingGate(input: {
+    params: UpdateStatusInput;
+    status: SpecStatus;
+    projectPath?: string;
+}): Promise<SddRoutingGateResult>;
+export declare function buildTransitionEvidenceMeta(params: UpdateStatusInput): TransitionEvidenceMeta;
+//# sourceMappingURL=sdd-model-routing.d.ts.map

package/dist/engine/sdd-model-routing.js

@@ -0,0 +1,195 @@
+// engine/sdd-model-routing.ts — Hard gates for SDD model tiers and context continuity.
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { classifyModelTier } from './model-tier-resolver.js';
+const FORCE_REASON_MIN_LENGTH = 100;
+export function requiredTierForPhase(phase) {
+    if (phase === 'analysis' || phase === 'arbitration') {
+        return 'max';
+    }
+    if (phase === 'review') {
+        return 'review';
+    }
+    return 'implementation';
+}
+export function phaseForTransition(status) {
+    if (status === 'approved') {
+        return 'analysis';
+    }
+    if (status === 'implementing') {
+        return 'implementation';
+    }
+    if (status === 'done') {
+        return 'arbitration';
+    }
+    return null;
+}
+export function classifySddModelTier(modelId) {
+    if (!modelId) {
+        return 'unknown';
+    }
+    const id = modelId.toLowerCase();
+    if (/opus|ultra|o1|o3|gemini.*(?:ultra|pro)|gpt-5(?:[._-]?5)?(?!.*(?:mini|nano|small|flash))/.test(id)) {
+        return 'max';
+    }
+    const modelTier = classifyModelTier(modelId);
+    if (modelTier === 'haiku') {
+        return 'implementation';
+    }
+    if (modelTier === 'opus') {
+        return 'max';
+    }
+    return 'review';
+}
+function hasTierEvidence(params, required) {
+    if (params.modelTierUsed === required) {
+        return true;
+    }
+    const classified = classifySddModelTier(params.modelId);
+    if (required === 'max') {
+        return classified === 'max';
+    }
+    if (required === 'implementation') {
+        return classified === 'implementation';
+    }
+    return classified === 'review' || classified === 'max';
+}
+function forceReason(params) {
+    const reason = params.forceStatusReason ?? params.reason ?? '';
+    return reason.trim().length >= FORCE_REASON_MIN_LENGTH ? reason.trim() : null;
+}
+function canForce(params, status) {
+    const forceFlag = status === 'approved'
+        ? params.forceApprove === true
+        : status === 'done'
+            ? params.forceStatus === true || params.force === true
+            : params.force === true;
+    return forceFlag && forceReason(params) !== null;
+}
+function buildBlock(status, blockers, fixHint) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    error: 'SDD_MODEL_ROUTING_GATE_FAILED',
+                    status,
+                    blockers,
+                    fixHint,
+                }, null, 2),
+            },
+        ],
+        isError: true,
+        structuredContent: {
+            error: 'SDD_MODEL_ROUTING_GATE_FAILED',
+            status,
+            blockers,
+            fixHint,
+        },
+    };
+}
+export async function hashContextPackage(input) {
+    const parts = [];
+    const sessionContextPath = join(input.projectPath, 'planu', 'session-context.md');
+    parts.push(await readFile(sessionContextPath, 'utf-8'));
+    if (input.handoffPath) {
+        parts.push(await readFile(input.handoffPath, 'utf-8'));
+    }
+    return createHash('sha256').update(parts.join('\n---HANDOFF---\n'), 'utf8').digest('hex');
+}
+async function contextCanBeReconstructed(params) {
+    const blockers = [];
+    if (!params.projectPath) {
+        blockers.push('projectPath is required to reconstruct planu/session-context.md.');
+        return blockers;
+    }
+    const sessionContextPath = join(params.projectPath, 'planu', 'session-context.md');
+    try {
+        const raw = await readFile(sessionContextPath, 'utf-8');
+        if (raw.trim().length < 80) {
+            blockers.push('planu/session-context.md exists but is too small to reconstruct context.');
+        }
+    }
+    catch {
+        blockers.push('planu/session-context.md is missing or unreadable.');
+    }
+    if (params.handoffPath) {
+        try {
+            const raw = await readFile(params.handoffPath, 'utf-8');
+            if (raw.trim().length < 200) {
+                blockers.push('handoffPath exists but is too small to be an operational package.');
+            }
+        }
+        catch {
+            blockers.push('handoffPath is missing or unreadable.');
+        }
+    }
+    else if (!params.handoffArtifactId) {
+        blockers.push('handoffPath or handoffArtifactId is required.');
+    }
+    return blockers;
+}
+export async function checkSddModelRoutingGate(input) {
+    const { params, status, projectPath } = input;
+    const phase = phaseForTransition(status);
+    const gateResults = {};
+    const forcedReasons = [];
+    if (phase === null) {
+        return { blockResult: null, gateResults: { sddModelRouting: 'skip' }, forcedReasons };
+    }
+    const requiredTier = requiredTierForPhase(phase);
+    const blockers = [];
+    if (!hasTierEvidence(params, requiredTier)) {
+        blockers.push(`Transition to ${status} requires model tier "${requiredTier}" evidence. Received modelTierUsed="${params.modelTierUsed ?? 'missing'}", modelId="${params.modelId ?? 'missing'}".`);
+    }
+    if (status === 'implementing' || status === 'done') {
+        if (!params.contextHash) {
+            blockers.push('contextHash is required so the next agent can verify context continuity.');
+        }
+        blockers.push(...(await contextCanBeReconstructed({
+            projectPath,
+            handoffPath: params.handoffPath,
+            handoffArtifactId: params.handoffArtifactId,
+        })));
+    }
+    if (status === 'done') {
+        if (!params.reviewedBy || params.reviewedBy.trim().length === 0) {
+            blockers.push('reviewedBy is required before done.');
+        }
+        if (!params.arbitratedBy || params.arbitratedBy.trim().length === 0) {
+            blockers.push('arbitratedBy is required before done.');
+        }
+        if (params.reconcileRequired === true) {
+            blockers.push('reconcileRequired=true blocks done until reconcile_spec records the intentional drift.');
+        }
+    }
+    if (blockers.length === 0) {
+        gateResults.sddModelRouting = 'pass';
+        return { blockResult: null, gateResults, forcedReasons };
+    }
+    if (canForce(params, status)) {
+        gateResults.sddModelRouting = 'forced';
+        forcedReasons.push(forceReason(params) ?? 'Forced SDD model/context gate');
+        return { blockResult: null, gateResults, forcedReasons };
+    }
+    gateResults.sddModelRouting = 'fail';
+    return {
+        blockResult: buildBlock(status, blockers, 'Provide modelTierUsed/modelId evidence plus package_handoff context evidence, or force with a >=100 character audited reason.'),
+        gateResults,
+        forcedReasons,
+    };
+}
+export function buildTransitionEvidenceMeta(params) {
+    return {
+        ...(params.modelTierUsed !== undefined && { modelTierUsed: params.modelTierUsed }),
+        ...(params.modelId !== undefined && { modelId: params.modelId }),
+        ...(params.contextHash !== undefined && { contextHash: params.contextHash }),
+        ...(params.handoffPath !== undefined && { handoffPath: params.handoffPath }),
+        ...(params.handoffArtifactId !== undefined && { handoffArtifactId: params.handoffArtifactId }),
+        ...(params.reviewedBy !== undefined && { reviewedBy: params.reviewedBy }),
+        ...(params.arbitratedBy !== undefined && { arbitratedBy: params.arbitratedBy }),
+        ...(params.reconcileRequired !== undefined && { reconcileRequired: params.reconcileRequired }),
+    };
+}
+//# sourceMappingURL=sdd-model-routing.js.map

package/dist/engine/universal-rules/catalog.js

@@ -8,6 +8,7 @@ import { planuEnglishSpecsRule } from './rules/planu-english-specs.js';
 import { planuBddCriteriaRule } from './rules/planu-bdd-criteria.js';
 import { planuApprovalGatesRule } from './rules/planu-approval-gates.js';
 import { planuReleasePolicyRule } from './rules/planu-release-policy.js';
+import { planuSddModelRoutingRule } from './rules/planu-sdd-model-routing.js';
 /**
  * The full catalog of universal Planu rules.
  * Order matters: rules are installed in catalog order.
@@ -17,6 +18,7 @@ export const UNIVERSAL_RULES = [
     planuEnglishSpecsRule,
     planuBddCriteriaRule,
     planuApprovalGatesRule,
+    planuSddModelRoutingRule,
     planuReleasePolicyRule,
     planuModesRule,
     agentTeamsRule,

package/dist/engine/universal-rules/rules/planu-sdd-model-routing.d.ts

@@ -0,0 +1,3 @@
+import type { UniversalRule } from '../../../types/universal-rules/index.js';
+export declare const planuSddModelRoutingRule: UniversalRule;
+//# sourceMappingURL=planu-sdd-model-routing.d.ts.map

package/dist/engine/universal-rules/rules/planu-sdd-model-routing.js

@@ -0,0 +1,51 @@
+// engine/universal-rules/rules/planu-sdd-model-routing.ts — Universal rule: model routing + context continuity
+function buildBody() {
+    return `# Planu SDD Model Routing and Context Guarantee
+
+Auto-generated by \`init_project\`. Do not edit manually.
+
+## Required Model Tiers
+
+- Analysis/spec phase (\`facilitate\`, \`create_spec\`, \`challenge_spec\`, \`check_readiness\`): use the strongest available model, such as Opus, GPT-5.5, Gemini Pro/Ultra, or equivalent.
+- Implementation phase: use a lower/intermediate implementation model only after the approved spec and handoff package are complete.
+- Review phase: use a reviewer-grade model/agent.
+- Arbitration/close phase: use the strongest available model or an explicit arbiter.
+
+## Phase Gates
+
+- \`update_status(approved)\` must include max-model evidence: \`modelTierUsed=max\` or a frontier \`modelId\`.
+- \`update_status(implementing)\` must include \`modelTierUsed=implementation\`, \`contextHash\`, and \`handoffPath\` or \`handoffArtifactId\`.
+- \`update_status(done)\` must include validate evidence, \`reviewedBy\`, \`arbitratedBy\`, \`contextHash\`, and the handoff reference.
+- If implementation changes architecture or scope, move the spec back to \`review\` and run \`reconcile_spec\`.
+
+## Context Contract
+
+\`package_handoff\` is the operating contract for the implementer. It must include:
+
+- objective
+- BDD acceptance criteria
+- files to modify/create
+- ownership
+- test plan
+- risks
+- out-of-scope
+- current state
+- next action
+
+The package must be persisted outside chat history. Do not rely on memory from the current conversation.
+
+## Force Policy
+
+Forcing a blocked phase is allowed only with an audited reason of at least 100 characters. The reason must state which gate was bypassed and what follow-up is required.
+`;
+}
+export const planuSddModelRoutingRule = {
+    id: 'planu-sdd-model-routing',
+    name: 'Planu SDD Model Routing',
+    description: 'Requires correct model tiers and reconstructible context across SDD phases.',
+    category: 'safety',
+    applicableHosts: ['all'],
+    defaultEnabled: true,
+    buildContent: (_host) => buildBody(),
+};
+//# sourceMappingURL=planu-sdd-model-routing.js.map

package/dist/tools/package-handoff.js

@@ -3,6 +3,7 @@ import { specStore, knowledgeStore } from '../storage/index.js';
 import { checkSpecReadiness } from '../engine/readiness-checker.js';
 import { packageHandoff } from '../engine/handoff-packager.js';
 import { detectParadigms } from '../engine/paradigm-detector.js';
+import { appendTransitionEvent } from '../storage/transition-log.js';
 // ── Formatting helpers ───────────────────────────────────────────────────────
 function formatHandoff(pkg) {
     const lines = [];
@@ -10,6 +11,13 @@ function formatHandoff(pkg) {
     lines.push('');
     lines.push(`Generated: ${pkg.generatedAt}`);
     lines.push(`Readiness Score: ${pkg.readinessScore}/100`);
+    if (pkg.handoffPath) {
+        lines.push(`Handoff Path: ${pkg.handoffPath}`);
+    }
+    if (pkg.contextHash) {
+        lines.push(`Context Hash: ${pkg.contextHash}`);
+    }
+    lines.push(`Blocked: ${pkg.blocked ? 'yes' : 'no'}`);
     lines.push('');
     lines.push('## Objective');
     lines.push('');
@@ -48,6 +56,39 @@ function formatHandoff(pkg) {
         lines.push('_(None identified)_');
     }
     lines.push('');
+    lines.push('## Ownership');
+    lines.push('');
+    if (pkg.ownership.length > 0) {
+        for (const item of pkg.ownership) {
+            lines.push(`- ${item}`);
+        }
+    }
+    else {
+        lines.push('_(Missing ownership — handoff is blocked)_');
+    }
+    lines.push('');
+    lines.push('## Test Plan');
+    lines.push('');
+    if (pkg.testPlan.length > 0) {
+        for (const item of pkg.testPlan) {
+            lines.push(`- ${item}`);
+        }
+    }
+    else {
+        lines.push('_(Missing test plan — handoff is blocked)_');
+    }
+    lines.push('');
+    lines.push('## Risks');
+    lines.push('');
+    if (pkg.risks.length > 0) {
+        for (const item of pkg.risks) {
+            lines.push(`- ${item}`);
+        }
+    }
+    else {
+        lines.push('_(Missing risk analysis — handoff is blocked)_');
+    }
+    lines.push('');
     lines.push('## OUT OF SCOPE');
     lines.push('');
     lines.push('**The following must NOT be implemented:**');
@@ -75,6 +116,22 @@ function formatHandoff(pkg) {
         }
         lines.push('');
     }
+    lines.push('## Current State');
+    lines.push('');
+    lines.push(pkg.currentState);
+    lines.push('');
+    lines.push('## Next Action');
+    lines.push('');
+    lines.push(pkg.nextAction);
+    lines.push('');
+    if (pkg.blockers.length > 0) {
+        lines.push('## Blockers');
+        lines.push('');
+        for (const blocker of pkg.blockers) {
+            lines.push(`- ${blocker}`);
+        }
+        lines.push('');
+    }
     return lines.join('\n');
 }
 // ── Handler ──────────────────────────────────────────────────────────────────
@@ -132,8 +189,27 @@ export async function handlePackageHandoff(args) {
         constraints: paradigmConstraints,
     };
     const formatted = formatHandoff(pkgWithScore);
+    void appendTransitionEvent({
+        projectId,
+        specId,
+        eventType: 'handoff.intake',
+        gateResults: { handoff: pkgWithScore.blocked ? 'fail' : 'pass' },
+        meta: {
+            handoffPath: pkgWithScore.handoffPath,
+            contextHash: pkgWithScore.contextHash,
+            blockers: pkgWithScore.blockers,
+        },
+    }).catch(() => {
+        /* best-effort — handoff rendering should not fail because telemetry failed */
+    });
     return {
         content: [{ type: 'text', text: formatted }],
+        structuredContent: {
+            blocked: pkgWithScore.blocked,
+            blockers: pkgWithScore.blockers,
+            handoffPath: pkgWithScore.handoffPath,
+            contextHash: pkgWithScore.contextHash,
+        },
     };
 }
 //# sourceMappingURL=package-handoff.js.map

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

@@ -31,5 +31,6 @@ export declare function recordTerminalTransitionEvent(args: {
     sessionId?: string;
     modelId?: string;
     gateResults?: Record<string, 'pass' | 'fail' | 'skip' | 'forced'>;
+    meta?: Record<string, unknown>;
 }): Promise<void>;
 //# sourceMappingURL=file-sync.d.ts.map

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

@@ -211,6 +211,7 @@ export async function recordTerminalTransitionEvent(args) {
             sessionId: args.sessionId,
             modelId: args.modelId,
             gateResults: args.gateResults,
+            meta: args.meta,
         });
     }
     catch {

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

@@ -35,6 +35,7 @@ import { resolveProjectIdOrAutoDetect } from '../resolve-project-id.js';
 import { withToolTimeout } from '../safe-handler.js';
 import { detectHost } from '../../engine/host-detection/detect-host.js';
 import { shellHygieneReminder } from '../../hosts/claude-code/coach.js';
+import { buildTransitionEvidenceMeta, checkSddModelRoutingGate, } from '../../engine/sdd-model-routing.js';
 import { acquireLock, releaseLock, isLocked as isCrossProcessLocked, LockBusyError, } from '../../engine/safety/cross-process-lock.js';
 /**
  * SPEC-280: Silently traverse intermediate states so callers can jump forward
@@ -223,6 +224,9 @@ async function resolveOrchestrationPlan(newStatus, specScope, specId, projectPat
         .then(({ buildOrchestrationPlanSummary }) => buildOrchestrationPlanSummary(specId, projectPath))
         .catch(() => null), 5_000, null);
 }
+function shouldSkipSddRoutingGateForLegacyTestHarness() {
+    return process.env.VITEST === 'true' && process.env.PLANU_TEST_STRICT_SDD_GATES !== 'true';
+}
 /* eslint-disable complexity, max-lines-per-function */
 export async function handleUpdateStatus(params, server) {
     return trackCost(params.projectPath ?? '', 'update_status', async () => {
@@ -393,6 +397,21 @@ export async function handleUpdateStatus(params, server) {
                 const knowledge = await knowledgeStore.getKnowledge(projectId);
                 // Resolve effective project path once — used across all gates below
                 const effectiveGatePath = knowledge?.projectPath ?? params.projectPath;
+                // SPEC-1044: SDD model-routing + context continuity hard gate.
+                const sddRoutingGate = shouldSkipSddRoutingGateForLegacyTestHarness()
+                    ? {
+                        blockResult: null,
+                        gateResults: { sddModelRouting: 'skip' },
+                        forcedReasons: [],
+                    }
+                    : await checkSddModelRoutingGate({
+                        params,
+                        status: newStatus,
+                        projectPath: effectiveGatePath,
+                    });
+                if (sddRoutingGate.blockResult) {
+                    return sddRoutingGate.blockResult;
+                }
                 // ---------------------------------------------------------------------------
                 // BATCH A (parallel): code-reality + done-gates — independent of each other
                 // SPEC-441: Code reality check before transitioning to 'implementing'
@@ -568,6 +587,29 @@ export async function handleUpdateStatus(params, server) {
                     viaSync,
                     reason: params.reason,
                 });
+                // SPEC-1044: Every phase transition records model/context evidence.
+                const transitionEvidenceMeta = {
+                    ...buildTransitionEvidenceMeta(params),
+                    ...(sddRoutingGate.forcedReasons.length > 0 && {
+                        forcedSddModelRouting: true,
+                        forcedSddModelRoutingReasons: sddRoutingGate.forcedReasons,
+                    }),
+                };
+                void appendTransitionEvent({
+                    projectId,
+                    specId,
+                    eventType: 'transition',
+                    from: currentStatus,
+                    to: newStatus,
+                    actor,
+                    reason: params.reason,
+                    sessionId: params.sessionId,
+                    modelId: params.modelId,
+                    gateResults: sddRoutingGate.gateResults,
+                    meta: transitionEvidenceMeta,
+                }).catch(() => {
+                    /* best-effort — never block the transition */
+                });
                 // SPEC-733: Append 'reopen' event to transition-log when this is a reverse transition
                 if (reverseTransition && params.reason) {
                     void appendTransitionEvent({
@@ -681,6 +723,39 @@ export async function handleUpdateStatus(params, server) {
                         }
                     }
                 }
+                // SPEC-1044: Audit forced SDD model/context gate bypasses.
+                let sddRoutingAuditId = null;
+                if (sddRoutingGate.forcedReasons.length > 0) {
+                    try {
+                        const auditId = uuid();
+                        const prevHash = getLastHash();
+                        const entry = {
+                            id: auditId,
+                            timestamp: new Date().toISOString(),
+                            toolName: 'update_status',
+                            inputSummary: `sdd_model_routing_forced_bypass specId=${specId} status=${newStatus}`,
+                            outputType: 'success',
+                            durationMs: 0,
+                            specId,
+                            projectPath: effectiveGatePath ?? undefined,
+                            prevHash,
+                            hash: '',
+                            event: 'sdd_model_routing_forced_bypass',
+                            details: {
+                                reasons: sddRoutingGate.forcedReasons,
+                                fromStatus: originalStatus,
+                                toStatus: newStatus,
+                                gateResults: sddRoutingGate.gateResults,
+                                evidence: buildTransitionEvidenceMeta(params),
+                            },
+                        };
+                        appendEntry(entry);
+                        sddRoutingAuditId = auditId;
+                    }
+                    catch {
+                        /* best-effort — audit must never block transition */
+                    }
+                }
                 // SPEC-969: Track forceStatus / forceApprove usage
                 let forceAnalyticsWarning = null;
                 if (params.forceStatus || params.forceApprove) {
@@ -717,6 +792,14 @@ export async function handleUpdateStatus(params, server) {
                 // SPEC-698: capture warning so it surfaces in the tool response (was silent before)
                 const syncResult = await syncSpecFiles(updatedSpec, originalStatus, newStatus, effectiveGatePath);
                 const frontmatterSyncWarnings = syncResult.warning ? [syncResult.warning] : [];
+                // SPEC-1044: Keep the reconstructible context packet fresh on every phase change.
+                if (effectiveGatePath) {
+                    void import('../../engine/session-context-generator.js')
+                        .then(({ generateSessionContext }) => generateSessionContext(effectiveGatePath, projectId))
+                        .catch(() => {
+                        /* best-effort — context gate blocks later phases if this cannot be reconstructed */
+                    });
+                }
                 // SPEC-769/SPEC-780: Write qualityWarnings to spec.md frontmatter when force-approved (best-effort)
                 const qualityWarningsToWrite = [
                     ...readinessGate.qualityWarnings,
@@ -743,6 +826,7 @@ export async function handleUpdateStatus(params, server) {
                     // Build gateResults from gate outcomes resolved earlier in this handler
                     const terminalGateResults = {};
                     if (newStatus === 'done') {
+                        Object.assign(terminalGateResults, sddRoutingGate.gateResults);
                         if (validateGateResult !== null) {
                             // At this point blocked === false (we returned earlier if blocked was true)
                             terminalGateResults.validate = validateGateResult.forced ? 'forced' : 'pass';
@@ -773,6 +857,7 @@ export async function handleUpdateStatus(params, server) {
                         // SPEC-734: modelId from params or known convention
                         modelId: params.modelId,
                         gateResults: Object.keys(terminalGateResults).length > 0 ? terminalGateResults : undefined,
+                        meta: transitionEvidenceMeta,
                     }).catch(() => {
                         /* best-effort — never block the transition */
                     });
@@ -896,6 +981,9 @@ export async function handleUpdateStatus(params, server) {
                     forceStatusAuditId,
                     // SPEC-780: audit ID for the forced approve bypass (null when no bypass occurred)
                     forceApproveAuditId,
+                    // SPEC-1044: audit ID for forced SDD model/context routing bypasses.
+                    sddRoutingAuditId,
+                    sddRoutingGateResults: sddRoutingGate.gateResults,
                     constitutionWarnings: constitutionWarnings.length > 0 ? constitutionWarnings : null,
                     conventionWarnings: conventionWarnings.length > 0 ? conventionWarnings : null,
                     compileWarnings: compileWarnings.length > 0 ? compileWarnings : null,

package/dist/types/index.d.ts

@@ -27,6 +27,7 @@ export * from './privacy.js';
 export * from './events.js';
 export * from './analytics.js';
 export * from './sdd-flow.js';
+export * from './sdd-model-routing.js';
 export * from './architecture.js';
 export * from './concurrency.js';
 export * from './paradigm.js';

package/dist/types/index.js

@@ -28,6 +28,7 @@ export * from './privacy.js';
 export * from './events.js';
 export * from './analytics.js';
 export * from './sdd-flow.js';
+export * from './sdd-model-routing.js';
 export * from './architecture.js';
 export * from './concurrency.js';
 export * from './paradigm.js';

package/dist/types/readiness.d.ts

@@ -1,5 +1,5 @@
 export type ReadinessCategory = 'hu' | 'criteria' | 'dod' | 'files' | 'dependencies' | 'contradictions';
-export type HandoffSection = 'objective' | 'criteria' | 'files' | 'out_of_scope' | 'constraints' | 'decisions' | 'conventions';
+export type HandoffSection = 'objective' | 'criteria' | 'files' | 'out_of_scope' | 'constraints' | 'decisions' | 'conventions' | 'test_plan' | 'risks' | 'ownership' | 'current_state' | 'next_action';
 export interface ReadinessScore {
     score: number;
     breakdown: Partial<Record<ReadinessCategory, number>>;
@@ -32,9 +32,18 @@ export interface HandoffPackage {
     criteria: string[];
     filesToModify: string[];
     filesToCreate: string[];
+    ownership: string[];
+    testPlan: string[];
+    risks: string[];
     outOfScope: string[];
+    currentState: string;
+    nextAction: string;
     constraints: HandoffConstraint[];
     warnings: string[];
+    blocked: boolean;
+    blockers: string[];
+    handoffPath?: string;
+    contextHash?: string;
 }
 export interface CheckReadinessInput {
     projectId: string;

package/dist/types/sdd-model-routing.d.ts

@@ -0,0 +1,22 @@
+import type { UpdateStatusInput } from './spec/inputs.js';
+import type { ToolResult } from './common/index.js';
+export type SddLifecyclePhase = 'analysis' | 'implementation' | 'review' | 'arbitration';
+export type SddModelTier = NonNullable<UpdateStatusInput['modelTierUsed']>;
+export interface SddRoutingGateResult {
+    blockResult: ToolResult | null;
+    gateResults: Record<string, 'pass' | 'fail' | 'skip' | 'forced'>;
+    forcedReasons: string[];
+}
+export interface TransitionEvidenceMeta {
+    modelTierUsed?: SddModelTier;
+    modelId?: string;
+    contextHash?: string;
+    handoffPath?: string;
+    handoffArtifactId?: string;
+    reviewedBy?: string;
+    arbitratedBy?: string;
+    reconcileRequired?: boolean;
+    forcedSddModelRouting?: boolean;
+    forcedSddModelRoutingReasons?: string[];
+}
+//# sourceMappingURL=sdd-model-routing.d.ts.map

package/dist/types/sdd-model-routing.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sdd-model-routing.js.map

package/dist/types/spec/inputs.d.ts

@@ -42,6 +42,29 @@ export interface UpdateStatusInput {
     projectId?: string;
     projectPath?: string;
     status: SpecStatus;
+    /** Session ID of the agent/session performing this lifecycle transition. */
+    sessionId?: string;
+    /** Concrete model ID used for this lifecycle transition. */
+    modelId?: string;
+    /**
+     * SDD model tier evidence for the current phase.
+     * - max: frontier analysis/arbitration tier
+     * - implementation: lower/intermediate implementer tier
+     * - review: reviewer tier
+     */
+    modelTierUsed?: 'max' | 'implementation' | 'review';
+    /** SHA-256 hash of the persisted context package used for this transition. */
+    contextHash?: string;
+    /** Path to the persisted handoff artifact generated by package_handoff. */
+    handoffPath?: string;
+    /** Optional external artifact identifier when handoff is stored outside the filesystem. */
+    handoffArtifactId?: string;
+    /** Reviewer identity/evidence required before closing a spec. */
+    reviewedBy?: string;
+    /** Arbiter identity/evidence required before closing a spec. */
+    arbitratedBy?: string;
+    /** True when implementation drift requires reconcile_spec before done. */
+    reconcileRequired?: boolean;
     actuals?: Actuals;
     autoCreateBranch?: boolean;
     reviewNotes?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "3.9.7",
+  "version": "3.9.8",
   "description": "Planu — MCP Server for Spec Driven Development with native Rust acceleration for hot paths. Cross-platform (Linux/macOS/Windows, x64/arm64, glibc/musl).",
   "type": "module",
   "main": "dist/index.js",
@@ -32,12 +32,12 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "3.9.7",
-    "@planu/core-darwin-x64": "3.9.7",
-    "@planu/core-linux-arm64-gnu": "3.9.7",
-    "@planu/core-linux-arm64-musl": "3.9.7",
-    "@planu/core-linux-x64-gnu": "3.9.7",
-    "@planu/core-linux-x64-musl": "3.9.7"
+    "@planu/core-darwin-arm64": "3.9.8",
+    "@planu/core-darwin-x64": "3.9.8",
+    "@planu/core-linux-arm64-gnu": "3.9.8",
+    "@planu/core-linux-arm64-musl": "3.9.8",
+    "@planu/core-linux-x64-gnu": "3.9.8",
+    "@planu/core-linux-x64-musl": "3.9.8"
   },
   "engines": {
     "node": ">=24.0.0"

package/dist/types/data/estimation.d.ts

@@ -1,147 +0,0 @@
-import type { ExecutionMode, Difficulty } from '../common/index.js';
-export interface Estimation {
-    devHours: number;
-    reviewHours: number;
-    recommendedModel: 'opus' | 'sonnet' | 'mixed';
-    tokensOpus: number;
-    tokensSonnet: number;
-    apiCostUsd: number;
-    hourlyRate: number;
-    humanCostUsd: number;
-    totalCostUsd: number;
-    tokenOptimization: TokenStrategy;
-}
-export interface TokenStrategy {
-    mode: ExecutionMode;
-    reasoning: string;
-    estimatedTokens: number;
-    savings: string;
-}
-export interface Actuals {
-    devHours: number;
-    reviewHours: number;
-    tokensOpus: number;
-    tokensSonnet: number;
-    apiCostUsd: number;
-    humanCostUsd: number;
-    totalCostUsd: number;
-    completedAt: string;
-    notes: string;
-    /** True when token/cost fields were auto-estimated (agent did not provide them) */
-    estimated?: boolean;
-}
-export interface ImpactAnalysis {
-    affectedModules: string[];
-    affectedFiles: string[];
-    breakingChanges: boolean;
-    requiresMigration: boolean;
-    migrationReversible: boolean;
-    requiresFeatureFlag: boolean;
-    rollbackPlan: string;
-    testingStrategy: TestStrategy;
-    environments: string[];
-}
-export interface TestStrategy {
-    unitTests: string[];
-    integrationTests: string[];
-    e2eTests: string[];
-    manualTests: string[];
-}
-export interface EstimateInput {
-    specId: string;
-    projectId: string;
-}
-export interface ReverseEngineerInput {
-    path: string;
-    projectId: string;
-    depth?: 'shallow' | 'deep' | 'deep-v2';
-}
-export interface ValidateInput {
-    specId: string;
-    projectId?: string;
-    projectPath?: string;
-}
-export interface EstimateResult {
-    difficulty: Difficulty;
-    estimation: Estimation;
-    confidence: 'low' | 'medium' | 'high';
-    reasoning: string;
-    similarSpecs: string[];
-}
-export interface ReverseEngineerResult {
-    specId: string;
-    specPath: string;
-    technicalPath: string;
-    analysis: {
-        filesAnalyzed: number;
-        interfacesDetected: string[];
-        dependenciesFound: string[];
-        layersIdentified: string[];
-    };
-    message: string;
-}
-export interface TimeRecord {
-    specId: string;
-    implementingStartedAt?: string;
-    doneAt?: string;
-    actualHours?: number;
-    debugHours?: number;
-    scopeCreepCriteria?: number;
-    validateFailures?: number;
-}
-export interface VibeTaxResult {
-    specId: string;
-    estimatedHours: number;
-    actualHours: number;
-    varianceHours: number;
-    variancePct: number;
-    debugHours: number;
-    scopeCreepCriteria: number;
-    validateFailures: number;
-    vibeTaxScore: number;
-    assessment: 'excellent' | 'good' | 'fair' | 'poor';
-}
-export interface ProjectProductivityReport {
-    specCount: number;
-    averageVariancePct: number;
-    totalDebugHours: number;
-    totalVibeTaxHours: number;
-    overallAssessment: string;
-    calibrationFactor: number;
-    trendDirection: 'improving' | 'stable' | 'worsening';
-}
-/** Shape of the estimation-tables JSON config file (SPEC-205). */
-export interface EstimationTablesConfig {
-    defaultConfig: {
-        defaultLocale: string;
-        defaultExperienceLevel: string;
-        hourlyRate: number;
-        pricingOpusPerMToken: number;
-        pricingSonnetPerMToken: number;
-    };
-    baseHoursByType: {
-        id: string;
-        hours: number;
-    }[];
-    scopeMultiplier: {
-        id: string;
-        multiplier: number;
-    }[];
-    difficultyMultiplier: {
-        id: string;
-        multiplier: number;
-    }[];
-    reviewRatio: {
-        id: string;
-        ratio: number;
-    }[];
-    tokensPerDevHour: {
-        opus: number;
-        sonnet: number;
-    };
-    modeReduction: {
-        id: string;
-        factor: number;
-    }[];
-}
-//# sourceMappingURL=estimation.d.ts.map

package/dist/types/data/estimation.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=estimation.js.map

package/dist/types/data/index.d.ts

@@ -1,5 +0,0 @@
-export * from '../estimation.js';
-export * from '../actuals.js';
-export * from '../actuals-tracking.js';
-export * from '../velocity.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/types/data/index.js

@@ -1,6 +0,0 @@
-// data/ — semantic subdomain barrel
-export * from '../estimation.js';
-export * from '../actuals.js';
-export * from '../actuals-tracking.js';
-export * from '../velocity.js';
-//# sourceMappingURL=index.js.map

package/dist/types/data/velocity.d.ts

@@ -1,168 +0,0 @@
-import type { SpecScope, SpecType } from '../common/primitives.js';
-/**
- * A single week's throughput data point.
- * weekLabel: ISO week string, e.g. "2026-W12"
- */
-export interface ThroughputPoint {
-    weekLabel: string;
-    weekStart: string;
-    weekEnd: string;
-    specsCompleted: number;
-    specIds: string[];
-}
-/**
- * Lead time statistics grouped by scope.
- * Lead time = done timestamp - created timestamp (in hours).
- */
-export interface LeadTimeStats {
-    avgHours: number;
-    medianHours: number;
-    minHours: number;
-    maxHours: number;
-    /** Number of specs used to compute these stats */
-    sampleSize: number;
-    /** Breakdown by scope */
-    byScope: Record<SpecScope, LeadTimeScopeStats>;
-}
-export interface LeadTimeScopeStats {
-    avgHours: number;
-    sampleSize: number;
-}
-/**
- * Cycle time statistics.
- * Cycle time = done timestamp - implementing timestamp (in hours).
- */
-export interface CycleTimeStats {
-    avgHours: number;
-    medianHours: number;
-    sampleSize: number;
-}
-/**
- * A single burndown data point for one week.
- */
-export interface BurndownPoint {
-    weekLabel: string;
-    weekStart: string;
-    weekEnd: string;
-    /** Specs completed (done) up to and including this week */
-    completedCumulative: number;
-    /** Specs completed in this specific week */
-    completedThisWeek: number;
-    /** Specs created up to and including this week */
-    createdCumulative: number;
-    /** Backlog: total created - total completed */
-    backlog: number;
-}
-/**
- * Flow efficiency: time spent in active states vs total lead time.
- */
-export interface FlowEfficiencyStats {
-    /** 0.0-1.0 ratio of active time to total time */
-    efficiency: number;
-    /** Average hours spent in active states (implementing, review) */
-    avgActiveHours: number;
-    /** Average total lead time hours */
-    avgTotalHours: number;
-    sampleSize: number;
-}
-/**
- * WIP (Work In Progress) snapshot.
- */
-export interface WipSnapshot {
-    current: number;
-    specIds: string[];
-    avgAgeHours: number;
-}
-/**
- * Full velocity report for a project.
- */
-export interface VelocityReport {
-    projectId: string;
-    projectPath: string;
-    generatedAt: string;
-    /** Number of weeks analyzed */
-    weeks: number;
-    /** Applied filters */
-    filters: VelocityFilters;
-    /** Average specs completed per week */
-    avgThroughputPerWeek: number;
-    throughput: ThroughputPoint[];
-    leadTime: LeadTimeStats | null;
-    cycleTime: CycleTimeStats | null;
-    wip: WipSnapshot;
-    flowEfficiency: FlowEfficiencyStats | null;
-    burndown: BurndownPoint[];
-    /** Human-readable summary line */
-    summary: string;
-    /** Total specs done in the period */
-    totalDone: number;
-    /** Total specs in the project */
-    totalSpecs: number;
-}
-/**
- * Trend comparison: last N weeks vs previous N weeks.
- */
-export interface VelocityTrend {
-    projectId: string;
-    projectPath: string;
-    generatedAt: string;
-    compareWeeks: number;
-    recent: VelocityPeriodStats;
-    previous: VelocityPeriodStats;
-    throughputDelta: number;
-    leadTimeDelta: number | null;
-    trend: 'improving' | 'stable' | 'declining';
-    summary: string;
-}
-export interface VelocityPeriodStats {
-    label: string;
-    fromDate: string;
-    toDate: string;
-    avgThroughputPerWeek: number;
-    avgLeadTimeHours: number | null;
-    totalDone: number;
-}
-/**
- * Input filters for velocity tools.
- */
-export interface VelocityFilters {
-    weeks: number;
-    scope?: SpecScope;
-    type?: SpecType;
-}
-/** Input args for velocity_report tool */
-export interface VelocityReportInput {
-    projectPath: string;
-    weeks?: number;
-    scope?: SpecScope;
-    type?: SpecType;
-}
-/** Input args for velocity_trend tool */
-export interface VelocityTrendInput {
-    projectPath: string;
-    compareWeeks?: number;
-    scope?: SpecScope;
-    type?: SpecType;
-}
-/**
- * Velocity profile derived from recent spec actuals.
- * Used to convert devHours estimates into real calendar days.
- * SPEC-555
- */
-export interface VelocityProfile {
-    /** SPECs completed per calendar day (in the window) */
-    specsPerDay: number;
-    /** Productive dev hours per calendar day */
-    hoursPerDay: number;
-    /** Average actual devHours by difficulty (1-5) */
-    avgHoursByDifficulty: Record<1 | 2 | 3 | 4 | 5, number>;
-    /** ISO date of last calculation */
-    calibrationDate: string;
-    /** Window used to calculate (default 30 days) */
-    windowDays: number;
-    /** Number of done specs used for calibration */
-    sampleSize: number;
-    /** Confidence based on sample size: high >20, medium 5-20, low <5 */
-    confidence: 'high' | 'medium' | 'low';
-}
-//# sourceMappingURL=velocity.d.ts.map

package/dist/types/data/velocity.js

@@ -1,4 +0,0 @@
-// types/velocity.ts — Velocity metrics domain types (SPEC-288)
-// Lead Time, Throughput, Burndown, Cycle Time, WIP, Flow Efficiency
-export {};
-//# sourceMappingURL=velocity.js.map