@planu/cli 4.2.6 → 4.3.1

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [4.3.0] - 2026-05-22
+
+**Tarball SHA-256:** `ebc3e7fe0a284d6ba6062dfb9aab41fe6e9396a7763c6d39764d676d20a0b6c3`
+
+### Features
+- feat(planu): enforce BDD SDD evidence gates
+
+
 ## [4.2.6] - 2026-05-22
 
 **Tarball SHA-256:** `07356a69166b2f47742118dcf06af14a105a44bb27024d6e28213c433530089e`

package/dist/engine/evidence-gates/artifact-reader.d.ts

@@ -0,0 +1,9 @@
+import type { Spec } from '../../types/spec/core.js';
+import type { EvidenceArtifacts } from '../../types/evidence-gates.js';
+export declare function readEvidenceArtifacts(args: {
+    spec: Spec;
+    projectId: string;
+    specId: string;
+    projectPath?: string;
+}): Promise<EvidenceArtifacts>;
+//# sourceMappingURL=artifact-reader.d.ts.map

package/dist/engine/evidence-gates/artifact-reader.js

@@ -0,0 +1,158 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join } from 'node:path';
+import { z } from 'zod';
+import { projectDataDir } from '../../storage/base-store.js';
+const DiscoverySchema = z.object({
+    version: z.literal(1),
+    rules: z.array(z.string().min(1)).max(200),
+    examples: z.array(z.object({ rule: z.string().min(1), example: z.string().min(1) })).max(500),
+    openQuestions: z
+        .array(z.object({
+        question: z.string().min(1),
+        status: z.enum(['open', 'resolved', 'out_of_scope']),
+        resolution: z.string().optional(),
+    }))
+        .max(200),
+    outOfScope: z.array(z.string()).max(200),
+    glossary: z.array(z.object({ term: z.string().min(1), meaning: z.string().min(1) })).max(200),
+});
+const TaskPlanSchema = z.object({
+    version: z.literal(1),
+    tasks: z
+        .array(z.object({
+        id: z.string().min(1).max(120),
+        title: z.string().min(1).max(500),
+        acceptanceCriteria: z.array(z.string().min(1)).max(200),
+        status: z.enum(['pending', 'doing', 'done']),
+    }))
+        .max(500),
+});
+const TraceabilityMatrixSchema = z.object({
+    version: z.literal(1),
+    rows: z
+        .array(z.object({
+        acceptanceCriterion: z.string().min(1),
+        scenario: z.string().optional(),
+        testEvidence: z.array(z.string().min(1)).optional(),
+        contractEvidence: z.array(z.string().min(1)).optional(),
+        manualEvidence: z.string().optional(),
+        changedFiles: z.array(z.string().min(1)).max(200),
+        validationEvidence: z.string().optional(),
+        reviewerEvidence: z.string().optional(),
+    }))
+        .max(1000),
+});
+const ContractValidationSchema = z.object({
+    version: z.literal(1),
+    kind: z.enum(['api', 'graphql', 'event', 'ui', 'mcp']),
+    passed: z.boolean(),
+    reportPath: z.string().optional(),
+    summary: z.string().optional(),
+});
+function resolveSpecPath(spec, projectPath) {
+    if (isAbsolute(spec.specPath) || !projectPath) {
+        return spec.specPath;
+    }
+    return join(projectPath, spec.specPath);
+}
+function specEvidencePath(spec, filename, projectPath) {
+    return join(dirname(resolveSpecPath(spec, projectPath)), 'evidence', filename);
+}
+function handoffEvidencePath(projectId, specId, filename) {
+    return join(projectDataDir(projectId), 'handoffs', specId, filename);
+}
+async function readUnknown(paths) {
+    for (const path of paths) {
+        try {
+            const raw = await readFile(path, 'utf-8');
+            return { path, value: JSON.parse(raw) };
+        }
+        catch (err) {
+            const code = err instanceof Error && 'code' in err ? err.code : undefined;
+            if (code === 'ENOENT') {
+                continue;
+            }
+            throw new Error(`${path}: ${err instanceof Error ? err.message : String(err)}`, {
+                cause: err,
+            });
+        }
+    }
+    return null;
+}
+async function readOptional(args) {
+    try {
+        const found = await readUnknown(args.paths);
+        if (!found) {
+            return undefined;
+        }
+        const parsed = args.schema.safeParse(found.value);
+        if (!parsed.success) {
+            args.invalidArtifacts.push(`${args.label} is invalid at ${found.path}: ${parsed.error.issues.map((issue) => issue.message).join('; ')}`);
+            return undefined;
+        }
+        return parsed.data;
+    }
+    catch (err) {
+        args.invalidArtifacts.push(`${args.label} is unreadable: ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+}
+export async function readEvidenceArtifacts(args) {
+    const invalidArtifacts = [];
+    const discovery = await readOptional({
+        label: 'Discovery evidence',
+        invalidArtifacts,
+        schema: DiscoverySchema,
+        paths: [
+            specEvidencePath(args.spec, 'discovery.json', args.projectPath),
+            handoffEvidencePath(args.projectId, args.specId, 'discovery.json'),
+        ],
+    });
+    const taskPlan = await readOptional({
+        label: 'Task plan evidence',
+        invalidArtifacts,
+        schema: TaskPlanSchema,
+        paths: [
+            specEvidencePath(args.spec, 'task-plan.json', args.projectPath),
+            handoffEvidencePath(args.projectId, args.specId, 'task-plan.json'),
+        ],
+    });
+    const traceabilityMatrix = await readOptional({
+        label: 'Traceability matrix evidence',
+        invalidArtifacts,
+        schema: TraceabilityMatrixSchema,
+        paths: [
+            specEvidencePath(args.spec, 'traceability-matrix.json', args.projectPath),
+            handoffEvidencePath(args.projectId, args.specId, 'traceability-matrix.json'),
+        ],
+    });
+    const contractValidations = [];
+    for (const filename of [
+        'contract-validation-api.json',
+        'contract-validation-graphql.json',
+        'contract-validation-event.json',
+        'contract-validation-ui.json',
+        'contract-validation-mcp.json',
+    ]) {
+        const evidence = await readOptional({
+            label: filename,
+            invalidArtifacts,
+            schema: ContractValidationSchema,
+            paths: [
+                specEvidencePath(args.spec, filename, args.projectPath),
+                handoffEvidencePath(args.projectId, args.specId, filename),
+            ],
+        });
+        if (evidence) {
+            contractValidations.push(evidence);
+        }
+    }
+    return {
+        discovery,
+        taskPlan,
+        traceabilityMatrix,
+        contractValidations,
+        invalidArtifacts,
+    };
+}
+//# sourceMappingURL=artifact-reader.js.map

package/dist/engine/evidence-gates/lifecycle-gate.d.ts

@@ -0,0 +1,13 @@
+import type { Spec } from '../../types/spec/core.js';
+import type { ContractValidationEvidence, EvidenceArtifacts, EvidenceGateIssue, EvidenceGateResult, EvidenceGateTransition } from '../../types/evidence-gates.js';
+export declare function inferRequiredContractEvidence(spec: Spec, criteria: string[]): ContractValidationEvidence['kind'][];
+export declare function checkDiscoveryGate(spec: Spec, artifacts: EvidenceArtifacts): EvidenceGateIssue[];
+export declare function checkTaskPlanGate(spec: Spec, criteria: string[], artifacts: EvidenceArtifacts): EvidenceGateIssue[];
+export declare function checkDoneEvidenceGate(spec: Spec, criteria: string[], artifacts: EvidenceArtifacts): EvidenceGateIssue[];
+export declare function checkLifecycleEvidenceGate(args: {
+    transition: EvidenceGateTransition;
+    spec: Spec;
+    criteria: string[];
+    artifacts: EvidenceArtifacts;
+}): EvidenceGateResult;
+//# sourceMappingURL=lifecycle-gate.d.ts.map

package/dist/engine/evidence-gates/lifecycle-gate.js

@@ -0,0 +1,153 @@
+const CONTRACT_HINTS = {
+    api: /\b(api|rest|endpoint|openapi|http route|controller)\b/i,
+    graphql: /\b(graphql|gql|schema\.graphql|resolver)\b/i,
+    event: /\b(event|webhook|queue|topic|message broker|kafka|rabbitmq|pubsub)\b/i,
+    ui: /\b(ui contract|component contract|screen contract|design contract)\b/i,
+    mcp: /\b(mcp|tool contract|model context protocol|registerTool|server tool)\b/i,
+};
+function isNonTrivial(spec) {
+    return spec.scope !== 'trivial';
+}
+function normalizeCriterion(value) {
+    return value
+        .replace(/^-\s*\[[ x]\]\s*/i, '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase();
+}
+function hasText(value) {
+    return value !== undefined && value.trim().length > 0;
+}
+export function inferRequiredContractEvidence(spec, criteria) {
+    const text = `${spec.title} ${spec.tags.join(' ')} ${criteria.join(' ')}`;
+    const required = [];
+    for (const [kind, pattern] of Object.entries(CONTRACT_HINTS)) {
+        if (pattern.test(text)) {
+            required.push(kind);
+        }
+    }
+    return required;
+}
+export function checkDiscoveryGate(spec, artifacts) {
+    if (!isNonTrivial(spec)) {
+        return [];
+    }
+    const issues = [];
+    if (!artifacts.discovery) {
+        issues.push({
+            code: 'discovery_missing',
+            message: 'Discovery evidence is required before approval. Add discovery.json with rules, examples, open questions, out-of-scope boundaries, and glossary.',
+        });
+        return issues;
+    }
+    const unresolved = artifacts.discovery.openQuestions.filter((q) => q.status === 'open');
+    if (unresolved.length > 0) {
+        issues.push({
+            code: 'discovery_unresolved_questions',
+            message: `Discovery has unresolved open questions: ${unresolved.map((q) => q.question).join('; ')}`,
+        });
+    }
+    return issues;
+}
+export function checkTaskPlanGate(spec, criteria, artifacts) {
+    if (!isNonTrivial(spec)) {
+        return [];
+    }
+    if (!artifacts.taskPlan) {
+        return [
+            {
+                code: 'task_plan_missing',
+                message: 'Task plan evidence is required before implementation. Add task-plan.json with tasks mapped to acceptance criteria.',
+            },
+        ];
+    }
+    const covered = new Set(artifacts.taskPlan.tasks.flatMap((task) => task.acceptanceCriteria.map(normalizeCriterion)));
+    const uncovered = criteria.filter((criterion) => !covered.has(normalizeCriterion(criterion)));
+    if (uncovered.length === 0) {
+        return [];
+    }
+    return [
+        {
+            code: 'task_plan_uncovered_criteria',
+            message: `Task plan does not cover acceptance criteria: ${uncovered.join('; ')}`,
+        },
+    ];
+}
+function rowHasEvidence(row) {
+    return (hasText(row.scenario) ||
+        (row.testEvidence !== undefined && row.testEvidence.length > 0) ||
+        (row.contractEvidence !== undefined && row.contractEvidence.length > 0) ||
+        hasText(row.manualEvidence));
+}
+export function checkDoneEvidenceGate(spec, criteria, artifacts) {
+    const issues = [];
+    const matrix = artifacts.traceabilityMatrix;
+    if (!matrix) {
+        issues.push({
+            code: 'traceability_missing',
+            message: 'Traceability matrix evidence is required before done. Add traceability-matrix.json covering each acceptance criterion.',
+        });
+    }
+    else {
+        const covered = new Set(matrix.rows.map((row) => normalizeCriterion(row.acceptanceCriterion)));
+        const uncovered = criteria.filter((criterion) => !covered.has(normalizeCriterion(criterion)));
+        if (uncovered.length > 0) {
+            issues.push({
+                code: 'traceability_uncovered_criteria',
+                message: `Traceability matrix does not cover acceptance criteria: ${uncovered.join('; ')}`,
+            });
+        }
+        const incompleteRows = matrix.rows.filter((row) => !rowHasEvidence(row) ||
+            row.changedFiles.length === 0 ||
+            !hasText(row.validationEvidence) ||
+            !hasText(row.reviewerEvidence));
+        if (incompleteRows.length > 0) {
+            issues.push({
+                code: 'traceability_incomplete_rows',
+                message: 'Traceability rows must include scenario/test/contract/manual evidence, changed files, validation evidence, and reviewer evidence.',
+            });
+        }
+    }
+    const requiredKinds = inferRequiredContractEvidence(spec, criteria);
+    const passedKinds = new Set(artifacts.contractValidations
+        .filter((artifact) => artifact.passed)
+        .map((artifact) => artifact.kind));
+    const failedKinds = artifacts.contractValidations
+        .filter((artifact) => !artifact.passed)
+        .map((artifact) => artifact.kind);
+    const missingKinds = requiredKinds.filter((kind) => !passedKinds.has(kind));
+    if (missingKinds.length > 0) {
+        issues.push({
+            code: 'contract_validation_missing',
+            message: `Contract validation evidence is required for: ${missingKinds.join(', ')}`,
+        });
+    }
+    if (failedKinds.length > 0) {
+        issues.push({
+            code: 'contract_validation_failed',
+            message: `Contract validation evidence failed for: ${failedKinds.join(', ')}`,
+        });
+    }
+    return issues;
+}
+export function checkLifecycleEvidenceGate(args) {
+    const issues = args.artifacts.invalidArtifacts.map((artifact) => ({
+        code: 'evidence_artifact_invalid',
+        message: artifact,
+    }));
+    if (args.transition === 'approved') {
+        issues.push(...checkDiscoveryGate(args.spec, args.artifacts));
+    }
+    else if (args.transition === 'implementing') {
+        issues.push(...checkTaskPlanGate(args.spec, args.criteria, args.artifacts));
+    }
+    else {
+        issues.push(...checkDoneEvidenceGate(args.spec, args.criteria, args.artifacts));
+    }
+    return {
+        passed: issues.length === 0,
+        issues,
+        requiredContractKinds: inferRequiredContractEvidence(args.spec, args.criteria),
+    };
+}
+//# sourceMappingURL=lifecycle-gate.js.map

package/dist/engine/host-rules-templates/templates.js

@@ -44,13 +44,19 @@ function buildSharedRules() {
         '| Trigger | Automatic action |',
         '|---------|-----------------|',
         '| New feature / bug / task described | `create_spec` |',
+        '| Spec needs approval | Create Discovery evidence before `update_status(approved)` |',
         '| Spec written | Run an independent `planu-spec-reviewer` review before approval |',
+        '| Spec approved for implementation | Create task-plan evidence mapped to acceptance criteria |',
         '| Spec status change | `update_status` |',
-        '| Implementation complete | `validate` + independent `planu-implementation-reviewer` review |',
+        '| Implementation complete | Create traceability evidence, run `validate`, and use independent `planu-implementation-reviewer` review |',
         '| Project start | `init_project` |',
         '',
         '### Review gates — non-bypassable',
+        '- A non-trivial spec cannot move to `approved` without Discovery evidence: rules, examples, open questions, out-of-scope, and glossary.',
         '- A spec cannot move to `approved` without `review_feedback` from `planu-spec-reviewer`.',
+        '- A non-trivial spec cannot move to `implementing` without task-plan evidence mapped to acceptance criteria.',
+        '- A spec cannot move to `done` without a traceability matrix covering every acceptance criterion.',
+        '- API, UI, event, GraphQL, and MCP specs require matching contract validation evidence before `done`.',
         '- The planner/spec author must not self-approve the spec.',
         '- A spec cannot move to `done` without validation evidence and review evidence from `planu-implementation-reviewer`.',
         '- The implementation reviewer must be different from the implementation agent.',

package/dist/engine/skills-reconciler.js

@@ -31,7 +31,7 @@ export async function reconcileSkills(projectPath, knowledge) {
     const newSkillsDetected = recommendedSkills
         .filter((s) => !installedSet.has(s.name))
         .map((s) => s.name);
-    const staleSkills = installedNames.filter((name) => !recommendedNames.has(name));
+    const staleSkills = installedNames.filter((name) => !recommendedNames.has(name) && !isProtectedBuiltInSkill(name, knowledge));
     const totalRelevant = recommendedNames.size;
     const alreadyInSync = installedNames.filter((name) => recommendedNames.has(name)).length;
     const healthScore = computeHealthScore(totalRelevant, alreadyInSync, staleSkills.length);
@@ -188,6 +188,16 @@ function computeHealthScore(totalRelevant, alreadyInSync, staleCount) {
     const penalty = staleCount * 5;
     return Math.max(0, base - penalty);
 }
+function isProtectedBuiltInSkill(name, knowledge) {
+    if (name !== 'typescript-patterns') {
+        return false;
+    }
+    const language = knowledge.language.toLowerCase();
+    const stack = knowledge.stack.map((item) => item.toLowerCase());
+    return (language === 'typescript' ||
+        language === 'javascript' ||
+        stack.some((item) => item.includes('typescript') || item.includes('javascript')));
+}
 /** Return a neutral reconciliation when prerequisites are missing. */
 function buildEmptyReconciliation(_reason) {
     return {

package/dist/engine/spec-generator/fallback-generator.js

@@ -1,34 +1,16 @@
-const MAX_SUMMARY_LENGTH = 700;
 export class FallbackGenerator {
     generate(request) {
-        const slug = slugify(request.title);
-        const pascalName = toPascalCase(request.title);
-        const sourceSummary = normalizeSummary(request.description, request.title);
+        const sourceDescription = normalizeSourceDescription(request.description, request.title);
         const contextLine = buildContextLine(request);
-        const technicalSection = buildTechnicalSection(slug, pascalName, contextLine);
+        const technicalSection = buildTechnicalSection(contextLine);
         const specBody = [
             '## Problem',
-            sourceSummary,
+            sourceDescription,
             '',
             '## Solution',
-            `Implement ${request.title} with explicit behavior, project-scoped file ownership, and verification gates. ${contextLine}`,
-            '',
-            '## Acceptance Criteria',
-            '',
-            `Scenario: ${request.title} happy path`,
-            'GIVEN the relevant user or system context exists',
-            `WHEN the requested ${request.title} behavior is executed`,
-            'THEN the expected outcome from the request is observable',
-            '',
-            `Scenario: ${request.title} failure handling`,
-            'GIVEN invalid input or an unavailable dependency',
-            `WHEN the requested ${request.title} behavior runs`,
-            'THEN the system returns a clear failure state without corrupting data',
-            '',
-            `Scenario: ${request.title} verification`,
-            'GIVEN the implementation is complete',
-            'WHEN the configured verification commands run',
-            'THEN tests and lint pass without regressions',
+            'Use the preserved source description above as the authoritative requirements body. ' +
+                'Do not infer implementation ownership beyond details explicitly provided in the source. ' +
+                contextLine,
             '',
             technicalSection,
         ].join('\n');
@@ -38,25 +20,18 @@ export class FallbackGenerator {
             generatedWithModel: 'deterministic-fallback',
             generatedAt: new Date().toISOString(),
             qualityWarnings: [
-                'Fallback generator used. Review candidate file paths and replace placeholders with exact code owners before approval.',
+                'Fallback generator used. Source description was preserved; no implementation files, type signatures, or ownership were inferred.',
             ],
             fallbackReason: 'No external model generator is configured for create_spec.',
         });
     }
 }
-function normalizeSummary(description, title) {
-    const compact = description
-        .replace(/\r\n/g, '\n')
-        .split('\n')
-        .map((line) => line.trim())
-        .filter((line) => line.length > 0 && !line.startsWith('- [ ]'))
-        .join(' ')
-        .replace(/\s+/g, ' ')
-        .trim();
-    const summary = compact.length > 0
-        ? compact.slice(0, MAX_SUMMARY_LENGTH)
-        : `The project needs ${title} defined with enough implementation detail to proceed safely.`;
-    return summary.endsWith('.') ? summary : `${summary}.`;
+function normalizeSourceDescription(description, title) {
+    const compact = description.replace(/\r\n/g, '\n').trim();
+    if (compact.length > 0) {
+        return compact;
+    }
+    return `The project needs ${title} defined with enough implementation detail to proceed safely.`;
 }
 function buildContextLine(request) {
     const parts = [
@@ -69,34 +44,22 @@ function buildContextLine(request) {
     }
     return `Use the existing ${parts.join(' / ')} project conventions.`;
 }
-function buildTechnicalSection(slug, pascalName, contextLine) {
+function buildTechnicalSection(contextLine) {
     return [
         '## Technical',
         '',
         '### Implementation Notes',
         `- ${contextLine}`,
-        '- Replace candidate paths with exact files before moving the spec to approved.',
+        '- Preserve the source requirements as the contract until a reviewer or agent adds exact implementation ownership.',
         '',
         '## Files',
         '',
         '### Create',
-        `- src/${slug}.ts (candidate path; replace with exact owner during planning)`,
+        '- _Not specified in source description._',
         '### Modify',
-        '- src/index.ts (candidate integration point; replace with exact owner during planning)',
+        '- _Not specified in source description._',
         '### Test',
-        `- tests/${slug}.test.ts (focused coverage for the behavior and failure path)`,
-        '',
-        '## Type Signatures',
-        '```typescript',
-        `interface ${pascalName}Input {`,
-        '  readonly requestId?: string;',
-        '}',
-        '',
-        `interface ${pascalName}Result {`,
-        '  readonly ok: boolean;',
-        '  readonly reason?: string;',
-        '}',
-        '```',
+        '- _Not specified in source description._',
         '',
         '## Verification',
         '- pnpm typecheck',
@@ -104,17 +67,4 @@ function buildTechnicalSection(slug, pascalName, contextLine) {
         '- pnpm test',
     ].join('\n');
 }
-function slugify(input) {
-    const slug = input
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '');
-    return slug.length > 0 ? slug : 'generated-spec';
-}
-function toPascalCase(input) {
-    const words = input.match(/[a-zA-Z0-9]+/g) ?? ['Generated', 'Spec'];
-    return words
-        .map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1).toLowerCase()}`)
-        .join('');
-}
 //# sourceMappingURL=fallback-generator.js.map

package/dist/engine/universal-rules/rules/planu-workflow.js

@@ -15,7 +15,20 @@ Auto-generated by \`init_project\`. Do not edit manually.
 | implementing | work in progress |
 | done | implemented + validated |
 
-Flow: \`facilitate → create_spec → challenge_spec → check_readiness → approve → implement → validate → done\`
+Flow: \`facilitate → create_spec → discovery evidence → challenge_spec → check_readiness → approve → task plan → implement → traceability evidence → validate → done\`
+
+## Evidence Gates
+
+For non-trivial specs, Planu blocks lifecycle transitions unless evidence is present:
+
+| Transition | Required evidence |
+|------------|-------------------|
+| approved | Discovery evidence: rules, examples, open questions, out-of-scope, glossary |
+| implementing | Task plan mapped to acceptance criteria |
+| done | Traceability matrix covering every acceptance criterion |
+| done for API/UI/event/MCP work | Passing contract validation evidence |
+
+Evidence can live under \`planu/specs/<spec>/evidence/\` or the external Planu handoff store. Trivial specs may use lightweight evidence, but \`done\` still needs at least one traceability row.
 
 ## When to use \`facilitate\`
 

package/dist/tools/update-status/evidence-gate.d.ts

@@ -0,0 +1,12 @@
+import type { ToolResult } from '../../types/index.js';
+import type { Spec } from '../../types/spec/core.js';
+import type { EvidenceGateTransition } from '../../types/evidence-gates.js';
+/** SPEC-1054: BDD/SDD lifecycle evidence gate. */
+export declare function checkLifecycleEvidenceTransitionGate(args: {
+    spec: Spec;
+    specId: string;
+    projectId: string;
+    projectPath?: string;
+    transition: EvidenceGateTransition;
+}): Promise<ToolResult | null>;
+//# sourceMappingURL=evidence-gate.d.ts.map

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

@@ -0,0 +1,85 @@
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+import { extractCriteria, extractListItems, extractSection, } from '../../engine/validator/extractors.js';
+import { stripFrontmatter } from '../../engine/frontmatter-parser.js';
+import { readEvidenceArtifacts } from '../../engine/evidence-gates/artifact-reader.js';
+import { checkLifecycleEvidenceGate } from '../../engine/evidence-gates/lifecycle-gate.js';
+/** SPEC-1054: BDD/SDD lifecycle evidence gate. */
+export async function checkLifecycleEvidenceTransitionGate(args) {
+    const [criteria, artifacts] = await Promise.all([
+        extractLifecycleGateCriteria(args.spec, args.projectPath),
+        readEvidenceArtifacts({
+            spec: args.spec,
+            projectId: args.projectId,
+            specId: args.specId,
+            projectPath: args.projectPath,
+        }),
+    ]);
+    const result = checkLifecycleEvidenceGate({
+        transition: args.transition,
+        spec: args.spec,
+        criteria,
+        artifacts,
+    });
+    if (result.passed) {
+        return null;
+    }
+    return evidenceGateError({
+        specId: args.specId,
+        transition: args.transition,
+        issues: result.issues.map((issue) => ({
+            code: issue.code,
+            message: issue.message,
+        })),
+        requiredContractKinds: result.requiredContractKinds,
+    });
+}
+async function extractLifecycleGateCriteria(spec, projectPath) {
+    const specPath = isAbsolute(spec.specPath) || !projectPath ? spec.specPath : join(projectPath, spec.specPath);
+    try {
+        const raw = await readFile(specPath, 'utf-8');
+        const body = stripFrontmatter(raw);
+        const acceptanceCriteria = extractSection(body, 'acceptance criteria', 'criterios de aceptaci');
+        if (acceptanceCriteria) {
+            const items = extractListItems(acceptanceCriteria);
+            if (items.length > 0) {
+                return [...new Set(items)];
+            }
+        }
+    }
+    catch {
+        // Fall back to the broader validator extractor when the canonical file is unavailable.
+    }
+    return extractCriteria(spec);
+}
+function evidenceGateError(args) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    error: 'lifecycle_evidence_gate_failed',
+                    message: `BDD/SDD evidence gate blocked ${args.transition}.`,
+                    specId: args.specId,
+                    transition: args.transition,
+                    issues: args.issues,
+                    requiredContractKinds: args.requiredContractKinds,
+                    fixHint: 'Add the missing evidence artifact under planu/specs/<spec>/evidence/ or external Planu project data handoffs/<specId>/, then retry the transition.',
+                }, null, 2),
+            },
+        ],
+        isError: true,
+        structuredContent: {
+            error: 'lifecycle_evidence_gate_failed',
+            code: 422,
+            context: {
+                specId: args.specId,
+                transition: args.transition,
+                issues: args.issues,
+                requiredContractKinds: args.requiredContractKinds,
+            },
+            fixHint: 'Add discovery.json, task-plan.json, traceability-matrix.json, and contract-validation-*.json as required for this transition.',
+        },
+    };
+}
+//# sourceMappingURL=evidence-gate.js.map

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

@@ -14,6 +14,7 @@ import { checkApprovalGate } from '../../engine/approval-workflow.js';
 import * as approvalStore from '../../storage/approval-store.js';
 import { isLocked, getLock } from '../../storage/spec-lock-store.js';
 import { runValidateGate, checkDoneGates, checkComplianceGate, checkQaGate, checkApprovedFormatGate, checkValidationReportGate, checkSpecReviewGate, writeSpecReviewArtifact, } from './dod-gates.js';
+import { checkLifecycleEvidenceTransitionGate } from './evidence-gate.js';
 import { buildStatusResponse, buildValidateBlockedResponse, buildDryRunResponse, } from './response-builder.js';
 import { getSuggestedMode } from './mode-hints.js';
 import { autoFillActuals, createDefaultActuals } from '../../engine/actuals-estimator.js';
@@ -227,6 +228,9 @@ async function resolveOrchestrationPlan(newStatus, specScope, specId, projectPat
 function shouldSkipSddRoutingGateForLegacyTestHarness() {
     return process.env.VITEST === 'true' && process.env.PLANU_TEST_STRICT_SDD_GATES !== 'true';
 }
+function shouldSkipEvidenceGateForLegacyTestHarness() {
+    return process.env.VITEST === 'true' && process.env.PLANU_TEST_STRICT_EVIDENCE_GATES !== 'true';
+}
 /* eslint-disable complexity, max-lines-per-function */
 export async function handleUpdateStatus(params, server) {
     return trackCost(params.projectPath ?? '', 'update_status', async () => {
@@ -434,6 +438,22 @@ export async function handleUpdateStatus(params, server) {
                 if (sddRoutingGate.blockResult) {
                     return sddRoutingGate.blockResult;
                 }
+                // SPEC-1054: BDD/SDD evidence gates. Non-trivial specs must carry
+                // Discovery before approval, task-plan before implementation, and
+                // traceability/contract evidence before done.
+                if (!shouldSkipEvidenceGateForLegacyTestHarness() &&
+                    (newStatus === 'approved' || newStatus === 'implementing' || newStatus === 'done')) {
+                    const evidenceGate = await checkLifecycleEvidenceTransitionGate({
+                        spec,
+                        specId,
+                        projectId,
+                        projectPath: effectiveGatePath,
+                        transition: newStatus,
+                    });
+                    if (evidenceGate !== null) {
+                        return evidenceGate;
+                    }
+                }
                 // ---------------------------------------------------------------------------
                 // BATCH A (parallel): code-reality + done-gates — independent of each other
                 // SPEC-441: Code reality check before transitioning to 'implementing'

package/dist/types/evidence-gates.d.ts

@@ -0,0 +1,65 @@
+export type EvidenceGateTransition = 'approved' | 'implementing' | 'done';
+export interface DiscoveryEvidence {
+    version: 1;
+    rules: string[];
+    examples: {
+        rule: string;
+        example: string;
+    }[];
+    openQuestions: {
+        question: string;
+        status: 'open' | 'resolved' | 'out_of_scope';
+        resolution?: string;
+    }[];
+    outOfScope: string[];
+    glossary: {
+        term: string;
+        meaning: string;
+    }[];
+}
+export interface TaskPlanEvidence {
+    version: 1;
+    tasks: {
+        id: string;
+        title: string;
+        acceptanceCriteria: string[];
+        status: 'pending' | 'doing' | 'done';
+    }[];
+}
+export interface TraceabilityMatrixEvidence {
+    version: 1;
+    rows: {
+        acceptanceCriterion: string;
+        scenario?: string;
+        testEvidence?: string[];
+        contractEvidence?: string[];
+        manualEvidence?: string;
+        changedFiles: string[];
+        validationEvidence?: string;
+        reviewerEvidence?: string;
+    }[];
+}
+export interface ContractValidationEvidence {
+    version: 1;
+    kind: 'api' | 'graphql' | 'event' | 'ui' | 'mcp';
+    passed: boolean;
+    reportPath?: string;
+    summary?: string;
+}
+export interface EvidenceArtifacts {
+    discovery?: DiscoveryEvidence;
+    taskPlan?: TaskPlanEvidence;
+    traceabilityMatrix?: TraceabilityMatrixEvidence;
+    contractValidations: ContractValidationEvidence[];
+    invalidArtifacts: string[];
+}
+export interface EvidenceGateIssue {
+    code: 'discovery_missing' | 'discovery_unresolved_questions' | 'task_plan_missing' | 'task_plan_uncovered_criteria' | 'traceability_missing' | 'traceability_uncovered_criteria' | 'traceability_incomplete_rows' | 'contract_validation_missing' | 'contract_validation_failed' | 'evidence_artifact_invalid';
+    message: string;
+}
+export interface EvidenceGateResult {
+    passed: boolean;
+    issues: EvidenceGateIssue[];
+    requiredContractKinds: ContractValidationEvidence['kind'][];
+}
+//# sourceMappingURL=evidence-gates.d.ts.map

package/dist/types/evidence-gates.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.2.6",
+  "version": "4.3.1",
   "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,14 +32,14 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "4.2.6",
-    "@planu/core-darwin-x64": "4.2.6",
-    "@planu/core-linux-arm64-gnu": "4.2.6",
-    "@planu/core-linux-arm64-musl": "4.2.6",
-    "@planu/core-linux-x64-gnu": "4.2.6",
-    "@planu/core-linux-x64-musl": "4.2.6",
-    "@planu/core-win32-arm64-msvc": "4.2.6",
-    "@planu/core-win32-x64-msvc": "4.2.6"
+    "@planu/core-darwin-arm64": "4.3.1",
+    "@planu/core-darwin-x64": "4.3.1",
+    "@planu/core-linux-arm64-gnu": "4.3.1",
+    "@planu/core-linux-arm64-musl": "4.3.1",
+    "@planu/core-linux-x64-gnu": "4.3.1",
+    "@planu/core-linux-x64-musl": "4.3.1",
+    "@planu/core-win32-arm64-msvc": "4.3.1",
+    "@planu/core-win32-x64-msvc": "4.3.1"
   },
   "engines": {
     "node": ">=24.0.0"