@planu/cli 4.4.2 → 4.5.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [4.5.0] - 2026-06-10
+
+### Features
+- feat(create-spec): generate intent-grounded questions
+
+### Chores
+- chore(deps): update release tooling
+
+
+## [4.4.3] - 2026-06-09
+
+### Features
+- feat(SPEC-1081): add skill security scan gate
+- feat(SPEC-1082): add implementation contract readiness
+
+
 ## [4.4.2] - 2026-06-05
 
 ### Bug Fixes
@@ -4035,4 +4051,4 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 - Mermaid diagram generation (architecture, sequence, state machine, ER, data flow)
 - Multi-language i18n (EN/ES/PT) for generated specs
 - Clean Architecture (hexagonal) — engine, tools, storage, types layers
-- 10,857 tests with ≥95% coverage
+- 10,857 tests with ≥95% coverage

package/dist/engine/elicitation/answer-extractor.js

@@ -5,6 +5,12 @@ const BACKEND_TERMS = /\b(api|endpoint|route|handler|migration|query|rpc|action|
 const INFRA_TERMS = /\b(deploy|ci|cd|docker|pipeline|config|env)\b/;
 const BILLING_TERMS = /\b(payment|billing|invoice|subscription|checkout|pricing|pay)\b/;
 const DATABASE_TERMS = /\b(database|schema|migration|table|query|sql|rls|rpc|persist|persistence|data access)\b/;
+const ACTION_RE = /\b(add|build|create|fix|update|remove|delete|integrate|sync|import|export|approve|reject|upload|download|migrate|configure|validate)\b\s+(?:(?:a|an|the|new)\s+)?([a-z0-9][a-z0-9 -]{1,60})/i;
+const ACTOR_TERMS = /\b(admin|administrator|manager|owner|customer|user|member|team|approver)\b/gi;
+const DATA_OBJECT_TERMS = /\b(account|profile|request|invoice|subscription|payment|order|report|file|avatar|table|policy|record|settings)\b/gi;
+const PERMISSION_TERMS = /\b(approval|approve|reject|admin|permission|role|rls|policy|access|auth|login|oauth|owner|manager)\b/;
+const DESTRUCTIVE_TERMS = /\b(delete|remove|archive|discard|drop|truncate|revoke|reset)\b/;
+const RISK_TERMS = /\b(approval|approve|payment|billing|auth|login|permission|role|delete|remove|migration|sync|webhook|external|api|rls|privacy|security)\b/gi;
 const PAYMENT_PROVIDERS = [
     { name: 'Stripe', pattern: /\bstripe\b/ },
     { name: 'PayPal', pattern: /\bpaypal\b/ },
@@ -33,7 +39,34 @@ export function extractSignals(description) {
     const hasBilling = BILLING_TERMS.test(lower) || namedProvider !== null;
     const wordCount = description.trim().split(/\s+/).length;
     const hasScope = wordCount >= 10;
-    return { hasTarget, hasBilling, hasDatabase, hasUi, namedProvider, hasScope };
+    const actionMatch = ACTION_RE.exec(lower);
+    const action = actionMatch?.[1] ?? null;
+    const domainObject = cleanDomainObject(actionMatch?.[2] ?? null);
+    const actors = uniqueMatches(lower, ACTOR_TERMS);
+    const dataObjects = uniqueMatches(lower, DATA_OBJECT_TERMS);
+    const riskTerms = uniqueMatches(lower, RISK_TERMS);
+    const integrations = [
+        ...PAYMENT_PROVIDERS.filter(({ pattern }) => pattern.test(lower)).map(({ name }) => name),
+        ...extractExternalIntegrations(lower),
+    ];
+    const hasPermissionRisk = PERMISSION_TERMS.test(lower);
+    const hasDestructiveAction = DESTRUCTIVE_TERMS.test(lower);
+    return {
+        hasTarget,
+        hasBilling,
+        hasDatabase,
+        hasUi,
+        namedProvider,
+        hasScope,
+        action,
+        domainObject,
+        actors,
+        integrations,
+        dataObjects,
+        hasPermissionRisk,
+        hasDestructiveAction,
+        riskTerms,
+    };
 }
 function stripIncidentalReferences(description) {
     return description
@@ -41,4 +74,23 @@ function stripIncidentalReferences(description) {
         .replace(/\b\S+\/\S+\b/g, ' ')
         .replace(/\b[\w-]+\.(?:ts|tsx|js|jsx|mjs|cjs|json|md|css|scss|py|go|rs|java|rb|php)\b/g, ' ');
 }
+function cleanDomainObject(value) {
+    if (value === null) {
+        return null;
+    }
+    const cleaned = value
+        .replace(/\b(that|with|to|from|when|where|and|or|but|using|in)\b.*$/i, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return cleaned.length > 0 ? cleaned : null;
+}
+function uniqueMatches(text, pattern) {
+    const flags = pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`;
+    const globalPattern = new RegExp(pattern.source, flags);
+    return Array.from(new Set(Array.from(text.matchAll(globalPattern)).map((match) => match[0])));
+}
+function extractExternalIntegrations(text) {
+    const matches = text.match(/\b([a-z][a-z0-9-]+)\s+(?:api|webhook|sdk|integration)\b/gi) ?? [];
+    return Array.from(new Set(matches.map((match) => match.replace(/\s+(api|webhook|sdk|integration)$/i, ''))));
+}
 //# sourceMappingURL=answer-extractor.js.map

package/dist/engine/elicitation/decision-gap-detector.d.ts

@@ -0,0 +1,3 @@
+import type { DecisionGap, ProjectKnowledge, DescriptionSignals } from '../../types/index.js';
+export declare function detectDecisionGaps(signals: DescriptionSignals, _projectContext: ProjectKnowledge | null): DecisionGap[];
+//# sourceMappingURL=decision-gap-detector.d.ts.map

package/dist/engine/elicitation/decision-gap-detector.js

@@ -0,0 +1,162 @@
+const MAX_GAPS = 3;
+export function detectDecisionGaps(signals, _projectContext) {
+    const gaps = [
+        buildPermissionGap(signals),
+        buildProviderGap(signals),
+        buildBillingModelGap(signals),
+        buildDataGap(signals),
+        buildFailureGap(signals),
+    ].filter((gap) => gap !== null);
+    if (gaps.length === 0 && !signals.hasScope) {
+        gaps.push(buildBehaviorGap(signals));
+    }
+    return gaps.slice(0, MAX_GAPS);
+}
+function buildPermissionGap(signals) {
+    if (!signals.hasPermissionRisk || signals.actors.length > 0) {
+        return null;
+    }
+    const subject = formatSubject(signals);
+    return makeGap({
+        id: 'permission-owner',
+        kind: 'permission',
+        header: 'Permission',
+        question: `For ${subject}, who is allowed to perform this action? This changes permissions, validation, and audit behavior.`,
+        evidence: evidenceFrom(signals, ['permission-sensitive wording']),
+        impact: 'Changes authorization checks and acceptance criteria.',
+        options: options([
+            ['Role-based owner (Recommended)', 'Use the existing role or owner model for this action.'],
+            ['Admin only', 'Restrict the behavior to administrators.'],
+            ['Any signed-in user', 'Allow all authenticated users and keep checks minimal.'],
+        ]),
+    });
+}
+function buildProviderGap(signals) {
+    if (!signals.hasBilling || signals.namedProvider !== null) {
+        return null;
+    }
+    const subject = formatSubject(signals);
+    return makeGap({
+        id: 'payment-provider',
+        kind: 'provider',
+        header: 'Provider',
+        question: `For ${subject}, which payment provider should own the payment flow? This changes API contracts, webhook handling, and test fixtures.`,
+        evidence: evidenceFrom(signals, ['billing/payment wording']),
+        impact: 'Changes integration code, webhook behavior, and verification fixtures.',
+        options: options([
+            ['Stripe (Recommended)', 'Use the most common provider for subscription and checkout flows.'],
+            ['PayPal', 'Use PayPal checkout and payment APIs.'],
+            [
+                'No provider yet',
+                'Keep provider integration out of scope and define internal contracts only.',
+            ],
+        ]),
+    });
+}
+function buildBillingModelGap(signals) {
+    if (!signals.hasBilling) {
+        return null;
+    }
+    const subject = formatSubject(signals);
+    return makeGap({
+        id: 'billing-model',
+        kind: 'billing-model',
+        header: 'Billing',
+        question: `For ${subject}, is the billing behavior recurring, one-time, or invoice-based? This changes states, events, and acceptance criteria.`,
+        evidence: evidenceFrom(signals, ['billing/payment wording']),
+        impact: 'Changes lifecycle states and acceptance criteria.',
+        options: options([
+            ['Recurring subscription (Recommended)', 'Model ongoing subscriptions and renewal states.'],
+            ['One-time checkout', 'Model a single payment completion flow.'],
+            ['Invoice-based', 'Model invoice creation, payment, and overdue states.'],
+        ]),
+    });
+}
+function buildDataGap(signals) {
+    if (!signals.hasDatabase || signals.dataObjects.length > 0) {
+        return null;
+    }
+    const subject = formatSubject(signals);
+    return makeGap({
+        id: 'data-shape',
+        kind: 'data',
+        header: 'Data',
+        question: `For ${subject}, what data must be stored or updated? This changes schema, validation, and migration work.`,
+        evidence: evidenceFrom(signals, ['database/data wording']),
+        impact: 'Changes schema, persistence, and validation requirements.',
+        options: options([
+            [
+                'Existing records only (Recommended)',
+                'Use existing tables or records without a new schema.',
+            ],
+            ['New table or field', 'Add persistence changes and migration coverage.'],
+            ['Read-only data', 'Do not persist new state for this behavior.'],
+        ]),
+    });
+}
+function buildFailureGap(signals) {
+    if (signals.integrations.length === 0 &&
+        !signals.riskTerms.includes('sync') &&
+        !signals.riskTerms.includes('api')) {
+        return null;
+    }
+    const subject = formatSubject(signals);
+    return makeGap({
+        id: 'failure-handling',
+        kind: 'failure',
+        header: 'Failure',
+        question: `For ${subject}, what should happen if ${formatIntegration(signals)} fails? This changes retry, error, and user-visible behavior.`,
+        evidence: evidenceFrom(signals, signals.integrations.length > 0 ? signals.integrations : ['integration/API wording']),
+        impact: 'Changes error handling, retries, and tests.',
+        options: options([
+            ['Show recoverable error (Recommended)', 'Return a clear error and preserve current state.'],
+            ['Retry automatically', 'Retry transient failures before surfacing an error.'],
+            ['Queue for later', 'Persist work for asynchronous retry.'],
+        ]),
+    });
+}
+function buildBehaviorGap(signals) {
+    const subject = formatSubject(signals);
+    return makeGap({
+        id: 'behavior-outcome',
+        kind: 'behavior',
+        header: 'Behavior',
+        question: `For ${subject}, what observable outcome should prove the work is done? This becomes the primary acceptance criterion.`,
+        evidence: evidenceFrom(signals, ['short request']),
+        impact: 'Changes the main acceptance criterion and verification command.',
+        options: options([
+            ['User-visible workflow (Recommended)', 'Define the end-to-end behavior a user can observe.'],
+            ['Backend behavior', 'Define API, persistence, job, or integration behavior.'],
+            ['Cleanup or fix', 'Define the before/after bug or cleanup result.'],
+        ]),
+    });
+}
+function makeGap(gap) {
+    return { ...gap, multiSelect: gap.multiSelect ?? false, blocking: true };
+}
+function formatSubject(signals) {
+    const action = signals.action ?? 'this request';
+    const object = signals.domainObject;
+    return object === null ? action : `${action} ${object}`;
+}
+function formatIntegration(signals) {
+    if (signals.integrations.length > 0) {
+        return signals.integrations[0] ?? 'the integration';
+    }
+    if (signals.riskTerms.includes('sync')) {
+        return 'the sync';
+    }
+    return 'the API';
+}
+function evidenceFrom(signals, extra) {
+    return [
+        ...(signals.action ? [`action:${signals.action}`] : []),
+        ...(signals.domainObject ? [`object:${signals.domainObject}`] : []),
+        ...signals.riskTerms.map((term) => `risk:${term}`),
+        ...extra,
+    ].slice(0, 6);
+}
+function options(items) {
+    return items.map(([label, description]) => ({ label, description }));
+}
+//# sourceMappingURL=decision-gap-detector.js.map

package/dist/engine/elicitation/question-grounding-gate.d.ts

@@ -0,0 +1,3 @@
+import type { InteractiveQuestion, QuestionGroundingContext, QuestionGroundingResult } from '../../types/index.js';
+export declare function validateQuestionGrounding(question: InteractiveQuestion, context: QuestionGroundingContext): QuestionGroundingResult;
+//# sourceMappingURL=question-grounding-gate.d.ts.map

package/dist/engine/elicitation/question-grounding-gate.js

@@ -0,0 +1,54 @@
+const GENERIC_QUESTION_PATTERNS = [
+    /^who (are|is) the users\??$/i,
+    /^what are the edge cases\??$/i,
+    /^what should happen\??$/i,
+    /^what is the scope\??$/i,
+    /^what data is needed\??$/i,
+    /^what are the requirements\??$/i,
+];
+export function validateQuestionGrounding(question, context) {
+    const text = question.question.trim();
+    if (GENERIC_QUESTION_PATTERNS.some((pattern) => pattern.test(text))) {
+        return { passed: false, reason: 'Question is a generic reusable prompt.' };
+    }
+    const lowerQuestion = text.toLowerCase();
+    const lowerEvidence = [context.requestText, ...context.gap.evidence].join(' ').toLowerCase();
+    const evidenceTokens = tokenSet(lowerEvidence);
+    const hasRequestEvidence = Array.from(evidenceTokens).some((token) => token.length >= 3 && lowerQuestion.includes(token));
+    if (!hasRequestEvidence) {
+        return {
+            passed: false,
+            reason: 'Question does not include evidence from the request or detected gap.',
+        };
+    }
+    if (!/\bchanges?\b|\bthis changes\b|\baffects?\b|\bbecause\b|\bbecomes?\b/i.test(text)) {
+        return {
+            passed: false,
+            reason: 'Question does not explain why the answer matters for the spec.',
+        };
+    }
+    return { passed: true };
+}
+function tokenSet(text) {
+    return new Set(text
+        .replace(/[^a-z0-9 ]/gi, ' ')
+        .split(/\s+/)
+        .filter((token) => !STOP_WORDS.has(token) && token.length > 2));
+}
+const STOP_WORDS = new Set([
+    'the',
+    'and',
+    'for',
+    'this',
+    'that',
+    'with',
+    'from',
+    'what',
+    'when',
+    'where',
+    'should',
+    'action',
+    'object',
+    'risk',
+]);
+//# sourceMappingURL=question-grounding-gate.js.map

package/dist/engine/implementation-contract/common.d.ts

@@ -0,0 +1,5 @@
+export declare const IMPLEMENTATION_CONTRACT_SECTION = "Implementation Contract";
+export declare const IMPLEMENTATION_CONTRACT_SUBSECTIONS: readonly ["User Outcome", "Behavior Contract", "File-Level Work Plan", "Acceptance-To-Verification Map", "Edge Cases And Failure Modes", "Non-Goals And Forbidden Approaches", "Verification Commands"];
+export declare function hasImplementationContract(specBody: string): boolean;
+export declare function extractTopLevelSection(body: string, sectionName: string): string;
+//# sourceMappingURL=common.d.ts.map

package/dist/engine/implementation-contract/common.js

@@ -0,0 +1,30 @@
+export const IMPLEMENTATION_CONTRACT_SECTION = 'Implementation Contract';
+export const IMPLEMENTATION_CONTRACT_SUBSECTIONS = [
+    'User Outcome',
+    'Behavior Contract',
+    'File-Level Work Plan',
+    'Acceptance-To-Verification Map',
+    'Edge Cases And Failure Modes',
+    'Non-Goals And Forbidden Approaches',
+    'Verification Commands',
+];
+export function hasImplementationContract(specBody) {
+    return extractTopLevelSection(specBody, IMPLEMENTATION_CONTRACT_SECTION).trim().length > 0;
+}
+export function extractTopLevelSection(body, sectionName) {
+    const normalized = body.replace(/\r\n/g, '\n');
+    const headingRe = new RegExp(`^##\\s+${escapeRegex(sectionName)}[ \\t]*$`, 'm');
+    const match = headingRe.exec(normalized);
+    if (!match) {
+        return '';
+    }
+    const start = match.index + match[0].length;
+    const nextRe = /^##\s+\S/gm;
+    nextRe.lastIndex = start;
+    const next = nextRe.exec(normalized);
+    return normalized.slice(start, next ? next.index : normalized.length).trim();
+}
+function escapeRegex(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=common.js.map

package/dist/engine/implementation-contract/evaluator.d.ts

@@ -0,0 +1,3 @@
+import type { ImplementationContractIssue } from '../../types/index.js';
+export declare function evaluateImplementationContract(specBody: string, acceptanceCriteria: string[]): ImplementationContractIssue[];
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/engine/implementation-contract/evaluator.js

@@ -0,0 +1,105 @@
+import { extractTopLevelSection, IMPLEMENTATION_CONTRACT_SECTION, IMPLEMENTATION_CONTRACT_SUBSECTIONS, } from './common.js';
+const FILLER_PATTERNS = [
+    /\bTBD\b/i,
+    /\bN\/A\b/i,
+    /\bimplement correctly\b/i,
+    /\bhandle errors\b/i,
+    /\bto be determined\b/i,
+];
+export function evaluateImplementationContract(specBody, acceptanceCriteria) {
+    const contract = extractTopLevelSection(specBody, IMPLEMENTATION_CONTRACT_SECTION);
+    if (contract.trim().length === 0) {
+        return [
+            {
+                code: 'contract_missing',
+                message: 'Implementation Contract is missing — add user outcome, behavior, file plan, verification map, edge cases, non-goals, and commands.',
+            },
+        ];
+    }
+    const issues = [];
+    const sections = new Map(IMPLEMENTATION_CONTRACT_SUBSECTIONS.map((section) => [
+        section,
+        extractSubsection(contract, section),
+    ]));
+    for (const [section, content] of sections.entries()) {
+        if (content === null) {
+            issues.push({
+                code: 'contract_subsection_missing',
+                message: `Implementation Contract subsection "${section}" is missing.`,
+            });
+            continue;
+        }
+        const trimmed = content.trim();
+        if (trimmed.length === 0) {
+            issues.push({
+                code: 'contract_subsection_empty',
+                message: `Implementation Contract subsection "${section}" is empty.`,
+            });
+        }
+        for (const pattern of FILLER_PATTERNS) {
+            if (pattern.test(trimmed)) {
+                issues.push({
+                    code: 'contract_filler',
+                    message: `Implementation Contract subsection "${section}" contains filler text.`,
+                });
+                break;
+            }
+        }
+        if (/\bNeeds decision:/i.test(trimmed)) {
+            issues.push({
+                code: 'contract_needs_decision',
+                message: `Implementation Contract subsection "${section}" still has unresolved Needs decision items.`,
+            });
+        }
+    }
+    const map = sections.get('Acceptance-To-Verification Map') ?? '';
+    for (const criterion of acceptanceCriteria) {
+        if (!criterionHasVerification(criterion, map)) {
+            issues.push({
+                code: 'contract_unmapped_criterion',
+                message: `Acceptance criterion is not mapped to verification evidence: ${criterion}`,
+            });
+        }
+    }
+    if (/\bmanual verification\b/i.test(map) &&
+        !/\b(given|when|then|step|observe|click|run)\b/i.test(map)) {
+        issues.push({
+            code: 'contract_manual_verification_vague',
+            message: 'Manual verification in the Implementation Contract must include exact observable steps.',
+        });
+    }
+    return issues;
+}
+function extractSubsection(sectionBody, subsectionName) {
+    const headingRe = new RegExp(`^###\\s+${escapeRegex(subsectionName)}[ \\t]*$`, 'm');
+    const match = headingRe.exec(sectionBody);
+    if (!match) {
+        return null;
+    }
+    const start = match.index + match[0].length;
+    const nextRe = /^###\s+\S/gm;
+    nextRe.lastIndex = start;
+    const next = nextRe.exec(sectionBody);
+    return sectionBody.slice(start, next ? next.index : sectionBody.length);
+}
+function criterionHasVerification(criterion, map) {
+    const normalizedCriterion = normalize(criterion);
+    if (normalizedCriterion.length === 0) {
+        return true;
+    }
+    const short = normalizedCriterion.slice(0, 48);
+    const normalizedMap = normalize(map);
+    return (normalizedMap.includes(short) &&
+        /\b(unit test|integration test|cli\/tool result|typecheck\/lint command|snapshot\/golden fixture|manual verification|pnpm|vitest|test)\b/i.test(map));
+}
+function normalize(value) {
+    return value
+        .replace(/[`*_()[\]:]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase();
+}
+function escapeRegex(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=evaluator.js.map

package/dist/engine/implementation-contract/index.d.ts

@@ -0,0 +1,4 @@
+export * from './common.js';
+export * from './renderer.js';
+export * from './evaluator.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/implementation-contract/index.js

@@ -0,0 +1,4 @@
+export * from './common.js';
+export * from './renderer.js';
+export * from './evaluator.js';
+//# sourceMappingURL=index.js.map

package/dist/engine/implementation-contract/renderer.d.ts

@@ -0,0 +1,4 @@
+import type { ImplementationContractInput } from '../../types/index.js';
+export declare function buildImplementationContractSection(input: ImplementationContractInput): string;
+export declare function appendImplementationContractIfMissing(specBody: string, input: ImplementationContractInput): string;
+//# sourceMappingURL=renderer.d.ts.map

package/dist/engine/implementation-contract/renderer.js

@@ -0,0 +1,98 @@
+import { hasImplementationContract, IMPLEMENTATION_CONTRACT_SECTION } from './common.js';
+export function buildImplementationContractSection(input) {
+    const criteria = input.criteria.length > 0 ? input.criteria : fallbackCriteria();
+    const testFiles = input.files.test.map((file) => file.path);
+    const verificationCommands = input.verificationCommands.length > 0
+        ? input.verificationCommands
+        : ['pnpm typecheck', 'pnpm lint', 'pnpm test'];
+    const lines = [
+        `## ${IMPLEMENTATION_CONTRACT_SECTION}`,
+        '### User Outcome',
+        firstConcreteSentence(input.description) ??
+            'Needs decision: define the exact user-visible outcome this spec must deliver.',
+        '',
+        '### Behavior Contract',
+        ...renderBehaviorContract(criteria),
+        '- Inputs: use the user request and existing project conventions as the source of truth.',
+        '- Outputs: update canonical `spec.md` behavior without creating sidecar implementation docs.',
+        '- State changes: persist only the files and metadata required by the spec workflow.',
+        '- Errors: missing implementation detail must surface as `Needs decision:` instead of generic filler.',
+        '',
+        '### File-Level Work Plan',
+        ...renderFilePlan(input.files),
+        '',
+        '### Acceptance-To-Verification Map',
+        ...criteria.map((criterion, index) => renderVerificationRow(criterion.text, index + 1, testFiles, verificationCommands)),
+        '',
+        '### Edge Cases And Failure Modes',
+        '- Generated specs with too little context must use `Needs decision:` placeholders.',
+        '- Existing specs without this section must remain readable and must not be rewritten by readiness checks.',
+        '- A heading with filler text must not count as a usable implementation contract.',
+        '- Manual verification must include exact observable steps when no automated proof is practical.',
+        '',
+        '### Non-Goals And Forbidden Approaches',
+        ...renderNonGoals(input.outOfScope),
+        '',
+        '### Verification Commands',
+        ...verificationCommands.map((command) => `- \`${command}\``),
+        '',
+    ];
+    return lines.join('\n');
+}
+export function appendImplementationContractIfMissing(specBody, input) {
+    if (hasImplementationContract(specBody)) {
+        return specBody.endsWith('\n') ? specBody : `${specBody}\n`;
+    }
+    return `${specBody.trimEnd()}\n\n${buildImplementationContractSection(input)}`;
+}
+function fallbackCriteria() {
+    return [
+        {
+            text: 'Needs decision: define at least one acceptance criterion with executable verification.',
+            done: false,
+        },
+    ];
+}
+function firstConcreteSentence(description) {
+    const body = description
+        .replace(/^---[\s\S]*?---/, '')
+        .replace(/^#{1,6}\s+.+$/gm, '')
+        .split('\n')
+        .map((line) => line.trim())
+        .find((line) => line.length >= 24 && !line.startsWith('-'));
+    if (!body) {
+        return null;
+    }
+    return body.replace(/\s+/g, ' ').slice(0, 240);
+}
+function renderFilePlan(files) {
+    const lines = [];
+    for (const [label, entries] of [
+        ['Create', files.create],
+        ['Modify', files.modify],
+        ['Test', files.test],
+    ]) {
+        for (const entry of entries) {
+            lines.push(`- ${label}: \`${entry.path}\` (${entry.status})`);
+        }
+    }
+    return lines.length > 0 ? lines : ['- Needs decision: identify expected source and test files.'];
+}
+function renderBehaviorContract(criteria) {
+    return criteria.map((criterion, index) => `- Expected behavior AC${String(index + 1)}: ${criterion.text}`);
+}
+function renderVerificationRow(criterion, index, testFiles, commands) {
+    const test = testFiles[0];
+    if (test) {
+        return `- AC${String(index)}: ${criterion} -> unit test \`${test}\` plus \`${commands[0] ?? 'pnpm test'}\`.`;
+    }
+    return `- AC${String(index)}: ${criterion} -> Needs decision: choose unit test, integration test, CLI/tool result, snapshot/golden fixture, or exact manual verification.`;
+}
+function renderNonGoals(outOfScope) {
+    const base = [
+        '- Do not create durable sidecar implementation docs outside canonical `spec.md`.',
+        '- Do not treat headings or filler text as implementation-ready detail.',
+    ];
+    return outOfScope.length > 0 ? [...base, ...outOfScope.map((item) => `- ${item}`)] : base;
+}
+//# sourceMappingURL=renderer.js.map

package/dist/engine/readiness-checker.js

@@ -4,7 +4,8 @@ import { readSpecTechnicalSection } from './spec-format/read-technical-section.j
 import { stripFrontmatter } from './frontmatter-parser.js';
 import { loadReadinessConfig } from './readiness-config-loader.js';
 import { runEarsGate } from './ears-gate.js';
-import { findScenariosWithoutTests } from './validator/spec-compliance-runner.js';
+import { findScenariosWithoutTests, parseFrontmatterScenarios, } from './validator/spec-compliance-runner.js';
+import { evaluateImplementationContract } from './implementation-contract/index.js';
 // ── SPEC-784: Technical section quality constants ─────────────────────────────
 const TECHNICAL_MIN_CHARS = 500;
 // Detects "See technical.md", "See spec.md", or "See `<file>` technical.md" patterns
@@ -110,6 +111,14 @@ export function extractCriteriaLines(huContent) {
     }
     return criteria;
 }
+function frontmatterScenarioCriteria(raw) {
+    return parseFrontmatterScenarios(raw).map((scenario) => {
+        const tests = scenario.tests
+            ?.map((test) => `${test.path}${test.line !== undefined ? ` line ${String(test.line)}` : ''}`)
+            .join(' ') ?? '';
+        return [scenario.title, tests].filter((part) => part.trim().length > 0).join(' ');
+    });
+}
 function scoreCriteria(criteriaLines, vagueWords) {
     const blockers = [];
     const warnings = [];
@@ -397,10 +406,8 @@ export async function checkSpecReadiness(spec, mode, projectHash) {
     // When a spec uses BDD format, acceptance criteria are stored as `scenarios:` in
     // the YAML frontmatter (multi-line YAML that the simple KV parser cannot handle).
     // If no criteria were found in the body, fall back to counting frontmatter scenarios.
-    const scenarioCount = criteriaLines.length === 0 ? countFrontmatterScenarios(huRaw) : 0;
-    const effectiveCriteriaLines = scenarioCount > 0
-        ? Array.from({ length: scenarioCount }).fill('bdd-scenario')
-        : criteriaLines;
+    const scenarioCriteria = criteriaLines.length === 0 ? frontmatterScenarioCriteria(huRaw) : [];
+    const effectiveCriteriaLines = scenarioCriteria.length > 0 ? scenarioCriteria : criteriaLines;
     const hu = scoreHuCompleteness(spec);
     const criteria = scoreCriteria(effectiveCriteriaLines, vagueWords);
     const files = scoreFilesIdentified(spec, fichaContent);
@@ -416,6 +423,11 @@ export async function checkSpecReadiness(spec, mode, projectHash) {
         ...earsBlockers,
     ];
     const allWarnings = [...hu.warnings, ...criteria.warnings, ...files.warnings, ...deps.warnings];
+    if (mode === 'strict' && spec.scope !== 'trivial' && spec.difficulty >= 3) {
+        for (const issue of evaluateImplementationContract(huContent, effectiveCriteriaLines)) {
+            allBlockers.push(`${issue.code}: ${issue.message}`);
+        }
+    }
     // SPEC-732: Executable AC gate — block approved when any scenario lacks a `tests` array.
     // Only enforce when the spec uses frontmatter scenarios (BDD format).
     const bddScenarioCount = countFrontmatterScenarios(huRaw);
@@ -436,7 +448,7 @@ export async function checkSpecReadiness(spec, mode, projectHash) {
     }
     // SPEC-629: Specificity gate caps score at 60 for difficulty >= 3 specs that lack
     // concrete file paths, function names, or anticipated test breaks.
-    const specificityBlockers = checkSpecificityGate(spec, criteriaLines, fichaContent);
+    const specificityBlockers = checkSpecificityGate(spec, effectiveCriteriaLines, fichaContent);
     allBlockers.push(...specificityBlockers);
     const effectiveScore = specificityBlockers.length > 0 && spec.difficulty >= 3 ? Math.min(totalScore, 60) : totalScore;
     const breakdown = {

package/dist/engine/skill-registry/index.d.ts

@@ -1,5 +1,6 @@
 export { searchAllRegistries } from './unified-search.js';
 export { installSkill, isSkillInstalled, readSkillManifest } from './installer.js';
+export { scanSkillSecurity } from './skill-security-scanner.js';
 export { searchAnthropicSkills, fetchAnthropicSkillContent, clearAnthropicCache, } from './anthropic-adapter.js';
 export { searchSkillsSh } from './skillssh-adapter.js';
 export { searchAgentSkills } from './agentskill-adapter.js';