@planu/cli 5.7.4 → 5.7.6

package/dist/resources/process.js

@@ -16,90 +16,63 @@ function getSddProcess() {
             {
                 id: 'initializing',
                 name: '1. Initialize',
-                tools: ['init_project', 'init_constitution', 'detect_agent'],
-                description: 'Detect project language, framework, architecture, and conventions. ' +
-                    'Generate the project constitution. Detect the AI agent platform in use.',
+                tools: ['init_project'],
+                description: 'Load or bootstrap the Planu project context for the current repository.',
             },
             {
-                id: 'analyzing',
-                name: '2. Analyze',
-                tools: [
-                    'clarify_requirements',
-                    'suggest_stack',
-                    'check_versions',
-                    'consult_docs',
-                    'discover_mcps',
-                    'suggest_mcps',
-                    'suggest_tooling',
-                ],
-                description: 'Clarify requirements, analyze the stack, check dependency versions, ' +
-                    'discover available MCP servers, and assess dev lifecycle tooling.',
-            },
-            {
-                id: 'creating-spec',
-                name: '3. Create Spec',
-                tools: ['create_spec', 'reverse_engineer', 'estimate'],
-                description: 'Create a full SDD spec.md from requirements or ' +
-                    'reverse-engineer from existing code. Estimate effort, cost, and tokens.',
+                id: 'defining',
+                name: '2. Define',
+                tools: ['facilitate', 'create_spec'],
+                description: 'Facilitate requirements discovery through the universal SDD entry point, ' +
+                    'then create the spec.md that becomes the contract for implementation.',
             },
             {
-                id: 'filtering',
-                name: '4. Filter & Enrich',
+                id: 'approving',
+                name: '3. Refine & Approve',
                 tools: [
-                    'generate_adr',
-                    'design_schema',
-                    'define_ui_contract',
                     'challenge_spec',
-                    'generate_execution_plan',
-                ],
-                description: 'Enrich the spec with architecture decisions, database schema, UI contracts, ' +
-                    'resilience analysis, and step-by-step execution plans.',
-            },
-            {
-                id: 'reviewing',
-                name: '5. Review',
-                tools: [
-                    'summarize_spec',
-                    'generate_checklist',
-                    'reconcile_spec',
-                    'list_specs',
+                    'check_readiness',
+                    'estimate',
+                    'request_changes',
                     'update_status',
                 ],
-                description: 'Review specs via summaries and checklists. Reconcile with changes. ' +
-                    'Transition spec status through the lifecycle.',
+                description: 'Stress-test the spec, verify it has enough detail to implement, estimate ' +
+                    'effort and cost, request changes if gaps remain, and move the spec through ' +
+                    'draft → review → approved.',
             },
             {
                 id: 'implementing',
-                name: '6. Implement',
-                tools: [
-                    'generate_skill',
-                    'generate_sub_agent',
-                    'generate_rules',
-                    'manage_git',
-                    'manage_context',
-                    'orchestrate',
-                ],
-                description: 'Generate agent skills and rules. Manage git branches and PRs. ' +
-                    'Orchestrate multi-agent workflows. Persist context across sessions.',
+                name: '4. Implement',
+                tools: ['package_handoff', 'bump_spec_version'],
+                description: 'Generate the implementation handoff package for the coding agent and bump ' +
+                    "the spec's SemVer as its contract evolves.",
             },
             {
                 id: 'validating',
-                name: '7. Validate',
-                tools: ['validate', 'detect_drift', 'audit', 'generate_tests'],
-                description: 'Validate implementation against spec. Detect drift. Audit code quality. ' +
-                    'Generate and run test plans.',
+                name: '5. Validate',
+                tools: ['validate', 'get_job', 'restart_job'],
+                description: 'Check the implementation against acceptance criteria, poll the durable ' +
+                    'validation job to completion, and restart it if it fails or is cancelled.',
+            },
+            {
+                id: 'closing',
+                name: '6. Reconcile & Close',
+                tools: ['reconcile_spec', 'migrate_legacy_spec', 'update_status_batch'],
+                description: 'Reconcile implementation drift back into the spec, migrate legacy spec docs ' +
+                    'onto the canonical spec.md, and batch-transition specs to done. Shipping ' +
+                    'runs the local-first release contract (`pnpm check:preflight`, then ' +
+                    '`pnpm release:local`) outside the MCP tool surface.',
             },
             {
-                id: 'documenting',
-                name: '8. Document & Ship',
-                tools: ['generate_docs', 'generate_docs_site', 'integrate_pm', 'learn_pattern'],
-                description: 'Generate documentation, run the local-first release contract ' +
-                    '(`pnpm check:preflight`, `pnpm release:local` when shipping), ' +
-                    'sync with project management tools, and learn patterns for future estimations.',
+                id: 'tracking',
+                name: '7. Track',
+                tools: ['list_specs', 'planu_status', 'session_checkpoint'],
+                description: 'List specs and their status, check overall project health, and persist ' +
+                    'session context so work can resume across sessions.',
             },
         ],
         specLifecycle: ['draft', 'review', 'approved', 'implementing', 'done'],
-        totalTools: 104,
+        totalTools: 19,
     };
 }
 /**

package/dist/storage/session-state-store.js

@@ -31,6 +31,8 @@ export function getStagedFiles(projectPath) {
             cwd: projectPath,
             encoding: 'utf-8',
             stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 5_000,
+            maxBuffer: 10 * 1024 * 1024,
         });
         return output
             .split('\n')

package/dist/tools/challenge-spec/scenarios-utils.js

@@ -33,8 +33,8 @@ const CAPABILITY_SIGNALS = {
         /\bbatch\s+upload\b/i,
     ],
     scale: [
-        /\b(?:traffic|load\b(?![\s‐-―-]+bearing)|throughput|requests?\s+per\s+second|concurrent\s+users?)\b/i,
-        /\b(?:auto[ -]?scal|load\s+test|capacity\s+plan)/i,
+        /\b(?:traffic|throughput|requests?\s+per\s+second|concurrent\s+users?)\b/i,
+        /\b(?:auto[ -]?scal|load\s+(?:test|balanc|shedding|envelope|spike)|(?:peak|heavy|normal|sustained|read|write)\s+load|capacity\s+plan)/i,
         /\b(?:data\s+growth|growing\s+dataset|query\s+performance\s+at\s+scale)\b/i,
     ],
     dataWrite: [

package/dist/tools/configure-checkpoint-policy.js

@@ -1,16 +1,16 @@
 // tools/configure-checkpoint-policy.ts — Configure auto checkpoint policy (SPEC-563).
-import { sessionTracker } from '../engine/session/session-tracker.js';
+import { setCheckpointPolicy, getCheckpointPolicy } from '../engine/session/session-tracker.js';
 import { compactResult } from './output-formatter.js';
 /**
  * Handle the configure_checkpoint_policy tool.
  * Updates threshold and/or enabled flag, returns the current policy.
  */
 export function handleConfigureCheckpointPolicy(args) {
-    sessionTracker.setPolicy({
+    setCheckpointPolicy({
         threshold: args.threshold,
         enabled: args.enabled,
     });
-    const policy = sessionTracker.getPolicy();
+    const policy = getCheckpointPolicy();
     return compactResult(`Checkpoint policy updated for ${args.projectPath}.\n` +
         `Threshold: every ${String(policy.threshold)} calls, ` +
         `enabled: ${String(policy.enabled)}.`);

package/dist/tools/create-spec-helpers.js

@@ -26,11 +26,8 @@ export async function tryAutoSetupGit(projectId, specId, options) {
     /* v8 ignore start -- requires real git repo with branches */
     try {
         const r = await handleAutoSetup(projectId, specId, undefined, options);
-        if (!r.isError && r.content[0]?.type === 'text') {
-            const data = JSON.parse(r.content[0].text);
-            if (typeof data.newBranch !== 'string') {
-                return undefined;
-            }
+        const data = r.structuredContent;
+        if (!r.isError && data && typeof data.newBranch === 'string') {
             return { data, branch: data.newBranch };
         }
     }

package/dist/tools/create-spec.js

@@ -20,6 +20,7 @@ import { generateLeanTechnicalContent, } from '../engine/spec-format/lean-techni
 import { extractFilesFromSpecBody, extractMarkerDeclaredPaths, } from '../engine/spec-format/technical-md-populator.js';
 import { buildCanonicalUnifiedSpecContent, containsUnresolvedContractPlaceholder, validateUnifiedSpecCandidate, } from '../engine/spec-format/unified-spec-builder.js';
 import { buildImplementationContractSection } from '../engine/implementation-contract/index.js';
+import { updateFrontmatterField } from '../engine/frontmatter-parser.js';
 import { resolveEnglishOnlySpecGate } from '../engine/spec-language/english-only.js';
 import { FallbackGenerator } from '../engine/spec-generator/index.js';
 import { analyzeProjectForSpec, getEmptyAutopilotResult, } from './create-spec/autopilot-analyzer.js';
@@ -1257,7 +1258,7 @@ async function prepareCreateSpecCandidate(initialParams, server) {
         outOfScope,
         verificationCommands,
     });
-    const unifiedSpec = buildCanonicalUnifiedSpecContent({
+    let unifiedSpec = buildCanonicalUnifiedSpecContent({
         leanSpecBody: leanSpec,
         sourceDescription: params.description,
         technicalBody: leanTechnical,
@@ -1269,12 +1270,18 @@ async function prepareCreateSpecCandidate(initialParams, server) {
     const candidateValidation = validateUnifiedSpecCandidate(unifiedSpec, {
         groundedFilePaths: groundedTechnical.records.map((record) => record.path),
     });
-    if (!candidateValidation.valid) {
+    // SPEC-1435: MISSING_EXECUTABLE_CRITERIA no longer blocks persistence — plain-text
+    // criteria are accepted input today (checkbox items via extractAcceptanceCriteriaTexts),
+    // and the constant GIVEN/WHEN/THEN scaffold that used to satisfy this check has been
+    // retired. The readiness-checker approval gate now blocks a zero-BDD spec at
+    // review -> approved instead; here it downgrades to a persisted quality warning.
+    const blockingCandidateIssues = candidateValidation.issues.filter((issue) => issue.code !== 'MISSING_EXECUTABLE_CRITERIA');
+    if (blockingCandidateIssues.length > 0) {
         return earlyPreparation({
             content: [
                 {
                     type: 'text',
-                    text: `Unified spec candidate is invalid: ${candidateValidation.issues
+                    text: `Unified spec candidate is invalid: ${blockingCandidateIssues
                         .slice(0, 3)
                         .map((issue) => issue.message)
                         .join('; ')}`,
@@ -1285,10 +1292,20 @@ async function prepareCreateSpecCandidate(initialParams, server) {
                 error: 'SPEC_FORMAT_INVALID',
                 code: 422,
                 persisted: false,
-                issues: candidateValidation.issues,
+                issues: blockingCandidateIssues,
             },
         });
     }
+    if (candidateValidation.issues.some((issue) => issue.code === 'MISSING_EXECUTABLE_CRITERIA')) {
+        const nonExecutableCriteriaWarning = 'Acceptance criteria are not executable GIVEN/WHEN/THEN — restate them before approval';
+        spec.qualityWarnings = [
+            ...new Set([...(spec.qualityWarnings ?? []), nonExecutableCriteriaWarning]),
+        ];
+        // unifiedSpec's frontmatter was already serialized from `spec` before this warning was
+        // known — patch the persisted YAML field directly rather than re-serializing the whole
+        // candidate.
+        unifiedSpec = updateFrontmatterField(unifiedSpec, 'qualityWarnings', JSON.stringify(spec.qualityWarnings));
+    }
     const genericOutputGate = checkGenericSpecOutput(unifiedSpec);
     if (!genericOutputGate.passed) {
         return earlyPreparation({

package/dist/tools/facilitate.js

@@ -39,8 +39,8 @@ function buildExistingProjectResponse(description) {
     return (`I'll run a diagnostic on your project.\n\n` +
         `Please provide the project path and call:\n` +
         `- \`init_project\` with your project path (if not yet initialized)\n` +
-        `- \`reverse_engineer\` to analyze the codebase\n` +
-        `- \`audit\` to check spec health\n\n` +
+        `- \`list_specs\` to see existing specs\n` +
+        `- \`planu_status\` to check overall project health\n\n` +
         `Request received: "${description.slice(0, 120)}"`);
 }
 // ---------------------------------------------------------------------------
@@ -51,7 +51,6 @@ const PROBLEM_TO_TOOL = [
     [/validat/i, 'validate', 'validate a spec'],
     [/spec|user stor/i, 'create_spec', 'create a spec/user story'],
     [/estimat/i, 'estimate', 'estimate effort and cost'],
-    [/test/i, 'generate_tests', 'generate tests'],
     [/document|doc/i, 'generate_docs', 'generate documentation'],
     [/drift|diverge/i, 'detect_drift', 'detect spec drift'],
     [/schema|database|db/i, 'design_schema', 'design a database schema'],
@@ -69,10 +68,8 @@ function buildConcreteProblemResponse(description) {
     }
     return (`I can help with that! Here are the most relevant Planu tools:\n\n` +
         `- \`create_spec\` — write a new user story / spec\n` +
-        `- \`clarify_requirements\` — clarify vague requirements\n` +
         `- \`estimate\` — estimate effort and cost\n` +
-        `- \`validate\` — check if a spec is complete\n` +
-        `- \`generate_tests\` — generate test scaffolds\n\n` +
+        `- \`validate\` — check if a spec is complete\n\n` +
         `What specifically would you like to do?`);
 }
 // ---------------------------------------------------------------------------

package/dist/tools/git/branch-ops.js

@@ -54,7 +54,10 @@ export async function handleCreateBranch(projectId, specId, config, resolvedProj
                     ? `Switched to existing branch '${branchName}'`
                     : `Branch '${branchName}' already exists (checkout left untouched)`,
             };
-            return compactResult(formatKeyValue(result));
+            return {
+                ...compactResult(formatKeyValue(result)),
+                structuredContent: result,
+            };
         }
     }
     catch {
@@ -74,7 +77,10 @@ export async function handleCreateBranch(projectId, specId, config, resolvedProj
         branchName,
         message: ti('tools.manage_git.success', { action: 'create-branch' }),
     };
-    return compactResult(formatKeyValue(result));
+    return {
+        ...compactResult(formatKeyValue(result)),
+        structuredContent: result,
+    };
 }
 export async function handleCheckBranch(projectId, _specId, config) {
     const projectPath = await resolveProjectPath(projectId);
@@ -217,7 +223,10 @@ export async function handleAutoSetup(projectId, specId, config, options) {
                     ? `Switched to existing branch '${branchName}' (${gitFlowType} workflow detected)`
                     : `Branch '${branchName}' already exists (checkout left untouched)`,
             };
-            return compactResult(formatKeyValue(result));
+            return {
+                ...compactResult(formatKeyValue(result)),
+                structuredContent: result,
+            };
         }
     }
     catch {
@@ -235,7 +244,10 @@ export async function handleAutoSetup(projectId, specId, config, options) {
             ? `Created branch '${branchName}' from '${baseBranch}' (${gitFlowType} workflow detected)`
             : `Created branch '${branchName}' from '${baseBranch}' without switching the checkout`,
     };
-    return compactResult(formatKeyValue(result));
+    return {
+        ...compactResult(formatKeyValue(result)),
+        structuredContent: result,
+    };
 }
 // ---------------------------------------------------------------------------
 // Worktree operations (SPEC-260)

package/dist/tools/github-release-handler.js

@@ -252,26 +252,7 @@ export async function handleCreateRelease(args, exec = defaultExec) {
             /* best-effort — release_completed cascade never blocks the release response */
         }
     })();
-    // SPEC-1003: Auto-merge develop to main after release (best-effort)
-    void (async () => {
-        try {
-            const releasePath = process.cwd();
-            const run = promisify(nodeExecFile);
-            const { stdout: currentBranch } = await run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
-                cwd: releasePath,
-            });
-            if (currentBranch.trim() === 'develop') {
-                await run('git', ['checkout', 'main'], { cwd: releasePath });
-                await run('git', ['merge', 'develop', '--no-edit'], { cwd: releasePath });
-                await run('git', ['push', '--no-verify', 'origin', 'main'], { cwd: releasePath });
-                await run('git', ['checkout', 'develop'], { cwd: releasePath });
-                outputLines.push('  Auto-merge: develop → main');
-            }
-        }
-        catch {
-            /* best-effort — auto-merge never blocks release */
-        }
-    })();
+    outputLines.push('  Mirror sync (run manually if develop exists): git checkout develop && git merge --ff-only origin/main && git push origin develop');
     return {
         content: [
             {

package/dist/tools/heal-spec-docs.js

@@ -13,6 +13,7 @@ import { replaceSectionInSpec } from '../engine/spec-format/replace-section.js';
 import { executionRemove } from '../engine/execution/deadline-io.js';
 import { buildMigrationDirective, scanLegacyArtifacts, } from '../engine/spec-migrator/legacy-classifier.js';
 import { escapeRegex } from '../core/shared/strings.js';
+import { isPlaceholderTechnical } from '../engine/spec-migrator/placeholder-technical.js';
 const SPANISH_INDICATORS = [
     'de',
     'del',
@@ -36,19 +37,6 @@ const SPANISH_INDICATORS = [
 // ---------------------------------------------------------------------------
 // Placeholder detection
 // ---------------------------------------------------------------------------
-function isPlaceholderTechnical(content) {
-    if (content.includes('(pending)')) {
-        return true;
-    }
-    if (/--[a-z]/.test(content)) {
-        return true;
-    }
-    if (content.includes('(to be determined)') &&
-        !/\.(ts|tsx|js|jsx|py|rb|go|java|cs)/.test(content)) {
-        return true;
-    }
-    return false;
-}
 function hasInlineTechnicalFilesPlaceholder(content) {
     return /^##\s+Technical\b[\s\S]*?^##\s+Files\b[\s\S]*?(?:\(pending\)|\(to be determined\)|\bTBD\b|--[a-z])/im.test(content);
 }

package/dist/tools/init-project/agents-md-writer.js

@@ -34,13 +34,13 @@ Auto-generated by \`init_project\`. Mirrors CLAUDE.md for IDEs that read AGENTS.
 \`\`\`
 facilitate("what to build") → create_spec → challenge_spec → check_readiness
 → update_status(review) → approve → update_status(approved) → implement
-→ validate (ack) → watch_job (completed) → inspect job.result → update_status(done)
+→ validate (ack) → get_job (poll until completed) → inspect job.result → update_status(done)
 \`\`\`
 
 ## Durable Validation Gate
 
-1. Call \`validate\` and capture \`operationId\`, \`projectId\`, \`workspaceId\`, and \`cursor\` from the acknowledgement
-2. Call \`watch_job\` with those identifiers and the latest cursor until the job reaches a terminal state
+1. Call \`validate\` and capture \`operationId\`, \`projectId\`, and \`workspaceId\` from the acknowledgement
+2. Poll \`get_job\` with those identifiers until the job reaches a terminal state
 3. Require \`completed\` and inspect \`job.result.structuredContent\`; stop on \`failed\`, \`dead-letter\`, or \`cancelled\`
 4. Call \`update_status(done)\` only when the completed result reports \`ready: true\`, \`status: "passing"\`, and passing quality gates
 
@@ -52,7 +52,7 @@ facilitate("what to build") → create_spec → challenge_spec → check_readine
 ## Session End
 
 - Call \`session_checkpoint\` to save context
-- Run \`validate\`, await the completed job with \`watch_job\`, inspect \`job.result.structuredContent\`, then call \`update_status(done)\`
+- Run \`validate\`, poll \`get_job\` until completed, inspect \`job.result.structuredContent\`, then call \`update_status(done)\`
 
 ## Quick Reference
 
@@ -79,7 +79,7 @@ Auto-generated by init_project.
 1. Before writing any code, call facilitate() or create_spec() first.
 2. Never write code without an approved Planu spec.
 3. Always call validate() after implementation; it returns a durable job acknowledgement, not pass/fail.
-4. Call watch_job() until completed and inspect job.result.structuredContent before marking done.
+4. Poll get_job() until completed and inspect job.result.structuredContent before marking done.
 5. Use update_status() to track progress: draft → review → approved → implementing → done.
 
 ## Session
@@ -91,7 +91,7 @@ Auto-generated by init_project.
 
 - New feature: facilitate("what to build")
 - Check status: planu_status
-- Mark done: validate, watch_job until completed, inspect job.result.structuredContent, then update_status(done)
+- Mark done: validate, poll get_job until completed, inspect job.result.structuredContent, then update_status(done)
 `;
 async function writeIfMissing(path, content) {
     try {

package/dist/tools/init-project/claude-md-generator.d.ts

@@ -1,4 +1,3 @@
 import type { ProjectKnowledge } from '../../types/project/core.js';
-export declare function buildTeamCoordinationSection(knowledge: ProjectKnowledge): string | null;
 export declare function buildProjectSections(knowledge: ProjectKnowledge): string;
 //# sourceMappingURL=claude-md-generator.d.ts.map

package/dist/tools/init-project/claude-md-generator.js

@@ -214,37 +214,6 @@ function buildDeployment(knowledge) {
     const label = key ? DEPLOY_PLATFORM_MAP[key] : raw;
     return wrap('deployment', `## Deployment\n- **Platform**: ${label}`);
 }
-export function buildTeamCoordinationSection(knowledge) {
-    const isMultiLayer = knowledge.layers.length > 2;
-    const isMonorepo = knowledge.monorepo;
-    if (!isMultiLayer && !isMonorepo) {
-        return null;
-    }
-    const patternList = [
-        '- `implement-and-test` — one agent implements, another writes tests (no shared files)',
-        '- `full-stack` — frontend/backend split with clear API boundary',
-        '- `research-then-build` — researcher gathers context, builder implements',
-        '- `parallel-specs` — N agents implement N independent specs simultaneously',
-    ];
-    const lines = [
-        '## Agent Teams (for 3+ specs in parallel)',
-        '',
-        'When implementing multiple independent specs simultaneously, use Agent Teams:',
-        '',
-        '1. Call `plan_team_distribution` with spec IDs → assigns exclusive file ownership per agent',
-        '2. Call `generate_teammate_prompt` for each teammate → generates isolated prompt with context',
-        '3. Spawn N Claude Code agents with the generated prompts (`claude -p "<prompt>"`)',
-        '4. Call `validate_team_results` after completion → verifies merged code integrity',
-        '',
-        '**When to use teams**: 3+ independent specs ready, estimated effort >8h, clear module boundaries.',
-        '',
-        '**Available patterns:**',
-        ...patternList,
-        '',
-        '> MANDATORY: two teammates NEVER modify the same file — `plan_team_distribution` enforces this.',
-    ];
-    return wrap('team-coordination', lines.join('\n'));
-}
 function buildGitWorkflow(knowledge) {
     const hasConventional = 'commitlint' in knowledge.conventions ||
         (knowledge.conventions['commit-style']?.toLowerCase().includes('conventional') ?? false) ||
@@ -288,10 +257,6 @@ export function buildProjectSections(knowledge) {
     if (gitWorkflow) {
         sections.push(gitWorkflow);
     }
-    const teamCoordination = buildTeamCoordinationSection(knowledge);
-    if (teamCoordination) {
-        sections.push(teamCoordination);
-    }
     // SPEC-655: Single hardcoded skill entry point — all others discovered via find-skills
     sections.push(wrap('find-skills', '## Skill Discovery\nUse find-skills to discover available workflows.'));
     // SPEC-755: Spec location preference — overrides brainstorming skill default (docs/superpowers/specs/)

package/dist/tools/init-project/handler.js

@@ -21,8 +21,11 @@ import { regeneratePages } from '../../engine/doc-generator/portal/index.js';
 import { detectStackPatterns } from './stack-detector.js';
 import { buildProjectConfig } from './config-builder.js';
 import { runSpecMigrations, listProjectSpecs } from './migration-runner.js';
-import { reconcilePortableSpecIndex, describeReconciliationOutcome, } from './portable-index-reconciler.js';
+import { reconcilePortableSpecIndex, buildAlreadyInitializedResult, buildAuthorizedMigrationResult, } from './portable-index-reconciler.js';
 import { refreshCoreHostAssets } from './host-assets-writer.js';
+import { generateWorkflowSkills } from '../../engine/skill-generator/workflow-skill-generator.js';
+import { fileExists } from '../../core/shared/fs.js';
+import { scanLegacyGuidance, summarizeLegacyGuidanceScan } from './legacy-guidance-scanner.js';
 import { runScaffoldWriter } from './scaffold-writer.js';
 import { readAutoInstallFlag, orchestrateSkillInstalls, runHealthCheckWithBaseline, runConventionScanSafe, fireTelemetry, } from './lifecycle-helpers.js';
 import { injectProactiveRules } from '../../engine/claude-md-injector/index.js';
@@ -31,7 +34,7 @@ import { join } from 'node:path';
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
 import { mkdir, stat } from 'node:fs/promises';
-import { generateAgentTeamsRulesIfMissing, generateWorkflowRulesIfMissing, } from './rules-generator.js';
+import { generateWorkflowRulesIfMissing } from './rules-generator.js';
 import { installUniversalRules } from '../../engine/universal-rules/installer.js';
 import { detectHost } from '../../engine/host-detection/detect-host.js';
 import { configurePlanuHooks } from './hooks-configurator.js';
@@ -223,28 +226,15 @@ export async function handleInitProject(params, server) {
             const authorizedMigrations = params.authorizedMigrations ?? [];
             if (isUpdate && authorizedMigrations.length === 0) {
                 const reconciliation = await reconcilePortableSpecIndex(projectPath, projectId);
-                const repositoryFilesChanged = reconciliation.failures.length === 0 ? await refreshCoreHostAssets(projectPath) : [];
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: describeReconciliationOutcome(reconciliation, repositoryFilesChanged),
-                        },
-                    ],
-                    structuredContent: {
-                        projectId,
-                        ...(reconciliation.failures.length === 0 ? { projectPath } : {}),
-                        isUpdate: true,
-                        repositoryFilesChanged,
-                        authorizedMigrations: [],
-                        importedSpecIds: reconciliation.importedSpecIds,
-                        failures: reconciliation.failures,
-                        skippedLegacy: reconciliation.skippedLegacy,
-                        strayRepoRemovals: reconciliation.strayRepoRemovals,
-                        migratedLegacyPaths: legacyMigration.migrated,
-                    },
-                    ...(reconciliation.failures.length > 0 ? { isError: true } : {}),
-                };
+                const canRefresh = reconciliation.failures.length === 0;
+                const legacyGuidanceScan = canRefresh
+                    ? await scanLegacyGuidance(projectPath)
+                    : { healed: [], warnings: [] };
+                const refreshedAssets = canRefresh ? await refreshCoreHostAssets(projectPath) : [];
+                const skillSync = canRefresh && existing !== null && (await fileExists(join(projectPath, '.claude/skills')))
+                    ? await generateWorkflowSkills(projectPath, existing).catch(() => null)
+                    : null;
+                return buildAlreadyInitializedResult(projectId, reconciliation, legacyMigration.migrated, refreshedAssets, legacyGuidanceScan, projectPath, skillSync);
             }
             if (isUpdate) {
                 if (existing === null) {
@@ -261,26 +251,8 @@ export async function handleInitProject(params, server) {
                 const migrationResult = await runSpecMigrations(projectPath, projectId, existing, {
                     repositoryMigration: 'planu-spec-format-v1',
                 });
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: migrationResult.criticalMigrationFailures.length === 0
-                                ? 'Authorized planu-spec-format-v1 migration completed.'
-                                : `Authorized migration completed with ${String(migrationResult.criticalMigrationFailures.length)} blocking issue(s).`,
-                        },
-                    ],
-                    structuredContent: {
-                        projectId,
-                        projectPath,
-                        isUpdate: true,
-                        authorizedMigrations,
-                        repositoryFilesChanged: migrationResult.changedPaths ?? [],
-                        migrationReportPath: migrationResult.migrationReportPath,
-                        criticalMigrationFailures: migrationResult.criticalMigrationFailures,
-                    },
-                    ...(migrationResult.criticalMigrationFailures.length > 0 ? { isError: true } : {}),
-                };
+                const legacyGuidanceScan = await scanLegacyGuidance(projectPath).catch(() => ({ healed: [], warnings: [] }));
+                return buildAuthorizedMigrationResult(projectId, projectPath, authorizedMigrations, migrationResult, legacyGuidanceScan);
             }
             // Get global config for defaults
             const globalConfig = await globalStore.getGlobalConfig();
@@ -439,6 +411,7 @@ export async function handleInitProject(params, server) {
             // Write scaffold files: rules, git setup, constitution, CLAUDE.md, lint, architecture rules
             const scaffoldResult = await runScaffoldWriter(projectPath, projectId, knowledge, recommendedSkills, params.permissionsMode, params.pluginsMode, autoInstallFromConfig);
             const { platform, generatedRules, rulesWritten, additionalFilesWritten, hooksInstalled, gitFlowType, gitignoreUpdated, gitRepoDetected, layoutOffenders, constitutionInitialized, claudeMdUpdated, eslintCreated, prettierCreated, lintSuggestions, architectureRulesWritten, architectureRulesSkipped, planuWorkflowInjected, planuHooksConfigured, planuRulesWritten, gitAutoStageInjected, } = scaffoldResult;
+            const legacyGuidanceScan = await scanLegacyGuidance(projectPath).catch(() => ({ healed: [], warnings: [] }));
             // SPEC-444: Inject proactive behavior rules into project CLAUDE.md
             const proactiveRulesInjected = await injectProactiveRules(join(projectPath, 'CLAUDE.md'), '1.22.0')
                 .then(() => true)
@@ -497,9 +470,6 @@ export async function handleInitProject(params, server) {
             // SPEC-200: Anonymous opt-in telemetry — fire-and-forget, never blocks response
             const neverPrompted = await fireTelemetry(knowledge).catch(() => false);
             // SPEC-457: Auto-bootstrap rules, hooks, skills for detected stack (fire-and-forget)
-            void withAudit(projectPath, 'init_project', 'generateAgentTeamsRulesIfMissing', () => generateAgentTeamsRulesIfMissing(projectPath)).catch(() => {
-                /* best-effort */
-            });
             void withAudit(projectPath, 'init_project', 'generateWorkflowRulesIfMissing', () => generateWorkflowRulesIfMissing(projectPath)).catch(() => {
                 /* best-effort */
             });
@@ -561,6 +531,7 @@ export async function handleInitProject(params, server) {
             if (skillsAutoInstalled.length > 0) {
                 collector.pushOk('skills-installed', `Auto-installed skills: ${skillsAutoInstalled.join(', ')}`);
             }
+            summarizeLegacyGuidanceScan(collector, legacyGuidanceScan);
             const toolResult = buildInitProjectResult({
                 projectId,
                 projectPath,
@@ -620,8 +591,12 @@ export async function handleInitProject(params, server) {
                 branchInfo,
             });
             if (toolResult.structuredContent) {
-                toolResult.structuredContent.repositoryFilesChanged = migrationChangedPaths;
-                toolResult.structuredContent.authorizedMigrations = authorizedMigrations;
+                Object.assign(toolResult.structuredContent, {
+                    repositoryFilesChanged: [...migrationChangedPaths, ...legacyGuidanceScan.healed],
+                    authorizedMigrations,
+                    legacyGuidanceHealed: legacyGuidanceScan.healed,
+                    legacyGuidanceWarnings: legacyGuidanceScan.warnings,
+                });
             }
             // Inject autopilotSummary into structuredContent
             if (collector.hasEntries() && toolResult.structuredContent) {

package/dist/tools/init-project/legacy-guidance-scanner.d.ts

@@ -0,0 +1,12 @@
+import type { AutopilotSummaryCollector } from '../../engine/autopilot/summary-collector.js';
+import type { LegacyGuidanceScanResult } from '../../types/index.js';
+/**
+ * Scan the bounded set of Planu-installed host guidance surfaces for stale
+ * directives that contradict the current spec.md-only contract, and
+ * neutralize what can be neutralized fail-closed. Never touches files
+ * outside the inventoried scan surface (no repo-wide walk).
+ */
+export declare function scanLegacyGuidance(projectPath: string): Promise<LegacyGuidanceScanResult>;
+/** Records a legacy-guidance scan outcome onto an init_project autopilot summary. */
+export declare function summarizeLegacyGuidanceScan(collector: AutopilotSummaryCollector, scan: LegacyGuidanceScanResult): void;
+//# sourceMappingURL=legacy-guidance-scanner.d.ts.map