@planu/cli 4.3.25 → 4.4.1

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/validate.js

@@ -73,9 +73,11 @@ export async function handleValidate(args, server) {
     const projectPath = knowledge.projectPath;
     // SPEC-1017: fail closed when planu/ contains non-canonical artifacts.
     try {
-        const { runStrictPlanuCleanup, validateStrictPlanuLayout } = await import('../engine/spec-migrator/index.js');
-        await runStrictPlanuCleanup(projectPath);
-        const layout = await validateStrictPlanuLayout(projectPath);
+        const { validateStrictPlanuLayout } = await import('../engine/spec-migrator/index.js');
+        const layout = await validateStrictPlanuLayout(projectPath, {
+            specPath: spec.specPath,
+            includeRoot: false,
+        });
         if (!layout.ok) {
             return {
                 content: [

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/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/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';
@@ -62,6 +65,7 @@ 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 +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';
@@ -63,6 +66,7 @@ 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';
@@ -105,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/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';
 }
@@ -47,6 +54,7 @@ export interface PlanuCanonicalPathPolicy {
     readonly canonicalRootFiles: readonly string[];
     readonly canonicalRootDirs: readonly string[];
     readonly canonicalSpecFiles: readonly string[];
+    readonly canonicalSpecDirs: readonly string[];
     readonly forbiddenHostAssetRootDirs: readonly string[];
     readonly generatedRuntimePatterns: readonly string[];
     readonly legacyMergeBeforeDeleteFiles: readonly string[];
@@ -61,6 +69,10 @@ export interface StrictPlanuValidationResult {
     offenders: string[];
     contract: string;
 }
+export interface StrictPlanuValidationOptions {
+    specPath?: string;
+    includeRoot?: boolean;
+}
 export interface UpdateStatusBatchInput {
     specIds: string[];
     status: SpecStatus;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.3.25",
+  "version": "4.4.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",
@@ -34,14 +34,14 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "4.3.25",
-    "@planu/core-darwin-x64": "4.3.25",
-    "@planu/core-linux-arm64-gnu": "4.3.25",
-    "@planu/core-linux-arm64-musl": "4.3.25",
-    "@planu/core-linux-x64-gnu": "4.3.25",
-    "@planu/core-linux-x64-musl": "4.3.25",
-    "@planu/core-win32-arm64-msvc": "4.3.25",
-    "@planu/core-win32-x64-msvc": "4.3.25"
+    "@planu/core-darwin-arm64": "4.4.1",
+    "@planu/core-darwin-x64": "4.4.1",
+    "@planu/core-linux-arm64-gnu": "4.4.1",
+    "@planu/core-linux-arm64-musl": "4.4.1",
+    "@planu/core-linux-x64-gnu": "4.4.1",
+    "@planu/core-linux-x64-musl": "4.4.1",
+    "@planu/core-win32-arm64-msvc": "4.4.1",
+    "@planu/core-win32-x64-msvc": "4.4.1"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -185,12 +185,12 @@
     "@types/node": "^25.9.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "@vitest/coverage-v8": "^4.1.8",
-    "@vue/test-utils": "^2.4.10",
+    "@vue/test-utils": "^2.4.11",
     "eslint": "^10.4.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import": "^2.32.0",
-    "happy-dom": "^20.9.0",
+    "happy-dom": "^20.10.1",
     "husky": "^9.1.7",
     "javascript-obfuscator": "^5.4.3",
     "knip": "^6.15.0",

package/planu-native.json

@@ -1,20 +1,26 @@
 {
   "name": "dev.planu.native",
   "displayName": "Planu Native Lightweight Surface",
-  "version": "4.3.25",
+  "version": "4.4.1",
   "packageName": "@planu/cli",
   "modes": {
     "lightweight": {
       "requiresMcp": false,
       "requiresDaemon": false,
-      "hosts": ["codex", "claude-code"],
+      "hosts": [
+        "codex",
+        "claude-code"
+      ],
       "commands": [
         {
           "id": "planu.status",
           "title": "Project status",
           "description": "Show the compact Planu project snapshot without loading the MCP tool graph.",
           "invocation": "planu status",
-          "hosts": ["codex", "claude-code"],
+          "hosts": [
+            "codex",
+            "claude-code"
+          ],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "handlePlanStatus"
@@ -24,7 +30,10 @@
           "title": "Create spec",
           "description": "Create a new spec through the CLI-backed SDD contract.",
           "invocation": "planu spec create \"<title>\"",
-          "hosts": ["codex", "claude-code"],
+          "hosts": [
+            "codex",
+            "claude-code"
+          ],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "handleCreateSpec"
@@ -34,7 +43,10 @@
           "title": "List specs",
           "description": "List specs in the current project with optional status/type filters.",
           "invocation": "planu spec list",
-          "hosts": ["codex", "claude-code"],
+          "hosts": [
+            "codex",
+            "claude-code"
+          ],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "handleListSpecs"
@@ -44,7 +56,10 @@
           "title": "Validate spec",
           "description": "Validate a spec against the current codebase from the native CLI surface.",
           "invocation": "planu spec validate SPEC-001",
-          "hosts": ["codex", "claude-code"],
+          "hosts": [
+            "codex",
+            "claude-code"
+          ],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "handleValidate"
@@ -54,7 +69,10 @@
           "title": "Audit technical debt",
           "description": "Run the read-only project audit path for lightweight debt checks.",
           "invocation": "planu audit debt",
-          "hosts": ["codex", "claude-code"],
+          "hosts": [
+            "codex",
+            "claude-code"
+          ],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "handleAudit"
@@ -64,7 +82,10 @@
           "title": "Check release readiness",
           "description": "Check local branch cleanliness and main/develop/release sync readiness.",
           "invocation": "planu release check",
-          "hosts": ["codex", "claude-code"],
+          "hosts": [
+            "codex",
+            "claude-code"
+          ],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "releaseCommand"

package/planu-plugin.json

@@ -2,9 +2,12 @@
   "name": "dev.planu.cli",
   "displayName": "Planu — Spec Driven Development",
   "description": "Manage software specs, estimations, and autonomous SDD workflows. Language-agnostic MCP server for Claude Code.",
-  "version": "4.3.25",
+  "version": "4.4.1",
   "icon": "assets/plugin/icon.svg",
-  "command": ["npx", "@planu/cli@latest"],
+  "command": [
+    "npx",
+    "@planu/cli@latest"
+  ],
   "packageName": "@planu/cli",
   "capabilities": {
     "tools": [
@@ -23,17 +26,42 @@
       "create_skill",
       "skill_search"
     ],
-    "resources": ["planu://specs/list", "planu://specs/{id}", "planu://project/status", "planu://roadmap"],
-    "prompts": ["create-spec-from-idea", "review-spec-readiness", "generate-implementation-plan"],
-    "subagents": ["sdd-orchestrator", "spec-challenger", "test-generator"]
+    "resources": [
+      "planu://specs/list",
+      "planu://specs/{id}",
+      "planu://project/status",
+      "planu://roadmap"
+    ],
+    "prompts": [
+      "create-spec-from-idea",
+      "review-spec-readiness",
+      "generate-implementation-plan"
+    ],
+    "subagents": [
+      "sdd-orchestrator",
+      "spec-challenger",
+      "test-generator"
+    ]
   },
   "compatibility": {
     "minimumHostVersion": "1.0.0",
-    "requiredFeatures": ["mcp-tools", "file-editing"]
+    "requiredFeatures": [
+      "mcp-tools",
+      "file-editing"
+    ]
   },
   "repository": "https://github.com/planu-dev/planu",
   "author": "Planu",
   "license": "MIT",
   "homepage": "https://planu.dev",
-  "keywords": ["sdd", "spec-driven-development", "mcp", "specs", "planning", "ai", "bdd", "tdd"]
+  "keywords": [
+    "sdd",
+    "spec-driven-development",
+    "mcp",
+    "specs",
+    "planning",
+    "ai",
+    "bdd",
+    "tdd"
+  ]
 }