@planu/cli 5.3.43 → 5.3.45

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+## [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
+- fix(spec-1596): align check-readiness validator test double with getSpecFresh
+- fix(spec-1594): gate example-only PII identifiers behind boundary-aware collection cue
+- fix(spec-1593): gate suppress-family verbs so no-op consequence criteria are not misflagged
+- fix(spec-1595): make strict readiness report reflect edited spec body content
+
+
 ## [5.3.43] - 2026-08-24
 
 ### Bug Fixes

package/dist/config/pii-patterns.json

@@ -170,6 +170,37 @@
     "Tenant",
     "Visitor"
   ],
+  "collectionCueVerbs": [
+    "collect",
+    "store",
+    "process",
+    "persist",
+    "save",
+    "record",
+    "provide",
+    "must have",
+    "includ",
+    "contain",
+    "track",
+    "log",
+    "updat",
+    "requir",
+    "verif",
+    "authenticat",
+    "scan"
+  ],
+  "provenance": {
+    "nonAffirmingSectionKeywords": [
+      "example",
+      "examples",
+      "reproducer",
+      "test fixture",
+      "test fixtures",
+      "vocabulary",
+      "out of scope",
+      "out-of-scope"
+    ]
+  },
   "frameworks": {
     "GDPR": {
       "defaultRetentionDays": 730,

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/engine/pii-detector/core.js

@@ -59,8 +59,49 @@ function isWhitelistedContext(modelContext) {
 function hasFieldCue(contextWindow) {
     return /\b(field|fields|column|columns|property|properties|attribute|schema|model|entity|table|class|interface)\b/i.test(contextWindow);
 }
+const COLLECTION_CUE_SUFFIXES = '(?:e|es|ed|ing|ion|ies|ied|ying|y|s)?';
+function escapeRegexLiteral(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function toCollectionCueBase(verb) {
+    return verb.endsWith('e') ? verb.slice(0, -1) : verb;
+}
+function buildCollectionCueRegex(verbs) {
+    const alternatives = verbs.flatMap((verb) => {
+        if (verb.includes(' ')) {
+            return [escapeRegexLiteral(verb)];
+        }
+        const base = toCollectionCueBase(verb);
+        const alts = [escapeRegexLiteral(base) + COLLECTION_CUE_SUFFIXES];
+        if (base === verb) {
+            const lastChar = base.slice(-1);
+            alts.push(escapeRegexLiteral(base + lastChar) + '(?:ed|ing)');
+        }
+        return alts;
+    });
+    return new RegExp(`\\b(?:${alternatives.join('|')})\\b`, 'i');
+}
+const collectionCueRegex = buildCollectionCueRegex(patterns.collectionCueVerbs);
 function hasCollectionCue(contextWindow) {
-    return /\b(collect|store|process|persist|save|record|provide|must have|includes?|contains?)\b/i.test(contextWindow);
+    return collectionCueRegex.test(contextWindow);
+}
+const HEADING_LINE_RE = /^#{1,6}\s+.+$/gm;
+function isNonAffirmingSection(text, index) {
+    const keywords = patterns.provenance?.nonAffirmingSectionKeywords ?? [];
+    if (keywords.length === 0) {
+        return false;
+    }
+    HEADING_LINE_RE.lastIndex = 0;
+    let lastHeading = '';
+    let match;
+    while ((match = HEADING_LINE_RE.exec(text)) !== null) {
+        if (match.index > index) {
+            break;
+        }
+        lastHeading = match[0];
+    }
+    const lowerHeading = lastHeading.toLowerCase();
+    return keywords.some((keyword) => lowerHeading.includes(keyword.toLowerCase()));
 }
 /**
  * Determines if a detected PII field is a GDPR Art. 9 special category.
@@ -121,9 +162,11 @@ function extractCandidates(text) {
         const wordIndex = lower.indexOf(word.toLowerCase());
         const contextWindow = cleaned.substring(Math.max(0, wordIndex - 100), wordIndex + 100);
         const context = inferModelContext(contextWindow);
-        if (isWhitelistedContext(context) ||
-            (hasFieldCue(contextWindow) && !isBlacklistedContext(contextWindow)) ||
-            (hasCollectionCue(contextWindow) && isWhitelistedContext(contextWindow))) {
+        const isBoundToCollection = hasCollectionCue(contextWindow) && !isNonAffirmingSection(cleaned, wordIndex);
+        if (isBoundToCollection &&
+            (isWhitelistedContext(context) ||
+                (hasFieldCue(contextWindow) && !isBlacklistedContext(contextWindow)) ||
+                (hasCollectionCue(contextWindow) && isWhitelistedContext(contextWindow)))) {
             candidates.push({ field: word, context });
         }
     }

package/dist/engine/readiness-checker.js

@@ -86,12 +86,24 @@ export function extractCriteriaLines(huContent) {
     const lines = huContent.split('\n');
     const criteria = [];
     let inCriteriaSection = false;
+    let criteriaHeadingLevel = 0;
     for (const raw of lines) {
         const line = raw.trim();
-        // Detect entering / leaving an Acceptance Criteria section
-        if (/^#{1,6}\s+/.test(line)) {
-            inCriteriaSection =
-                /^#{1,6}\s+(acceptance\s+criteria|criteria|criterios\s+de\s+aceptaci[oó]n|criterios)\b/i.test(line);
+        // Detect entering / leaving an Acceptance Criteria section. A heading
+        // deeper than the criteria heading (e.g. `### Scenario` nested under
+        // `## Acceptance Criteria`) stays inside the section — only a heading
+        // at the same or shallower level closes it.
+        const headingMatch = /^(#{1,6})\s+/.exec(line);
+        if (headingMatch?.[1] !== undefined) {
+            const level = headingMatch[1].length;
+            const isCriteriaHeading = /^#{1,6}\s+(acceptance\s+criteria|criteria|criterios\s+de\s+aceptaci[oó]n|criterios)\b/i.test(line);
+            if (isCriteriaHeading) {
+                inCriteriaSection = true;
+                criteriaHeadingLevel = level;
+            }
+            else if (level <= criteriaHeadingLevel) {
+                inCriteriaSection = false;
+            }
             continue;
         }
         // Form 1 — checkbox (always counts, regardless of section)
@@ -349,10 +361,12 @@ function checkSpecificityGate(spec, criteriaLines, fichaContent, anticipatedTest
     if (!hasFunctionName && !hasTypeName) {
         blockers.push(`Difficulty ${String(spec.difficulty)} spec requires at least 1 criterion with an exact function name (e.g. createFoo()) or type name (e.g. FooBar).`);
     }
-    // Detect anticipated test breaks: a test file path + "line N" (with optional ~) or "change ... from ... to"
+    const anticipatedTestBreaksHasTestPathWithNumber = /\d/.test(anticipatedTestBreaksContent) &&
+        [...extractFilePaths(anticipatedTestBreaksContent)].some((path) => /\.test\.[a-z0-9]+$/i.test(path));
     const hasTestBreak = /\btests?\/[a-zA-Z0-9/_.-]+\.test\.[a-z]+.*\bline\s+~?\d+/i.test(allText) ||
-        /\bchange\b.*\bfrom\b.*\bto\b/i.test(allText) ||
-        /\btests\/[a-zA-Z0-9/_.-]+\.test\.[a-z0-9]+(?![a-zA-Z0-9_.\\/-])[^\n]*\bline\s+~?\d+/i.test(anticipatedTestBreaksContent);
+        /\bchanges?\b.*\bfrom\b.*\bto\b/i.test(allText) ||
+        /\btests\/[a-zA-Z0-9/_.-]+\.test\.[a-z0-9]+(?![a-zA-Z0-9_.\\/-])[^\n]*\bline\s+~?\d+/i.test(anticipatedTestBreaksContent) ||
+        anticipatedTestBreaksHasTestPathWithNumber;
     if (!hasTestBreak) {
         blockers.push(`Difficulty ${String(spec.difficulty)} spec requires at least 1 anticipated test break ` +
             `(e.g. 'tests/api/foo.test.ts line 47: change count from 477 to 478').`);

package/dist/engine/scope-boundaries/contradiction-checker.js

@@ -100,7 +100,7 @@ function splitClauses(text) {
         .map((clause) => clause.trim())
         .filter(Boolean);
 }
-const AFFIRMATIVE_ACTION_VERBS = /\b(?:build(?:s|ing)?|chang(?:e|es|ing)|modif(?:y|ies|ying)|alter(?:s|ing)?|add(?:s|ing)?|introduc(?:e|es|ing)|implement(?:s|ing)?|enabl(?:e|es|ing)|expos(?:e|es|ing|ed)|mutat(?:e|es|ing)|rewrit(?:e|es|ing|ten)|remov(?:e|es|ing|ed)|relax(?:es|ing|ed)?|forc(?:e|es|ing))\b/;
+const AFFIRMATIVE_ACTION_VERBS = /\b(?:build(?:s|ing)?|chang(?:e|es|ing)|modif(?:y|ies|ying)|alter(?:s|ing)?|add(?:s|ing)?|introduc(?:e|es|ing)|implement(?:s|ing)?|enabl(?:e|es|ing)|expos(?:e|es|ing|ed)|mutat(?:e|es|ing)|rewrit(?:e|es|ing|ten)|remov(?:e|es|ing|ed)|relax(?:es|ing|ed)?|forc(?:e|es|ing)|suppress(?:es|ing|ed)?)\b/;
 function assertsForbiddenAction(text) {
     return AFFIRMATIVE_ACTION_VERBS.test(normalize(text));
 }

package/dist/engine/spec-quality-scorer.js

@@ -1,6 +1,6 @@
 // engine/spec-quality-scorer.ts — Spec quality scoring logic (SPEC-314)
 import { readFile } from 'node:fs/promises';
-import { readSpecTechnicalSection } from './spec-format/read-technical-section.js';
+import { extractSectionBody, readSpecTechnicalSection, } from './spec-format/read-technical-section.js';
 import { extractAcceptanceCriteriaTexts } from './spec-format/acceptance-criteria.js';
 import { stripFrontmatter } from './frontmatter-parser.js';
 // ── Constants ────────────────────────────────────────────────────────────────
@@ -327,7 +327,7 @@ function scoreAmbiguity(content, criteriaLines) {
         recommendations,
     };
 }
-function scoreRisk(spec, technicalContent) {
+function scoreRisk(spec, technicalContent, specBody) {
     const issues = [];
     const recommendations = [];
     let score = MAX_DIMENSION_SCORE;
@@ -364,8 +364,11 @@ function scoreRisk(spec, technicalContent) {
             'throughput',
             'sla',
             'nfr',
+            'non-functional',
         ];
-        const hasNfrs = nfrKeywords.some((k) => lowerTech.includes(k));
+        const hasNfrKeyword = nfrKeywords.some((k) => lowerTech.includes(k));
+        const hasNfrSubsection = extractSectionBody(specBody, 'Non-Functional Requirements').trim().length > 0;
+        const hasNfrs = hasNfrKeyword || hasNfrSubsection;
         if (!hasNfrs) {
             score -= 5;
             issues.push('No non-functional requirements found in technical spec');
@@ -401,7 +404,7 @@ export async function scoreSpecQuality(spec) {
     const completenessDetail = scoreCompleteness(spec, specContent);
     const testabilityDetail = scoreTestability(criteriaLines);
     const ambiguityDetail = scoreAmbiguity(specContent, criteriaLines);
-    const riskDetail = scoreRisk(spec, technicalContent);
+    const riskDetail = scoreRisk(spec, technicalContent, specContent);
     const total = completenessDetail.score + testabilityDetail.score + ambiguityDetail.score + riskDetail.score;
     const qualityScore = {
         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/check-readiness.js

@@ -1,8 +1,36 @@
 // tools/check-readiness.ts — Completeness checkpoint tool (SPEC-039, SPEC-314, SPEC-716)
+import { readFile } from 'node:fs/promises';
 import { specStore } from '../storage/index.js';
 import { buildCheckReadinessSummary } from '../engine/human-summary.js';
 import { validateSpecFormat } from '../core/spec-validator.js';
+import { parseFrontmatter } from '../engine/frontmatter-parser.js';
 import { resolveProjectId } from './resolve-project-id.js';
+const VALID_DIFFICULTIES = [1, 2, 3, 4, 5];
+const VALID_SCOPES = ['trivial', 'feature', 'cross-module', 'architectural'];
+function asDifficulty(value) {
+    return VALID_DIFFICULTIES.find((candidate) => candidate === value);
+}
+function asSpecScope(value) {
+    return VALID_SCOPES.find((candidate) => candidate === value);
+}
+/**
+ * Re-derive difficulty/scope from the freshly-read spec.md frontmatter so the
+ * readiness gate honors on-disk edits instead of the specs.json snapshot that
+ * `specStore` caches in memory.
+ */
+async function readFreshDifficultyAndScope(specPath) {
+    try {
+        const raw = await readFile(specPath, 'utf-8');
+        const { metadata } = parseFrontmatter(raw);
+        return {
+            difficulty: asDifficulty(metadata.difficulty),
+            scope: asSpecScope(metadata.scope),
+        };
+    }
+    catch {
+        return {};
+    }
+}
 // ── Formatting helpers ───────────────────────────────────────────────────────
 const MAX_VISIBLE_BLOCKERS = 8;
 const MAX_VISIBLE_WARNINGS = 8;
@@ -120,7 +148,7 @@ export async function handleCheckReadiness(args) {
         };
     }
     const { specId, mode = 'strict' } = args;
-    const spec = await specStore.getSpec(projectId, specId);
+    const spec = await specStore.getSpecFresh(projectId, specId);
     if (!spec) {
         return {
             content: [
@@ -132,9 +160,15 @@ export async function handleCheckReadiness(args) {
             isError: true,
         };
     }
+    const fresh = spec.specPath ? await readFreshDifficultyAndScope(spec.specPath) : {};
+    const effectiveSpec = {
+        ...spec,
+        difficulty: fresh.difficulty ?? spec.difficulty,
+        scope: fresh.scope ?? spec.scope,
+    };
     // validateSpecFormat owns the readiness and quality evaluation so the response
     // cannot combine separately computed evidence from different reads of spec.md.
-    const validationResult = await validateSpecFormat(spec, { readinessMode: mode });
+    const validationResult = await validateSpecFormat(effectiveSpec, { readinessMode: mode });
     // SPEC-716: Ground ready flag in unified SpecValidationResult.
     // Only non-file-access errors from validateSpecFormat are surfaced in the
     // report — MISSING_FRONTMATTER due to file-not-found is best-effort since

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

@@ -119,6 +119,13 @@ export interface PiiFrameworkConfig {
     dataPortability: boolean;
     regions: string[];
 }
+/**
+ * Provenance guards that keep PII detection anchored to affirmative,
+ * data-collecting spec content rather than example enumerations.
+ */
+export interface PiiProvenanceConfig {
+    nonAffirmingSectionKeywords: string[];
+}
 /**
  * Full structure of pii-patterns.json.
  */
@@ -126,8 +133,10 @@ export interface PiiPatterns {
     vocabulary: Record<string, string[]>;
     modelContextBlacklist: string[];
     modelContextWhitelist: string[];
+    collectionCueVerbs: string[];
     frameworks: Record<string, PiiFrameworkConfig>;
     thirdPartySignatures: Record<string, string[]>;
+    provenance?: PiiProvenanceConfig;
 }
 /**
  * Input for the data_governance MCP tool.

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