@planu/cli 4.3.24 → 4.4.0

package/dist/tools/git/branch-ops.js

@@ -1,5 +1,4 @@
 import { specStore } from '../../storage/index.js';
-import { handleUpdateStatus } from '../update-status/index.js';
 import { ti } from '../../i18n/index.js';
 import { git, resolveProjectPath, slugify, mergeConfig, detectGitFlowType, resolveBaseBranch, DEFAULT_BRANCH_PREFIXES, DEFAULT_PROTECTED_BRANCHES, } from './git-helpers.js';
 import { compactResult, compactError, formatKeyValue, formatTable, formatList, } from '../output-formatter.js';
@@ -20,59 +19,6 @@ function randomSuffix() {
         .toString(16)
         .padStart(8, '0');
 }
-export async function autoCompleteSpecs(projectId, projectPath) {
-    // Try develop first, fall back to main
-    let mergedOut;
-    try {
-        const r = await git(projectPath, ['branch', '--merged', 'develop']);
-        mergedOut = r.stdout;
-    }
-    catch {
-        const r = await git(projectPath, ['branch', '--merged', 'main']);
-        mergedOut = r.stdout;
-    }
-    const mergedList = mergedOut
-        .split('\n')
-        .map((b) => b.replace(/^\*?\s+/, '').trim())
-        .filter(Boolean);
-    const mergedSet = new Set(mergedList);
-    /** Returns true if the spec's branch (exact or by ID pattern) appears in merged branches. */
-    function isMerged(specId, gitBranch) {
-        if (gitBranch && mergedSet.has(gitBranch)) {
-            return true;
-        }
-        const num = /SPEC-(\d+)/i.exec(specId)?.[1];
-        if (!num) {
-            return false;
-        }
-        const pat = new RegExp(`[/\\-]SPEC-${num}([/\\-]|$)`, 'i');
-        return mergedList.some((b) => pat.test(b));
-    }
-    const specs = (await specStore.listSpecs(projectId)).filter((s) => (s.status === 'implementing' || s.status === 'approved') && isMerged(s.id, s.gitBranch));
-    const completed = [];
-    const blocked = [];
-    for (const spec of specs) {
-        // SPEC-720: Route through handleUpdateStatus so all gates (DoD/validate/QA) run.
-        // Never call specStore.updateSpec({status}) directly.
-        const result = await handleUpdateStatus({
-            specId: spec.id,
-            status: 'done',
-            projectId,
-            projectPath,
-            trigger: 'git-merge',
-            actor: 'system',
-            reviewNotes: 'Auto-completed: branch merged',
-        });
-        if (result.isError) {
-            const reason = result.content[0]?.type === 'text' ? result.content[0].text : 'gate blocked (no message)';
-            blocked.push({ specId: spec.id, reason });
-        }
-        else {
-            completed.push(spec.id);
-        }
-    }
-    return { completed, blocked };
-}
 export async function handleCreateBranch(projectId, specId, config) {
     if (!specId) {
         return compactError('❌ Error: specId is required for create-branch action');

package/dist/tools/git/cleanup-ops.js

@@ -3,7 +3,6 @@ import { existsSync } from 'node:fs';
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { git, resolveProjectPath } from './git-helpers.js';
-import { autoCompleteSpecs } from './branch-ops.js';
 import { compactResult, compactError } from '../output-formatter.js';
 const WORKTREES_DIR = '.claude/worktrees';
 const STALE_DAYS_THRESHOLD = 7;
@@ -283,23 +282,12 @@ export async function handleCleanup(projectId, config) {
         stashesDropped = dropped;
         errors.push(...stashErrors);
     }
-    // 6. Auto-complete implementing specs whose branch is merged to develop (SPEC-397)
-    // SPEC-720: autoCompleteSpecs now returns {completed, blocked}
-    const autoCompleteResult = await autoCompleteSpecs(projectId, projectPath).catch(() => ({
-        completed: [],
-        blocked: [],
-    }));
-    const autoCompleted = autoCompleteResult.completed;
     const messageParts = [
         `Worktrees removed: ${worktreesRemoved.length}`,
         `Branches removed: ${branchesRemoved.length}`,
         `Remote pruned: ${remotePruned ? 'yes' : 'no'}`,
         `Stale stashes (>${STALE_DAYS_THRESHOLD}d): ${staleStashes.length}`,
         ...(force ? [`Stashes dropped: ${stashesDropped}`] : ['Use force:true to drop stale stashes']),
-        ...(autoCompleted.length > 0 ? [`Specs auto-completed: ${autoCompleted.join(', ')}`] : []),
-        ...(autoCompleteResult.blocked.length > 0
-            ? [`Specs blocked (gates): ${autoCompleteResult.blocked.map((b) => b.specId).join(', ')}`]
-            : []),
         ...(errors.length > 0 ? [`Errors: ${errors.length}`] : []),
     ];
     const report = {
@@ -311,7 +299,6 @@ export async function handleCleanup(projectId, config) {
         stashesDropped,
         errors,
         message: messageParts.join(' | '),
-        ...(autoCompleted.length > 0 ? { autoCompleted } : {}),
     };
     const lines = [report.message];
     if (worktreesRemoved.length > 0) {
@@ -323,9 +310,6 @@ export async function handleCleanup(projectId, config) {
     if (staleStashes.length > 0) {
         lines.push('', `**Stale stashes**: ${staleStashes.map((s) => `${s.ref} (${String(s.daysOld)}d)`).join(', ')}`);
     }
-    if (autoCompleted.length > 0) {
-        lines.push('', `**Auto-completed specs**: ${autoCompleted.join(', ')}`);
-    }
     if (errors.length > 0) {
         lines.push('', `**Errors**: ${errors.join('; ')}`);
     }

package/dist/tools/git/release-ops.js

@@ -1,6 +1,6 @@
 import { git, resolveProjectPath, resolveBaseBranch, mergeConfig } from './git-helpers.js';
 import { specStore } from '../../storage/index.js';
-import { autoCompleteSpecs } from './branch-ops.js';
+import { autoCompleteSpecs } from './auto-complete-ops.js';
 import { compactResult, formatKeyValue, formatList } from '../output-formatter.js';
 export async function handleRelease(projectId, config) {
     const projectPath = await resolveProjectPath(projectId);

package/dist/tools/init-project/handler.js

@@ -13,7 +13,7 @@ import { checkBundledVersionGap } from '../../engine/version-detector/bundled-ve
 import { checkAndFixBundledVersion } from '../../engine/mcp-config/mcp-config-writer.js';
 import { buildInitProjectResult } from './result-builder.js';
 import { fetchRecommendedSkills } from '../suggest-tooling/skills-fetcher.js';
-import { autoCompleteSpecs } from '../git/branch-ops.js';
+import { autoCompleteSpecs } from '../git/auto-complete-ops.js';
 import { regeneratePages } from '../../engine/doc-generator/portal/index.js';
 import { detectStackPatterns } from './stack-detector.js';
 import { buildProjectConfig } from './config-builder.js';

package/dist/tools/manage-hooks.js

@@ -1,6 +1,8 @@
 // tools/manage-hooks.ts — MCP tool handler for manage_hooks (SPEC-071)
 import { hooksStore } from '../storage/index.js';
-import { dispatchEvent, dryRunDispatch, getTemplate, listTemplateNames, generateGitHooks, formatGitHookInstallGuide, } from '../engine/hooks/index.js';
+import { dispatchEvent, dryRunDispatch } from '../engine/hooks/core.js';
+import { getTemplate, listTemplateNames } from '../engine/hooks/templates.js';
+import { generateGitHooks, formatGitHookInstallGuide } from '../engine/hooks/git-hook-generator.js';
 import { compactResult, compactError, formatKeyValue, formatTable, formatList, formatConfirmation, } from './output-formatter.js';
 // ---------------------------------------------------------------------------
 // Operation handlers

package/dist/tools/status-handler.js

@@ -8,7 +8,7 @@ import { promisify } from 'node:util';
 import { join } from 'node:path';
 import { readFile } from 'node:fs/promises';
 import { shouldSuggestBtw, buildBtwHint } from '../engine/context-advisor/btw-advisor.js';
-import { autoCompleteSpecs } from './git/branch-ops.js';
+import { autoCompleteSpecs } from './git/auto-complete-ops.js';
 import { computeSessionAgeMinutes } from '../engine/session-handoff-generator.js';
 import { loadSessionState } from '../storage/session-state-store.js';
 import { consumeUpdateBanner } from '../engine/update-notifier.js';

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

@@ -4,10 +4,13 @@ import { extractCriteria, extractListItems, extractSection, } from '../../engine
 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';
+import { buildSpecEvidenceIndex } from '../../engine/evidence-index/index-builder.js';
+import { checkDoneDriftContract } from '../../engine/evidence-index/done-drift.js';
+import { parseTechnicalReferenceGroundingRecords } from '../../engine/spec-grounding/contract.js';
 /** SPEC-1054: BDD/SDD lifecycle evidence gate. */
 export async function checkLifecycleEvidenceTransitionGate(args) {
-    const [criteria, artifacts] = await Promise.all([
-        extractLifecycleGateCriteria(args.spec, args.projectPath),
+    const [criteriaResult, artifacts] = await Promise.all([
+        extractLifecycleGateCriteriaAndBody(args.spec, args.projectPath),
         readEvidenceArtifacts({
             spec: args.spec,
             projectId: args.projectId,
@@ -15,13 +18,26 @@ export async function checkLifecycleEvidenceTransitionGate(args) {
             projectPath: args.projectPath,
         }),
     ]);
+    const { criteria, body } = criteriaResult;
     const result = checkLifecycleEvidenceGate({
         transition: args.transition,
         spec: args.spec,
         criteria,
         artifacts,
     });
-    if (result.passed) {
+    if (args.transition === 'done') {
+        const index = await buildSpecEvidenceIndex({
+            specId: args.specId,
+            criteria,
+            artifacts,
+            projectPath: args.projectPath,
+        });
+        const groundedTechnicalPaths = body
+            ? parseTechnicalReferenceGroundingRecords(body).map((record) => record.path)
+            : [];
+        result.issues.push(...checkDoneDriftContract({ index, groundedTechnicalPaths }));
+    }
+    if (result.issues.length === 0) {
         return null;
     }
     return evidenceGateError({
@@ -34,7 +50,7 @@ export async function checkLifecycleEvidenceTransitionGate(args) {
         requiredContractKinds: result.requiredContractKinds,
     });
 }
-async function extractLifecycleGateCriteria(spec, projectPath) {
+async function extractLifecycleGateCriteriaAndBody(spec, projectPath) {
     const specPath = isAbsolute(spec.specPath) || !projectPath ? spec.specPath : join(projectPath, spec.specPath);
     try {
         const raw = await readFile(specPath, 'utf-8');
@@ -43,14 +59,14 @@ async function extractLifecycleGateCriteria(spec, projectPath) {
         if (acceptanceCriteria) {
             const items = extractListItems(acceptanceCriteria);
             if (items.length > 0) {
-                return [...new Set(items)];
+                return { criteria: [...new Set(items)], body: raw };
             }
         }
     }
     catch {
         // Fall back to the broader validator extractor when the canonical file is unavailable.
     }
-    return extractCriteria(spec);
+    return { criteria: await extractCriteria(spec), body: null };
 }
 function evidenceGateError(args) {
     return {
@@ -72,6 +88,7 @@ function evidenceGateError(args) {
         structuredContent: {
             error: 'lifecycle_evidence_gate_failed',
             code: 422,
+            sddConstitutionRuleId: args.transition === 'done' ? 'sdd.done-evidence-required' : 'sdd.grounded-contract',
             context: {
                 specId: args.specId,
                 transition: args.transition,

package/dist/tools/update-status/transition-guard.js

@@ -6,6 +6,8 @@ import { dispatchFeedbackEvent } from '../learn.js';
 import { scoreAmbiguityFromPath } from '../../engine/ambiguity-scorer.js';
 import { checkReadinessInternal } from '../../engine/readiness-checker.js';
 import { validateEnglishOnlySpecText } from '../../engine/spec-language/english-only.js';
+import { checkGroundedSpecContract } from '../../engine/spec-grounding/contract.js';
+import { checkGenericSpecOutput } from '../../engine/spec-quality/generic-output-gate.js';
 /**
  * Valid state transitions for spec lifecycle.
  * draft -> review -> approved -> implementing -> done
@@ -224,6 +226,53 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
             qualityWarnings: [],
         };
     }
+    const groundingResult = checkGroundedSpecContract(spec, body);
+    if (!groundingResult.passed) {
+        return {
+            blockResult: {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Grounded spec contract blocked transition to ${newStatus}. ` +
+                            groundingResult.issues.slice(0, 3).join('; '),
+                    },
+                ],
+                isError: true,
+                structuredContent: {
+                    error: 'GROUNDED_SPEC_CONTRACT_BLOCKED',
+                    sddConstitutionRuleId: 'sdd.grounded-contract',
+                    issues: groundingResult.issues,
+                    fixHint: 'Add grounding metadata for every contract criterion or move ungrounded criteria to advisory/discovery before review or approval.',
+                },
+            },
+            qualityWarnings: [],
+        };
+    }
+    const genericOutputGate = checkGenericSpecOutput(body);
+    if (!genericOutputGate.passed) {
+        return {
+            blockResult: {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Spec quality gate blocked transition to ${newStatus}. ` +
+                            genericOutputGate.issues
+                                .slice(0, 3)
+                                .map((issue) => `${issue.phrase}: ${issue.reason}`)
+                                .join('; '),
+                    },
+                ],
+                isError: true,
+                structuredContent: {
+                    error: 'GENERIC_SPEC_OUTPUT_BLOCKED',
+                    sddConstitutionRuleId: 'sdd.no-generic-output',
+                    issues: genericOutputGate.issues,
+                    fixHint: 'Replace generic criteria or placeholder references with grounded, testable behavior before review or approval.',
+                },
+            },
+            qualityWarnings: [],
+        };
+    }
     let score;
     let warnings;
     let criteriaCount;

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

@@ -1,7 +1,5 @@
 import { specStore, knowledgeStore } from '../storage/index.js';
-import { handleCreateBranch } from './git/branch-ops.js';
 import { checkConstitutionCompliance } from './create-spec-tech.js';
-import { cleanupSpecOnDone } from './git/cleanup-ops.js';
 import { withAudit } from '../engine/autopilot/audit-logger.js';
 import { hasPending, markPending, clearPending } from '../engine/autopilot/cascade-deduplicator.js';
 export async function runImplementingActions(projectId, specId) {
@@ -27,10 +25,12 @@ export async function runImplementingActions(projectId, specId) {
         let branchResult;
         try {
             const { resolveProjectPath: resolveBranchPath } = await import('./git/git-helpers.js');
+            const { handleCreateBranch } = await import('./git/branch-ops.js');
             const branchProjectPath = await resolveBranchPath(projectId);
             branchResult = await withAudit(branchProjectPath, 'update_status(implementing)', 'handleCreateBranch', () => handleCreateBranch(projectId, specId), (r) => ({ isError: r.isError }));
         }
         catch {
+            const { handleCreateBranch } = await import('./git/branch-ops.js');
             branchResult = await handleCreateBranch(projectId, specId);
         }
         if (!branchResult.isError) {
@@ -224,9 +224,12 @@ export async function runDoneActions(projectId, specId, gitBranch) {
             // SPEC-491: Sweep planu/ to remove legacy files
             // SPEC-496: Auto-generate portable session context snapshot
             void Promise.allSettled([
-                withAudit(projectPath, 'update_status(done)', 'cleanupSpecOnDone', () => cleanupSpecOnDone(projectPath, specId, gitBranch)).catch(() => {
-                    /* best-effort — never blocks status transition */
-                }),
+                (async () => {
+                    const { cleanupSpecOnDone } = await import('./git/cleanup-ops.js');
+                    await withAudit(projectPath, 'update_status(done)', 'cleanupSpecOnDone', () => cleanupSpecOnDone(projectPath, specId, gitBranch)).catch(() => {
+                        /* best-effort — never blocks status transition */
+                    });
+                })(),
                 // SPEC-633: Remove spec from session.json index when done
                 (async () => {
                     const { removeSpecFromSession } = await import('../engine/session-state/writer.js');

package/dist/types/actionable-spec-metrics.d.ts

@@ -0,0 +1,8 @@
+export type ActionableSpecMetricName = 'groundingCoverage' | 'verificationCoverage' | 'ambiguityCount' | 'driftRisk';
+export interface ActionableSpecMetric {
+    name: ActionableSpecMetricName;
+    value: number | 'none' | 'low' | 'medium' | 'high';
+    inputs: string[];
+    nextAction: string;
+}
+//# sourceMappingURL=actionable-spec-metrics.d.ts.map

package/dist/types/actionable-spec-metrics.js

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

package/dist/types/clarification-token.d.ts

@@ -1,4 +1,4 @@
-import type { InteractiveQuestion } from './clarification.js';
+import type { InteractiveQuestion } from './interactive-question.js';
 import type { ToolResult } from './common/primitives.js';
 /**
  * Persisted token that blocks a tool from proceeding until the LLM relays

package/dist/types/clarification.d.ts

@@ -1,21 +1,5 @@
-/** A single option in an interactive question. */
-export interface InteractiveOption {
-    /** Display text — add "(Recommended)" suffix to preferred option. */
-    label: string;
-    /** What this option means or what happens if chosen. */
-    description: string;
-}
-/** A structured question for the user, presented via the LLM's native UI. */
-export interface InteractiveQuestion {
-    /** The full question text, ending with "?". */
-    question: string;
-    /** Short chip/tag label (max 12 chars). E.g. "Auth", "Scope", "Target". */
-    header: string;
-    /** 2-4 options to choose from. An "Other" free-text option is added automatically by the LLM. */
-    options: InteractiveOption[];
-    /** True for non-exclusive choices (user can pick multiple). */
-    multiSelect: boolean;
-}
+import type { InteractiveQuestion } from './interactive-question.js';
+export type { InteractiveOption, InteractiveQuestion } from './interactive-question.js';
 /** Tool response when interactive clarification is needed instead of creating a spec. */
 export interface InteractiveClarificationResponse {
     needsClarification: true;

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

@@ -54,7 +54,7 @@ export interface EvidenceArtifacts {
     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';
+    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' | 'done_drift_uncovered_criteria' | 'done_drift_stale_evidence' | 'done_drift_unapproved_scope' | 'evidence_artifact_invalid';
     message: string;
 }
 export interface EvidenceGateResult {

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

@@ -0,0 +1,24 @@
+export type EvidenceRecordKind = 'scenario' | 'test' | 'contract' | 'manual' | 'changed-file' | 'validation' | 'reviewer';
+export type EvidenceRecordStatus = 'valid' | 'stale' | 'invalid' | 'missing';
+export interface EvidenceRecord {
+    kind: EvidenceRecordKind;
+    value: string;
+    status: EvidenceRecordStatus;
+    source: string;
+    command?: string;
+    passed?: boolean;
+    timestamp?: string;
+    reason?: string;
+}
+export interface CriterionEvidenceIndexEntry {
+    criterion: string;
+    criterionKey: string;
+    evidence: EvidenceRecord[];
+}
+export interface SpecEvidenceIndex {
+    specId: string;
+    generatedAt: string;
+    criteria: CriterionEvidenceIndexEntry[];
+    diagnostics: string[];
+}
+//# sourceMappingURL=evidence-index.d.ts.map

package/dist/types/evidence-index.js

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

package/dist/types/hook-status-update.d.ts

@@ -0,0 +1,10 @@
+import type { ToolResult } from './common/primitives.js';
+import type { UpdateStatusInput } from './spec/inputs.js';
+export interface HookUpdateStatusInput extends UpdateStatusInput {
+    trigger: 'fs-hook';
+    actor: 'system';
+}
+export interface UpdateStatusModule {
+    handleUpdateStatus: (input: HookUpdateStatusInput) => Promise<ToolResult>;
+}
+//# sourceMappingURL=hook-status-update.d.ts.map

package/dist/types/hook-status-update.js

@@ -0,0 +1,3 @@
+// types/hook-status-update.ts — Runtime bridge types for hook-triggered status transitions
+export {};
+//# sourceMappingURL=hook-status-update.js.map

package/dist/types/index.d.ts

@@ -25,6 +25,8 @@ export * from './migration/index.js';
 export * from './migration-advanced.js';
 export * from './privacy.js';
 export * from './events.js';
+export * from './evidence-gates.js';
+export * from './evidence-index.js';
 export * from './analytics.js';
 export * from './sdd-flow.js';
 export * from './sdd-model-routing.js';
@@ -48,6 +50,7 @@ export * from './dynamic-migration.js';
 export * from './multi-agent.js';
 export * from './ai-native.js';
 export * from './actuals-tracking.js';
+export * from './actionable-spec-metrics.js';
 export * from './actuals.js';
 export * from './risk.js';
 export * from './context-budget.js';
@@ -57,10 +60,12 @@ export * from './changelog.js';
 export * from './coverage.js';
 export * from './ai-cost.js';
 export * from './hooks.js';
+export * from './hook-status-update.js';
 export * from './webhook.js';
 export * from './ci.js';
 export * from './spec-templates.js';
 export * from './spec-generator.js';
+export * from './spec-grounding.js';
 export * from './registry.js';
 export * from './tool-groups.js';
 export * from './code-transforms.js';
@@ -103,6 +108,7 @@ export * from './legal.js';
 export * from './mcp-recommendation.js';
 export * from './approval.js';
 export * from './scan-project.js';
+export * from './sdd-constitution.js';
 export * from './import-spec.js';
 export * from './error-telemetry.js';
 export * from './audit-trail.js';

package/dist/types/index.js

@@ -26,6 +26,8 @@ export * from './migration/index.js';
 export * from './migration-advanced.js';
 export * from './privacy.js';
 export * from './events.js';
+export * from './evidence-gates.js';
+export * from './evidence-index.js';
 export * from './analytics.js';
 export * from './sdd-flow.js';
 export * from './sdd-model-routing.js';
@@ -49,6 +51,7 @@ export * from './dynamic-migration.js';
 export * from './multi-agent.js';
 export * from './ai-native.js';
 export * from './actuals-tracking.js';
+export * from './actionable-spec-metrics.js';
 export * from './actuals.js';
 export * from './risk.js';
 export * from './context-budget.js';
@@ -58,10 +61,12 @@ export * from './changelog.js';
 export * from './coverage.js';
 export * from './ai-cost.js';
 export * from './hooks.js';
+export * from './hook-status-update.js';
 export * from './webhook.js';
 export * from './ci.js';
 export * from './spec-templates.js';
 export * from './spec-generator.js';
+export * from './spec-grounding.js';
 export * from './registry.js';
 export * from './tool-groups.js';
 export * from './code-transforms.js';
@@ -104,6 +109,7 @@ export * from './legal.js';
 export * from './mcp-recommendation.js';
 export * from './approval.js';
 export * from './scan-project.js';
+export * from './sdd-constitution.js';
 export * from './import-spec.js';
 export * from './error-telemetry.js';
 export * from './audit-trail.js';

package/dist/types/interactive-question.d.ts

@@ -0,0 +1,19 @@
+/** A single option in an interactive question. */
+export interface InteractiveOption {
+    /** Display text — add "(Recommended)" suffix to preferred option. */
+    label: string;
+    /** What this option means or what happens if chosen. */
+    description: string;
+}
+/** A structured question for the user, presented via the LLM's native UI. */
+export interface InteractiveQuestion {
+    /** The full question text, ending with "?". */
+    question: string;
+    /** Short chip/tag label (max 12 chars). E.g. "Auth", "Scope", "Target". */
+    header: string;
+    /** 2-4 options to choose from. An "Other" free-text option is added automatically by the LLM. */
+    options: InteractiveOption[];
+    /** True for non-exclusive choices (user can pick multiple). */
+    multiSelect: boolean;
+}
+//# sourceMappingURL=interactive-question.d.ts.map

package/dist/types/interactive-question.js

@@ -0,0 +1,3 @@
+// types/interactive-question.ts — LLM-native interactive question primitives
+export {};
+//# sourceMappingURL=interactive-question.js.map

package/dist/types/sdd-constitution.d.ts

@@ -0,0 +1,27 @@
+export type SddConstitutionRuleLevel = 'blocking' | 'advisory';
+export interface SddConstitutionRule {
+    id: string;
+    title: string;
+    level: SddConstitutionRuleLevel;
+    category: 'grounding' | 'quality' | 'evidence' | 'approval' | 'metrics';
+    description: string;
+    nextAction: string;
+}
+export interface SddConstitutionOverride {
+    ruleId: string;
+    level?: SddConstitutionRuleLevel;
+    enabled?: boolean;
+    rationale: string;
+}
+export interface EffectiveSddConstitutionRule extends SddConstitutionRule {
+    enabled: boolean;
+    overrideRationale?: string;
+}
+export interface SddConstitutionViolation {
+    ruleId: string;
+    level: SddConstitutionRuleLevel;
+    message: string;
+    evidence: string[];
+    nextAction: string;
+}
+//# sourceMappingURL=sdd-constitution.d.ts.map

package/dist/types/sdd-constitution.js

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

package/dist/types/spec-format.d.ts

@@ -1,6 +1,7 @@
 import type { Spec } from './spec/core.js';
 import type { Estimation } from './estimation.js';
 import type { SpecStatus } from './common/index.js';
+import type { CriterionGroundingRecord, TechnicalReferenceGroundingRecord } from './spec-grounding.js';
 /** A criterion in the lean spec frontmatter. */
 export interface LeanCriterion {
     text: string;
@@ -29,6 +30,12 @@ export interface LeanSpecInput {
     estimation: Estimation;
     /** SPEC-461 Phase 3: Extra criteria from autopilot pattern detection. */
     extraCriteria?: string[];
+    /** SPEC-1074: Explicit criteria after grounding filters are applied. */
+    criteriaOverride?: LeanCriterion[];
+    /** SPEC-1074: Criterion-level grounding records for new specs. */
+    groundingCriteria?: CriterionGroundingRecord[];
+    /** SPEC-1074: Technical reference grounding records for new specs. */
+    groundingTechnicalReferences?: TechnicalReferenceGroundingRecord[];
     /** SPEC-481: Acceptance criteria format. Defaults to 'checkbox'. */
     acFormat?: 'checkbox' | 'bdd';
 }

package/dist/types/spec-grounding.d.ts

@@ -0,0 +1,22 @@
+export type GroundingSource = 'user_input' | 'project_evidence' | 'documented_assumption' | 'ungrounded_advisory';
+export type GroundingConfidence = 'low' | 'medium' | 'high';
+export interface CriterionGroundingRecord {
+    text: string;
+    source: GroundingSource;
+    evidence: string[];
+    confidence: GroundingConfidence;
+}
+export interface TechnicalReferenceGroundingRecord {
+    path: string;
+    section: 'create' | 'modify' | 'test';
+    source: GroundingSource;
+    evidence: string[];
+    confidence: GroundingConfidence;
+}
+export interface GroundingGateResult {
+    passed: boolean;
+    required: boolean;
+    issues: string[];
+    records: CriterionGroundingRecord[];
+}
+//# sourceMappingURL=spec-grounding.d.ts.map

package/dist/types/spec-grounding.js

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

package/dist/types/spec-quality.d.ts

@@ -35,6 +35,16 @@ export interface SpecQualityReport {
         risk: QualityDimensionDetail;
     };
 }
+export type GenericSpecOutputIssueKind = 'generic-criterion' | 'unsupported-verification' | 'placeholder-reference' | 'generic-technical-reference';
+export interface GenericSpecOutputIssue {
+    kind: GenericSpecOutputIssueKind;
+    phrase: string;
+    reason: string;
+}
+export interface GenericSpecOutputGateResult {
+    passed: boolean;
+    issues: GenericSpecOutputIssue[];
+}
 /** A single over-engineering signal detected in a spec. SPEC-485 */
 export interface ComplexitySignal {
     type: string;

package/dist/types/storage.d.ts

@@ -2,7 +2,7 @@
  * A minimal CRUD store backed by a single JSON array file.
  * Items must have an `id: string` field for lookup / update / remove.
  *
- * Created by `createCrudStore()` in `storage/base-store.ts`.
+ * JSON-backed stores expose this shape when they implement CRUD operations.
  */
 export interface CrudStore<T extends {
     id: string;