@planu/cli 5.7.5 → 5.7.7

package/dist/config/spec-templates/stripe-payments/template.json

@@ -4,7 +4,11 @@
   "variables": [
     { "name": "currency", "description": "Default currency code (e.g. usd, eur)", "default": "usd" },
     { "name": "plan_name", "description": "Name of the subscription plan or product", "default": "Pro Plan" },
-    { "name": "webhook_endpoint", "description": "Path for the Stripe webhook endpoint", "default": "/api/webhooks/stripe" }
+    {
+      "name": "webhook_endpoint",
+      "description": "Path for the Stripe webhook endpoint",
+      "default": "/api/webhooks/stripe"
+    }
   ],
   "tags": ["payments", "stripe", "subscriptions", "backend"]
 }

package/dist/config/spec-templates/webhook-system/template.json

@@ -4,7 +4,11 @@
   "variables": [
     { "name": "max_retries", "description": "Maximum delivery retry attempts", "default": "3" },
     { "name": "timeout_seconds", "description": "HTTP request timeout per delivery attempt", "default": "10" },
-    { "name": "signature_header", "description": "HTTP header name for HMAC signature", "default": "X-Webhook-Signature" }
+    {
+      "name": "signature_header",
+      "description": "HTTP header name for HMAC signature",
+      "default": "X-Webhook-Signature"
+    }
   ],
   "tags": ["webhooks", "events", "backend", "integrations"]
 }

package/dist/config/subagent-templates/planu-challenger.md

@@ -5,10 +5,7 @@ tools:
   - Read
   - mcp__planu__challenge_spec
   - mcp__planu__list_specs
-  - mcp__planu__suggest_criteria
-  - mcp__planu__red_team
-  - mcp__planu__ears_lint
-  - mcp__planu__validate_criteria_quality
+  - mcp__planu__check_readiness
 ---
 
 # Planu Challenger
@@ -25,11 +22,9 @@ You are a adversarial spec reviewer. Your job is to find every weakness in a spe
 
 1. **Load spec** — call `list_specs` to find the spec. Read `spec.md` fully.
 2. **Run challenge** — call `challenge_spec({ specId })`. Read all findings.
-3. **EARS lint** — call `ears_lint({ specId })` to check criteria format quality.
-4. **Criteria quality** — call `validate_criteria_quality({ specId })` for testability gaps.
-5. **Red team** — call `red_team({ specId })` for adversarial scenarios.
-6. **Synthesize** — group findings by severity: blocking gaps, missing edge cases, ambiguous wording, implementation risks.
-7. **Suggest fixes** — for each finding, propose a concrete criterion rewrite or addition.
+3. **Check readiness** — call `check_readiness({ specId })` to verify the spec has enough detail to implement.
+4. **Synthesize** — group findings by severity: blocking gaps, missing edge cases, ambiguous wording, implementation risks.
+5. **Suggest fixes** — for each finding, propose a concrete criterion rewrite or addition.
 
 ## Output format
 

package/dist/config/subagent-templates/planu-spec-implementer.md

@@ -12,9 +12,7 @@ tools:
   - mcp__planu__update_status
   - mcp__planu__validate
   - mcp__planu__get_job
-  - mcp__planu__watch_job
   - mcp__planu__check_readiness
-  - mcp__planu__tdd_scaffold
 ---
 
 # Planu Spec Implementer
@@ -32,11 +30,11 @@ You are an autonomous implementation agent for Spec Driven Development. Your job
 2. **Verify approval** — confirm spec status is `approved`. If not, call `check_readiness` and stop with a note.
 3. **Update status to `implementing`** — call `update_status({ specId, status: "implementing" })`.
 4. **Create a feature branch** — `git checkout -b feat/SPEC-NNN-slug`.
-5. **Scaffold TDD tests** — call `tdd_scaffold` to generate test stubs from acceptance criteria.
+5. **Write TDD tests** — write failing test stubs mirroring `src/` in `tests/`, one per acceptance criterion.
 6. **Implement** — write all source files in dependency order: types → engine → storage → tools/resources. Follow Clean Architecture (types layer imports nothing; tools import engine+storage+types).
 7. **Run tests** — `pnpm typecheck && pnpm lint && pnpm test:coverage`. Fix all failures.
 8. **Submit validation** — call `validate({ specId })` and capture `operationId`, `projectId`, `workspaceId`, and `cursor` from the durable acknowledgement.
-9. **Await and inspect** — call `watch_job` with those identifiers and the latest cursor until terminal. Require `completed`, then inspect `job.result.structuredContent`. Stop on `failed`, `dead-letter`, or `cancelled`; fix failures and submit a new validation job.
+9. **Await and inspect** — poll `get_job` with those identifiers and the latest cursor until terminal. Require `completed`, then inspect `job.result.structuredContent`. Stop on `failed`, `dead-letter`, or `cancelled`; fix failures and submit a new validation job.
 10. **Commit** — only after the completed validation result reports `ready: true`, `status: "passing"`, and passing quality gates, run `git add <files> && git commit -m "feat(SPEC-NNN): <title>"`.
 11. **Update status to `done`** — call `update_status({ specId, status: "done" })` only after that completed passing result.
 

package/dist/config/subagent-templates/planu-validator.md

@@ -8,11 +8,9 @@ tools:
   - Grep
   - mcp__planu__validate
   - mcp__planu__get_job
-  - mcp__planu__watch_job
   - mcp__planu__list_specs
-  - mcp__planu__spec_health_check
   - mcp__planu__check_readiness
-  - mcp__planu__auto_fix_validation
+  - mcp__planu__restart_job
 ---
 
 # Planu Validator
@@ -29,15 +27,14 @@ You are a validation specialist. Your job is to verify that implemented code sat
 
 1. **Load spec** — call `list_specs` and read `spec.md` for all acceptance criteria.
 2. **Submit validation** — call `validate({ specId })` and capture `operationId`, `projectId`, `workspaceId`, and `cursor` from the durable acknowledgement.
-3. **Wait for the terminal result** — call `watch_job` with those identifiers and the latest cursor. Repeat while state is `accepted`, `running`, or `checkpointed`. Require `completed`; stop and report `failed`, `dead-letter`, or `cancelled`.
+3. **Wait for the terminal result** — poll `get_job` with those identifiers and the latest cursor. Repeat while state is `accepted`, `running`, or `checkpointed`. Require `completed`; stop and report `failed`, `dead-letter`, or `cancelled`.
 4. **Read the validation result** — inspect `job.result.structuredContent`. The acknowledgement is not a pass/fail result.
-5. **Run health check** — call `spec_health_check({ specId })` for structural issues.
-6. **Assess gaps** — for each failing criterion:
+5. **Assess gaps** — for each failing criterion:
    - Identify which source files are responsible
    - Diagnose the root cause (missing logic, wrong condition, untested branch)
    - Propose a minimal fix
-7. **Auto-fix when safe** — call `auto_fix_validation` for fixable issues, then submit and await a new validation job.
-8. **Report** — provide a summary with: passing count, failing count, and concrete next steps for each failure.
+6. **Fix and re-validate** — fix the underlying code or test, then call `validate({ specId })` again and poll `get_job` until terminal; use `restart_job` if the job itself failed or was cancelled rather than the criteria.
+7. **Report** — provide a summary with: passing count, failing count, and concrete next steps for each failure.
 
 ## Output format
 

package/dist/config/tool-groups.json

@@ -3,22 +3,8 @@
     {
       "id": "core",
       "name": "Core",
-      "description": "The 9 Tier 1 tools every new user needs: project setup, spec creation, lifecycle management, and status.",
-      "tools": [
-        "facilitate",
-        "init_project",
-        "create_spec",
-        "list_specs",
-        "update_status",
-        "validate",
-        "planu_status",
-        "capture_idea",
-        "quick_start",
-        "set_locale",
-        "init_constitution",
-        "activate_group",
-        "list_groups"
-      ],
+      "description": "The Tier 1 tools every new user needs: project setup, spec creation, lifecycle management, and status.",
+      "tools": ["facilitate", "init_project", "create_spec", "list_specs", "update_status", "validate", "planu_status"],
       "defaultEnabled": true,
       "locked": true
     },
@@ -26,143 +12,19 @@
       "id": "spec-lifecycle",
       "name": "Spec Lifecycle",
       "description": "Create, validate, estimate, and manage specs through their full lifecycle.",
-      "tools": [
-        "estimate",
-        "request_changes",
-        "challenge_spec",
-        "check_readiness",
-        "clarify_requirements",
-        "summarize_spec",
-        "reconcile_spec",
-        "reconcile_hooks",
-        "reconcile_rules",
-        "reconcile_skills",
-        "config_health",
-        "list_templates",
-        "apply_template",
-        "spec_history",
-        "log_decision"
-      ],
+      "tools": ["estimate", "request_changes", "challenge_spec", "check_readiness", "reconcile_spec"],
       "defaultEnabled": true,
       "locked": false,
       "triggerTools": ["estimate", "challenge_spec", "check_readiness"]
     },
-    {
-      "id": "analysis",
-      "name": "Analysis",
-      "description": "Audit, drift detection, contradiction checks, and deep code analysis.",
-      "tools": [
-        "audit",
-        "audit_stack",
-        "detect_drift",
-        "detect_contradictions",
-        "detect_deprecations",
-        "detect_agent",
-        "reality_check",
-        "check_spec_accuracy",
-        "paradigm_report",
-        "spec_coverage",
-        "validate_annotations",
-        "generate_annotations",
-        "snapshot_spec_hashes",
-        "auto_reconcile",
-        "living_spec_watch",
-        "living_spec_status",
-        "spec_diff",
-        "living_spec_coverage",
-        "sync_spec_to_code",
-        "sync_code_to_spec",
-        "resolve_sync_conflict"
-      ],
-      "defaultEnabled": false,
-      "locked": false,
-      "triggerTools": ["audit", "detect_drift", "reality_check"]
-    },
-    {
-      "id": "generation",
-      "name": "Generation",
-      "description": "Generate docs, tests, schemas, UI contracts, skills, rules, and ADRs.",
-      "tools": [
-        "generate_docs",
-        "generate_tests",
-        "design_schema",
-        "define_ui_contract",
-        "generate_adr",
-        "generate_checklist",
-        "generate_rules",
-        "generate_skill",
-        "generate_sub_agent",
-        "consult_docs",
-        "event_contracts"
-      ],
-      "defaultEnabled": false,
-      "locked": false,
-      "triggerTools": ["generate_docs", "generate_tests", "design_schema"]
-    },
     {
       "id": "orchestration",
       "name": "Orchestration",
-      "description": "Multi-agent orchestration, execution plans, handoff packages, and AI cost estimation.",
-      "tools": [
-        "orchestrate",
-        "orchestrate_agents",
-        "package_handoff",
-        "generate_execution_plan",
-        "generate_orchestration_script",
-        "estimate_ai_cost",
-        "integrate_pm"
-      ],
-      "defaultEnabled": false,
-      "locked": false,
-      "triggerTools": ["orchestrate", "orchestrate_agents", "generate_execution_plan"]
-    },
-    {
-      "id": "devops",
-      "name": "DevOps",
-      "description": "Git management, tooling suggestions, CI generation, upgrades, and stack recommendations.",
-      "tools": [
-        "manage_git",
-        "suggest_tooling",
-        "suggest_stack",
-        "suggest_mcps",
-        "suggest_mcp_server",
-        "plan_upgrade",
-        "check_versions",
-        "check_config_health",
-        "generate_ci",
-        "discover_mcps",
-        "validate_workflow"
-      ],
-      "defaultEnabled": false,
-      "locked": false,
-      "triggerTools": ["manage_git", "suggest_tooling", "generate_ci"]
-    },
-    {
-      "id": "governance",
-      "name": "Governance",
-      "description": "Security checks, data governance, scope management, and context control.",
-      "tools": [
-        "security_check",
-        "data_governance",
-        "legal_compliance_report",
-        "manage_scope",
-        "manage_context",
-        "context_budget",
-        "request_context",
-        "contribute_context"
-      ],
-      "defaultEnabled": false,
-      "locked": false,
-      "triggerTools": ["security_check", "data_governance", "manage_scope"]
-    },
-    {
-      "id": "learning",
-      "name": "Learning",
-      "description": "Pattern learning, knowledge capture, reverse engineering, and migration.",
-      "tools": ["learn_pattern", "capture_learning", "reverse_engineer", "migrate_tech", "manage_hooks"],
+      "description": "Handoff packages for implementation agents.",
+      "tools": ["package_handoff"],
       "defaultEnabled": false,
       "locked": false,
-      "triggerTools": ["learn_pattern", "capture_learning", "reverse_engineer"]
+      "triggerTools": ["package_handoff"]
     }
   ]
 }

package/dist/engine/ambiguity-scorer.js

@@ -40,6 +40,44 @@ function buildSuggestion(term, criterion) {
     const clean = criterion.slice(0, 80);
     return `Replace "${term}" with a concrete measurable value, e.g.: "${clean.replace(new RegExp(`\\b${term}\\b`, 'gi'), `<${term}_value>`)}"`;
 }
+const ENUM_LITERAL_TOKEN = /^[A-Za-z0-9_.-]+$/;
+const NON_WORD_MASK_CHAR = '#';
+function maskSpan(span) {
+    return span.replace(/\S/g, NON_WORD_MASK_CHAR);
+}
+function maskLiteralSpans(line) {
+    let masked = '';
+    let cursor = 0;
+    while (cursor < line.length) {
+        const char = line.charAt(cursor);
+        if (char === '`') {
+            const closeIndex = line.indexOf('`', cursor + 1);
+            if (closeIndex === -1) {
+                masked += line.slice(cursor);
+                break;
+            }
+            masked += maskSpan(line.slice(cursor, closeIndex + 1));
+            cursor = closeIndex + 1;
+            continue;
+        }
+        if (char === '"') {
+            const closeIndex = line.indexOf('"', cursor + 1);
+            if (closeIndex === -1) {
+                masked += line.slice(cursor);
+                break;
+            }
+            const content = line.slice(cursor + 1, closeIndex);
+            masked += ENUM_LITERAL_TOKEN.test(content)
+                ? maskSpan(line.slice(cursor, closeIndex + 1))
+                : line.slice(cursor, closeIndex + 1);
+            cursor = closeIndex + 1;
+            continue;
+        }
+        masked += char;
+        cursor += 1;
+    }
+    return masked;
+}
 function hasAdjacentNumber(line, term) {
     // Check if a number appears within 4 words of the vague term
     const words = line.toLowerCase().split(/\s+/);
@@ -63,10 +101,11 @@ export function scoreAmbiguity(criteriaLines) {
             continue;
         }
         const lower = line.toLowerCase();
+        const maskedLower = maskLiteralSpans(line).toLowerCase();
         // Check vague units (skip if adjacent number is present)
         for (const [term, reason] of Object.entries(VAGUE_UNITS)) {
             const pattern = new RegExp(`\\b${term}\\b`);
-            if (pattern.test(lower) && !hasAdjacentNumber(lower, term)) {
+            if (pattern.test(maskedLower) && !hasAdjacentNumber(maskedLower, term)) {
                 violations.push({
                     term,
                     criterion: line.slice(0, 120),

package/dist/engine/autopilot/bootstrap.js

@@ -106,7 +106,7 @@ function registerPluginInstalledListener() {
 /**
  * SPEC-1345 AC4: Fire-and-forget semantic index refresh on spec:created.
  * Reconciles the persisted TF-IDF index against the current corpus so the next
- * semantic_search call hits a warm, up-to-date index.
+ * internal pattern-learning lookup hits a warm, up-to-date index.
  */
 function registerSemanticIndexRefreshListener() {
     onAutopilotEvent('spec:created', (event) => {

package/dist/engine/code-impact-analyzer.js

@@ -1,5 +1,5 @@
 // engine/code-impact-analyzer.ts — Code Change → Spec Impact Analyzer (SPEC-366)
-import { execSync } from 'node:child_process';
+import { execGitCapture } from './git/exec-git.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -138,11 +138,7 @@ export function suggestSpecUpdates(specs, filePath) {
 export function runGitDiffImpact(specs, projectPath) {
     let diffText = '';
     try {
-        diffText = execSync('git diff HEAD', {
-            cwd: projectPath,
-            encoding: 'utf-8',
-            stdio: ['pipe', 'pipe', 'pipe'],
-        });
+        diffText = execGitCapture('git diff HEAD', projectPath);
     }
     catch {
         // ignore git errors — proceed with empty diff

package/dist/engine/context-orchestrator/index.js

@@ -1,6 +1,6 @@
 import { suggestArchivableSpecs, archiveSpecToPath } from '../context-manager.js';
 import { writeCheckpoint } from '../session/checkpoint-writer.js';
-import { sessionTracker } from '../session/session-tracker.js';
+import { getSessionTracker } from '../session/session-tracker.js';
 // eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { specStore } from '../../storage/index.js';
 // eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
@@ -114,7 +114,7 @@ async function archiveDoneSpecs(projectId, projectPath, actionsExecuted) {
 }
 async function createSessionCheckpoint(projectPath, actionsExecuted) {
     try {
-        const snapshot = sessionTracker.getSnapshot();
+        const snapshot = getSessionTracker(projectPath).getSnapshot();
         await writeCheckpoint(projectPath, snapshot);
         actionsExecuted.push('session_checkpoint: written to planu/session-context.md');
     }

package/dist/engine/convention-scanner/codebase-scanner.js

@@ -1,13 +1,13 @@
 // engine/convention-scanner/codebase-scanner.ts — SPEC-192
 // Scans actual codebase files against parsed conventions
-import { execSync } from 'node:child_process';
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, relative } from 'node:path';
+import { execGitCapture } from '../git/exec-git.js';
 const MAX_VIOLATIONS_PER_CATEGORY = 50;
 // ── helpers ───────────────────────────────────────────────────────────────────
 function execSafe(cmd, cwd) {
     try {
-        return execSync(cmd, { cwd, timeout: 5_000, stdio: ['pipe', 'pipe', 'pipe'] }).toString();
+        return execGitCapture(cmd, cwd);
     }
     catch {
         return '';

package/dist/engine/dogfooding/runtime-gap-detector.js

@@ -78,7 +78,7 @@ const SIGNAL_RULES = [
         signature: 'manual-recovery-loop',
         title: 'Repeated manual recovery steps',
         severity: 'medium',
-        nextAction: 'submit_feedback',
+        nextAction: 'create_spec',
         patterns: [
             /\bmanual recovery\b/gi,
             /\brepair_frontmatter_drift\b/gi,
@@ -342,7 +342,7 @@ export async function analyzeRuntimeDogfooding(projectPath) {
             signature: 'session-version-drift',
             title: 'Persisted session version drifted from the current package version',
             severity: 'medium',
-            nextAction: 'submit_feedback',
+            nextAction: 'create_spec',
             occurrences: 1,
             evidence: ['Persisted session version does not match package.json'],
         });

package/dist/engine/evidence-gates/artifact-reader.d.ts

@@ -45,6 +45,7 @@ export declare function traceabilityRowHasCurrentCommandEvidence(row: Traceabili
     projectId: string;
     projectPath: string;
 }): boolean;
+export declare function artifactHint(label: string): string;
 /** SPEC-1356: exported so evidence-autofill (and other producers) target the same path convention. */
 export declare function handoffEvidencePath(projectId: string, specId: string, filename: string): string;
 export declare function readEvidenceArtifacts(args: {

package/dist/engine/evidence-gates/artifact-reader.js

@@ -247,7 +247,7 @@ const ARTIFACT_HINTS = {
     'contract-validation-ui.json': 'Expected filename contract-validation-ui.json with { version: 1, kind: "ui", passed: boolean, reportPath?, summary? }.',
     'contract-validation-mcp.json': 'Expected filename contract-validation-mcp.json with { version: 1, kind: "mcp", passed: boolean, reportPath?, summary? }.',
 };
-function artifactHint(label) {
+export function artifactHint(label) {
     return ARTIFACT_HINTS[label] ?? '';
 }
 /** SPEC-1356: exported so evidence-autofill (and other producers) target the same path convention. */

package/dist/engine/evidence-gates/evidence-autofill.d.ts

@@ -4,12 +4,20 @@ export declare const PLANU_BOOKKEEPING_FILES: readonly ['planu/context.md', 'pla
 /** Normalizes a spec.md path (absolute or already repo-relative) to a repo-relative,
  * forward-slash path so it can be compared against `git diff` output. */
 export declare function toRepoRelativePath(specPath: string, projectPath?: string): string;
+/** Prose template + matching regex for the generator's validation evidence, shared by the
+ * generator (renders it) and the staleness classifier (recognizes it). */
+export declare function buildValidationEvidenceText(specId: string, score: number | undefined): string;
+export declare const VALIDATION_EVIDENCE_PATTERN: RegExp;
+/** Prose template + matching regex for the generator's reviewer evidence, shared by the
+ * generator (renders it) and the staleness classifier (recognizes it). */
+export declare function buildReviewerEvidenceText(agent: string, kind: string, verdict: string): string;
+export declare const REVIEWER_EVIDENCE_PATTERN: RegExp;
 /**
- * Generate `traceability-matrix.json` in the handoff evidence store when it does
- * not already exist. Never overwrites an existing file — if one is present this
- * is a no-op that reports `already-exists`. Tolerates every failure by returning
- * a typed non-throwing result; callers must never let this crash a lifecycle
- * transition.
+ * Generate `traceability-matrix.json` in the handoff evidence store, or regenerate
+ * it in place when it is autofill-shaped but stale relative to the current
+ * validation report. Never touches a hand-written or mixed matrix — those are a
+ * permanent no-op. Tolerates every failure by returning a typed non-throwing
+ * result; callers must never let this crash a lifecycle transition.
  */
 export declare function autofillTraceabilityMatrix(args: AutofillTraceabilityMatrixArgs): Promise<AutofillTraceabilityMatrixResult>;
 //# sourceMappingURL=evidence-autofill.d.ts.map