@planu/cli 5.3.44 → 5.3.45

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [5.3.45] - 2026-08-24
+
+### Bug Fixes
+- fix(spec-1278): derive coherent challenge pass semantics from unresolved critical findings
+- fix(spec-1326): prevent registry release language from activating web-auth challenge families
+
+### Chores
+- chore(planu): record SPEC-1278 done state and file SPEC-1597 dogfood spec
+
+
 ## [5.3.44] - 2026-08-24
 
 ### Bug Fixes

package/dist/engine/human-summary.d.ts

@@ -1,13 +1,18 @@
+import type { ChallengeGateStatus } from '../types/index.js';
 /** create_spec — plan was created successfully */
 export declare function buildCreateSpecSummary(title: string, devHours: number): string;
 /** update_status — status transition completed */
 export declare function buildUpdateStatusSummary(title: string, newStatus: string): string;
 /** check_readiness — readiness score evaluated */
 export declare function buildCheckReadinessSummary(score: number, blockerCount: number): string;
-/** challenge_spec — risks and scenarios identified */
-export declare function buildChallengeSpecSummary(topScenarios: {
+/**
+ * challenge_spec — risks and scenarios identified.
+ * Language is derived from the evidence-based gate state, never from overallRisk alone,
+ * so a blocked gate can never read as passed and a passed gate is never called coding-ready.
+ */
+export declare function buildChallengeSpecSummary(blockingScenarios: {
     scenario: string;
-}[], overallRisk: string): string;
+}[], gateStatus: ChallengeGateStatus, advisoryCount: number): string;
 /** validate — criteria checked against implementation */
 export declare function buildValidateSummary(passing: number, total: number): string;
 /** list_specs — specs listed for a project */

package/dist/engine/human-summary.js

@@ -38,19 +38,38 @@ export function buildCheckReadinessSummary(score, blockerCount) {
     }
     return `This plan scores ${String(score)}/100 and needs more detail before it can be approved. Check the recommendations and fill in the gaps.`;
 }
-/** challenge_spec — risks and scenarios identified */
-export function buildChallengeSpecSummary(topScenarios, overallRisk) {
-    const count = topScenarios.length;
-    if (count === 0) {
-        return `No critical issues found — this plan looks solid. Approve it when you're ready to build.`;
-    }
-    const noun = count === 1 ? 'thing' : 'things';
-    const items = topScenarios.map((s) => s.scenario);
-    const list = count <= 3
+/**
+ * challenge_spec — risks and scenarios identified.
+ * Language is derived from the evidence-based gate state, never from overallRisk alone,
+ * so a blocked gate can never read as passed and a passed gate is never called coding-ready.
+ */
+export function buildChallengeSpecSummary(blockingScenarios, gateStatus, advisoryCount) {
+    const list = describeBlockingScenarios(blockingScenarios);
+    if (gateStatus === 'blocked-critical') {
+        return `BLOCKED — ${String(blockingScenarios.length)} unresolved critical finding(s) must be resolved before this passes the challenge gate: ${list}. Record mitigation or accepted-risk evidence, then run challenge_spec again.`;
+    }
+    if (gateStatus === 'blocked-evidence' || gateStatus === 'refresh-required') {
+        if (gateStatus === 'refresh-required') {
+            return `BLOCKED — the stored report predates impact tracking and cannot rule out unresolved critical findings. Run challenge_spec again to refresh it.`;
+        }
+        return `${String(blockingScenarios.length)} thing(s) you must handle before coding: ${list}. Fix these, then run challenge_spec again to confirm.`;
+    }
+    if (gateStatus === 'passed-with-advisories') {
+        const advisoryNote = advisoryCount > 0
+            ? ` ${String(advisoryCount)} non-critical advisory finding(s) remain — review them, but they do not block this gate.`
+            : '';
+        return `Challenge gate threshold satisfied — this is not coding readiness.${advisoryNote} Run check_readiness for implementation readiness.`;
+    }
+    return `Every discovered finding is resolved and the challenge gate passed — this is not coding readiness by itself. Run check_readiness for implementation readiness.`;
+}
+function describeBlockingScenarios(scenarios) {
+    if (scenarios.length === 0) {
+        return 'no remaining blockers';
+    }
+    const items = scenarios.map((s) => s.scenario);
+    return scenarios.length <= 3
         ? items.join(', ')
-        : `${items.slice(0, 3).join(', ')}, and ${String(count - 3)} more`;
-    const urgency = overallRisk === 'critical' || overallRisk === 'high' ? ' before coding' : '';
-    return `${String(count)} ${noun} you must handle${urgency}: ${list}. Fix these, then run challenge_spec again to confirm.`;
+        : `${items.slice(0, 3).join(', ')}, and ${String(scenarios.length - 3)} more`;
 }
 /** validate — criteria checked against implementation */
 export function buildValidateSummary(passing, total) {

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

@@ -1,10 +1,21 @@
-import type { ChallengeReport, ChallengeResolutionEvidence, FailureScenario } from '../../types/index.js';
+import type { ChallengeFinding, ChallengeGateState, 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. */
+/**
+ * The single evidence-and-impact-derived authority for challenge gate state.
+ * Ignores caller-supplied addressedCount/resolved/passed — resolution comes only
+ * from evidence that exactly matches a currently discovered scenario identity.
+ */
+export declare function deriveChallengeGateState(input: {
+    findings: readonly ChallengeFinding[] | undefined;
+    resolutionEvidence: readonly ChallengeResolutionEvidence[] | undefined;
+    totalScenarios: number;
+    overallRisk: ChallengeReport['overallRisk'];
+}): ChallengeGateState;
+/** Build a report whose resolution and gate state are derived exclusively from explicit evidence. */
 export declare function buildChallengeReport(input: {
     scenarios: FailureScenario[];
     focusAreas: string[];

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

@@ -91,7 +91,67 @@ export function getResolvedChallengeEvidence(report) {
         .filter((scenario) => typeof scenario === 'string' && scenario.trim().length > 0));
     return uniqueMatchingEvidence(report.resolutionEvidence, scenarioNames);
 }
-/** Build a report whose resolution state is derived exclusively from explicit evidence. */
+function dedupeFindingsByIdentity(findings) {
+    const byIdentity = new Map();
+    for (const finding of findings) {
+        if (typeof finding.scenario === 'string' &&
+            finding.scenario.trim().length > 0 &&
+            !byIdentity.has(finding.scenario)) {
+            byIdentity.set(finding.scenario, finding);
+        }
+    }
+    return byIdentity;
+}
+/**
+ * The single evidence-and-impact-derived authority for challenge gate state.
+ * Ignores caller-supplied addressedCount/resolved/passed — resolution comes only
+ * from evidence that exactly matches a currently discovered scenario identity.
+ */
+export function deriveChallengeGateState(input) {
+    const identities = dedupeFindingsByIdentity(input.findings ?? []);
+    const scenarioNames = new Set(identities.keys());
+    const resolvedScenarios = new Set(uniqueMatchingEvidence(input.resolutionEvidence, scenarioNames).map((item) => item.scenario));
+    const requiredCount = requiredResolvedChallenges(scenarioNames.size);
+    const addressedCount = resolvedScenarios.size;
+    const unresolved = [...identities.values()].filter((finding) => !resolvedScenarios.has(finding.scenario));
+    const isAboveMediumRisk = input.overallRisk === 'high' || input.overallRisk === 'critical';
+    const hasUnknownImpact = unresolved.some((finding) => finding.impact === undefined);
+    if (isAboveMediumRisk && hasUnknownImpact && unresolved.length > 0) {
+        const unresolvedIdentities = unresolved.map((finding) => finding.scenario);
+        return {
+            addressedCount,
+            requiredCount,
+            unresolvedCount: unresolved.length,
+            unresolvedCriticalCount: 0,
+            unresolvedIdentities,
+            unresolvedCriticalIdentities: [],
+            unresolvedAdvisoryIdentities: unresolvedIdentities,
+            gateStatus: 'refresh-required',
+            passed: false,
+        };
+    }
+    const unresolvedCritical = unresolved.filter((finding) => finding.impact === 'critical');
+    const unresolvedAdvisory = unresolved.filter((finding) => finding.impact !== 'critical');
+    const gateStatus = unresolvedCritical.length > 0
+        ? 'blocked-critical'
+        : addressedCount < requiredCount
+            ? 'blocked-evidence'
+            : unresolved.length > 0
+                ? 'passed-with-advisories'
+                : 'passed-all-resolved';
+    return {
+        addressedCount,
+        requiredCount,
+        unresolvedCount: unresolved.length,
+        unresolvedCriticalCount: unresolvedCritical.length,
+        unresolvedIdentities: unresolved.map((finding) => finding.scenario),
+        unresolvedCriticalIdentities: unresolvedCritical.map((finding) => finding.scenario),
+        unresolvedAdvisoryIdentities: unresolvedAdvisory.map((finding) => finding.scenario),
+        gateStatus,
+        passed: gateStatus === 'passed-with-advisories' || gateStatus === 'passed-all-resolved',
+    };
+}
+/** Build a report whose resolution and gate state are derived exclusively from explicit evidence. */
 export function buildChallengeReport(input) {
     const scenarioNames = new Set(input.scenarios.map((scenario) => scenario.scenario));
     const resolutionEvidence = uniqueMatchingEvidence([
@@ -101,19 +161,29 @@ export function buildChallengeReport(input) {
         ...(Array.isArray(input.explicitResolutionEvidence) ? input.explicitResolutionEvidence : []),
     ], scenarioNames);
     const resolvedScenarios = new Set(resolutionEvidence.map((item) => item.scenario));
-    const addressedCount = resolvedScenarios.size;
-    const requiredCount = requiredResolvedChallenges(scenarioNames.size);
+    const findings = input.scenarios.map((scenario) => ({
+        scenario: scenario.scenario,
+        resolved: resolvedScenarios.has(scenario.scenario),
+        impact: scenario.impact,
+    }));
+    const gateState = deriveChallengeGateState({
+        findings,
+        resolutionEvidence,
+        totalScenarios: input.scenarios.length,
+        overallRisk: input.overallRisk,
+    });
     return {
         runAt: input.runAt ?? new Date().toISOString(),
         totalScenarios: input.scenarios.length,
-        addressedCount,
+        addressedCount: gateState.addressedCount,
+        requiredCount: gateState.requiredCount,
+        unresolvedCount: gateState.unresolvedCount,
+        unresolvedCriticalCount: gateState.unresolvedCriticalCount,
+        gateStatus: gateState.gateStatus,
         focusAreas: input.focusAreas,
         overallRisk: input.overallRisk,
-        passed: addressedCount >= requiredCount,
-        findings: input.scenarios.map((scenario) => ({
-            scenario: scenario.scenario,
-            resolved: resolvedScenarios.has(scenario.scenario),
-        })),
+        passed: gateState.passed,
+        findings,
         resolutionEvidence,
     };
 }

package/dist/tools/challenge-spec/scenarios-utils.js

@@ -1,5 +1,5 @@
 // tools/challenge-spec/scenarios-utils.ts — Shared utilities for scenario generators
-import { hasAnyAffirmedMatch, stripMetaAnalysisText, stripNonContractText, } from '../../engine/text-signal-boundaries.js';
+import { hasAffirmedMatch, hasAnyAffirmedMatch, stripMetaAnalysisText, stripNonContractText, } from '../../engine/text-signal-boundaries.js';
 const CAPABILITY_SIGNALS = {
     networkApi: [
         /(?<!compiler\s)\bapi\b(?!\s+(?:compatibility|surface|package|type))/i,
@@ -14,9 +14,7 @@ const CAPABILITY_SIGNALS = {
         /\b(?:database|persistence)\s+(?:query|schema|table|migration|transaction)\b/i,
         /\b(?:orm|prisma|drizzle|typeorm|sequelize)\b/i,
     ],
-    authentication: [
-        /\b(?:auth(?:entication|enticate)?|login|sign[ -]?in|password|jwt|oauth2?|session\s+auth)\b/i,
-    ],
+    authentication: [/\b(?:login|sign[ -]?in|password|jwt|oauth2?|session\s+auth)\b/i],
     authorization: [
         /\b(?:authori[sz]ation|permission|rbac|role-based|access\s+control|resource\s+ownership|tenant)\b/i,
     ],
@@ -92,6 +90,20 @@ const CAPABILITY_SIGNALS = {
         /\b(?:smart\s+contract|solidity|discord\s+bot|telegram\s+bot|iot\s+device|firmware|infrastructure\s+as\s+code|terraform|machine\s+learning\s+model)\b/i,
     ],
 };
+const AUTHENTICATION_BARE_TOKEN_RE = /\bauth(?:entication|enticate)?\b/i;
+// A bare "auth" token next to registry/package-manager vocabulary describes a
+// dependency-registry failure, not a product authentication contract, in either
+// word order ("npm registry authentication failure" / "auth failure in the package registry").
+// Deliberately narrow to registry/npm/package/dependency — generic security words like
+// "token" or "credential" stay affirmative so genuine CSRF/session-token prose is untouched.
+const REGISTRY_AUTH_CONTEXT_RE = /\b(?:registry|npm|npmjs|package|dependency)\b(?:\W+\w+){0,6}?\W+auth(?:entication|enticate)?\b|\bauth(?:entication|enticate)?\b(?:\W+\w+){0,6}?\W+(?:registry|npm|npmjs|package|dependency)\b/i;
+function hasProductAuthenticationEvidence(contract) {
+    if (hasAnyAffirmedMatch(contract, CAPABILITY_SIGNALS.authentication)) {
+        return true;
+    }
+    return (hasAffirmedMatch(contract, AUTHENTICATION_BARE_TOKEN_RE) &&
+        !REGISTRY_AUTH_CONTEXT_RE.test(contract));
+}
 function keywordPattern(keyword) {
     const escaped = keyword.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\s+/g, '\\s+');
     const suffix = /^[a-z0-9]+$/i.test(keyword) && keyword.length > 3 ? '[a-z0-9_-]*' : '';
@@ -122,10 +134,12 @@ export function detectChallengeCapabilities(spec, specContent) {
     const contractSource = stripReaderPrefix(spec, specContent);
     const source = contractSource.trim().length > 0 ? contractSource : spec.title;
     const contract = stripMetaAnalysisText(stripNonContractText(source));
-    return Object.fromEntries(Object.entries(CAPABILITY_SIGNALS).map(([capability, patterns]) => [
+    const capabilities = Object.fromEntries(Object.entries(CAPABILITY_SIGNALS).map(([capability, patterns]) => [
         capability,
         hasAnyAffirmedMatch(contract, patterns),
     ]));
+    capabilities.authentication = hasProductAuthenticationEvidence(contract);
+    return capabilities;
 }
 export function hasAnyChallengeCapability(capabilities, names) {
     return names.some((name) => capabilities[name]);

package/dist/tools/challenge-spec.js

@@ -19,7 +19,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, parseChallengeResolutionEvidence, } from './challenge-spec/challenge-report.js';
+import { buildChallengeReport, deriveChallengeGateState, parseChallengeResolutionEvidence, } from './challenge-spec/challenge-report.js';
 import { extractListItems, findMarkdownSectionRange, } from '../engine/spec-format/markdown-sections.js';
 import { extractSectionCriteria } from '../engine/spec-format/acceptance-criteria.js';
 const ALL_FOCUS_AREAS = [
@@ -262,9 +262,9 @@ export async function handleChallengeSpec(args, server) {
     const scalabilityAssessment = buildScalabilityAssessment(spec, knowledge, actionableFailureScenarios);
     // 8. Calculate overall risk from grounded scenarios only.
     const overallRisk = calculateOverallRisk(actionableFailureScenarios, concurrencyAnalysis);
-    // 9. Compute relevance scores and select top-3 (SPEC-338)
+    // 9. Compute relevance scores and select top-3 diagnostics (SPEC-338) — retained as-is
+    // regardless of gate state; blocker/advisory summaries are derived separately below.
     const prioritized = prioritizeScenarios(actionableFailureScenarios, spec);
-    const prioritizedSummary = buildPrioritizedSummary(prioritized);
     const failureScenariosScored = actionableFailureScenarios.map((s) => {
         const match = prioritized.find((p) => p.scenario === s.scenario);
         return match !== undefined ? { ...s, relevanceScore: match.relevanceScore } : s;
@@ -285,7 +285,20 @@ export async function handleChallengeSpec(args, server) {
         explicitResolutionEvidence,
         runAt: challengeRunAt,
     });
-    const rawHumanSummary = buildChallengeSpecSummary(prioritized, overallRisk);
+    const gateState = deriveChallengeGateState({
+        findings: challengeReport.findings,
+        resolutionEvidence: challengeReport.resolutionEvidence,
+        totalScenarios: challengeReport.totalScenarios,
+        overallRisk: challengeReport.overallRisk,
+    });
+    const scenarioByIdentity = new Map(failureScenariosScored.map((s) => [s.scenario, s]));
+    const { blocking: blockingIdentities, advisory: advisoryIdentities } = splitBlockingAndAdvisoryIdentities(gateState);
+    const blockingScenarios = blockingIdentities
+        .map((id) => scenarioByIdentity.get(id))
+        .filter((s) => s !== undefined);
+    const prioritizedBlocking = prioritizeScenarios(blockingScenarios, spec);
+    const prioritizedSummary = buildPrioritizedSummary(prioritizedBlocking);
+    const rawHumanSummary = buildChallengeSpecSummary(prioritizedBlocking, gateState.gateStatus, advisoryIdentities.length);
     // SPEC-620: Inject token budget tag into the LLM-facing summary prompt
     const specDevHours = spec.estimation.devHours;
     const challengeBudget = calculateTokenBudget(specDevHours > 0 ? specDevHours : 2, 'architecture');
@@ -303,19 +316,14 @@ export async function handleChallengeSpec(args, server) {
             suppressedLowRelevanceScenarios: suppressedScenarioCount + concurrencySuppressedCount,
             shownByDefault: 3,
             mustAddressBeforeCoding: prioritizedSummary,
+            remainingAdvisories: advisoryIdentities,
+            gateStatus: gateState.gateStatus,
             criticalImpact: actionableFailureScenarios.filter((s) => s.impact === 'critical').length,
             highImpact: actionableFailureScenarios.filter((s) => s.impact === 'high').length,
             raceConditions: concurrencyAnalysis.raceConditions.length,
             overallRisk,
             focusAreas: focusAreas,
-            warnings: overallRisk === 'critical' || overallRisk === 'high'
-                ? [
-                    `⚠️ HIGH RISK spec: overall risk is "${overallRisk}". Review all critical/high scenarios before implementation.`,
-                    overallRisk === 'critical'
-                        ? 'BLOCK: Resolve critical scenarios before merging to main branch.'
-                        : 'CAUTION: Add extra code review and integration tests for high-risk paths.',
-                ]
-                : [],
+            warnings: buildChallengeWarnings(overallRisk, gateState.unresolvedCriticalCount),
         },
         constitutionCompliance: constitution
             ? {
@@ -335,8 +343,8 @@ export async function handleChallengeSpec(args, server) {
     catch {
         // Best-effort: don't fail the challenge if persistence fails
     }
-    // SPEC-595: Elicit how user wants to apply suggestions when critical issues exist
-    const criticalCount = actionableFailureScenarios.filter((s) => s.impact === 'critical').length;
+    // SPEC-595: Elicit how user wants to apply suggestions when unresolved critical findings exist
+    const criticalCount = gateState.unresolvedCriticalCount;
     if (server !== undefined && criticalCount > 0) {
         const { field, property } = buildEnumSchema('apply', ['all', 'critical', 'none'], ['Apply all suggestions', 'Apply critical only (Recommended)', 'Review manually'], 'Apply suggestions', 'critical');
         const schema = { type: 'object', properties: { [field]: property } };
@@ -394,6 +402,47 @@ export async function handleChallengeSpec(args, server) {
         structuredContent: analysisPayload,
     };
 }
+/**
+ * Splits unresolved finding identities into blockers (critical, or non-critical
+ * findings still needed to reach the resolution threshold) and advisories (every
+ * other unresolved finding). Resolved findings never appear in either list.
+ */
+function splitBlockingAndAdvisoryIdentities(gateState) {
+    if (gateState.gateStatus === 'refresh-required') {
+        return { blocking: gateState.unresolvedIdentities, advisory: [] };
+    }
+    if (gateState.gateStatus === 'blocked-critical') {
+        const blockingSet = new Set(gateState.unresolvedCriticalIdentities);
+        return {
+            blocking: gateState.unresolvedCriticalIdentities,
+            advisory: gateState.unresolvedIdentities.filter((id) => !blockingSet.has(id)),
+        };
+    }
+    if (gateState.gateStatus === 'blocked-evidence') {
+        const neededCount = Math.max(gateState.requiredCount - gateState.addressedCount, 0);
+        const blocking = gateState.unresolvedIdentities.slice(0, neededCount);
+        const blockingSet = new Set(blocking);
+        return {
+            blocking,
+            advisory: gateState.unresolvedIdentities.filter((id) => !blockingSet.has(id)),
+        };
+    }
+    return { blocking: [], advisory: gateState.unresolvedIdentities };
+}
+/** Warnings never claim a blocked gate as passed and never fire on a resolved critical. */
+function buildChallengeWarnings(overallRisk, unresolvedCriticalCount) {
+    const warnings = [];
+    if (overallRisk === 'critical' || overallRisk === 'high') {
+        warnings.push(`⚠️ HIGH RISK spec: overall risk is "${overallRisk}". Review all critical/high scenarios before implementation.`);
+    }
+    if (unresolvedCriticalCount > 0) {
+        warnings.push('BLOCK: Resolve critical scenarios before merging to main branch.');
+    }
+    else if (overallRisk === 'high') {
+        warnings.push('CAUTION: Add extra code review and integration tests for high-risk paths.');
+    }
+    return warnings;
+}
 function isScenarioSupportedByCapabilities(scenario, capabilities) {
     const haystack = `${scenario.scenario} ${scenario.currentHandling} ${scenario.requiredHandling}`
         .toLowerCase()

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, STRUCTURAL_INTERPOLATION_KIND, } from '../../engine/spec-quality/generic-output-gate.js';
 import { formatKeyValue } from '../output-formatter.js';
-import { getResolvedChallengeEvidence, requiredResolvedChallenges, } from '../challenge-spec/challenge-report.js';
+import { deriveChallengeGateState } from '../challenge-spec/challenge-report.js';
 import { evaluateSpecDependencies } from '../../engine/dependency-evaluator.js';
 import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
 /**
@@ -556,9 +556,49 @@ export function checkChallengeGate(spec, newStatus) {
             },
         };
     }
-    const resolutionEvidence = getResolvedChallengeEvidence(report);
-    const addressedCount = resolutionEvidence.length;
-    const requiredCount = requiredResolvedChallenges(new Set(report.findings.map((finding) => finding.scenario)).size);
+    const gateState = deriveChallengeGateState({
+        findings: report.findings,
+        resolutionEvidence: report.resolutionEvidence,
+        totalScenarios: report.totalScenarios,
+        overallRisk: report.overallRisk,
+    });
+    const { addressedCount, requiredCount, unresolvedCount, unresolvedCriticalCount } = gateState;
+    if (gateState.gateStatus === 'refresh-required') {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Challenge gate blocked: the stored ${report.overallRisk}-risk report has unresolved findings without persisted impact classification, so unresolved critical findings cannot be ruled out. Run challenge_spec(specId="${spec.id}") to regenerate it before transitioning to review.`,
+                },
+            ],
+            isError: true,
+            structuredContent: {
+                error: 'CHALLENGE_GATE_BLOCKED',
+                code: 'CHALLENGE_REPORT_REFRESH_REQUIRED',
+                fixHint: `Run challenge_spec(specId="${spec.id}") to regenerate the report with impact metadata, then retry update_status(specId="${spec.id}", status="review").`,
+            },
+        };
+    }
+    if (unresolvedCriticalCount > 0) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Challenge gate blocked: ${String(unresolvedCriticalCount)} unresolved critical finding(s) remain (addressed ${String(addressedCount)}/${String(requiredCount)} required). Record mitigation or accepted-risk evidence for every critical finding before retrying.`,
+                },
+            ],
+            isError: true,
+            structuredContent: {
+                error: 'CHALLENGE_GATE_BLOCKED',
+                code: 'UNRESOLVED_CRITICAL_CHALLENGES',
+                addressedCount,
+                requiredCount,
+                unresolvedCount,
+                unresolvedCriticalCount,
+                fixHint: `Resolve every critical challenge_spec finding with concrete evidence, then retry update_status(specId="${spec.id}", status="review").`,
+            },
+        };
+    }
     if (addressedCount < requiredCount) {
         return {
             content: [

package/dist/types/spec/core.d.ts

@@ -4,6 +4,7 @@ import type { SpecFormatVersion, SpecHistoryEntry } from './versioning.js';
 import type { Estimation, Actuals, ImpactAnalysis } from '../estimation.js';
 import type { ConstitutionViolation } from '../project/core.js';
 import type { AgentTeamPlan } from '../agent-team.js';
+import type { FailureScenario } from '../analysis.js';
 /** A single entry in the status transition history of a spec. */
 export interface StatusHistoryEntry {
     readonly status: SpecStatus;
@@ -157,12 +158,36 @@ export interface ChallengeReport {
     findings?: ChallengeFinding[];
     /** Explicit mitigation or risk-acceptance evidence for resolved findings. */
     resolutionEvidence?: ChallengeResolutionEvidence[];
+    /** Minimum unique resolution evidence required to satisfy the gate. */
+    requiredCount?: number;
+    /** Distinct findings without matching resolution evidence. */
+    unresolvedCount?: number;
+    /** Unresolved findings whose persisted impact is critical. */
+    unresolvedCriticalCount?: number;
+    /** Machine-readable explanation of why the challenge gate passed or failed. */
+    gateStatus?: ChallengeGateStatus;
 }
 export interface ChallengeFinding {
     /** Exact scenario text emitted by challenge_spec. */
     scenario: string;
     /** Derived from matching explicit resolution evidence; discovery alone is never resolution. */
     resolved: boolean;
+    /** Impact classification generated with the scenario; persisted so the lifecycle gate can recompute gate state without regenerating scenarios. */
+    impact?: FailureScenario['impact'];
+}
+/** Outcome of deriveChallengeGateState(): why the challenge gate passed or failed. */
+export type ChallengeGateStatus = 'blocked-evidence' | 'blocked-critical' | 'refresh-required' | 'passed-with-advisories' | 'passed-all-resolved';
+/** Evidence-and-impact-derived gate state shared by report construction and the transition guard. */
+export interface ChallengeGateState {
+    addressedCount: number;
+    requiredCount: number;
+    unresolvedCount: number;
+    unresolvedCriticalCount: number;
+    unresolvedIdentities: string[];
+    unresolvedCriticalIdentities: string[];
+    unresolvedAdvisoryIdentities: string[];
+    gateStatus: ChallengeGateStatus;
+    passed: boolean;
 }
 export interface ChallengeResolutionEvidence {
     /** Exact scenario text being resolved. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "5.3.44",
+  "version": "5.3.45",
   "description": "Planu — MCP Server for Spec Driven Development. Cross-platform (Linux/macOS/Windows, x64/arm64).",
   "type": "module",
   "main": "dist/index.js",

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": "5.3.44",
+  "version": "5.3.45",
   "icon": "assets/plugin/icon.svg",
   "command": ["npx", "@planu/cli@latest"],
   "packageName": "@planu/cli",