@planu/cli 4.3.4 → 4.3.6

package/dist/engine/dashboard/templates-project.d.ts

@@ -3,7 +3,7 @@ import type { DashboardProjectSummary, DashboardUsageStats, ProjectHealthMetrics
 export declare function renderHomePage(projects: DashboardProjectSummary[], usage: DashboardUsageStats): string;
 /** Render the project detail page — spec cards + kanban board + health panel */
 export declare function renderProjectPage(project: DashboardProjectSummary, metrics: ProjectHealthMetrics, usage: DashboardUsageStats): string;
-/** Render the spec detail page — HU, FICHA, PROGRESS tabs */
+/** Render the spec detail page — canonical spec.md sections */
 export declare function renderSpecPage(projectId: string, projectName: string, specId: string, hu: string | null, ficha: string | null, progress: string | null): string;
 /** Render a 404 not found page */
 export declare function render404Page(path: string): string;

package/dist/engine/dashboard/templates-project.js

@@ -226,15 +226,17 @@ export function renderProjectPage(project, metrics, usage) {
   `;
     return renderLayout(project.name, body, getKanbanStyles(), getKanbanScript());
 }
-/** Render the spec detail page — HU, FICHA, PROGRESS tabs */
+/** Render the spec detail page — canonical spec.md sections */
 export function renderSpecPage(projectId, projectName, specId, hu, ficha, progress) {
-    const huHtml = hu !== null ? markdownToHtml(hu) : '<p style="color:var(--text-muted)">HU.md no encontrado</p>';
+    const huHtml = hu !== null
+        ? markdownToHtml(hu)
+        : '<p style="color:var(--text-muted)">spec.md no encontrado</p>';
     const fichaHtml = ficha !== null
         ? markdownToHtml(ficha)
-        : '<p style="color:var(--text-muted)">FICHA-TECNICA.md no encontrado</p>';
+        : '<p style="color:var(--text-muted)">## Technical no encontrado en spec.md</p>';
     const progressHtml = progress !== null
         ? markdownToHtml(progress)
-        : '<p style="color:var(--text-muted)">PROGRESS.md no encontrado</p>';
+        : '<p style="color:var(--text-muted)">## Progress no encontrado en spec.md</p>';
     const body = `
     <div class="breadcrumb">
       <a href="/">Inicio</a> &rsaquo;

package/dist/engine/docs-site-generator/index.js

@@ -7,6 +7,7 @@ import { renderSpecPage, renderSpecIndex } from './spec-renderer.js';
 import { renderToolsCatalog } from './tools-renderer.js';
 import { renderDiagramsPage } from './diagrams-renderer.js';
 import { stripFrontmatter } from '../frontmatter-parser.js';
+import { extractSectionBody } from '../spec-format/read-technical-section.js';
 export async function generateDocsSite(config) {
     const { projectPath, outputDir, title = 'Planu Documentation' } = config;
     const [specs, metrics] = await Promise.all([
@@ -33,7 +34,6 @@ export async function generateDocsSite(config) {
     });
     for (const spec of specs) {
         let specContent = '';
-        let techContent = '';
         try {
             const raw = await readFile(spec.specPath, 'utf-8');
             specContent = stripFrontmatter(raw);
@@ -41,16 +41,7 @@ export async function generateDocsSite(config) {
         catch {
             /* missing */
         }
-        try {
-            const techPath = spec.specPath
-                .replace(/spec\.md$/, 'technical.md')
-                .replace(/HU\.md$/, 'FICHA-TECNICA.md');
-            const rawTech = await readFile(techPath, 'utf-8');
-            techContent = stripFrontmatter(rawTech);
-        }
-        catch {
-            /* missing */
-        }
+        const techContent = extractSectionBody(specContent, 'Technical');
         pages.push({
             path: `specs/${spec.slug}.html`,
             title: spec.title,

package/dist/engine/drift-monitor.js

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import { readFile, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { fastScanProjectMetadata, isNativeActive, fastDetectDriftParallel, } from './core-bridge.js';
+import { readSpecTechnicalSection } from './spec-format/read-technical-section.js';
 // ---------------------------------------------------------------------------
 // Config builder
 // ---------------------------------------------------------------------------
@@ -107,14 +108,14 @@ const TEMPORAL_DRIFT_DAYS = 30;
  * Note: score represents HEALTH (100 = no drift). Callers may invert if needed.
  */
 export async function computeDriftScore(projectPath, specId, spec, technicalPath, metadataMap) {
-    const resolvedTechnical = resolveTechnicalPath(projectPath, specId, technicalPath);
+    const resolvedSpec = resolveSpecPath(projectPath, specId, technicalPath);
     let content = '';
-    if (resolvedTechnical !== null) {
+    if (resolvedSpec !== null) {
         try {
-            content = await readFile(resolvedTechnical, 'utf8');
+            content = await readSpecTechnicalSection({ specPath: resolvedSpec });
         }
         catch {
-            // cannot read technical.md — treat all layers as fully healthy
+            // cannot read spec.md technical section — treat all layers as fully healthy
         }
     }
     const filePaths = extractFilePaths(content, projectPath);
@@ -311,13 +312,14 @@ async function computeAcCoverageScore(criteria, filePaths) {
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
-/** Resolve the path to a spec's technical.md file. */
-function resolveTechnicalPath(projectPath, specId, technicalPath) {
-    /* v8 ignore next 3 */
+/** Resolve the path to a canonical spec.md file. */
+function resolveSpecPath(projectPath, specId, technicalPath) {
+    /* v8 ignore next 5 */
     if (technicalPath !== undefined && fs.existsSync(technicalPath)) {
-        return technicalPath;
+        const specPathFromLegacyHint = path.join(path.dirname(technicalPath), 'spec.md');
+        return fs.existsSync(specPathFromLegacyHint) ? specPathFromLegacyHint : null;
     }
-    // Convention: planu/specs/<specId>-<slug>/technical.md
+    // Convention: planu/specs/<specId>-<slug>/spec.md
     const specsDir = path.join(projectPath, 'planu', 'specs');
     if (!fs.existsSync(specsDir)) {
         return null;
@@ -334,10 +336,10 @@ function resolveTechnicalPath(projectPath, specId, technicalPath) {
     if (match === undefined) {
         return null;
     }
-    const candidate = path.join(specsDir, match, 'technical.md');
+    const candidate = path.join(specsDir, match, 'spec.md');
     return fs.existsSync(candidate) ? candidate : null;
 }
-/** Extract implementation file paths from technical.md content. */
+/** Extract implementation file paths from a spec's inline ## Technical content. */
 function extractFilePaths(content, projectPath) {
     const FILE_PATTERN = /\b([\w./-]+\.(?:ts|tsx|js|jsx|py|go|rs|java|rb|cs))\b/g;
     const found = new Set();

package/dist/engine/qa-gate.js

@@ -26,7 +26,12 @@ export function runQaGate(spec, projectPath) {
     const coverageThreshold = extractCoverageThreshold(spec);
     const checks = [];
     checks.push(runCheck('typecheck', 'pnpm', ['typecheck'], projectPath));
-    checks.push(runCheck('test-coverage', 'pnpm', ['test:coverage'], projectPath));
+    if (coverageThreshold === null) {
+        checks.push(runCheck('test', 'pnpm', ['test'], projectPath));
+    }
+    else {
+        checks.push(runCheck('test-coverage', 'pnpm', ['test:coverage'], projectPath));
+    }
     const passed = checks.every((c) => c.passed);
     return Promise.resolve({
         specId: spec.id,

package/dist/engine/readiness-checker.js

@@ -155,7 +155,7 @@ function scoreFilesIdentified(spec, fichaContent) {
     }
     else {
         points = 0;
-        warnings.push('No FICHA-TECNICA.md found — files to create/modify are not identified. Run create_spec_tech first.');
+        warnings.push('No inline ## Technical section found in spec.md — files to create/modify are not identified.');
     }
     return { points, blockers, warnings };
 }
@@ -180,7 +180,7 @@ function buildRecommendations(score, huPoints, criteriaPoints, filesPoints, deps
         recs.push('Add more acceptance criteria (aim for 5+ testable criteria)');
     }
     if (filesPoints < 20) {
-        recs.push('Generate FICHA-TECNICA.md with create_spec_tech to identify key files');
+        recs.push('Add an inline ## Technical section to spec.md with key files');
     }
     if (depsPoints < 30) {
         recs.push('Verify all spec dependencies are in "done" status');
@@ -360,7 +360,7 @@ export function checkReadinessInternal(body) {
     // Vague criteria detection (re-uses existing logic)
     const criteriaResult = scoreCriteria(criteriaLines.length > 0 ? criteriaLines : [], vagueWords);
     warnings.push(...criteriaResult.warnings);
-    // Technical files presence (proxy for technical.md — check src/ paths in body)
+    // Technical files presence (proxy for inline ## Technical — check src/ paths in body)
     const hasTechnicalFiles = /\bsrc\/[^\s]+\.[jt]s\b/.test(bodyContent);
     const technicalScore = hasTechnicalFiles ? 30 : 0;
     if (!hasTechnicalFiles && criteriaCount > 0) {

package/dist/engine/spec-conflict-graph.d.ts

@@ -2,7 +2,7 @@ import type { SpecConflictSafety, SpecConflictCheckResult, ConflictGraphEntry, S
 export type { SpecConflictSafety, SpecConflictCheckResult, ConflictGraphEntry, SpecConflictGraph };
 /**
  * SPEC-657: Update the conflict graph entry for a single spec.
- * Called whenever a spec's technical.md changes.
+ * Called whenever a spec's inline ## Technical section changes.
  */
 export declare function updateConflictGraphEntry(projectPath: string, specId: string): Promise<void>;
 /**

package/dist/engine/spec-conflict-graph.js

@@ -39,8 +39,7 @@ async function readTechnicalFiles(projectPath, specId) {
         return [];
     }
     const specPath = join(specsDir, folder, 'spec.md');
-    const technicalPath = join(specsDir, folder, 'technical.md');
-    const content = await readSpecTechnicalSection({ specPath, technicalPath });
+    const content = await readSpecTechnicalSection({ specPath });
     if (content.length === 0) {
         return [];
     }
@@ -62,7 +61,7 @@ async function saveGraph(projectPath, graph) {
 }
 /**
  * SPEC-657: Update the conflict graph entry for a single spec.
- * Called whenever a spec's technical.md changes.
+ * Called whenever a spec's inline ## Technical section changes.
  */
 export async function updateConflictGraphEntry(projectPath, specId) {
     const files = await readTechnicalFiles(projectPath, specId);

package/dist/engine/spec-format/read-technical-section.d.ts

@@ -2,14 +2,8 @@ import type { Spec } from '../../types/index.js';
 /**
  * Read the `## Technical` section body from a spec's unified `spec.md`.
  * Returns "" when the spec file is unreadable or the section is missing.
- *
- * The legacy `spec.technicalPath` is consulted as a transitional fallback:
- * if the spec.md does not yet contain a `## Technical` section but a
- * standalone `technical.md` still exists on disk (pre-migration data),
- * we read that file instead and strip its YAML frontmatter so callers
- * receive the body content uniformly.
  */
-export declare function readSpecTechnicalSection(spec: Pick<Spec, 'specPath' | 'technicalPath'>): Promise<string>;
+export declare function readSpecTechnicalSection(spec: Pick<Spec, 'specPath'>): Promise<string>;
 /**
  * Extract the body of a top-level (`## `) section from a markdown document.
  * Returns the content AFTER the heading line, up to the next top-level

package/dist/engine/spec-format/read-technical-section.js

@@ -1,35 +1,16 @@
 // engine/spec-format/read-technical-section.ts — SPEC-1010 PR-B
 //
 // SSR back-migration (SPEC-752, v2.4.0) folded `technical.md` into the
-// unified `spec.md` as a `## Technical` section. The reader call sites
-// that previously read the standalone `technical.md` file silently
-// degrade to "" today because the file never gets written. This helper
-// is the single source of truth for "give me the technical body for
-// this spec": it extracts the `## Technical` section from `spec.md`
-// and falls back to the legacy `technical.md` only when the unified
-// section is empty (transitional safety net for specs not yet auto-
-// migrated).
+// unified `spec.md` as a `## Technical` section. This helper is the
+// single source of truth for "give me the technical body for this spec":
+// it extracts only the canonical inline `## Technical` section.
 import { readFile } from 'node:fs/promises';
 /**
  * Read the `## Technical` section body from a spec's unified `spec.md`.
  * Returns "" when the spec file is unreadable or the section is missing.
- *
- * The legacy `spec.technicalPath` is consulted as a transitional fallback:
- * if the spec.md does not yet contain a `## Technical` section but a
- * standalone `technical.md` still exists on disk (pre-migration data),
- * we read that file instead and strip its YAML frontmatter so callers
- * receive the body content uniformly.
  */
 export async function readSpecTechnicalSection(spec) {
-    const fromUnified = await extractFromUnified(spec.specPath);
-    if (fromUnified.length > 0) {
-        return fromUnified;
-    }
-    if (!spec.technicalPath) {
-        return '';
-    }
-    const legacy = await readFile(spec.technicalPath, 'utf-8').catch(() => '');
-    return stripFrontmatter(legacy).trim();
+    return extractFromUnified(spec.specPath);
 }
 async function extractFromUnified(specPath) {
     const content = await readFile(specPath, 'utf-8').catch(() => '');
@@ -85,13 +66,6 @@ function maskFencedBlocks(body) {
         return block.replace(/[^\n]/g, ' ');
     });
 }
-/**
- * Strip a leading YAML frontmatter block (between `---` fences at the top
- * of the document). No-op if frontmatter is absent.
- */
-function stripFrontmatter(content) {
-    return content.replace(/^---\n[\s\S]*?\n---\n?/, '');
-}
 function escapeRegex(input) {
     return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }

package/dist/engine/spec-registry/scorer.d.ts

@@ -1,7 +1,7 @@
 import type { ScoreBreakdown } from '../../types/index.js';
 /**
  * Calculate a completeness score (0-100) for a spec directory.
- * Reads spec.md and technical.md, evaluates 6 quality categories.
+ * Reads canonical spec.md, evaluates 6 quality categories.
  */
 export declare function calculateCompletenessScore(specDir: string): Promise<{
     score: number;

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

@@ -81,7 +81,7 @@ function scoreKeyFiles(specContent, technicalContent) {
     /* v8 ignore next -- files header present but no file-like entries */
     return 0;
 }
-/** Score technical.md based on existence and length. */
+/** Score inline technical content based on existence and length. */
 function scoreTechnicalCompleteness(technicalContent) {
     if (!technicalContent) {
         return 0;
@@ -126,14 +126,13 @@ function scoreFrontmatter(specContent) {
 // ---------------------------------------------------------------------------
 /**
  * Calculate a completeness score (0-100) for a spec directory.
- * Reads spec.md and technical.md, evaluates 6 quality categories.
+ * Reads canonical spec.md, evaluates 6 quality categories.
  */
 export async function calculateCompletenessScore(specDir) {
     const specPath = join(specDir, 'spec.md');
-    const technicalPath = join(specDir, 'technical.md');
     const [specContent, technicalContent] = await Promise.all([
         readFileOrEmpty(specPath),
-        readSpecTechnicalSection({ specPath, technicalPath }),
+        readSpecTechnicalSection({ specPath }),
     ]);
     const breakdown = {
         acceptanceCriteria: scoreAcceptanceCriteria(specContent),

package/dist/engine/validator/extractors.js

@@ -17,8 +17,10 @@ export async function extractCriteria(spec) {
             const items = extractListItems(acSection);
             criteria.push(...items);
         }
-        // Also check for "Given/When/Then" patterns
-        const gwtMatches = huContent.matchAll(/(?:Given|Dado|When|Cuando|Then|Entonces)\s+(.+)/gi);
+        // Also check for explicit "Given/When/Then" patterns at line start.
+        // Keep this anchored so narrative text containing "when" is not treated
+        // as an acceptance criterion.
+        const gwtMatches = huContent.matchAll(/^\s*(?:[-*+]\s+|\d+[.)]\s+)?(?:Given|Dado|When|Cuando|Then|Entonces)\s+(.+)$/gim);
         for (const match of gwtMatches) {
             /* v8 ignore next 3 -- defensive regex capture group guard */
             if (match[1]) {

package/dist/engine/validator.d.ts

@@ -7,7 +7,7 @@ export { buildHolisticReportFromFlatScore } from './validator/holistic-report.js
 export type { HolisticValidateReport } from '../types/analysis.js';
 /**
  * Validate a spec against the actual codebase.
- * Reads the spec files (HU.md, FICHA-TECNICA.md), extracts criteria,
+ * Reads the canonical spec.md, extracts criteria,
  * then checks the filesystem/code for compliance.
  *
  * SPEC-730: The returned ValidateResult is enriched with `holisticReport`

package/dist/engine/validator.js

@@ -6,6 +6,7 @@ import { extractCriteria, extractVerifyBlocks } from './validator/extractors.js'
 import { scanCodeForSpec, checkCriterion, classifyDriftSeverity, quickQualityCheck, } from './validator/analyzer.js';
 import { resolveApplicableDimensions } from './validator/scope-resolver.js';
 import { buildHolisticReportFromFlatScore } from './validator/holistic-report.js';
+import { readEvidenceArtifacts } from './evidence-gates/artifact-reader.js';
 // Re-export the full public API so external callers never need to know
 // about the sub-module layout.
 export { generateDoR, generateDoD } from './validator/dor-dod.js';
@@ -13,9 +14,43 @@ export { generateChecklist } from './validator/checklist.js';
 // SPEC-730: export scope-resolver and holistic-report for consumers
 export { resolveApplicableDimensions, normaliseScore } from './validator/scope-resolver.js';
 export { buildHolisticReportFromFlatScore } from './validator/holistic-report.js';
+function normalizeCriterionForEvidence(value) {
+    return value
+        .replace(/^-\s*\[[ xX]\]\s*/i, '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase();
+}
+function rowHasValidationEvidence(row) {
+    const hasEvidence = [
+        row.testEvidence?.length,
+        row.contractEvidence?.length,
+        row.manualEvidence?.trim(),
+        row.validationEvidence?.trim(),
+        row.reviewerEvidence?.trim(),
+    ].some((value) => Boolean(value));
+    return row.changedFiles.length > 0 && hasEvidence;
+}
+async function readTraceabilityEvidence(spec, projectPath) {
+    try {
+        const artifacts = await readEvidenceArtifacts({
+            spec,
+            projectId: spec.projectId,
+            specId: spec.id,
+            projectPath,
+        });
+        const rows = artifacts.traceabilityMatrix?.rows ?? [];
+        return new Map(rows
+            .filter(rowHasValidationEvidence)
+            .map((row) => [normalizeCriterionForEvidence(row.acceptanceCriterion), row]));
+    }
+    catch {
+        return new Map();
+    }
+}
 /**
  * Validate a spec against the actual codebase.
- * Reads the spec files (HU.md, FICHA-TECNICA.md), extracts criteria,
+ * Reads the canonical spec.md, extracts criteria,
  * then checks the filesystem/code for compliance.
  *
  * SPEC-730: The returned ValidateResult is enriched with `holisticReport`
@@ -45,6 +80,7 @@ export async function validateSpec(spec, projectPath) {
         };
     }
     const criteria = await extractCriteria(spec);
+    const traceabilityEvidence = await readTraceabilityEvidence(spec, projectPath);
     const codeState = await scanCodeForSpec(spec, projectPath);
     // Extract verify blocks from spec file (forgiving — empty map if file unreadable)
     let verifyBlockMap = new Map();
@@ -61,7 +97,9 @@ export async function validateSpec(spec, projectPath) {
     const qualityIssues = [];
     for (const criterion of criteria) {
         const verifyBlock = verifyBlockMap.get(criterion);
-        const found = await checkCriterion(criterion, projectPath, codeState, verifyBlock);
+        const evidenceRow = traceabilityEvidence.get(normalizeCriterionForEvidence(criterion));
+        const found = evidenceRow !== undefined ||
+            (await checkCriterion(criterion, projectPath, codeState, verifyBlock));
         if (found) {
             matches.push(criterion);
         }

package/dist/tools/code-graph-handler.js

@@ -43,6 +43,10 @@ export async function handleConfigureCodeGraph(input) {
         JSON.stringify({ [providerKey]: entry }, null, 2),
         '```',
         '',
+        providerKey === 'codegraph'
+            ? 'Initialize the project index with `npx -y @colbymchenry/codegraph init -i` from the project root before relying on graph queries.'
+            : 'Initialize the provider index using the provider documentation before relying on graph queries.',
+        '',
         'Restart Claude Code (or your MCP client) to activate the new server.',
     ];
     return { content: [{ type: 'text', text: lines.join('\n') }] };

package/dist/tools/create-spec/post-creation.d.ts

@@ -11,6 +11,8 @@ export declare function checkContradictions(projectId: string, specId: string, d
 export declare function fireSpecCreatedHook(projectId: string, spec: Spec, projectPath: string): void;
 /** Generates post-creation suggestions based on project state and spec description. Best-effort: never throws. */
 export declare function generatePostCreationSuggestions(projectPath: string, description: string, knowledge?: ProjectKnowledge): Promise<PostCreationSuggestion[]>;
+/** Formats a structured post-creation suggestion for human-readable next steps. */
+export declare function formatPostCreationSuggestion(suggestion: PostCreationSuggestion): string;
 /**
  * SPEC-781: Run heavy analysis (contradiction detection, complexity advice) in a
  * fire-and-forget fashion after the spec has already been persisted synchronously.

package/dist/tools/create-spec/post-creation.js

@@ -162,6 +162,11 @@ export async function generatePostCreationSuggestions(projectPath, description,
     });
     return suggestions;
 }
+/** Formats a structured post-creation suggestion for human-readable next steps. */
+export function formatPostCreationSuggestion(suggestion) {
+    const templateSuffix = suggestion.templateCategory !== undefined ? ` (${suggestion.templateCategory})` : '';
+    return `${suggestion.tool}${templateSuffix}: ${suggestion.reason}`;
+}
 /**
  * SPEC-781: Run heavy analysis (contradiction detection, complexity advice) in a
  * fire-and-forget fashion after the spec has already been persisted synchronously.

package/dist/tools/create-spec.js

@@ -10,7 +10,7 @@ import { estimateSpec } from '../engine/estimator.js';
 import { checkSpecReadiness } from '../engine/readiness-checker.js';
 import { buildSpecContext, buildSplitResult } from './create-spec/spec-builder.js';
 import { validateConstitution } from './create-spec/constitution-validator.js';
-import { setupGitBranch, checkContradictions, fireSpecCreatedHook, generatePostCreationSuggestions, runAutopilotAsync, getAsyncAnalysisPath, } from './create-spec/post-creation.js';
+import { setupGitBranch, checkContradictions, fireSpecCreatedHook, generatePostCreationSuggestions, formatPostCreationSuggestion, runAutopilotAsync, getAsyncAnalysisPath, } from './create-spec/post-creation.js';
 import { notifyStoreChange } from '../engine/doc-generator/portal/regen-hook.js';
 import { compactObj } from '../engine/compact-obj.js';
 import { buildCreateSpecSummary } from '../engine/human-summary.js';
@@ -894,7 +894,7 @@ export async function handleCreateSpec(inputParams, server) {
             }
             // Append auto-pipeline output (SPEC-445)
             lines.push(...formatPipelineLines(pipelineResult));
-            const allNextSteps = result.nextSteps ?? [];
+            const allNextSteps = (result.nextSteps ?? []).map((step) => (typeof step === 'string' ? step : formatPostCreationSuggestion(step)));
             const markdownText = allNextSteps.length > 0
                 ? addNextSteps(formatSuccess(ti('tools.create_spec.success', { id: spec.id, title: spec.title }), lines.join('\n')), allNextSteps)
                 : formatSuccess(ti('tools.create_spec.success', { id: spec.id, title: spec.title }), lines.join('\n'));

package/dist/tools/license-gate.js

@@ -88,7 +88,12 @@ export function getTierSync() {
 // ---------------------------------------------------------------------------
 const sessionTierCache = new Map();
 const SESSION_TIER_TTL_MS = 10 * 60 * 1000; // 10 min — longer since online validation is expensive
-const RATE_LIMIT_EXEMPT_TOOLS = new Set(['planu_status', 'update_status_batch']);
+const RATE_LIMIT_EXEMPT_TOOLS = new Set([
+    'planu_status',
+    'update_status_batch',
+    'configure_code_graph',
+    'code_graph_status',
+]);
 export function shouldBypassDailyRateLimit(toolName) {
     return RATE_LIMIT_EXEMPT_TOOLS.has(toolName);
 }

package/dist/tools/output-integrity-guard.d.ts

@@ -0,0 +1,11 @@
+import type { ToolResult } from '../types/index.js';
+type MalformedOutputCode = 'OBJECT_OBJECT' | 'OBJECT_PROMISE';
+interface MalformedOutputIssue {
+    code: MalformedOutputCode;
+    pattern: string;
+    contentIndex: number;
+}
+export declare function findMalformedToolOutput(result: ToolResult): MalformedOutputIssue | null;
+export declare function guardToolResultOutput(toolName: string | undefined, result: ToolResult): ToolResult;
+export {};
+//# sourceMappingURL=output-integrity-guard.d.ts.map

package/dist/tools/output-integrity-guard.js

@@ -0,0 +1,53 @@
+const MALFORMED_TEXT_PATTERNS = [
+    { code: 'OBJECT_OBJECT', pattern: /\[object Object\]/, label: '[object Object]' },
+    { code: 'OBJECT_PROMISE', pattern: /\[object Promise\]/, label: '[object Promise]' },
+];
+export function findMalformedToolOutput(result) {
+    for (let index = 0; index < result.content.length; index++) {
+        const item = result.content[index];
+        const text = item?.text ?? '';
+        for (const rule of MALFORMED_TEXT_PATTERNS) {
+            if (rule.pattern.test(text)) {
+                return {
+                    code: rule.code,
+                    pattern: rule.label,
+                    contentIndex: index,
+                };
+            }
+        }
+    }
+    return null;
+}
+export function guardToolResultOutput(toolName, result) {
+    const issue = findMalformedToolOutput(result);
+    if (issue === null) {
+        return result;
+    }
+    const name = toolName ?? 'unknown';
+    const structuredKeys = Object.keys(result.structuredContent ?? {});
+    return {
+        content: [
+            {
+                type: 'text',
+                text: [
+                    '❌ **Output integrity guard blocked malformed response**',
+                    '',
+                    `Tool \`${name}\` produced non-human-readable text (${issue.code}).`,
+                    'The operation may have completed before the response was blocked.',
+                    'Run `planu_status` or retry the tool after the formatting bug is fixed.',
+                ].join('\n'),
+            },
+        ],
+        isError: true,
+        structuredContent: {
+            error: 'OUTPUT_INTEGRITY_GUARD',
+            toolName: name,
+            pattern: issue.code,
+            contentIndex: issue.contentIndex,
+            operationMayHaveCompleted: true,
+            originalStructuredContentKeys: structuredKeys,
+            fixHint: 'A Planu tool attempted to render a structured object as human text. Format the object explicitly before returning content[].text.',
+        },
+    };
+}
+//# sourceMappingURL=output-integrity-guard.js.map

package/dist/tools/register-sdd-tools.d.ts

@@ -1,4 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare const OFFICIAL_SDD_TOOL_NAMES: readonly ["planu_status", "facilitate", "init_project", "clarify_requirements", "create_spec", "challenge_spec", "check_readiness", "update_status", "update_status_batch", "package_handoff", "validate", "reconcile_spec", "create_rule", "create_skill", "skill_search"];
+export declare const OFFICIAL_SDD_TOOL_NAMES: readonly ["planu_status", "facilitate", "init_project", "clarify_requirements", "create_spec", "challenge_spec", "check_readiness", "update_status", "update_status_batch", "package_handoff", "validate", "reconcile_spec", "create_rule", "create_skill", "skill_search", "configure_code_graph", "code_graph_status"];
 export declare function registerSddTools(server: McpServer): void;
 //# sourceMappingURL=register-sdd-tools.d.ts.map

package/dist/tools/register-sdd-tools.js

@@ -28,6 +28,8 @@ export const OFFICIAL_SDD_TOOL_NAMES = [
     'create_rule',
     'create_skill',
     'skill_search',
+    'configure_code_graph',
+    'code_graph_status',
 ];
 const OFFICIAL_SDD_TOOL_SET = new Set(OFFICIAL_SDD_TOOL_NAMES);
 const noop = () => undefined;

package/dist/tools/safe-handler.js

@@ -17,6 +17,7 @@ import { consumeUpdateBanner } from '../engine/update-notifier.js';
 import { getOrCreateInstallationId } from '../engine/telemetry/telemetry-store.js';
 import { compressToolOutput } from './output-compressor.js';
 import { recordToolTokens as recordLlmTokens } from '../engine/llm-runtime/index.js';
+import { guardToolResultOutput } from './output-integrity-guard.js';
 // SPEC-902: Structured error contract
 import { wrapError, isStructuredError } from '../engine/errors/error-wrapper.js';
 import { getErrorRecoveryRegistry } from '../engine/errors/registry-loader.js';
@@ -279,26 +280,27 @@ function safeWithTelemetry(toolName, handler) {
                     content: [...withDrift.content, { type: 'text', text: updateBanner }],
                 }
                 : withDrift;
+            const guardedResult = guardToolResultOutput(toolName, finalResult);
             // Report validation errors (isError:true returned by handler logic, not exceptions)
-            if (toolName !== undefined && finalResult.isError === true) {
-                const firstContent = finalResult.content[0];
+            if (toolName !== undefined && guardedResult.isError === true) {
+                const firstContent = guardedResult.content[0];
                 const errText = firstContent?.type === 'text' ? firstContent.text : 'unknown error';
                 reportToolValidationError(toolName, errText);
             }
             // Record token usage for successful calls (fire-and-forget, only when projectPath available)
-            if (toolName !== undefined && projectPath !== undefined && finalResult.isError !== true) {
-                const outputText = extractOutputText(finalResult);
+            if (toolName !== undefined && projectPath !== undefined && guardedResult.isError !== true) {
+                const outputText = extractOutputText(guardedResult);
                 recordToolTokens(toolName, projectPath, args, outputText, SESSION_ID);
             }
             // SPEC-460: Track real token estimates in LLM runtime (session-scoped, measured)
             if (toolName !== undefined) {
                 const inputText = JSON.stringify(args);
-                const outputText = extractOutputText(finalResult);
+                const outputText = extractOutputText(guardedResult);
                 recordLlmTokens(toolName, inputText, outputText);
             }
             // Emit tool_used telemetry for successful calls (fire-and-forget)
             /* v8 ignore start */
-            if (toolName !== undefined && finalResult.isError !== true && isErrorReportingEnabled()) {
+            if (toolName !== undefined && guardedResult.isError !== true && isErrorReportingEnabled()) {
                 getOrCreateInstallationId()
                     .then((installationId) => {
                     sendTelemetryEvent({
@@ -331,7 +333,7 @@ function safeWithTelemetry(toolName, handler) {
                     const partial = buildAuditEntry({
                         toolName,
                         args,
-                        outputType: finalResult.isError === true ? 'error' : 'success',
+                        outputType: guardedResult.isError === true ? 'error' : 'success',
                         durationMs: Date.now() - startTime,
                         prevHash,
                     });
@@ -344,9 +346,9 @@ function safeWithTelemetry(toolName, handler) {
             /* v8 ignore stop */
             // SPEC-563: Auto session checkpoint — fire-and-forget, non-blocking
             if (toolName !== undefined) {
-                maybeWriteCheckpoint(toolName, finalResult.isError !== true, projectPath);
+                maybeWriteCheckpoint(toolName, guardedResult.isError !== true, projectPath);
             }
-            return finalResult;
+            return guardedResult;
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);