@planu/cli 4.7.2 → 4.7.4

package/dist/tools/init-project/rules-generator.js

@@ -20,6 +20,19 @@ Auto-generated by \`init_project\`. Do not edit manually.
 
 Flow: \`facilitate → create_spec → challenge_spec → check_readiness → approve → implement → 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 lives in the external Planu handoff store, not under \`planu/specs/<spec>/\`. Spec folders remain \`spec.md\`-only.
+
 ## When to use \`facilitate\`
 
 Any new feature, bug fix, refactor, integration, or task > 5 min.
@@ -51,6 +64,7 @@ Any new feature, bug fix, refactor, integration, or task > 5 min.
 - NEVER write code before spec is \`approved\`
 - NEVER skip \`validate\` after implementation
 - NEVER create design docs outside \`planu/specs/\`
+- NEVER recreate legacy \`technical.md\`, \`progress.md\`, or \`HU.md\` files for new specs
 
 ## Model Selection (MANDATORY)
 

package/dist/tools/safe-handler.js

@@ -268,7 +268,10 @@ function safeWithTelemetry(toolName, handler) {
             // SPEC-455: Compress verbose JSON outputs to save LLM tokens
             const compressed = compressToolOutput(result);
             // SPEC-922: Apply compact mode middleware
-            const compacted = applyCompactMode(compressed, decision);
+            const compacted = applyCompactMode(compressed, decision, {
+                projectPath,
+                flow: toolName,
+            });
             // Inject pending drift banner (non-blocking, informational only)
             const driftBanner = projectPath !== undefined ? await checkPendingDriftBanner(projectPath) : null;
             const withDrift = injectDriftBanner(compacted, driftBanner);

package/dist/tools/token-usage-handler.js

@@ -27,10 +27,12 @@ export function handleTokenUsage(args) {
     let details;
     if (groupBy === 'tool' && toolRecords.length > 0) {
         const lines = toolRecords.map((r) => `| ${r.toolName} | ${String(r.totalTokens)} | ${String(r.callCount)} | ` +
-            `${String(r.cacheHits)}/${String(r.cacheHits + r.cacheMisses)} | ${String(r.tokensSaved)} |`);
+            `${String(r.cacheHits)}/${String(r.cacheHits + r.cacheMisses)} | ` +
+            `${String(r.tokensSaved)} | ${String(r.compactionTokensSaved ?? 0)} | ` +
+            `${String(r.artifactRetrievals ?? 0)} |`);
         details = [
-            '| Tool | Tokens | Calls | Cache H/T | Saved |',
-            '|------|--------|-------|-----------|-------|',
+            '| Tool | Tokens | Calls | Cache H/T | Saved | Compaction Saved | Retrievals |',
+            '|------|--------|-------|-----------|-------|------------------|------------|',
             ...lines,
         ].join('\n');
     }

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

@@ -1,12 +1,12 @@
 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 { extractCriteria } from '../../engine/validator/extractors.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';
+import { extractAcceptanceCriteriaTexts } from '../../engine/spec-format/acceptance-criteria.js';
 /** SPEC-1054: BDD/SDD lifecycle evidence gate. */
 export async function checkLifecycleEvidenceTransitionGate(args) {
     const [criteriaResult, artifacts] = await Promise.all([
@@ -54,13 +54,9 @@ 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');
-        const body = stripFrontmatter(raw);
-        const acceptanceCriteria = extractSection(body, 'acceptance criteria', 'criterios de aceptaci');
-        if (acceptanceCriteria) {
-            const items = extractListItems(acceptanceCriteria);
-            if (items.length > 0) {
-                return { criteria: [...new Set(items)], body: raw };
-            }
+        const criteria = extractAcceptanceCriteriaTexts(raw);
+        if (criteria.length > 0) {
+            return { criteria: [...new Set(criteria)], body: raw };
         }
     }
     catch {

package/dist/types/cascade-hooks.d.ts

@@ -35,6 +35,11 @@ export type CoreActionResult = {
     ok: false;
     error: string;
 };
+export interface PendingReleaseEntry {
+    specId: string;
+    title: string;
+    completedAt: string;
+}
 /** SPEC-772: Result of a single fast hook execution. */
 export interface FastHookResult {
     hookId: string;

package/dist/types/compact/compact-mode.d.ts

@@ -20,6 +20,11 @@ export interface CompactDecision {
     contextUsed?: number;
     reason: 'header_above_enter' | 'header_below_exit' | 'hysteresis_keep' | 'no_header';
 }
+export interface CompactModeOptions {
+    projectPath?: string;
+    sourcePath?: string;
+    flow?: string;
+}
 export interface CompactMetrics {
     compactDecisions: number;
     verboseDecisions: number;

package/dist/types/context-artifacts.d.ts

@@ -0,0 +1,96 @@
+export type ContextArtifactContentType = 'json' | 'test-log' | 'runtime-log' | 'search-results' | 'code' | 'spec-or-handoff' | 'generic-text';
+export interface ContextArtifactCompactionMetadata {
+    artifactRef: string;
+    originalTokens: number;
+    compactTokens: number;
+    tokensSaved: number;
+    strategy: string;
+    contentType: ContextArtifactContentType;
+    expiresAt: string;
+    retrievalHint: string;
+}
+export interface ContextArtifact {
+    ref: string;
+    contentHash: string;
+    createdAt: string;
+    expiresAt: string;
+    ttlMs: number;
+    projectId: string;
+    contentType: ContextArtifactContentType;
+    strategy: string;
+    originalTokens: number;
+    compactTokens: number;
+    tokensSaved: number;
+    retrievalCount: number;
+    metadata: Record<string, string | number | boolean>;
+    originalContent: string;
+    compactContent: string;
+}
+export interface StoreContextArtifactInput {
+    projectPath: string;
+    originalContent: string;
+    compactContent: string;
+    contentType: ContextArtifactContentType;
+    strategy: string;
+    originalTokens: number;
+    compactTokens: number;
+    ttlMs: number;
+    sourcePath?: string;
+    flow?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface StoreContextArtifactResult {
+    stored: boolean;
+    artifact?: ContextArtifact;
+    metadata?: ContextArtifactCompactionMetadata;
+    refusedReason?: string;
+}
+export interface RetrieveContextArtifactResult {
+    found: boolean;
+    artifact?: ContextArtifact;
+    reason?: 'missing' | 'expired' | 'corrupt' | 'invalid-ref' | 'unauthorized';
+    hint: string;
+}
+export interface ContextArtifactStats {
+    artifactCount: number;
+    totalOriginalTokens: number;
+    totalCompactTokens: number;
+    totalTokensSaved: number;
+    retrievalCount: number;
+}
+export interface ContentAwareCompactionInput {
+    text: string;
+    policy: {
+        contextArtifacts?: {
+            enabled?: boolean;
+            ttlMs?: number;
+            minTokens?: number;
+        };
+        contentCompaction?: {
+            strategies?: Partial<Record<ContextArtifactContentType, {
+                maxLines?: number;
+                maxSnippetChars?: number;
+            }>>;
+        };
+        redaction: {
+            maxSnippetChars: number;
+            redactPatterns: string[];
+        };
+    };
+    projectPath?: string;
+    kind?: string;
+    sourcePath?: string;
+    flow?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ContentAwareCompactionResult {
+    text: string;
+    originalTokens: number;
+    compactTokens: number;
+    tokensSaved: number;
+    strategy: string;
+    contentType: ContextArtifactContentType;
+    artifact?: ContextArtifactCompactionMetadata;
+    refusedReason?: string;
+}
+//# sourceMappingURL=context-artifacts.d.ts.map

package/dist/types/context-artifacts.js

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

package/dist/types/index.d.ts

@@ -80,6 +80,7 @@ export * from './workers.js';
 export * from './orchestration-runtime.js';
 export * from './token-optimization.js';
 export * from './token-waste-autopilot.js';
+export * from './context-artifacts.js';
 export * from './minimal-implementation-gate.js';
 export * from './llm-providers.js';
 export * from './plugins.js';

package/dist/types/index.js

@@ -81,6 +81,7 @@ export * from './workers.js';
 export * from './orchestration-runtime.js';
 export * from './token-optimization.js';
 export * from './token-waste-autopilot.js';
+export * from './context-artifacts.js';
 export * from './minimal-implementation-gate.js';
 export * from './llm-providers.js';
 export * from './plugins.js';

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

@@ -27,6 +27,12 @@ export interface BddScenario {
         line?: number;
     }[];
 }
+export interface NormalizedAcceptanceCriterion {
+    id: string;
+    text: string;
+    source: 'body' | 'frontmatter';
+    aliases: string[];
+}
 /** Input for lean spec generation. */
 export interface LeanSpecInput {
     spec: Spec;

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

@@ -104,6 +104,8 @@ export interface ToolTokenRecord {
     cacheHits: number;
     cacheMisses: number;
     tokensSaved: number;
+    compactionTokensSaved?: number;
+    artifactRetrievals?: number;
 }
 export interface BatchEntry {
     input: unknown;

package/dist/types/token-waste-autopilot.d.ts

@@ -1,3 +1,4 @@
+import type { ContextArtifactCompactionMetadata } from './context-artifacts.js';
 export type TokenWasteDecisionKind = 'include' | 'summarize' | 'exclude' | 'recommend' | 'avoid' | 'warn' | 'override';
 export type TokenWasteConfidence = 'high' | 'medium' | 'low';
 export type TokenWasteAction = string;
@@ -21,6 +22,7 @@ export interface TokenWasteOutputStrategy {
     keepFailures?: boolean;
     uniqueOnly?: boolean;
     summarizeKeys?: boolean;
+    maxSnippetChars?: number;
 }
 export interface TokenWastePolicy {
     version: 1;
@@ -35,6 +37,14 @@ export interface TokenWastePolicy {
     outputs: {
         strategies: Record<string, TokenWasteOutputStrategy>;
     };
+    contextArtifacts?: {
+        enabled: boolean;
+        ttlMs: number;
+        minTokens: number;
+    };
+    contentCompaction?: {
+        strategies: Record<string, TokenWasteOutputStrategy>;
+    };
     tools: {
         groups: Record<string, string[]>;
         maxRecommended: number;
@@ -83,12 +93,17 @@ export interface VerboseOutputInput {
     text: string;
     policy: TokenWastePolicy;
     fullOutputRef?: string;
+    projectPath?: string;
+    sourcePath?: string;
+    flow?: string;
+    metadata?: Record<string, unknown>;
 }
 export interface VerboseOutputResult {
     text: string;
     originalLines: number;
     returnedLines: number;
     fullOutputRef?: string;
+    compaction?: ContextArtifactCompactionMetadata;
     decisions: TokenWasteDecision[];
 }
 export interface ToolRelevanceInput {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.7.2",
+  "version": "4.7.4",
   "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.7.2",
-    "@planu/core-darwin-x64": "4.7.2",
-    "@planu/core-linux-arm64-gnu": "4.7.2",
-    "@planu/core-linux-arm64-musl": "4.7.2",
-    "@planu/core-linux-x64-gnu": "4.7.2",
-    "@planu/core-linux-x64-musl": "4.7.2",
-    "@planu/core-win32-arm64-msvc": "4.7.2",
-    "@planu/core-win32-x64-msvc": "4.7.2"
+    "@planu/core-darwin-arm64": "4.7.4",
+    "@planu/core-darwin-x64": "4.7.4",
+    "@planu/core-linux-arm64-gnu": "4.7.4",
+    "@planu/core-linux-arm64-musl": "4.7.4",
+    "@planu/core-linux-x64-gnu": "4.7.4",
+    "@planu/core-linux-x64-musl": "4.7.4",
+    "@planu/core-win32-arm64-msvc": "4.7.4",
+    "@planu/core-win32-x64-msvc": "4.7.4"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -129,7 +129,7 @@
   ],
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.104.2",
+    "@anthropic-ai/sdk": "^0.105.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "glob": "^13.0.6",
     "yaml": "^2.9.0",
@@ -168,8 +168,8 @@
     }
   },
   "devDependencies": {
-    "@commitlint/cli": "^21.0.2",
-    "@commitlint/config-conventional": "^21.0.2",
+    "@commitlint/cli": "^21.1.0",
+    "@commitlint/config-conventional": "^21.1.0",
     "@eslint/js": "^10.0.1",
     "@napi-rs/cli": "^3.7.2",
     "@secretlint/secretlint-rule-no-homedir": "^13.0.2",
@@ -183,7 +183,7 @@
     "@stryker-mutator/core": "^9.6.1",
     "@stryker-mutator/vitest-runner": "^9.6.1",
     "@supabase/supabase-js": "^2.108.2",
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.0.0",
     "@vitejs/plugin-vue": "^6.0.7",
     "@vitest/coverage-v8": "^4.1.9",
     "@vue/test-utils": "^2.4.11",
@@ -191,11 +191,11 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import": "^2.32.0",
-    "happy-dom": "^20.10.5",
+    "happy-dom": "^20.10.6",
     "husky": "^9.1.7",
     "javascript-obfuscator": "^5.4.3",
-    "knip": "^6.17.1",
-    "lint-staged": "^17.0.7",
+    "knip": "^6.18.0",
+    "lint-staged": "^17.0.8",
     "madge": "^8.0.0",
     "prettier": "^3.8.4",
     "secretlint": "^13.0.2",
@@ -203,8 +203,8 @@
     "tsc-alias": "^1.8.17",
     "type-coverage": "^2.29.7",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.61.1",
-    "vite": "^8.0.16",
+    "typescript-eslint": "^8.62.0",
+    "vite": "^8.1.0",
     "vitest": "^4.1.9",
     "vue": "^3.5.38"
   }

package/planu-native.json

@@ -1,20 +1,26 @@
 {
   "name": "dev.planu.native",
   "displayName": "Planu Native Lightweight Surface",
-  "version": "4.7.2",
+  "version": "4.7.4",
   "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"
@@ -62,9 +80,12 @@
         {
           "id": "planu.release.check",
           "title": "Check release readiness",
-          "description": "Check local branch cleanliness and main/develop/release sync readiness.",
+          "description": "Check local-first release readiness, branch cleanliness, and optional gitflow drift.",
           "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.7.2",
+  "version": "4.7.4",
   "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"
+  ]
 }