@planu/cli 4.11.3 → 4.11.4

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [4.11.4] - 2026-07-18
+
+### Bug Fixes
+- fix(planu): unblock challenge gate and record debt specs
+- fix(release): harden local recovery environment
+
+
 ## [4.11.3] - 2026-07-10
 
 ### Bug Fixes

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

@@ -6,6 +6,8 @@ const FILLER_PATTERNS = [
     /\bhandle errors\b/i,
     /\bto be determined\b/i,
 ];
+const MANUAL_VERIFICATION_STEP_RE = /\b(given|when|then|step|observe|click|run)\b/i;
+const CONCRETE_MANUAL_EVIDENCE_RE = /`[^`]+`|\b(?:src|tests|docs|scripts|website|planu)\/[\w./-]+/i;
 export function evaluateImplementationContract(specBody, acceptanceCriteria) {
     const contract = extractTopLevelSection(specBody, IMPLEMENTATION_CONTRACT_SECTION);
     if (contract.trim().length === 0) {
@@ -62,7 +64,8 @@ export function evaluateImplementationContract(specBody, acceptanceCriteria) {
         }
     }
     if (/\bmanual verification\b/i.test(map) &&
-        !/\b(given|when|then|step|observe|click|run)\b/i.test(map)) {
+        !MANUAL_VERIFICATION_STEP_RE.test(map) &&
+        !CONCRETE_MANUAL_EVIDENCE_RE.test(map)) {
         issues.push({
             code: 'contract_manual_verification_vague',
             message: 'Manual verification in the Implementation Contract must include exact observable steps.',

package/dist/tools/challenge-spec/challenge-report.d.ts

@@ -1,5 +1,7 @@
 import type { ChallengeReport, ChallengeResolutionEvidence, FailureScenario } from '../../types/index.js';
 export declare const MINIMUM_RESOLVED_CHALLENGES = 3;
+export declare function requiredResolvedChallenges(totalScenarios: number): number;
+export declare function parseChallengeResolutionEvidence(specContent: string, scenarios: readonly FailureScenario[], runAt: string): ChallengeResolutionEvidence[];
 /** Count only evidence tied to findings persisted by the same challenge report. */
 export declare function getResolvedChallengeEvidence(report: ChallengeReport | undefined): ChallengeResolutionEvidence[];
 /** Build a report whose resolution state is derived exclusively from explicit evidence. */
@@ -8,6 +10,7 @@ export declare function buildChallengeReport(input: {
     focusAreas: string[];
     overallRisk: ChallengeReport['overallRisk'];
     previousReport?: ChallengeReport;
+    explicitResolutionEvidence?: ChallengeResolutionEvidence[];
     runAt?: string;
 }): ChallengeReport;
 //# sourceMappingURL=challenge-report.d.ts.map

package/dist/tools/challenge-spec/challenge-report.js

@@ -1,4 +1,7 @@
 export const MINIMUM_RESOLVED_CHALLENGES = 3;
+export function requiredResolvedChallenges(totalScenarios) {
+    return Math.min(MINIMUM_RESOLVED_CHALLENGES, Math.max(0, totalScenarios));
+}
 function isExplicitResolutionEvidence(value) {
     if (typeof value !== 'object' || value === null) {
         return false;
@@ -12,16 +15,72 @@ function isExplicitResolutionEvidence(value) {
         typeof candidate.resolvedAt === 'string' &&
         candidate.resolvedAt.trim().length > 0);
 }
-function uniqueMatchingEvidence(report, scenarioNames) {
-    const evidence = Array.isArray(report?.resolutionEvidence) ? report.resolutionEvidence : [];
+function uniqueMatchingEvidence(evidence, scenarioNames) {
     const matched = new Map();
-    for (const item of evidence) {
+    for (const item of evidence ?? []) {
         if (isExplicitResolutionEvidence(item) && scenarioNames.has(item.scenario)) {
             matched.set(item.scenario, item);
         }
     }
     return [...matched.values()];
 }
+function inferResolution(text) {
+    return /\b(accepted|accept risk|accepted risk|known risk)\b/i.test(text)
+        ? 'accepted'
+        : 'mitigated';
+}
+function extractChallengeResolutionSection(specContent) {
+    const normalized = specContent.replace(/\r\n/g, '\n');
+    const headingRe = /^###\s+Challenge Resolution[ \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();
+}
+export function parseChallengeResolutionEvidence(specContent, scenarios, runAt) {
+    const section = extractChallengeResolutionSection(specContent);
+    if (section.length === 0 || scenarios.length === 0) {
+        return [];
+    }
+    if (scenarios.length === 1) {
+        const [singleScenario] = scenarios;
+        if (!singleScenario) {
+            return [];
+        }
+        return [
+            {
+                scenario: singleScenario.scenario,
+                resolution: inferResolution(section),
+                evidence: section.replace(/\s+/g, ' ').trim(),
+                resolvedAt: runAt,
+            },
+        ];
+    }
+    const bullets = section
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => /^-\s+/.test(line))
+        .map((line) => line.replace(/^-\s+/, '').trim());
+    const evidence = [];
+    for (const bullet of bullets) {
+        const scenario = scenarios.find((item) => bullet.includes(item.scenario));
+        if (!scenario) {
+            continue;
+        }
+        evidence.push({
+            scenario: scenario.scenario,
+            resolution: inferResolution(bullet),
+            evidence: bullet,
+            resolvedAt: runAt,
+        });
+    }
+    return evidence;
+}
 /** Count only evidence tied to findings persisted by the same challenge report. */
 export function getResolvedChallengeEvidence(report) {
     if (!Array.isArray(report?.findings)) {
@@ -30,21 +89,27 @@ export function getResolvedChallengeEvidence(report) {
     const scenarioNames = new Set(report.findings
         .map((finding) => finding.scenario)
         .filter((scenario) => typeof scenario === 'string' && scenario.trim().length > 0));
-    return uniqueMatchingEvidence(report, scenarioNames);
+    return uniqueMatchingEvidence(report.resolutionEvidence, scenarioNames);
 }
 /** Build a report whose resolution state is derived exclusively from explicit evidence. */
 export function buildChallengeReport(input) {
     const scenarioNames = new Set(input.scenarios.map((scenario) => scenario.scenario));
-    const resolutionEvidence = uniqueMatchingEvidence(input.previousReport, scenarioNames);
+    const resolutionEvidence = uniqueMatchingEvidence([
+        ...(Array.isArray(input.previousReport?.resolutionEvidence)
+            ? input.previousReport.resolutionEvidence
+            : []),
+        ...(Array.isArray(input.explicitResolutionEvidence) ? input.explicitResolutionEvidence : []),
+    ], scenarioNames);
     const resolvedScenarios = new Set(resolutionEvidence.map((item) => item.scenario));
     const addressedCount = resolvedScenarios.size;
+    const requiredCount = requiredResolvedChallenges(input.scenarios.length);
     return {
         runAt: input.runAt ?? new Date().toISOString(),
         totalScenarios: input.scenarios.length,
         addressedCount,
         focusAreas: input.focusAreas,
         overallRisk: input.overallRisk,
-        passed: addressedCount >= MINIMUM_RESOLVED_CHALLENGES,
+        passed: addressedCount >= requiredCount,
         findings: input.scenarios.map((scenario) => ({
             scenario: scenario.scenario,
             resolved: resolvedScenarios.has(scenario.scenario),

package/dist/tools/challenge-spec.js

@@ -18,7 +18,7 @@ import { calculateTokenBudget, injectBudgetIntoPrompt } from '../engine/token-bu
 import { analyzeMinimalImplementation, loadMinimalImplementationPolicy, } from '../engine/minimality/index.js';
 import { detectChallengeCapabilities, } from './challenge-spec/scenarios-utils.js';
 import { collectCapabilityScenarios } from './challenge-spec/scenario-collector.js';
-import { buildChallengeReport } from './challenge-spec/challenge-report.js';
+import { buildChallengeReport, parseChallengeResolutionEvidence, } from './challenge-spec/challenge-report.js';
 const ALL_FOCUS_AREAS = [
     'failures',
     'concurrency',
@@ -194,11 +194,15 @@ export async function handleChallengeSpec(args, server) {
         scalabilityAssessment,
         overallRisk,
     };
+    const challengeRunAt = new Date().toISOString();
+    const explicitResolutionEvidence = parseChallengeResolutionEvidence(specContent, failureScenariosScored, challengeRunAt);
     const challengeReport = buildChallengeReport({
         scenarios: failureScenariosScored,
         focusAreas,
         overallRisk,
         previousReport: spec.challengeReport,
+        explicitResolutionEvidence,
+        runAt: challengeRunAt,
     });
     const rawHumanSummary = buildChallengeSpecSummary(prioritized, overallRisk);
     // SPEC-620: Inject token budget tag into the LLM-facing summary prompt

package/dist/tools/update-status/transition-guard.d.ts

@@ -76,7 +76,7 @@ export declare function checkReadinessGate(spec: Spec, newStatus: SpecStatus, fo
  * or does not contain enough explicit resolution evidence.
  *
  * - Requires challengeReport to exist on the spec
- * - Requires at least 3 scenarios with explicit mitigation/risk-acceptance evidence
+ * - Requires explicit mitigation/risk-acceptance evidence for up to the first 3 findings
  * - High-risk specs (high/critical) require all 5 focus areas
  */
 export declare function checkChallengeGate(spec: Spec, newStatus: SpecStatus): ToolResult | null;

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

@@ -9,7 +9,7 @@ import { validateEnglishOnlySpecText } from '../../engine/spec-language/english-
 import { checkGroundedSpecContract } from '../../engine/spec-grounding/contract.js';
 import { checkGenericSpecOutput } from '../../engine/spec-quality/generic-output-gate.js';
 import { formatKeyValue } from '../output-formatter.js';
-import { getResolvedChallengeEvidence, MINIMUM_RESOLVED_CHALLENGES, } from '../challenge-spec/challenge-report.js';
+import { getResolvedChallengeEvidence, requiredResolvedChallenges, } from '../challenge-spec/challenge-report.js';
 /**
  * Valid state transitions for spec lifecycle.
  * draft -> review -> approved -> implementing -> done
@@ -436,7 +436,7 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
  * or does not contain enough explicit resolution evidence.
  *
  * - Requires challengeReport to exist on the spec
- * - Requires at least 3 scenarios with explicit mitigation/risk-acceptance evidence
+ * - Requires explicit mitigation/risk-acceptance evidence for up to the first 3 findings
  * - High-risk specs (high/critical) require all 5 focus areas
  */
 export function checkChallengeGate(spec, newStatus) {
@@ -462,12 +462,16 @@ export function checkChallengeGate(spec, newStatus) {
     }
     const resolutionEvidence = getResolvedChallengeEvidence(report);
     const addressedCount = resolutionEvidence.length;
-    if (addressedCount < MINIMUM_RESOLVED_CHALLENGES) {
+    const findingsCount = Array.isArray(report.findings)
+        ? report.findings.length
+        : report.totalScenarios;
+    const requiredCount = requiredResolvedChallenges(findingsCount);
+    if (addressedCount < requiredCount) {
         return {
             content: [
                 {
                     type: 'text',
-                    text: `Challenge gate blocked: only ${String(addressedCount)} scenario(s) have explicit resolution evidence (minimum ${String(MINIMUM_RESOLVED_CHALLENGES)} required). Record mitigation or accepted-risk evidence for discovered findings before retrying.`,
+                    text: `Challenge gate blocked: only ${String(addressedCount)} scenario(s) have explicit resolution evidence (minimum ${String(requiredCount)} required). Record mitigation or accepted-risk evidence for discovered findings before retrying.`,
                 },
             ],
             isError: true,
@@ -475,7 +479,7 @@ export function checkChallengeGate(spec, newStatus) {
                 error: 'CHALLENGE_GATE_BLOCKED',
                 code: 'INSUFFICIENT_CHALLENGES',
                 addressedCount,
-                requiredCount: MINIMUM_RESOLVED_CHALLENGES,
+                requiredCount,
                 fixHint: `Resolve challenge_spec findings with concrete evidence, then retry update_status(specId="${spec.id}", status="review").`,
             },
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.11.3",
+  "version": "4.11.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.11.3",
-    "@planu/core-darwin-x64": "4.11.3",
-    "@planu/core-linux-arm64-gnu": "4.11.3",
-    "@planu/core-linux-arm64-musl": "4.11.3",
-    "@planu/core-linux-x64-gnu": "4.11.3",
-    "@planu/core-linux-x64-musl": "4.11.3",
-    "@planu/core-win32-arm64-msvc": "4.11.3",
-    "@planu/core-win32-x64-msvc": "4.11.3"
+    "@planu/core-darwin-arm64": "4.11.4",
+    "@planu/core-darwin-x64": "4.11.4",
+    "@planu/core-linux-arm64-gnu": "4.11.4",
+    "@planu/core-linux-arm64-musl": "4.11.4",
+    "@planu/core-linux-x64-gnu": "4.11.4",
+    "@planu/core-linux-x64-musl": "4.11.4",
+    "@planu/core-win32-arm64-msvc": "4.11.4",
+    "@planu/core-win32-x64-msvc": "4.11.4"
   },
   "engines": {
     "node": ">=24.0.0"

package/planu-native.json

@@ -1,7 +1,7 @@
 {
   "name": "dev.planu.native",
   "displayName": "Planu Native Lightweight Surface",
-  "version": "4.11.3",
+  "version": "4.11.4",
   "packageName": "@planu/cli",
   "modes": {
     "lightweight": {

package/planu-plugin.json

@@ -2,7 +2,7 @@
   "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.11.3",
+  "version": "4.11.4",
   "icon": "assets/plugin/icon.svg",
   "command": [
     "npx",