@planu/cli 4.3.3 → 4.3.5

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+## [4.3.5] - 2026-05-24
+
+### Features
+- feat(codegraph): expose Colby CodeGraph setup and status tools on the official MCP surface
+
+### Bug Fixes
+- fix(create-spec): render structured post-creation suggestions as readable next steps
+- fix(mcp): guard malformed human-facing tool output before it reaches clients
+
+
+## [4.3.4] - 2026-05-22
+
+**Tarball SHA-256:** `e1ac042fd623c1421d7a0788fed14c369472489180ffe80eb8bce4d422d360d8`
+
+### Bug Fixes
+- fix(planu): keep host adapters outside managed state
+
+
 ## [4.3.3] - 2026-05-22
 
 **Tarball SHA-256:** `d681d7d176a263f3b059c4ed5fbc7647a17758dc3c56cc79fd47658bab082fe6`
@@ -3930,4 +3948,4 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 - Mermaid diagram generation (architecture, sequence, state machine, ER, data flow)
 - Multi-language i18n (EN/ES/PT) for generated specs
 - Clean Architecture (hexagonal) — engine, tools, storage, types layers
-- 10,857 tests with ≥95% coverage
+- 10,857 tests with ≥95% coverage

package/dist/config/license-plans.json

@@ -42,12 +42,14 @@
     "check_update_status",
     "check_versions",
     "clarify_requirements",
+    "code_graph_status",
     "compliance_coverage_report",
     "compliance_gap_analysis",
     "compliance_gate_status",
     "compliance_score_report",
     "config_health",
     "configure_approval_policy",
+    "configure_code_graph",
     "configure_compliance",
     "configure_deploy_target",
     "configure_memory",

package/dist/engine/code-graph-configurator.d.ts

@@ -19,5 +19,5 @@ export declare function buildStatusResult(config: ClaudeJsonConfig): CodeGraphSt
 /**
  * Return the key used in .claude.json for a given action.
  */
-export declare function actionToProviderKey(action: 'setup-codegraph-context' | 'setup-pathfinder' | 'setup-axon'): string;
+export declare function actionToProviderKey(action: 'setup-colby-codegraph' | 'setup-codegraph-context' | 'setup-pathfinder' | 'setup-axon'): string;
 //# sourceMappingURL=code-graph-configurator.d.ts.map

package/dist/engine/code-graph-configurator.js

@@ -2,6 +2,12 @@
 // Provider definitions
 // ---------------------------------------------------------------------------
 const PROVIDER_DEFS = [
+    {
+        key: 'codegraph',
+        provider: 'colby-codegraph',
+        command: 'npx',
+        args: ['-y', '@colbymchenry/codegraph', 'serve', '--mcp'],
+    },
     {
         key: 'codegraphcontext',
         provider: 'codegraph-context',
@@ -71,6 +77,7 @@ export function buildStatusResult(config) {
  */
 export function actionToProviderKey(action) {
     const map = {
+        'setup-colby-codegraph': 'codegraph',
         'setup-codegraph-context': 'codegraphcontext',
         'setup-pathfinder': 'code-pathfinder',
         'setup-axon': 'axon',

package/dist/engine/spec-migrator/planu-canonical-policy.js

@@ -4,6 +4,7 @@ export const PLANU_CANONICAL_POLICY = {
     canonicalRootFiles: ['conventions.json', 'context.md', 'session-context.md', 'session.json'],
     canonicalRootDirs: ['releases', 'specs'],
     canonicalSpecFiles: ['spec.md'],
+    forbiddenHostAssetRootDirs: ['agents', 'skills', 'rules', 'hooks'],
     generatedRuntimePatterns: [
         'planu/index.html',
         'planu/roadmap.html',
@@ -57,6 +58,12 @@ export function canonicalContractText() {
         '  specs/',
         '    SPEC-XXX-slug/',
         '      spec.md',
+        '',
+        'Host adapters are written outside planu/:',
+        '  Claude Code: .claude/agents, .claude/skills, .claude/rules',
+        '  Codex: AGENTS.md, .agents/skills, .codex/agents',
+        '  Gemini: GEMINI.md, .gemini/skills',
+        '  Cursor: .cursor/rules/planu.mdc',
     ].join('\n');
 }
 //# sourceMappingURL=planu-canonical-policy.js.map

package/dist/hosts/codex/config-scaffold.js

@@ -13,6 +13,7 @@ import { join } from 'node:path';
 import { detectCodexWorkspace } from './workspace-scope.js';
 import { buildRulesForHost } from '../../engine/host-rules-templates/index.js';
 import { assertEnglishOnlyArtifactText } from '../../engine/spec-language/english-only.js';
+import { generateImplementerRole, generateReviewerRole, generateSpecWriterRole, } from '../../engine/ai-integration/codex/agent-roles-generator.js';
 const CODEX_CONFIG_TOML = `# .openai/config.toml — Planu Codex workspace configuration
 # Auto-generated by Planu init_project. Safe to customize.
 
@@ -69,6 +70,7 @@ export async function scaffoldCodexConfig(projectPath, planuVersion = '1.96.0')
     await mkdir(openaiDir, { recursive: true });
     await writeIfMissing(join(openaiDir, 'config.toml'), CODEX_CONFIG_TOML);
     await writeIfMissing(join(projectPath, 'AGENTS.md'), AGENTS_MD_CONTENT);
+    await scaffoldCodexAgentRoles(projectPath);
     await injectRulesBlock(join(projectPath, 'AGENTS.md'), planuVersion);
 }
 // ---------------------------------------------------------------------------
@@ -86,6 +88,15 @@ async function writeIfMissing(filePath, content) {
         await writeFile(filePath, content, 'utf-8');
     }
 }
+async function scaffoldCodexAgentRoles(projectPath) {
+    const agentsDir = join(projectPath, '.codex', 'agents');
+    await mkdir(agentsDir, { recursive: true });
+    await Promise.all([
+        writeIfMissing(join(agentsDir, 'spec-writer.toml'), generateSpecWriterRole()),
+        writeIfMissing(join(agentsDir, 'implementer.toml'), generateImplementerRole()),
+        writeIfMissing(join(agentsDir, 'reviewer.toml'), generateReviewerRole()),
+    ]);
+}
 const PLANU_RULES_BLOCK_REGEX = /<!-- planu:rules:start[\s\S]*?<!-- planu:rules:end -->/;
 const PLANU_RULES_START_REGEX = /<!-- planu:rules:start[^>]* -->/;
 /**

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);

package/dist/tools/tool-registry/group-infra.js

@@ -71,6 +71,8 @@ import { handleAuditClaudeConfig } from '../audit-claude-config.js';
 import { handleGenerateDocsSite } from '../generate-docs-site.js';
 // ── Memory config tools (register-memory-config-tools.ts) ────────────────────
 import { handleConfigureMemory, handleMemoryStatus } from '../memory-config-handler.js';
+// ── Code graph tools (SPEC-376 / SPEC-1060) ─────────────────────────────────
+import { handleConfigureCodeGraph, handleCodeGraphStatus } from '../code-graph-handler.js';
 // ── Onboarding tools (register-onboarding-tools.ts) ──────────────────────────
 import { handleStartOnboarding, handleGuidedTour, handleOnboardingChecklist, handleQuickStart, handleOnboardingProgress, } from '../onboarding-handler.js';
 // ── Docs registry tools (register-docs-registry-tools.ts) ────────────────────
@@ -827,6 +829,30 @@ export function registerInfraGroupTools(server) {
             projectPath: z.string().describe('Absolute path to the project root directory'),
         },
     }, safeLicensed('memory_status', async (args) => handleMemoryStatus(args)));
+    // ── Code graph tools ──────────────────────────────────────────────────────
+    server.registerTool('configure_code_graph', {
+        description: 'Configure a local code graph MCP provider for the project. Supports Colby CodeGraph, CodeGraphContext, Pathfinder, and Axon. Writes the provider entry to .claude.json.',
+        annotations: { title: 'Configure Code Graph', readOnlyHint: false },
+        inputSchema: {
+            projectPath: z.string().min(1).max(4096).describe('Absolute path to the project root'),
+            action: z
+                .enum([
+                'setup-colby-codegraph',
+                'setup-codegraph-context',
+                'setup-pathfinder',
+                'setup-axon',
+                'status',
+            ])
+                .describe('setup-colby-codegraph: configure @colbymchenry/codegraph | setup-codegraph-context: configure CodeGraphContext | setup-pathfinder: configure Pathfinder | setup-axon: configure Axon | status: show current provider status'),
+        },
+    }, safeLicensed('configure_code_graph', async (args) => handleConfigureCodeGraph(args)));
+    server.registerTool('code_graph_status', {
+        description: 'Returns the current code graph MCP provider status from .claude.json, including the active provider if one is configured.',
+        annotations: { title: 'Code Graph Status', readOnlyHint: true },
+        inputSchema: {
+            projectPath: z.string().min(1).max(4096).describe('Absolute path to the project root'),
+        },
+    }, safeLicensed('code_graph_status', async (args) => handleCodeGraphStatus(args)));
     // ── Onboarding tools ───────────────────────────────────────────────────────
     server.registerTool('start_onboarding', {
         description: 'Start interactive onboarding for a new project. Generates personalized recommendations based on your role, project type, and team size. Returns a markdown guide with next steps.',

package/dist/types/code-graph-integration.d.ts

@@ -1,5 +1,5 @@
-export type CodeGraphProvider = 'codegraph-context' | 'pathfinder' | 'axon';
-export type CodeGraphAction = 'setup-codegraph-context' | 'setup-pathfinder' | 'setup-axon' | 'status';
+export type CodeGraphProvider = 'colby-codegraph' | 'codegraph-context' | 'pathfinder' | 'axon';
+export type CodeGraphAction = 'setup-colby-codegraph' | 'setup-codegraph-context' | 'setup-pathfinder' | 'setup-axon' | 'status';
 export interface CodeGraphSetupInput {
     projectPath: string;
     action: CodeGraphAction;

package/dist/types/spec-format.d.ts

@@ -47,6 +47,7 @@ export interface PlanuCanonicalPathPolicy {
     readonly canonicalRootFiles: readonly string[];
     readonly canonicalRootDirs: readonly string[];
     readonly canonicalSpecFiles: readonly string[];
+    readonly forbiddenHostAssetRootDirs: readonly string[];
     readonly generatedRuntimePatterns: readonly string[];
     readonly legacyMergeBeforeDeleteFiles: readonly string[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.3.3",
+  "version": "4.3.5",
   "description": "Planu — MCP Server for Spec Driven Development with native Rust acceleration for hot paths. Cross-platform (Linux/macOS/Windows, x64/arm64, glibc/musl).",
   "type": "module",
   "main": "dist/index.js",
@@ -32,14 +32,14 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "4.3.3",
-    "@planu/core-darwin-x64": "4.3.3",
-    "@planu/core-linux-arm64-gnu": "4.3.3",
-    "@planu/core-linux-arm64-musl": "4.3.3",
-    "@planu/core-linux-x64-gnu": "4.3.3",
-    "@planu/core-linux-x64-musl": "4.3.3",
-    "@planu/core-win32-arm64-msvc": "4.3.3",
-    "@planu/core-win32-x64-msvc": "4.3.3"
+    "@planu/core-darwin-arm64": "4.3.5",
+    "@planu/core-darwin-x64": "4.3.5",
+    "@planu/core-linux-arm64-gnu": "4.3.5",
+    "@planu/core-linux-arm64-musl": "4.3.5",
+    "@planu/core-linux-x64-gnu": "4.3.5",
+    "@planu/core-linux-x64-musl": "4.3.5",
+    "@planu/core-win32-arm64-msvc": "4.3.5",
+    "@planu/core-win32-x64-msvc": "4.3.5"
   },
   "engines": {
     "node": ">=24.0.0"