@planu/cli 4.11.3 → 4.11.5

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [4.11.5] - 2026-07-18
+
+### Bug Fixes
+- fix: close weekly technical debt backlog
+
+
+## [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/ai-integration/gemini/gemini-md-generator.js

@@ -58,12 +58,19 @@ function buildSddSection(options) {
         '',
         '### Architecture Rules',
         '',
+        '- Primary implementation stays in `src/`; Rust is an optional acceleration layer, not the default destination for every feature',
         '- `types/` → no imports from other layers',
         '- `engine/` → imports only from `types/`',
         '- `storage/` → imports only from `types/`',
         '- `tools/` → imports from `engine/` + `storage/` + `types/`',
         '- Cross-layer violations → ESLint error',
         '',
+        '### Release Rules',
+        '',
+        '- `main` is the authoritative release branch',
+        '- `develop` and `release` are optional mirrors that must not drift from `main`',
+        '- Run `pnpm check` and `pnpm test` before local release publishing',
+        '',
         PLANU_SECTION_END,
     ].join('\n');
 }

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/engine/outbound-webhook-dispatcher.d.ts

@@ -1,4 +1,4 @@
-import type { OutboundWebhookPayload, OutboundWebhookEventType, OutboundWebhookConfig, OutboundWebhookDelivery } from '../types/index.js';
-export declare function dispatchToWebhooks(webhooks: readonly OutboundWebhookConfig[], payload: OutboundWebhookPayload, onDelivery: (delivery: OutboundWebhookDelivery) => Promise<void>): Promise<void>;
+import type { OutboundWebhookPayload, OutboundWebhookEventType, OutboundWebhookConfig, OutboundWebhookDelivery, WebhookDispatchOptions } from '../types/index.js';
+export declare function dispatchToWebhooks(webhooks: readonly OutboundWebhookConfig[], payload: OutboundWebhookPayload, onDelivery: (delivery: OutboundWebhookDelivery) => Promise<void>, options?: WebhookDispatchOptions): Promise<void>;
 export declare function buildSpecLifecyclePayload(event: OutboundWebhookEventType, specId: string, specTitle: string, status: string, projectPath: string): OutboundWebhookPayload;
 //# sourceMappingURL=outbound-webhook-dispatcher.d.ts.map

package/dist/engine/outbound-webhook-dispatcher.js

@@ -40,13 +40,15 @@ async function attemptDelivery(url, body, signature) {
 // Retry logic: 3 attempts with exponential backoff (1s, 5s, 30s)
 // ---------------------------------------------------------------------------
 const RETRY_DELAYS_MS = [1_000, 5_000, 30_000];
-async function deliverWithRetry(webhook, body, payload, onDelivery) {
+async function deliverWithRetry(webhook, body, payload, onDelivery, options) {
     let lastResult = null;
     const signature = signPayload(webhook.secret, body);
-    for (let attempt = 0; attempt < 3; attempt++) {
+    const retryDelays = options.retryDelaysMs ?? RETRY_DELAYS_MS;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    for (let attempt = 0; attempt < retryDelays.length + 1; attempt++) {
         if (attempt > 0) {
-            const delay = RETRY_DELAYS_MS[attempt - 1] ?? 1_000;
-            await new Promise((resolve) => setTimeout(resolve, delay));
+            const delay = retryDelays[attempt - 1] ?? 0;
+            await sleep(delay);
         }
         lastResult = await attemptDelivery(webhook.url, body, signature);
         if (lastResult.success) {
@@ -71,12 +73,12 @@ async function deliverWithRetry(webhook, body, payload, onDelivery) {
 // ---------------------------------------------------------------------------
 // Core dispatch (pure — no storage deps)
 // ---------------------------------------------------------------------------
-export async function dispatchToWebhooks(webhooks, payload, onDelivery) {
+export async function dispatchToWebhooks(webhooks, payload, onDelivery, options = {}) {
     if (webhooks.length === 0) {
         return;
     }
     const body = JSON.stringify(payload);
-    await Promise.allSettled(webhooks.map((webhook) => deliverWithRetry(webhook, body, payload, onDelivery)));
+    await Promise.allSettled(webhooks.map((webhook) => deliverWithRetry(webhook, body, payload, onDelivery, options)));
 }
 // ---------------------------------------------------------------------------
 // Helper to build spec lifecycle payloads

package/dist/engine/web-fetcher/registry-auto-discovery.d.ts

@@ -1,4 +1,4 @@
-import type { DiscoveredDocsEntry, DocsRegistryHealth } from '../../types/index.js';
+import type { DiscoveredDocsEntry, DocsRegistryHealth, DocsDiscoveryOptions } from '../../types/index.js';
 /**
  * Verify that a URL is alive with a HEAD request (timeout 3s).
  * Returns true if status is 200, 301, or 302.
@@ -9,7 +9,7 @@ export declare function validateRegistryUrl(url: string): Promise<boolean>;
  * Respects a 1 req/s rate limit per registry via simple delay.
  * Returns null if not found anywhere.
  */
-export declare function discoverDocsUrl(tech: string): Promise<DiscoveredDocsEntry | null>;
+export declare function discoverDocsUrl(tech: string, options?: DocsDiscoveryOptions): Promise<DiscoveredDocsEntry | null>;
 /**
  * Batch validate all entries in the docs registry.
  * Categorizes each entry as healthy (<=2s), slow (2-5s), or broken (timeout/error).

package/dist/engine/web-fetcher/registry-auto-discovery.js

@@ -113,10 +113,14 @@ export async function validateRegistryUrl(url) {
  * Respects a 1 req/s rate limit per registry via simple delay.
  * Returns null if not found anywhere.
  */
-export async function discoverDocsUrl(tech) {
-    const tryWithDelay = async (fn) => {
+export async function discoverDocsUrl(tech, options = {}) {
+    const rateLimitDelayMs = options.rateLimitDelayMs ?? RATE_LIMIT_DELAY_MS;
+    const sleepFn = options.sleep ?? sleep;
+    const tryWithDelay = async (fn, shouldDelay) => {
         const result = await fn();
-        await sleep(RATE_LIMIT_DELAY_MS);
+        if (shouldDelay && rateLimitDelayMs > 0) {
+            await sleepFn(rateLimitDelayMs);
+        }
         return result;
     };
     const registries = [
@@ -124,8 +128,8 @@ export async function discoverDocsUrl(tech) {
         { source: 'pypi', fn: () => tryPypi(tech) },
         { source: 'crates', fn: () => tryCrates(tech) },
     ];
-    for (const { source, fn } of registries) {
-        const url = await tryWithDelay(fn);
+    for (const [index, { source, fn }] of registries.entries()) {
+        const url = await tryWithDelay(fn, index < registries.length - 1);
         if (url) {
             const verified = await validateRegistryUrl(url);
             return {

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/dist/types/docs.d.ts

@@ -285,6 +285,10 @@ export interface DocsRegistryHealth {
     broken: string[];
     slow: string[];
 }
+export interface DocsDiscoveryOptions {
+    rateLimitDelayMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
 /** Input for validate_docs_registry tool. */
 export interface ValidateDocsRegistryInput {
     projectPath: string;

package/dist/types/outbound-webhook.d.ts

@@ -48,4 +48,8 @@ export interface WebhookAttemptResult {
     readonly success: boolean;
     readonly error?: string;
 }
+export interface WebhookDispatchOptions {
+    readonly retryDelaysMs?: readonly number[];
+    readonly sleep?: (ms: number) => Promise<void>;
+}
 //# sourceMappingURL=outbound-webhook.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.11.3",
+  "version": "4.11.5",
   "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.5",
+    "@planu/core-darwin-x64": "4.11.5",
+    "@planu/core-linux-arm64-gnu": "4.11.5",
+    "@planu/core-linux-arm64-musl": "4.11.5",
+    "@planu/core-linux-x64-gnu": "4.11.5",
+    "@planu/core-linux-x64-musl": "4.11.5",
+    "@planu/core-win32-arm64-msvc": "4.11.5",
+    "@planu/core-win32-x64-msvc": "4.11.5"
   },
   "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.5",
   "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.5",
   "icon": "assets/plugin/icon.svg",
   "command": [
     "npx",