@planu/cli 5.7.5 → 5.7.6

package/dist/engine/host-tool-filter.js

@@ -7,63 +7,34 @@ import { fileURLToPath } from 'node:url';
 // Core AGENTS.md tool reference — curated list of key Planu tools
 // ---------------------------------------------------------------------------
 export const CORE_AGENTS_MD_TOOLS = [
+    { name: 'init_project', description: 'Load or bootstrap Planu project context' },
+    { name: 'facilitate', description: 'Universal entry point for SDD workflow' },
     { name: 'create_spec', description: 'Create a new spec from a description' },
     { name: 'list_specs', description: 'List all specs and their status' },
     { name: 'update_status', description: 'Move a spec through workflow stages' },
+    {
+        name: 'update_status_batch',
+        description: 'Batch update many specs to the same status in one MCP execution',
+    },
     { name: 'validate', description: 'Check implementation against spec criteria' },
     { name: 'challenge_spec', description: 'Stress-test a spec for gaps before implementation' },
     { name: 'check_readiness', description: 'Verify spec has enough detail to implement' },
-    { name: 'planu_status', description: 'Quick project health snapshot' },
-    { name: 'facilitate', description: 'Universal entry point for SDD workflow' },
-    { name: 'plan_mode', description: 'Preview implementation plan before writing code' },
-    { name: 'generate_steering_file', description: 'Generate host-aware steering files' },
-    { name: 'search_specs', description: 'Search specs with fuzzy text matching' },
-    { name: 'spec_quality_score', description: 'Compute quality score for a spec' },
-    { name: 'analyze_spec_size', description: 'Analyze if a spec should be split' },
-    { name: 'decompose_spec', description: 'Decompose a spec into agent tasks' },
-    { name: 'estimate', description: 'Estimate time and cost for a spec' },
-    { name: 'session_checkpoint', description: 'Save session context' },
-    { name: 'project_overview', description: 'Single-call project state query' },
-    { name: 'scan_project', description: 'Scan project and generate specs' },
-    { name: 'validate_workflow', description: 'Validate a workflow definition' },
-    { name: 'tdd_scaffold', description: 'Generate TDD test stubs from spec criteria' },
-    { name: 'coverage_gap_analyzer', description: 'Analyze untested acceptance criteria' },
-    { name: 'security_scan', description: 'Scan dependencies for vulnerabilities' },
-    { name: 'bootstrap_skills', description: 'Auto-install skills for detected stack' },
-    { name: 'manage_drift', description: 'Detect and resolve spec drift' },
-    { name: 'sync_spec_state', description: 'Sync spec status between frontmatter and store' },
-    { name: 'health_check_all', description: 'Run health check on all specs' },
-    { name: 'tokens', description: 'Token usage dashboard' },
-    { name: 'configure_workers', description: 'Configure background analysis workers' },
     {
-        name: 'approve_spec',
-        description: 'Record that a reviewer has approved a spec — requires reviewer token',
+        name: 'bump_spec_version',
+        description: "Bump the SemVer spec_version of a spec's frontmatter",
+    },
+    { name: 'reconcile_spec', description: 'Reconcile implementation drift back into the spec' },
+    {
+        name: 'migrate_legacy_spec',
+        description: 'Persist a synthesized spec.md and retire legacy files',
     },
-    { name: 'lock_spec', description: 'Acquire exclusive lock on a spec' },
-    { name: 'register_api_surface', description: 'Register API surfaces exposed by a spec' },
-    { name: 'analyze_breaking_changes', description: 'Analyze specs impacted by API changes' },
-    { name: 'track_tech_debt', description: 'Track a new tech debt item' },
-    { name: 'capture_idea', description: 'Capture a lightweight idea' },
-    { name: 'log_lesson', description: 'Log a lesson learned' },
-    { name: 'semantic_search', description: 'Search project knowledge by meaning' },
-    { name: 'render_spec_for_provider', description: 'Render spec for target LLM provider' },
-    { name: 'convert_to_bdd', description: 'Convert spec criteria to BDD format' },
-    { name: 'generate_e2e_tests', description: 'Generate E2E tests from spec criteria' },
-    { name: 'run_spec_lint', description: 'Run custom lint rules against specs' },
-    { name: 'suggest_criteria', description: 'Suggest missing best-practice criteria' },
-    { name: 'check_compliance', description: 'Unified compliance tool' },
-    { name: 'create_release', description: 'Create a GitHub Release' },
-    { name: 'generate_changelog', description: 'Generate changelog from merged PRs' },
-    { name: 'create_pr_from_spec', description: 'Create a PR from a spec' },
-    { name: 'onboarding_progress', description: 'View onboarding progress' },
-    { name: 'list_templates', description: 'Browse spec template catalog' },
-    { name: 'generate_docs_site', description: 'Generate static HTML docs site' },
-    { name: 'plan_team_distribution', description: 'Distribute specs across agents' },
-    { name: 'optimize_spec_scheduling', description: 'Minimize agent idle time' },
-    { name: 'context_window_status', description: 'Estimate token consumption' },
-    { name: 'archive_spec_context', description: 'Archive a spec to free tokens' },
-    { name: 'workspace_overview', description: 'Get overview of all projects' },
-    { name: 'search_all_projects', description: 'Search specs across all projects' },
+    { name: 'package_handoff', description: 'Generate an implementation handoff package for a spec' },
+    { name: 'planu_status', description: 'Quick project health snapshot' },
+    { name: 'session_checkpoint', description: 'Save session context' },
+    { name: 'estimate', description: 'Estimate time and cost for a spec' },
+    { name: 'request_changes', description: 'Request changes on a spec, moving it back to draft' },
+    { name: 'get_job', description: 'Read the durable state of a local Planu job' },
+    { name: 'restart_job', description: 'Restart a cancelled or failed durable job' },
 ];
 // ---------------------------------------------------------------------------
 // Interactive detection heuristics

package/dist/engine/human-summary.js

@@ -89,20 +89,31 @@ export function buildListSpecsSummary(total, byStatus) {
         return `No plans found in this project yet. Use create_spec to add your first one.`;
     }
     const get = (key) => byStatus[key] ?? 0;
-    const inProgress = get('implementing') + get('approved');
+    const inProgress = get('implementing');
+    const approved = get('approved');
     const inReview = get('review');
+    const approvedClause = approved > 0 ? `${String(approved)} approved ready to implement` : '';
     if (inReview > 0 && inProgress > 0) {
         const reviewNoun = inReview === 1 ? 'plan' : 'plans';
-        return `You have ${String(inProgress)} in progress and ${String(inReview)} ${reviewNoun} ready to review. Start with the ones under review.`;
+        const suffix = approvedClause ? ` and ${approvedClause}` : '';
+        return `You have ${String(inProgress)} in progress and ${String(inReview)} ${reviewNoun} ready to review${suffix}. Start with the ones under review.`;
     }
     if (inReview > 0) {
         const noun = inReview === 1 ? 'plan' : 'plans';
-        return `You have ${String(inReview)} ${noun} ready to review. Approve or request changes to move forward.`;
+        const suffix = approvedClause ? ` You also have ${approvedClause}.` : '';
+        return `You have ${String(inReview)} ${noun} ready to review. Approve or request changes to move forward.${suffix}`;
+    }
+    if (inProgress > 0 && approved > 0) {
+        return `You have ${String(inProgress)} in progress and ${approvedClause}. Run validate when implementation is done.`;
     }
     if (inProgress > 0) {
         const noun = inProgress === 1 ? 'plan' : 'plans';
         return `You have ${String(inProgress)} ${noun} in progress. Run validate when implementation is done.`;
     }
+    if (approved > 0) {
+        const noun = approved === 1 ? 'plan' : 'plans';
+        return `You have ${String(approved)} ${noun} approved ready to implement. Run validate when implementation is done.`;
+    }
     return `You have ${String(total)} plans in this project. Approve a plan to start implementing.`;
 }
 /** estimate — time and cost estimated for a spec */

package/dist/engine/implementation-contract/common.d.ts

@@ -1,6 +1,6 @@
 export declare const IMPLEMENTATION_CONTRACT_SECTION = "Implementation Contract";
 /** Subsections every rendered contract must include — omitting one is a defect. */
-export declare const IMPLEMENTATION_CONTRACT_REQUIRED_SUBSECTIONS: readonly ['User Outcome', 'File-Level Work Plan', 'Acceptance-To-Verification Map', 'Verification Commands'];
+export declare const IMPLEMENTATION_CONTRACT_REQUIRED_SUBSECTIONS: readonly ['User Outcome'];
 /**
  * SPEC-1406: subsections that carry no grounded content are omitted from the rendered
  * body rather than filled with restated-criterion filler. Their absence is not an
@@ -8,10 +8,15 @@ export declare const IMPLEMENTATION_CONTRACT_REQUIRED_SUBSECTIONS: readonly ['Us
  * already-persisted specs that still carry these sections (with real, non-empty
  * content) transitionable: `evaluateImplementationContract` only requires them when
  * the rendered body chose to include the heading.
+ *
+ * SPEC-1435: extends the same omission precedent to File-Level Work Plan,
+ * Acceptance-To-Verification Map, and Verification Commands — the renderer used to
+ * fill these with a constant "no evidence was grounded" sentence that its own quality
+ * gates could not see. Now the renderer omits the subsection instead.
  */
-export declare const IMPLEMENTATION_CONTRACT_OPTIONAL_SUBSECTIONS: readonly ['Behavior Contract', 'Edge Cases And Failure Modes', 'Non-Goals And Forbidden Approaches'];
+export declare const IMPLEMENTATION_CONTRACT_OPTIONAL_SUBSECTIONS: readonly ['Behavior Contract', 'Edge Cases And Failure Modes', 'Non-Goals And Forbidden Approaches', 'File-Level Work Plan', 'Acceptance-To-Verification Map', 'Verification Commands'];
 /** Union of required + optional subsections. Kept for callers that only need the full set. */
-export declare const IMPLEMENTATION_CONTRACT_SUBSECTIONS: readonly ["User Outcome", "File-Level Work Plan", "Acceptance-To-Verification Map", "Verification Commands", "Behavior Contract", "Edge Cases And Failure Modes", "Non-Goals And Forbidden Approaches"];
+export declare const IMPLEMENTATION_CONTRACT_SUBSECTIONS: readonly ["User Outcome", "Behavior Contract", "Edge Cases And Failure Modes", "Non-Goals And Forbidden Approaches", "File-Level Work Plan", "Acceptance-To-Verification Map", "Verification Commands"];
 export declare function hasImplementationContract(specBody: string): boolean;
 export declare function extractTopLevelSection(body: string, sectionName: string): string;
 //# sourceMappingURL=common.d.ts.map

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

@@ -1,12 +1,7 @@
 import { escapeRegex } from '../../core/shared/strings.js';
 export const IMPLEMENTATION_CONTRACT_SECTION = 'Implementation Contract';
 /** Subsections every rendered contract must include — omitting one is a defect. */
-export const IMPLEMENTATION_CONTRACT_REQUIRED_SUBSECTIONS = [
-    'User Outcome',
-    'File-Level Work Plan',
-    'Acceptance-To-Verification Map',
-    'Verification Commands',
-];
+export const IMPLEMENTATION_CONTRACT_REQUIRED_SUBSECTIONS = ['User Outcome'];
 /**
  * SPEC-1406: subsections that carry no grounded content are omitted from the rendered
  * body rather than filled with restated-criterion filler. Their absence is not an
@@ -14,11 +9,19 @@ export const IMPLEMENTATION_CONTRACT_REQUIRED_SUBSECTIONS = [
  * already-persisted specs that still carry these sections (with real, non-empty
  * content) transitionable: `evaluateImplementationContract` only requires them when
  * the rendered body chose to include the heading.
+ *
+ * SPEC-1435: extends the same omission precedent to File-Level Work Plan,
+ * Acceptance-To-Verification Map, and Verification Commands — the renderer used to
+ * fill these with a constant "no evidence was grounded" sentence that its own quality
+ * gates could not see. Now the renderer omits the subsection instead.
  */
 export const IMPLEMENTATION_CONTRACT_OPTIONAL_SUBSECTIONS = [
     'Behavior Contract',
     'Edge Cases And Failure Modes',
     'Non-Goals And Forbidden Approaches',
+    'File-Level Work Plan',
+    'Acceptance-To-Verification Map',
+    'Verification Commands',
 ];
 /** Union of required + optional subsections. Kept for callers that only need the full set. */
 export const IMPLEMENTATION_CONTRACT_SUBSECTIONS = [

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

@@ -83,12 +83,10 @@ function evaluateSubsection(section, content) {
     }
     const trimmed = content.trim();
     if (trimmed.length === 0) {
-        if (!OPTIONAL_SUBSECTIONS.has(section)) {
-            issues.push({
-                code: 'contract_subsection_empty',
-                message: `Implementation Contract subsection "${section}" is empty.`,
-            });
-        }
+        issues.push({
+            code: 'contract_subsection_empty',
+            message: `Implementation Contract subsection "${section}" is empty.`,
+        });
         return issues;
     }
     for (const pattern of FILLER_PATTERNS) {

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

@@ -3,32 +3,32 @@ export function buildImplementationContractSection(input) {
     const criteria = input.criteria;
     const testFiles = input.files.test.map((file) => file.path);
     const verificationCommands = input.verificationCommands;
+    const filePlan = renderFilePlan(input.files);
     const verificationRows = renderVerificationRows(criteria, testFiles, verificationCommands);
     const failureModes = renderFailureModes(criteria);
     const nonGoals = renderNonGoals(input.outOfScope);
+    const verificationCommandLines = verificationCommands.length > 0
+        ? verificationCommands.map((command) => `- \`${command}\``)
+        : criteria.length > 0
+            ? []
+            : ['- Needs decision: provide a repository-supported verification command.'];
     const lines = [
         `## ${IMPLEMENTATION_CONTRACT_SECTION}`,
         '### User Outcome',
         criteria[0]?.text ??
             'Needs decision: define the exact observable outcome this spec must deliver.',
         '',
-        '### File-Level Work Plan',
-        ...renderFilePlan(input.files, criteria.length > 0),
-        '',
-        '### Acceptance-To-Verification Map',
-        ...verificationRows,
-        '',
-        // SPEC-1406 (DEFECT 5): a subsection with no grounded content is omitted rather than
-        // filled with a restated-criterion placeholder — prefer omission over filler.
+        // SPEC-1406 (DEFECT 5) / SPEC-1435: a subsection with no grounded content is omitted
+        // rather than filled with a restated-criterion placeholder — prefer omission over filler.
+        ...(filePlan.length > 0 ? ['### File-Level Work Plan', ...filePlan, ''] : []),
+        ...(verificationRows.length > 0
+            ? ['### Acceptance-To-Verification Map', ...verificationRows, '']
+            : []),
         ...(failureModes.length > 0 ? ['### Edge Cases And Failure Modes', ...failureModes, ''] : []),
         ...(nonGoals.length > 0 ? ['### Non-Goals And Forbidden Approaches', ...nonGoals, ''] : []),
-        '### Verification Commands',
-        ...(verificationCommands.length > 0
-            ? verificationCommands.map((command) => `- \`${command}\``)
-            : criteria.length > 0
-                ? ['- No repository-supported verification command was grounded for this candidate.']
-                : ['- Needs decision: provide a repository-supported verification command.']),
-        '',
+        ...(verificationCommandLines.length > 0
+            ? ['### Verification Commands', ...verificationCommandLines, '']
+            : []),
     ];
     return lines.join('\n');
 }
@@ -38,7 +38,7 @@ export function appendImplementationContractIfMissing(specBody, input) {
     }
     return `${specBody.trimEnd()}\n\n${buildImplementationContractSection(input)}`;
 }
-function renderFilePlan(files, hasGroundedBehavior) {
+function renderFilePlan(files) {
     const lines = [];
     for (const [label, entries] of [
         ['Create', files.create],
@@ -49,12 +49,7 @@ function renderFilePlan(files, hasGroundedBehavior) {
             lines.push(`- ${label}: \`${entry.path}\` (${entry.status})`);
         }
     }
-    if (lines.length > 0) {
-        return lines;
-    }
-    return hasGroundedBehavior
-        ? ['- No file ownership was grounded for this behavior.']
-        : ['- Needs decision: identify expected source and test files.'];
+    return lines;
 }
 /**
  * SPEC-1406 (DEFECT 1, round 2): renders the Acceptance-To-Verification Map body.
@@ -80,7 +75,7 @@ function renderVerificationRows(criteria, testFiles, commands) {
         return rows;
     }
     if (testFiles.length === 0) {
-        return ['- No repository-supported verification evidence was grounded for these criteria.'];
+        return [];
     }
     return renderSharedVerificationRow(testFiles, commands);
 }

package/dist/engine/project-health-checker.js

@@ -2,15 +2,15 @@ import { technologyValue } from './technology-registry.js';
 import { fileExists } from '../core/shared/fs.js';
 // @crash-shield-ignore-file — config/cache reader for Planu-controlled JSON; writer is this codebase, shape guaranteed by build/seed.
 // engine/project-health-checker.ts — SPEC-180 + SPEC-192 + SPEC-177: Project health check with convention scanning
-import { execSync } from 'node:child_process';
 import { readFile } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 import { parseConventions, scanConventions } from './convention-scanner/index.js';
 import { fastFindPatterns } from './core-bridge.js';
+import { execGitCapture } from './git/exec-git.js';
 // ── helpers ──────────────────────────────────────────────────────────────────
 function execSafe(cmd, cwd) {
     try {
-        return execSync(cmd, { cwd, stdio: ['pipe', 'pipe', 'pipe'] }).toString();
+        return execGitCapture(cmd, cwd);
     }
     catch {
         return '';

package/dist/engine/readiness-checker.js

@@ -10,11 +10,24 @@ import { findScenariosWithoutTests, parseFrontmatterScenarios, } from './validat
 import { normalizeExecutableEvidence } from './validator/executable-evidence.js';
 import { evaluateImplementationContract } from './implementation-contract/index.js';
 import { extractNormalizedAcceptanceCriteria } from './spec-format/acceptance-criteria.js';
+import { isRetiredScaffoldText } from './spec-format/retired-scaffold.js';
 import { detectCrossSpecPremiseContradictions } from './contradiction-detector.js';
 // ── SPEC-784: Technical section quality constants ─────────────────────────────
 const TECHNICAL_MIN_CHARS = 500;
 // Detects "See technical.md", "See spec.md", or "See `<file>` technical.md" patterns
 const TECHNICAL_PLACEHOLDER_REGEX = /\bSee\s+(?:`?[^`\n]+`?\s+)?(?:technical|spec)\.md/i;
+const BDD_CRITERION_RE = /\bGIVEN\b[\s\S]*\bWHEN\b[\s\S]*\bTHEN\b/i;
+function isExecutableBddLine(line) {
+    return !isRetiredScaffoldText(line) && BDD_CRITERION_RE.test(line);
+}
+function checkZeroBddCriteria(criteriaLines) {
+    if (criteriaLines.length === 0 || criteriaLines.some(isExecutableBddLine)) {
+        return [];
+    }
+    return [
+        'NO_BDD_CRITERIA: no acceptance criterion parses as GIVEN/WHEN/THEN — restate at least one criterion in executable form',
+    ];
+}
 // ── Helpers ──────────────────────────────────────────────────────────────────
 function scoreHuCompleteness(spec) {
     const blockers = [];
@@ -73,6 +86,15 @@ function countFrontmatterScenarios(raw) {
     // Each scenario entry starts with "  - title:" (2-space indent)
     return (block.match(/^\s+-\s+title:/gm) ?? []).length;
 }
+function frontmatterScenarioScavengeWarning(bddScenarioCount, normalizedCriteria) {
+    const bodyCriteriaCount = normalizedCriteria.filter((criterion) => criterion.source === 'body').length;
+    if (bddScenarioCount === 0 || bddScenarioCount >= bodyCriteriaCount) {
+        return null;
+    }
+    return (`frontmatter_scenarios_below_body_criteria: frontmatter declares ${String(bddScenarioCount)} ` +
+        `scenarios but body renders ${String(bodyCriteriaCount)} acceptance criteria — scenarios may ` +
+        `have been scavenged from prose`);
+}
 async function readFichaContent(spec) {
     return readSpecTechnicalSection(spec);
 }
@@ -418,6 +440,7 @@ export async function checkSpecReadiness(spec, mode, projectHash) {
         ...earsBlockers,
     ];
     const allWarnings = [...hu.warnings, ...criteria.warnings, ...files.warnings, ...deps.warnings];
+    allBlockers.push(...checkZeroBddCriteria(effectiveCriteriaLines));
     if (mode === 'strict' && spec.scope !== 'trivial' && spec.difficulty >= 3) {
         for (const issue of evaluateImplementationContract(huContent, canonicalCriteriaLines)) {
             allBlockers.push(`${issue.code}: ${issue.message}`);
@@ -432,6 +455,10 @@ export async function checkSpecReadiness(spec, mode, projectHash) {
             allBlockers.push(`scenarios_missing_tests: scenario "${title}" has no tests array — add tests entries as a block list (tests: with one "- path" line per test) or an inline array (tests: ["path"]) (SPEC-732)`);
         }
     }
+    const scavengeWarning = frontmatterScenarioScavengeWarning(bddScenarioCount, normalizedCriteria);
+    if (scavengeWarning) {
+        allWarnings.push(scavengeWarning);
+    }
     // SPEC-1214: BDD-criteria executable-evidence gate — when a spec has no frontmatter
     // scenarios, its criteria must carry a TEST: marker mapping to an executable test file,
     // or validation will later score 0 with "No executable scenarios declared".

package/dist/engine/reconcile/apply-changes.js

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { atomicWriteFile } from '../safety/atomic-write-file.js';
 import { SECTIONS_WITHOUT_LITERAL_BODY_TEXT, } from '../../types/index.js';
 import { escapeRegex } from '../../core/shared/strings.js';
+import { propagateMirrors } from './propagate-mirrors.js';
 function findSectionBounds(content, section) {
     const headingRe = new RegExp(`^(#{1,6})\\s+${escapeRegex(section)}\\s*$`, 'mi');
     const match = headingRe.exec(content);
@@ -54,6 +55,7 @@ export async function applyChangesToSpec(specPath, changes) {
     let modified = content;
     let applied = 0;
     const skipped = [];
+    const appliedSections = new Set();
     for (const change of approvedTextChanges) {
         const bounds = findSectionBounds(modified, change.section);
         if (bounds === null) {
@@ -92,10 +94,12 @@ export async function applyChangesToSpec(specPath, changes) {
                 change.newValue +
                 modified.slice(absoluteIdx + change.originalValue.length);
         applied++;
+        appliedSections.add(change.section);
     }
     if (applied === 0) {
         return { applied: 0, skipped, fileWritten: false };
     }
+    modified = propagateMirrors(modified, appliedSections);
     await atomicWriteFile(specPath, modified);
     return { applied, skipped, fileWritten: true };
 }

package/dist/engine/reconcile/propagate-mirrors.d.ts

@@ -0,0 +1,3 @@
+import type { AppliedSections } from '../../types/index.js';
+export declare function propagateMirrors(content: string, appliedSections: AppliedSections): string;
+//# sourceMappingURL=propagate-mirrors.d.ts.map