@planu/cli 4.11.4 → 4.11.6

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [4.11.6] - 2026-07-18
+
+### Bug Fixes
+- fix: tighten SDD gates and release readiness
+- fix: allow routine dependency drift during pre-push
+
+### Chores
+- chore: finalize weekly debt spec state
+
+
+## [4.11.5] - 2026-07-18
+
+### Bug Fixes
+- fix: close weekly technical debt backlog
+
+
 ## [4.11.4] - 2026-07-18
 
 ### Bug Fixes

package/README.md

@@ -57,8 +57,8 @@ Every transition is gated by Definition of Ready (DoR) and Definition of Done (D
 
 Planu runs follow-up actions automatically after each step:
 
-- `create_spec` automatically runs `challenge_spec` + `check_readiness`.
-- `update_status(done)` automatically runs `validate` + scans crash risks + **freezes the spec**.
+- `create_spec` runs a bounded post-create analysis and surfaces challenge/readiness signals when they complete in time.
+- `update_status(done)` runs `validate`, writes implementation-review evidence, then scans crash risks + **freezes the spec** before finalizing.
 - `update_status(approved)` automatically snapshots the spec version.
 
 ---

package/dist/engine/actuals/progress-parser.js

@@ -1,3 +1,6 @@
+function escapeRegex(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 /**
  * Parses progress.md content and extracts any actual metrics found.
  *
@@ -45,7 +48,7 @@ export function parseProgressActuals(content) {
  * Returns undefined if the actual column is `-` or missing.
  */
 function parseMetricRow(content, metricName) {
-    const escapedName = RegExp.escape(metricName);
+    const escapedName = escapeRegex(metricName);
     const pattern = new RegExp(`\\|\\s*${escapedName}[^|]*\\|[^|]*\\|\\s*([^|]+)\\|`, 'i');
     const match = pattern.exec(content);
     if (!match?.[1]) {

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/detectors/idp-detector.js

@@ -121,6 +121,6 @@ function extractYamlField(content, fieldPath) {
     return value.replace(/^['"]|['"]$/g, '');
 }
 function escapeRegex(str) {
-    return RegExp.escape(str);
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 //# sourceMappingURL=idp-detector.js.map

package/dist/engine/evidence-gates/lifecycle-gate.js

@@ -22,19 +22,23 @@ function isNonTrivial(spec) {
 }
 function normalizeCriterion(value) {
     const withoutCheckbox = value.replace(/^-\s*\[[ x]\]\s*/i, '').trim();
-    const criterionOnly = /^(AC\d+)\s*[:.)-]?\s*$/i.exec(withoutCheckbox)?.[1];
+    const criterionOnly = /^([A-Z]{2}\d+)\s*[:.)-]?\s*$/i.exec(withoutCheckbox)?.[1];
     if (criterionOnly) {
         return criterionOnly.toLowerCase();
     }
     return withoutCheckbox
-        .replace(/^AC\d+\s*[:.)-]?\s*/i, '')
+        .replace(/^[A-Z]{2}\d+\s*[:.)-]?\s*/i, '')
         .replace(/\s+/g, ' ')
         .trim()
         .toLowerCase();
 }
 function criterionAliases(value, index) {
-    const aliases = new Set([normalizeCriterion(value), `ac${String(index + 1)}`]);
-    const explicit = /^(AC\d+)\b/i.exec(value)?.[1];
+    const aliases = new Set([
+        normalizeCriterion(value),
+        `ac${String(index + 1)}`,
+        `ab${String(index + 1)}`,
+    ]);
+    const explicit = /^([A-Z]{2}\d+)\b/i.exec(value)?.[1];
     if (explicit) {
         aliases.add(normalizeCriterion(explicit));
     }

package/dist/engine/evidence-index/index-builder.js

@@ -108,7 +108,10 @@ async function pathRecord(kind, value, source, args, fieldName) {
         .then(() => true)
         .catch(() => false);
     const missingReason = evidencePathReason(fieldName, `Missing path: ${value}`);
-    return record(kind, value, exists ? 'valid' : 'stale', source, exists ? undefined : missingReason);
+    return record(kind, value, exists ? 'valid' : missingPathStatus(fieldName), source, exists ? undefined : missingReason);
+}
+function missingPathStatus(fieldName) {
+    return fieldName === 'changedFiles' ? 'missing' : 'stale';
 }
 function resolveSafeProjectPath(value, projectPath, fieldName) {
     if (value.trim().length === 0) {
@@ -156,12 +159,12 @@ function record(kind, value, status, source, reason) {
 }
 function normalizeCriterion(value) {
     const withoutCheckbox = value.replace(/^-\s*\[[ x]\]\s*/i, '').trim();
-    const criterionOnly = /^(AC\d+)\s*[:.)-]?\s*$/i.exec(withoutCheckbox)?.[1];
+    const criterionOnly = /^([A-Z]{2}\d+)\s*[:.)-]?\s*$/i.exec(withoutCheckbox)?.[1];
     if (criterionOnly) {
         return criterionOnly.toLowerCase();
     }
     return withoutCheckbox
-        .replace(/^AC\d+\s*[:.)-]?\s*/i, '')
+        .replace(/^[A-Z]{2}\d+\s*[:.)-]?\s*/i, '')
         .replace(/\s+/g, ' ')
         .trim()
         .toLowerCase();

package/dist/engine/github/quality-dimensions.js

@@ -1,6 +1,9 @@
 // engine/github/quality-dimensions.ts — Quality analysis dimensions (SPEC-309)
 // Duplication, complexity, and dead-code checks extracted from review-dimensions.ts
 import { parseDiffFiles } from './review-helpers.js';
+function escapeRegex(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 // ---------------------------------------------------------------------------
 // Duplication dimension
 // ---------------------------------------------------------------------------
@@ -203,7 +206,7 @@ function runDeadCode(diff) {
                         continue;
                     }
                     const withoutImport = allContent.replace(content, '');
-                    const escapedId = RegExp.escape(id);
+                    const escapedId = escapeRegex(id);
                     const occurrences = withoutImport.split(new RegExp(`\\b${escapedId}\\b`)).length - 1;
                     if (occurrences === 0) {
                         findings.push({

package/dist/engine/hooks/event-bus.js

@@ -55,7 +55,7 @@ export class EventBus extends EventEmitter {
      * treated as literal glob-style strings (* and ? retain special meaning).
      */
     static escapeRegex(str) {
-        return RegExp.escape(str);
+        return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     }
     /**
      * Get filtered event history.

package/dist/engine/lifecycle-hints.js

@@ -10,9 +10,9 @@ const NEXT_ACTION_MAP = {
     },
     review: {
         step: 'Get approval',
-        prompt: "Share this plan with your team or just tell me 'approved' to move forward",
+        prompt: 'Move the spec through review evidence first, then approve it once the plan reviewer passes',
         suggestedCommand: 'update_status(status="approved")',
-        whenToDoIt: "When you're happy with the plan",
+        whenToDoIt: 'After review feedback is approved',
     },
     approved: {
         step: 'Start implementation',
@@ -22,9 +22,9 @@ const NEXT_ACTION_MAP = {
     },
     implementing: {
         step: 'Validate the implementation',
-        prompt: 'Check the implementation against every acceptance criterion',
-        suggestedCommand: 'validate(specId)',
-        whenToDoIt: 'After all tests pass',
+        prompt: 'Run validate first, then mark the spec done once reviewer evidence is written',
+        suggestedCommand: 'validate(specId) → update_status(status="done")',
+        whenToDoIt: 'After all tests pass and the implementation reviewer approves',
     },
 };
 /**

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/qa-gate.d.ts

@@ -1,5 +1,6 @@
 import type { QaGateResult } from '../types/qa-gate.js';
 import type { Spec } from '../types/spec/core.js';
 export declare function extractCoverageThreshold(spec: Spec): number | null;
+export declare function computeQaGateFingerprint(spec: Spec, projectPath: string): string;
 export declare function runQaGate(spec: Spec, projectPath: string): Promise<QaGateResult>;
 //# sourceMappingURL=qa-gate.d.ts.map

package/dist/engine/qa-gate.js

@@ -1,6 +1,21 @@
 // engine/qa-gate.ts — SPEC-642
 import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveProjectCommandPlan } from '../tools/validate-runtime.js';
 const TIMEOUT_MS = 120_000;
+const QA_FINGERPRINT_FILES = [
+    'package.json',
+    'pnpm-lock.yaml',
+    'package-lock.json',
+    'yarn.lock',
+    'bun.lockb',
+    'tsconfig.json',
+    'vitest.config.ts',
+    'vitest.config.mts',
+    'vitest.config.js',
+];
 export function extractCoverageThreshold(spec) {
     const text = [spec.title, ...spec.tags].join(' ');
     const match = /coverage\s*[>=]+\s*(\d+)%/i.exec(text);
@@ -34,15 +49,65 @@ function runCheck(name, command, args, cwd) {
         errorMessage: result.error?.message,
     };
 }
+function runRequestedCheck(name, requestedCommand, cwd) {
+    const plan = resolveProjectCommandPlan(cwd, requestedCommand);
+    return runCheck(name, plan.executable, plan.args, cwd);
+}
+function readProjectPackageManager(projectPath) {
+    try {
+        const raw = readFileSync(join(projectPath, 'package.json'), 'utf-8');
+        const parsed = JSON.parse(raw);
+        return typeof parsed.packageManager === 'string' ? parsed.packageManager : null;
+    }
+    catch {
+        return null;
+    }
+}
+function resolveRequestedQaCommand(projectPath, check) {
+    const manager = readProjectPackageManager(projectPath)?.split('@')[0] ?? 'pnpm';
+    if (check === 'typecheck') {
+        return `${manager} typecheck`;
+    }
+    if (check === 'test-coverage') {
+        return `${manager} test:coverage`;
+    }
+    return `${manager} test`;
+}
+function asStableString(value) {
+    return typeof value === 'string' ? value : '';
+}
+function asStableStringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === 'string')
+        : [];
+}
+export function computeQaGateFingerprint(spec, projectPath) {
+    const hash = createHash('sha256');
+    hash.update(spec.id);
+    hash.update(asStableString(spec.updatedAt));
+    hash.update(asStableString(spec.title));
+    hash.update(asStableStringArray(spec.tags).join('|'));
+    for (const file of QA_FINGERPRINT_FILES) {
+        const fullPath = join(projectPath, file);
+        try {
+            const stats = statSync(fullPath);
+            hash.update(`${file}:${String(stats.mtimeMs)}:${String(stats.size)}`);
+        }
+        catch {
+            hash.update(`${file}:missing`);
+        }
+    }
+    return hash.digest('hex');
+}
 export function runQaGate(spec, projectPath) {
     const coverageThreshold = extractCoverageThreshold(spec);
     const checks = [];
-    checks.push(runCheck('typecheck', 'pnpm', ['typecheck'], projectPath));
+    checks.push(runRequestedCheck('typecheck', resolveRequestedQaCommand(projectPath, 'typecheck'), projectPath));
     if (coverageThreshold === null) {
-        checks.push(runCheck('test', 'pnpm', ['test'], projectPath));
+        checks.push(runRequestedCheck('test', resolveRequestedQaCommand(projectPath, 'test'), projectPath));
     }
     else {
-        checks.push(runCheck('test-coverage', 'pnpm', ['test:coverage'], projectPath));
+        checks.push(runRequestedCheck('test-coverage', resolveRequestedQaCommand(projectPath, 'test-coverage'), projectPath));
     }
     const passed = checks.every((c) => c.passed);
     return Promise.resolve({
@@ -51,6 +116,7 @@ export function runQaGate(spec, projectPath) {
         checks,
         ranAt: new Date().toISOString(),
         coverageThreshold,
+        fingerprint: computeQaGateFingerprint(spec, projectPath),
     });
 }
 //# sourceMappingURL=qa-gate.js.map

package/dist/engine/spec-repair.js

@@ -163,7 +163,7 @@ function extractFrontmatterArray(content, field) {
     if (!match?.[1]) {
         return [];
     }
-    const escaped = RegExp.escape(field);
+    const escaped = field.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     const fieldRe = new RegExp(`^${escaped}:\\s*\\[(.*)\\]`, 'm');
     const fieldMatch = fieldRe.exec(match[1]);
     if (!fieldMatch?.[1]) {

package/dist/engine/token-optimizer/response-cache.js

@@ -7,6 +7,9 @@ const DEFAULT_CACHE_CONFIG = {
     maxPersistentSizeMb: 5,
     persistMinTtlMs: 60 * 60 * 1000, // 1 hour
 };
+function escapeRegex(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 /**
  * In-memory LRU response cache with content-hash keys and TTL support.
  */
@@ -84,7 +87,7 @@ export class ResponseCache {
         }
         // Glob-like pattern: escape regex metacharacters, then restore glob wildcards.
         // This prevents ReDoS from user-supplied patterns with special regex chars.
-        const escaped = RegExp.escape(keyOrPattern).replace(/\\\*/g, '.*').replace(/\\\?/g, '.');
+        const escaped = escapeRegex(keyOrPattern).replace(/\\\*/g, '.*').replace(/\\\?/g, '.');
         const regex = new RegExp(`^${escaped}$`);
         let count = 0;
         for (const key of [...this.entries.keys()]) {

package/dist/engine/validator/deep-code-checker.js

@@ -4,6 +4,9 @@ import { readFile, stat } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 import { glob } from 'glob';
 const DEFAULT_IGNORE = ['node_modules/**', 'dist/**', 'build/**', '.git/**', 'coverage/**'];
+function escapeRegex(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 // ─── Keyword classification ──────────────────────────────────────────────────
 /**
  * Classify criterion text into a check type using keyword heuristics.
@@ -123,7 +126,7 @@ function buildRegex(pattern) {
     }
     catch {
         try {
-            const escaped = RegExp.escape(pattern);
+            const escaped = escapeRegex(pattern);
             return new RegExp(escaped, 'g');
         }
         catch {

package/dist/engine/validator.js

@@ -17,6 +17,7 @@ export { buildHolisticReportFromFlatScore } from './validator/holistic-report.js
 function normalizeCriterionForEvidence(value) {
     return value
         .replace(/^-\s*\[[ xX]\]\s*/i, '')
+        .replace(/^[A-Z]{2}\d+\s*[:.)-]?\s*/i, '')
         .replace(/\s+/g, ' ')
         .trim()
         .toLowerCase();

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/storage/path-resolver.js

@@ -119,11 +119,6 @@ export async function resolveProjectPath(input) {
         resolutionCache.set(cacheKey, result);
         return result;
     }
-    if (gitRoot) {
-        const result = { projectPath: gitRoot, resolvedFrom: 'git-root' };
-        resolutionCache.set(cacheKey, result);
-        return result;
-    }
     // Cannot resolve — fall back to cwd
     const result = { projectPath: cwd, resolvedFrom: 'cwd-walk-planu' };
     resolutionCache.set(cacheKey, result);

package/dist/storage/qa-gate-store.js

@@ -8,7 +8,7 @@ function gatePath(projectPath, specId) {
 export async function saveGateState(projectPath, specId, result) {
     const path = gatePath(projectPath, specId);
     await mkdir(dirname(path), { recursive: true });
-    const state = { specId, lastResult: result };
+    const state = { specId, lastResult: result, fingerprint: result.fingerprint };
     await writeFile(path, JSON.stringify(state, null, 2), 'utf-8');
 }
 export async function getGateState(projectPath, specId) {

package/dist/tools/challenge-spec.js

@@ -271,10 +271,6 @@ export async function handleChallengeSpec(args, server) {
                         }),
                     },
                     { type: 'text', text: humanSummary },
-                    {
-                        type: 'text',
-                        text: '⚡ INTERACTIVE — call AskUserQuestion now with the interactiveQuestions from structuredContent',
-                    },
                 ],
                 structuredContent: {
                     ...analysisPayload,

package/dist/tools/create-spec/auto-pipeline.js

@@ -8,9 +8,21 @@ import { generateFailureScenarios, generateSecurityScenarios, generateScaleScena
 import { readSpecContent, calculateOverallRisk } from '../challenge-spec-helpers.js';
 import { prioritizeScenarios, buildPrioritizedSummary, } from '../../engine/challenge-prioritizer.js';
 const AUTO_PIPELINE_TIMEOUT_MS = 10_000;
-async function runChallengePhase(spec, knowledge) {
+function abortError(message) {
+    const error = new Error(message);
+    error.name = 'AbortError';
+    return error;
+}
+function throwIfAborted(signal) {
+    if (signal.aborted) {
+        throw abortError(signal.reason instanceof Error ? signal.reason.message : 'Auto-pipeline aborted');
+    }
+}
+async function runChallengePhase(spec, knowledge, signal) {
     try {
+        throwIfAborted(signal);
         const specContent = knowledge ? await readSpecContent(spec) : '';
+        throwIfAborted(signal);
         const failureScenarios = [
             ...(knowledge ? generateFailureScenarios(spec, specContent, knowledge) : []),
             ...(knowledge ? generateSecurityScenarios(spec, specContent, knowledge) : []),
@@ -34,12 +46,13 @@ async function runChallengePhase(spec, knowledge) {
         return null;
     }
 }
-async function runPipelineInternal(specId, projectId) {
+async function runPipelineInternal(specId, projectId, signal) {
     // Load spec and knowledge (both required for challenge)
     const [spec, knowledge] = await Promise.all([
         specStore.getSpec(projectId, specId),
         knowledgeStore.getKnowledge(projectId),
     ]);
+    throwIfAborted(signal);
     if (!spec) {
         return {
             challengeSummary: null,
@@ -49,12 +62,14 @@ async function runPipelineInternal(specId, projectId) {
         };
     }
     // --- Challenge phase ---
-    const challengeSummary = await runChallengePhase(spec, knowledge);
+    const challengeSummary = await runChallengePhase(spec, knowledge, signal);
     // --- Readiness phase ---
     let readinessScore = null;
     let readinessSuggestion = null;
     try {
+        throwIfAborted(signal);
         const report = await checkSpecReadiness(spec, 'lenient');
+        throwIfAborted(signal);
         readinessScore = report.score;
         if (report.score >= 80) {
             readinessSuggestion = 'Listo para review. Usa update_status(review) cuando quieras proceder.';
@@ -72,6 +87,7 @@ async function runPipelineInternal(specId, projectId) {
     // SPEC-501: AC testability gate — flag vague criteria, suggest EARS rewrites
     let acTestabilityWarning = null;
     try {
+        throwIfAborted(signal);
         acTestabilityWarning = await scoreSpecCriteria(spec);
     }
     catch {
@@ -81,8 +97,10 @@ async function runPipelineInternal(specId, projectId) {
     let relevantLessons = null;
     try {
         if (knowledge?.projectPath && spec.tags.length > 0) {
+            throwIfAborted(signal);
             const { getLessons } = await import('../../storage/lessons-store.js');
             const lessons = await getLessons(knowledge.projectPath, { tags: spec.tags, limit: 3 });
+            throwIfAborted(signal);
             if (lessons.length > 0) {
                 relevantLessons = lessons.map((l) => `- ${l.title}: ${l.prevention}`);
             }
@@ -94,10 +112,13 @@ async function runPipelineInternal(specId, projectId) {
     // SPEC-664: Resolve npm package versions mentioned in spec text
     let resolvedVersions = null;
     try {
+        throwIfAborted(signal);
         const specBody = await readSpecContent(spec);
         if (specBody) {
+            throwIfAborted(signal);
             const { resolveSpecVersions } = await import('../../engine/version-resolver.js');
             resolvedVersions = await resolveSpecVersions(specBody, projectId);
+            throwIfAborted(signal);
         }
     }
     catch {
@@ -182,22 +203,22 @@ export function formatPipelineLines(result) {
  * Has a 10s total timeout. Never throws — errors are captured in the result.
  */
 export async function runAutoPostCreatePipeline(specId, projectId, _projectPath) {
-    const timeoutPromise = new Promise((resolve) => {
-        /* c8 ignore next */
-        setTimeout(() => {
-            /* c8 ignore next */
-            resolve({
-                challengeSummary: null,
-                readinessScore: null,
-                readinessSuggestion: null,
-                error: 'Auto-pipeline timeout (10s)',
-            });
-        }, AUTO_PIPELINE_TIMEOUT_MS);
-    });
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+        controller.abort(abortError(`Auto-pipeline timeout (${String(AUTO_PIPELINE_TIMEOUT_MS / 1000)}s)`));
+    }, AUTO_PIPELINE_TIMEOUT_MS);
     try {
-        return await Promise.race([runPipelineInternal(specId, projectId), timeoutPromise]);
+        return await runPipelineInternal(specId, projectId, controller.signal);
     }
     catch (err) {
+        if (err instanceof Error && err.name === 'AbortError') {
+            return {
+                challengeSummary: null,
+                readinessScore: null,
+                readinessSuggestion: null,
+                error: err.message,
+            };
+        }
         const message = err instanceof Error ? err.message : String(err);
         return {
             challengeSummary: null,
@@ -206,5 +227,8 @@ export async function runAutoPostCreatePipeline(specId, projectId, _projectPath)
             error: message,
         };
     }
+    finally {
+        clearTimeout(timeout);
+    }
 }
 //# sourceMappingURL=auto-pipeline.js.map

package/dist/tools/create-spec.js

@@ -1290,20 +1290,10 @@ export async function handleCreateSpec(inputParams, server) {
                     .catch(() => {
                     /* best-effort */
                 });
-                // Auto post-creation pipeline: challenge + readiness (SPEC-445)
-                // SPEC-713: Convert to fire-and-forget — pipeline has its own 10s internal timeout
-                // but was blocking the MCP response. Now runs in background after response is built.
-                const pipelineResult = {
-                    challengeSummary: null,
-                    readinessScore: null,
-                    readinessSuggestion: null,
-                    error: 'pipeline deferred (SPEC-713 fire-and-forget)',
-                };
-                // Start pipeline in background — result will be lost after response, but spec is
-                // already persisted so this is a best-effort enrichment only.
-                void runAutoPostCreatePipeline(spec.id, projectId, knowledge?.projectPath ?? params.projectPath ?? '').catch(() => {
-                    /* best-effort */
-                });
+                // Auto post-creation pipeline: challenge + readiness (SPEC-445).
+                // Keep it observable and bounded so users see the actual result instead of
+                // background work that may finish invisibly after the tool already returned.
+                const pipelineResult = await runAutoPostCreatePipeline(spec.id, projectId, knowledge?.projectPath ?? params.projectPath ?? '');
                 // Build markdown response
                 const lines = [
                     `**SPEC-${spec.id}** — ${spec.title}`,

package/dist/tools/init-project/agents-md-writer.js

@@ -45,7 +45,7 @@ facilitate("what to build") → create_spec → challenge_spec → check_readine
 ## Session End
 
 - Call \`session_checkpoint\` to save context
-- Call \`update_status(done)\` if work is complete
+- Run \`validate\`, then call \`update_status(done)\` when work is complete
 
 ## Quick Reference
 
@@ -82,7 +82,7 @@ Auto-generated by init_project.
 
 - New feature: facilitate("what to build")
 - Check status: planu_status
-- Mark done: update_status(done) then validate
+- Mark done: validate, then update_status(done)
 `;
 async function writeIfMissing(path, content) {
     try {

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

@@ -228,7 +228,7 @@ const AGENT_RULE_FILES = [
 function injectOrReplaceSection(content, section, marker) {
     if (content.includes(marker)) {
         // Replace everything between (and including) the two marker lines
-        const escaped = RegExp.escape(marker);
+        const escaped = marker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
         const re = new RegExp(`${escaped}[\\s\\S]*?${escaped}`, 'g');
         // Extract the new wrapped block from the section (it already contains the markers)
         const newBlock = section.includes(marker) ? section : `${marker}\n${section}\n${marker}`;

package/dist/tools/init-project/planu-workflow-generator.js

@@ -74,8 +74,8 @@ export function injectOrReplacePlanuBlock(existing, block, openMarker) {
     const closeMarker = openMarker.replace('<!-- ', '<!-- /');
     if (existing.includes(openMarker)) {
         // Replace everything from openMarker to closeMarker (inclusive)
-        const escapedOpen = RegExp.escape(openMarker);
-        const escapedClose = RegExp.escape(closeMarker);
+        const escapedOpen = openMarker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const escapedClose = closeMarker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
         const re = new RegExp(`${escapedOpen}[\\s\\S]*?${escapedClose}`, 'g');
         return existing.replace(re, block);
     }

package/dist/tools/resolve-project-path.js

@@ -11,6 +11,8 @@
 // This module is intentionally side-effect-free: it reads the global registry
 // and the env var but never mutates any state.
 import { spawnSync } from 'node:child_process';
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
 import { hashProjectPath } from '../storage/base-store.js';
 import { getProjects } from '../storage/global-projects-store.js';
 // ---------------------------------------------------------------------------
@@ -37,6 +39,15 @@ export function detectGitRoot() {
         return null;
     }
 }
+async function hasPlanuDir(projectPath) {
+    try {
+        const stats = await stat(join(projectPath, 'planu'));
+        return stats.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Derive a human-readable project name from its absolute path.
  * Uses the last non-empty path segment (the directory name).
@@ -121,7 +132,7 @@ export async function resolveProjectPath(params) {
     }
     // 4. SPEC-509: git rev-parse --show-toplevel — detect from current working directory
     const gitRoot = detectGitRoot();
-    if (gitRoot) {
+    if (gitRoot && (await hasPlanuDir(gitRoot))) {
         return {
             kind: 'resolved',
             projectId: hashProjectPath(gitRoot),

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

@@ -13,7 +13,7 @@ import { checkApprovedDepGate } from '../../engine/dep-guard/index.js';
 import { checkApprovalGate } from '../../engine/approval-workflow.js';
 import * as approvalStore from '../../storage/approval-store.js';
 import { isLocked, getLock } from '../../storage/spec-lock-store.js';
-import { runValidateGate, checkDoneGates, checkComplianceGate, checkQaGate, checkApprovedFormatGate, checkValidationReportGate, readApprovedValidationReportGate, checkSpecReviewGate, writeSpecReviewArtifact, } from './dod-gates.js';
+import { runValidateGate, checkDoneGates, checkComplianceGate, checkQaGate, checkApprovedFormatGate, readApprovedValidationReportGate, checkSpecReviewGate, writeSpecReviewArtifact, } from './dod-gates.js';
 import { checkLifecycleEvidenceTransitionGate } from './evidence-gate.js';
 import { buildStatusResponse, buildValidateBlockedResponse, buildDryRunResponse, } from './response-builder.js';
 import { recordDoneMetrics, syncSpecFiles, tryReconcile, recordTerminalTransitionEvent, } from './file-sync.js';
@@ -529,29 +529,14 @@ export async function handleUpdateStatus(params, server) {
                 let crashShieldSkipReason = null;
                 let complianceGateResult = null;
                 let validationReportGate = null;
-                if (newStatus === 'done' && !(params.force ?? params.forceStatus ?? false)) {
-                    validationReportGate = await readApprovedValidationReportGate(specId, projectId, false);
-                    if (!validationReportGate.ok) {
-                        return validationReportGate.error;
-                    }
-                }
                 // SPEC-628: Rate-limit crash scan — check before entering the parallel batch
                 crashShieldSkipReason = await checkCrashScanRateLimit(newStatus, effectiveGatePath ?? null);
-                const approvedValidationReportScore = validationReportGate?.ok === true && validationReportGate.score === 100
-                    ? validationReportGate.score
-                    : null;
                 const [validateGateResult, crashRisksReport, complianceResult] = await Promise.all([
                     // Validate: only on 'done'.
                     // SPEC-721: timeout lives inside runValidateGate (Promise.race) — do NOT wrap with
                     // withToolTimeout here, which would silently convert timeout into blocked:false (fail-open).
                     newStatus === 'done'
-                        ? approvedValidationReportScore !== null
-                            ? Promise.resolve({
-                                blocked: false,
-                                score: approvedValidationReportScore,
-                                forced: false,
-                            })
-                            : runValidateGate(spec, effectiveGatePath ?? '', params.forceStatus ?? false, params.forceStatusReason, 9_000, { projectId, specId })
+                        ? runValidateGate(spec, effectiveGatePath ?? '', params.forceStatus ?? false, params.forceStatusReason, 9_000, { projectId, specId })
                         : Promise.resolve(null),
                     // Crash shield: only on 'done', skipped if rate-limited (SPEC-628)
                     newStatus === 'done' && effectiveGatePath && !crashShieldSkipReason
@@ -582,16 +567,17 @@ export async function handleUpdateStatus(params, server) {
                         };
                     }
                     else {
-                        validateScoreSource =
-                            approvedValidationReportScore !== null ? 'validation-report' : 'validateSpec';
+                        validateScoreSource = 'validateSpec';
                     }
                 }
-                if (newStatus === 'done' &&
-                    !(params.force ?? params.forceStatus ?? false) &&
-                    validationReportGate === null) {
-                    const validationReportError = await checkValidationReportGate(specId, projectId, false);
-                    if (validationReportError) {
-                        return validationReportError;
+                if (newStatus === 'done' && !(params.force ?? params.forceStatus ?? false)) {
+                    validationReportGate = await readApprovedValidationReportGate(specId, projectId, false);
+                    if (!validationReportGate.ok) {
+                        return validationReportGate.error;
+                    }
+                    if (validationReportGate.score !== null) {
+                        validateScore = validationReportGate.score;
+                        validateScoreSource = 'validation-report';
                     }
                 }
                 if (newStatus === 'done' &&

package/dist/tools/update-status/qa-gate.d.ts

@@ -1,5 +1,4 @@
 import type { ToolResult } from '../../types/index.js';
 import type { Spec } from '../../types/spec/core.js';
-/** SPEC-642 / SPEC-1111: verify and persist local QA evidence before done. */
 export declare function checkQaGate(spec: Spec, projectPath: string | undefined, force: boolean): Promise<ToolResult | null>;
 //# sourceMappingURL=qa-gate.d.ts.map

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

@@ -1,23 +1,36 @@
 /** SPEC-642 / SPEC-1111: verify and persist local QA evidence before done. */
+const QA_GATE_TTL_MS = 15 * 60 * 1000;
 export async function checkQaGate(spec, projectPath, force) {
     if (force || !projectPath) {
         return null;
     }
     const specId = spec.id;
     const { getGateState, saveGateState } = await import('../../storage/qa-gate-store.js');
+    const { computeQaGateFingerprint, runQaGate } = await import('../../engine/qa-gate.js');
+    const fingerprint = computeQaGateFingerprint(spec, projectPath);
     const state = await getGateState(projectPath, specId).catch(() => null);
-    if (state?.lastResult?.passed === true) {
+    const ranAtMs = state?.lastResult?.ranAt ? Date.parse(state.lastResult.ranAt) : NaN;
+    const freshEnough = Number.isFinite(ranAtMs) && Date.now() - ranAtMs <= QA_GATE_TTL_MS;
+    if (state?.lastResult?.passed === true &&
+        state.lastResult.fingerprint === fingerprint &&
+        freshEnough) {
         return null;
     }
     if (await hasPassedExternalQaEvidence(spec, projectPath)) {
         return null;
     }
     let effectiveResult = state?.lastResult ?? null;
-    if (effectiveResult === null) {
-        const { runQaGate } = await import('../../engine/qa-gate.js');
+    const canReuseLocalQa = effectiveResult !== null &&
+        effectiveResult.fingerprint === fingerprint &&
+        freshEnough &&
+        effectiveResult.passed;
+    if (!canReuseLocalQa) {
         effectiveResult = await runQaGate(spec, projectPath);
         await saveGateState(projectPath, specId, effectiveResult);
     }
+    if (effectiveResult === null) {
+        return null;
+    }
     if (effectiveResult.passed) {
         return null;
     }

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

@@ -349,10 +349,6 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
                         type: 'text',
                         text: `Readiness gate: spec has 0 acceptance criteria — cannot approve an empty spec.`,
                     },
-                    {
-                        type: 'text',
-                        text: '⚡ INTERACTIVE — call AskUserQuestion now with the interactiveQuestions from structuredContent',
-                    },
                 ],
                 structuredContent: {
                     interactiveQuestions: [question],
@@ -419,10 +415,6 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
                     type: 'text',
                     text: `Readiness gate: score ${String(score)}/100 — below 70 threshold. Warnings: ${warningsSummary}`,
                 },
-                {
-                    type: 'text',
-                    text: '⚡ INTERACTIVE — call AskUserQuestion now with the interactiveQuestions from structuredContent',
-                },
             ],
             structuredContent: {
                 interactiveQuestions: [question],

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

@@ -16,24 +16,33 @@ function isSafeCommand(cmd) {
 async function execGate(cmd, cwd, timeoutMs) {
     const [bin, ...args] = cmd.split(/\s+/);
     try {
-        const { stdout } = await execFile(bin ?? 'sh', args, {
+        const { stdout, stderr } = await execFile(bin ?? 'sh', args, {
             cwd,
             timeout: timeoutMs,
             maxBuffer: 4 * 1024 * 1024,
         });
-        return { output: stdout.trim(), ok: true, timedOut: false };
+        return { output: mergeCommandOutput(stdout, stderr), ok: true, timedOut: false };
     }
     catch (err) {
         const e = err;
-        const raw = Buffer.isBuffer(e.stdout)
-            ? e.stdout.toString('utf-8')
-            : typeof e.stdout === 'string'
-                ? e.stdout
-                : '';
+        const raw = mergeCommandOutput(e.stdout, e.stderr);
         const timedOut = e.killed === true || e.signal === 'SIGTERM' || e.code === 'ETIMEDOUT';
         return { output: raw.trim(), ok: false, timedOut, errorMessage: e.message };
     }
 }
+function mergeCommandOutput(stdout, stderr) {
+    const stdoutText = Buffer.isBuffer(stdout)
+        ? stdout.toString('utf-8')
+        : typeof stdout === 'string'
+            ? stdout
+            : '';
+    const stderrText = Buffer.isBuffer(stderr)
+        ? stderr.toString('utf-8')
+        : typeof stderr === 'string'
+            ? stderr
+            : '';
+    return [stdoutText.trim(), stderrText.trim()].filter((part) => part.length > 0).join('\n');
+}
 function countLintIssues(output) {
     // Handle eslint, tsc, and generic "N problem(s)" patterns
     const problemMatch = /(\d+)\s+problem/i.exec(output);

package/dist/tools/validate.js

@@ -326,13 +326,7 @@ export async function handleValidate(args, server) {
         if (outcome.mode === 'fallback') {
             return {
                 phaseEvent: createBasicPhaseEvent('validate', 'completed', 100, 'validating'),
-                content: [
-                    { type: 'text', text: compactText + graphText },
-                    {
-                        type: 'text',
-                        text: '⚡ INTERACTIVE — call AskUserQuestion now with the interactiveQuestions from structuredContent',
-                    },
-                ],
+                content: [{ type: 'text', text: compactText + graphText }],
                 structuredContent: {
                     ...structuredBase,
                     interactiveQuestions: outcome.interactiveQuestions,

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

@@ -14,9 +14,11 @@ export interface QaGateResult {
     checks: QaCheckResult[];
     ranAt: string;
     coverageThreshold: number | null;
+    fingerprint?: string;
 }
 export interface QaGateState {
     specId: string;
     lastResult: QaGateResult | null;
+    fingerprint?: string;
 }
 //# sourceMappingURL=qa-gate.d.ts.map

package/package.json

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