@planu/cli 3.9.14 → 4.1.0

package/dist/tools/create-spec.js

@@ -2,14 +2,14 @@ import { checkGate } from '../engine/clarification-gate/gate.js';
 import { upsertToken, hashQuestions } from '../engine/clarification-gate/token-store.js';
 import { ti } from '../i18n/index.js';
 import { knowledgeStore, specStore } from '../storage/index.js';
-import { formatSuccess, addNextSteps, toolResult } from './response-helpers.js';
+import { formatSuccess, addNextSteps, toolResult, interactiveResult } from './response-helpers.js';
 import { writeFile, mkdir, rm, readFile, stat } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 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, } from './create-spec/post-creation.js';
+import { setupGitBranch, checkContradictions, fireSpecCreatedHook, generatePostCreationSuggestions, 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';
@@ -36,6 +36,7 @@ import { runPriorDecisionsHint } from './create-spec/adapters/prior-decisions-hi
 import { suggestOutOfScope } from '../engine/scope-boundaries/index.js';
 import { adviseSimilarSpecs } from '../engine/complexity-budget/index.js';
 import { issuePlannerToken } from '../engine/reviewer-tokens/issuer.js';
+import { generateInteractiveQuestions } from './create-spec/question-generator.js';
 /** SPEC-584: Persist a clarification token when interactive questions are emitted. Best-effort. */
 async function persistClarificationToken(earlyReturn, projectId, toolName) {
     try {
@@ -65,7 +66,7 @@ async function runClarificationGate(projectPath, toolName, answers) {
     });
     return gateResult.allow ? null : gateResult.error;
 }
-function handleClarification(_server, _description, _knowledge, autopilot, params) {
+function handleClarification(_server, description, knowledge, autopilot, params) {
     if (!autopilot.needsClarification) {
         return null;
     }
@@ -75,12 +76,32 @@ function handleClarification(_server, _description, _knowledge, autopilot, param
     if (hasAnswers) {
         return null;
     }
-    // The description is too vague — ask the LLM to gather more context from the user.
-    // No hardcoded question templates: the host LLM asks its own contextual questions.
+    const generatedQuestions = generateInteractiveQuestions(description, knowledge);
+    const questions = generatedQuestions.length > 0
+        ? generatedQuestions
+        : [
+            {
+                question: 'What specific behavior should this spec deliver?',
+                header: 'Scope',
+                options: [
+                    {
+                        label: 'User workflow (Recommended)',
+                        description: 'Focus the spec on the end-to-end user behavior and completion state.',
+                    },
+                    {
+                        label: 'Backend behavior',
+                        description: 'Focus the spec on API, persistence, jobs, or integration behavior.',
+                    },
+                    {
+                        label: 'Cleanup/fix',
+                        description: 'Focus the spec on removing stale behavior or fixing a known bug.',
+                    },
+                ],
+                multiSelect: false,
+            },
+        ];
     return {
-        earlyReturn: toolResult('The description needs more detail before a spec can be created.\n\n' +
-            'Ask the user to clarify: what specific behavior they want, who will use it, ' +
-            'and what "done" looks like. Then call create_spec again with the enriched description.', { needsClarification: true }),
+        earlyReturn: interactiveResult(questions, 'The description needs more detail before a spec can be created. Answer the questions, then retry create_spec with clarificationAnswers or an enriched description.', 'universal'),
     };
 }
 const HIGH_RISK_WARNING = 'High-risk spec — consider: ' +
@@ -236,15 +257,12 @@ function computeIdempotencyKey(title, projectPath) {
 }
 /**
  * SPEC-781: Check if async analysis has completed for a given spec.
- * Returns { pending: true } when .analysis.json is absent (analysis still running or never started).
+ * Returns { pending: true } when external analysis state is absent.
  */
 async function checkAnalysisStatus(projectPath, specId) {
     try {
-        const { glob } = await import('glob');
-        const { join: pathJoin } = await import('node:path');
-        const pattern = pathJoin(projectPath, 'planu/specs', `${specId}-*`, '.analysis.json');
-        const matches = await glob(pattern);
-        return { pending: matches.length === 0 };
+        await readFile(getAsyncAnalysisPath(projectPath, specId), 'utf-8');
+        return { pending: false };
     }
     catch {
         return { pending: true };
@@ -358,6 +376,12 @@ export async function handleCreateSpec(inputParams, server) {
         return {
             content: [{ type: 'text', text: DESCRIPTION_EXCEED_MSG }],
             isError: true,
+            structuredContent: {
+                error: 'DESCRIPTION_TOO_LONG',
+                maxChars: DESCRIPTION_MAX_CHARS,
+                actualChars: inputParams.description.length,
+                fixHint: 'Create with a summary description under 3000 chars, then append detailed context through reconcile_spec.',
+            },
         };
     }
     // SPEC-509: resolve projectPath from git root when omitted
@@ -406,7 +430,7 @@ export async function handleCreateSpec(inputParams, server) {
     const idempotencyKey = computeIdempotencyKey(inputParams.title, resolvedPath);
     const existingByKey = await findByIdempotencyKey(resolvedPath, idempotencyKey, hashProjectPath(resolvedPath));
     if (existingByKey) {
-        // SPEC-781: Check if async analysis has completed (.analysis.json exists)
+        // SPEC-781: Check if async analysis has completed in external project data.
         const analysisStatus = await checkAnalysisStatus(resolvedPath, existingByKey.id);
         return {
             content: [
@@ -630,7 +654,7 @@ export async function handleCreateSpec(inputParams, server) {
             });
             // Build result (SPEC-461: lean — no progress, HTML, diagrams, scope filters)
             const result = {
-                // SPEC-781: async analysis running in background (writes .analysis.json when done)
+                // SPEC-781: async analysis running in background (external project data)
                 pendingAnalysis: true,
                 specId: spec.id,
                 title: spec.title,
@@ -684,7 +708,7 @@ export async function handleCreateSpec(inputParams, server) {
             }
             // Dispatch hook event (fire-and-forget)
             fireSpecCreatedHook(projectId, spec, params.projectPath ?? '');
-            // SPEC-781: Fire-and-forget async analysis (writes .analysis.json when complete)
+            // SPEC-781: Fire-and-forget async analysis (external project data)
             runAutopilotAsync(spec.id, params.projectPath ?? '', description);
             // SPEC-713: Track warnings from budgeted post-creation steps
             const budgetWarnings = [];
@@ -770,7 +794,7 @@ export async function handleCreateSpec(inputParams, server) {
             if (budgetWarnings.length > 0) {
                 result.budgetWarnings = budgetWarnings;
             }
-            // SPEC-464: Removed auto-regeneration of planu/index.html — use generate_dashboard on demand
+            // SPEC-1017: No auto-regeneration of project-tree dashboard HTML.
             if (params.projectPath) {
                 notifyStoreChange(params.projectPath, 'specs');
             }

package/dist/tools/flag-spec-gap.d.ts

@@ -13,7 +13,7 @@ export interface FlagSpecGapInput {
  * Handle the flag_spec_gap tool invocation.
  *
  * Validates inputs (severity enum, affectedSpecs pattern + existence),
- * applies defaults, and appends a hash-chained entry to planu/research/gaps.jsonl.
+ * applies defaults, and appends a hash-chained entry to external Planu project data.
  */
 export declare function handleFlagSpecGap(input: FlagSpecGapInput): Promise<ToolResult>;
 //# sourceMappingURL=flag-spec-gap.d.ts.map

package/dist/tools/flag-spec-gap.js

@@ -8,7 +8,7 @@ const VALID_SEVERITIES = ['low', 'medium', 'high'];
  * Handle the flag_spec_gap tool invocation.
  *
  * Validates inputs (severity enum, affectedSpecs pattern + existence),
- * applies defaults, and appends a hash-chained entry to planu/research/gaps.jsonl.
+ * applies defaults, and appends a hash-chained entry to external Planu project data.
  */
 export async function handleFlagSpecGap(input) {
     const { projectId, specId, description } = input;

package/dist/tools/generate-dashboard.js

@@ -4,11 +4,11 @@ import { specStore } from '../storage/index.js';
 import { hashProjectPath } from '../storage/base-store.js';
 export function registerGenerateDashboardTools(server) {
     server.registerTool('generate_spec_dashboard', {
-        description: 'Regenerate planu/index.html dashboard with all specs, metrics, and pagination. Call after bulk changes or to fix a stale dashboard.',
+        description: 'Deprecated compatibility tool. Planu no longer writes generated dashboard HTML into planu/.',
         inputSchema: {
             projectPath: z.string().describe('Absolute path to the project root directory'),
         },
-        annotations: { readOnlyHint: false },
+        annotations: { readOnlyHint: true },
     }, async (args) => {
         const projectId = hashProjectPath(args.projectPath);
         const specs = await specStore.listSpecs(projectId);
@@ -18,7 +18,7 @@ export function registerGenerateDashboardTools(server) {
             content: [
                 {
                     type: 'text',
-                    text: `Dashboard regenerated: ${String(specs.length)} specs (${String(doneCount)} done). File: planu/index.html`,
+                    text: `Dashboard generation is deprecated; no project files were written. Current specs: ${String(specs.length)} (${String(doneCount)} done).`,
                 },
             ],
         };

package/dist/tools/housekeeping-sweep.js

@@ -143,6 +143,21 @@ export async function handleHousekeepingSweep(args, resolvedProjectPath) {
     catch {
         /* best-effort — never block housekeeping_sweep */
     }
+    let strictPlanuCleanup = null;
+    try {
+        const { runStrictPlanuCleanup, validateStrictPlanuLayout } = await import('../engine/spec-migrator/index.js');
+        if (!dryRun) {
+            const cleanup = await runStrictPlanuCleanup(projectPath);
+            strictPlanuCleanup = { deleted: cleanup.deleted, merged: cleanup.merged, offenders: [] };
+        }
+        else {
+            const validation = await validateStrictPlanuLayout(projectPath);
+            strictPlanuCleanup = { deleted: [], merged: [], offenders: validation.offenders };
+        }
+    }
+    catch {
+        /* best-effort — never block housekeeping_sweep */
+    }
     // SPEC-1012: Detect and auto-fix specs released on main but still in non-terminal status
     let releaseStatusDrift = null;
     try {
@@ -186,6 +201,7 @@ export async function handleHousekeepingSweep(args, resolvedProjectPath) {
             details: report,
             ...(orphanSummary ? { orphanBrainstorming: orphanSummary } : {}),
             ...(ephemeralResult ? { ephemeralArtifacts: ephemeralResult } : {}),
+            ...(strictPlanuCleanup ? { strictPlanuCleanup } : {}),
             ...(releaseStatusDrift ? { releaseStatusDrift } : {}),
         },
     };

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

@@ -3,6 +3,7 @@
 // SPEC-972: Added host-aware tool filtering for Codex and other MCP hosts.
 import { writeFile, mkdir, access } from 'node:fs/promises';
 import { join } from 'node:path';
+import { assertEnglishOnlyArtifactText } from '../../engine/spec-language/english-only.js';
 import { CORE_AGENTS_MD_TOOLS, loadHostRegistry, filterToolsByHost, formatToolsForAgentsMd, } from '../../engine/host-tool-filter.js';
 const AGENTS_MD_PATH = 'AGENTS.md';
 const CURSORRULES_PATH = '.cursorrules';
@@ -89,6 +90,7 @@ async function writeIfMissing(path, content) {
         return false;
     }
     catch {
+        assertEnglishOnlyArtifactText(content, 'agent');
         await writeFile(path, content, 'utf-8');
         return true;
     }

package/dist/tools/init-project/conventions-writer.js

@@ -2,6 +2,7 @@
 // with project-specific conventions detected by init_project
 import { writeFile, mkdir, access } from 'node:fs/promises';
 import { join } from 'node:path';
+import { assertEnglishOnlyArtifactText } from '../../engine/spec-language/english-only.js';
 const CONVENTIONS_MD_PATH = '.claude/rules/conventions.md';
 function buildConventionsContent(knowledge) {
     const stackItems = knowledge.stack;
@@ -44,6 +45,7 @@ export async function generateConventionsMdIfMissing(projectPath, knowledge) {
         const rulesDir = join(projectPath, '.claude/rules');
         await mkdir(rulesDir, { recursive: true });
         const content = buildConventionsContent(knowledge);
+        assertEnglishOnlyArtifactText(content, 'rule');
         await writeFile(conventionsPath, content, 'utf-8');
         return true;
     }

package/dist/tools/init-project/find-skills-writer.js

@@ -2,6 +2,7 @@
 // Single hardcoded entry point for skill discovery in generated config files
 import { writeFile, mkdir, access } from 'node:fs/promises';
 import { join } from 'node:path';
+import { assertEnglishOnlyArtifactText } from '../../engine/spec-language/english-only.js';
 const FIND_SKILLS_PATH = '.claude/skills/find-skills.md';
 const FIND_SKILLS_CONTENT = `# /find-skills — Discover Available Workflows
 
@@ -42,6 +43,7 @@ export async function generateFindSkillsIfMissing(projectPath) {
     catch {
         const skillsDir = join(projectPath, '.claude', 'skills');
         await mkdir(skillsDir, { recursive: true });
+        assertEnglishOnlyArtifactText(FIND_SKILLS_CONTENT, 'skill');
         await writeFile(skillPath, FIND_SKILLS_CONTENT, 'utf-8');
         return true;
     }

package/dist/tools/init-project/git-setup.js

@@ -121,9 +121,18 @@ async function configureGitignore(projectPath) {
         // SPEC-724: Gitignore heal_spec_docs backup files (.bak.<ts>)
         const planuIgnores = [
             'planu/*.html',
-            'planu/*.pdf',
             'planu/status.json',
-            'planu/session-state.json',
+            'planu/CHANGELOG.md',
+            'planu/.housekeeping-history.jsonl',
+            'planu/audits/',
+            'planu/handoffs/',
+            'planu/data/',
+            'planu/state/',
+            'planu/.locks/',
+            'planu/specs/data/',
+            'planu/specs/**/.analysis.json',
+            'planu/specs/**/technical-report.html',
+            'planu/specs/**/reference/',
             'planu/specs/**/*.bak.*',
         ];
         for (const entry of planuIgnores) {

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

@@ -24,7 +24,7 @@ import { readAutoInstallFlag, orchestrateSkillInstalls, runHealthCheckWithBaseli
 import { injectProactiveRules } from '../../engine/claude-md-injector/index.js';
 import { discoverSkillsForInit } from '../../engine/skill-bootstrap/registry-fetcher.js';
 import { join } from 'node:path';
-import { stat, readFile } from 'node:fs/promises';
+import { stat } from 'node:fs/promises';
 import { generateAgentTeamsRulesIfMissing, generateWorkflowRulesIfMissing, } from './rules-generator.js';
 import { installUniversalRules } from '../../engine/universal-rules/installer.js';
 import { detectHost } from '../../engine/host-detection/detect-host.js';
@@ -126,32 +126,6 @@ export async function handleInitProject(params, server) {
             // Read-only — we surface the finding but never touch existing data.
             const ancestorReport = await detectAncestorDataDirs(projectPath, projectId);
             const ancestorWarning = buildAncestorDataWarning(ancestorReport);
-            // SPEC-540: Idempotency check — if planu/status.json exists, return early with existing projectId
-            const statusJsonPath = join(projectPath, 'planu', 'status.json');
-            try {
-                const statusRaw = await readFile(statusJsonPath, 'utf-8');
-                const statusData = JSON.parse(statusRaw);
-                const existingProjectId = typeof statusData.projectId === 'string' ? statusData.projectId : null;
-                if (existingProjectId) {
-                    const baseText = `Project already initialized at ${projectPath}. Using existing projectId: ${existingProjectId}. Use list_specs to see existing specs or create_spec to add new ones.`;
-                    const text = ancestorWarning !== null ? `${baseText}\n\n⚠️  ${ancestorWarning}` : baseText;
-                    return {
-                        content: [{ type: 'text', text }],
-                        structuredContent: {
-                            projectId: existingProjectId,
-                            projectPath,
-                            alreadyInitialized: true,
-                            message: `Project already initialized at ${projectPath}. Using existing projectId: ${existingProjectId}.`,
-                            ...(ancestorWarning !== null
-                                ? { ancestorDataWarning: ancestorWarning, ancestorDataDirs: ancestorReport }
-                                : {}),
-                        },
-                    };
-                }
-            }
-            catch {
-                // status.json does not exist or is not parseable — proceed with normal init
-            }
             if (ancestorWarning !== null) {
                 console.warn(`[Planu] init_project: ${ancestorWarning}`);
             }

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

@@ -1,4 +1,5 @@
 import { detectLegalFramework, detectThirdParties, buildDefaultPrivacyConfig, } from '../../engine/pii-detector.js';
+import { assertEnglishOnlyArtifactText } from '../../engine/spec-language/english-only.js';
 import { readFile, writeFile, access, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { glob } from 'glob';
@@ -283,6 +284,10 @@ export async function injectSddIntoClaude(projectPath, projectSections) {
         if (updated === content) {
             continue; // nothing changed for this file
         }
+        assertEnglishOnlyArtifactText(SDD_BLOCK, 'agent');
+        if (projectSections) {
+            assertEnglishOnlyArtifactText(projectSections, 'agent');
+        }
         await writeFile(filePath, updated, 'utf-8');
         anyModified = true;
     }

package/dist/tools/init-project/migration-runner.js

@@ -63,6 +63,14 @@ export async function runSpecMigrations(projectPath, projectId, knowledge) {
     catch {
         /* best-effort — never block init_project */
     }
+    // SPEC-1017: strict managed planu/ cleanup after all legacy migrations.
+    try {
+        const { runStrictPlanuCleanup } = await import('../../engine/spec-migrator/index.js');
+        await runStrictPlanuCleanup(projectPath);
+    }
+    catch {
+        /* best-effort — never block init_project */
+    }
     return { discoveryResult, migrationResult, folderMigrationResult };
 }
 /** Return all specs for the project (needed by caller for health check refs). */

package/dist/tools/init-project/per-client-files-writer.js

@@ -2,6 +2,7 @@
 import { writeFile, mkdir, access } from 'node:fs/promises';
 import { join } from 'node:path';
 import { detectAndCacheClient } from '../../engine/client-detection.js';
+import { assertEnglishOnlyArtifactText } from '../../engine/spec-language/english-only.js';
 const CURSOR_MDC_CONTENT = `---
 description: Planu SDD workflow for Cursor
 globs: ["**/*"]
@@ -70,6 +71,7 @@ async function writeIfMissing(filePath, content) {
     }
     catch {
         await mkdir(join(filePath, '..'), { recursive: true });
+        assertEnglishOnlyArtifactText(content, filePath.includes('/skills/') ? 'skill' : 'agent');
         await writeFile(filePath, content, 'utf-8');
         return true;
     }

package/dist/tools/init-project/planu-workflow-generator.js

@@ -2,6 +2,7 @@
 // SPEC-263: Autonomous CLAUDE.md that makes Planu mandatory
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { dirname } from 'node:path';
+import { assertEnglishOnlyArtifactText } from '../../engine/spec-language/english-only.js';
 const PLANU_WORKFLOW_MARKER = '<!-- planu-sdd-workflow -->';
 const PLANU_WORKFLOW_CONTENT = `<!-- planu-sdd-workflow -->
 ## Planu SDD Workflow (MANDATORY)
@@ -61,6 +62,7 @@ export async function injectPlanuSection(claudeMdPath, section) {
         await mkdir(dirname(claudeMdPath), { recursive: true });
     }
     const updated = injectOrReplacePlanuBlock(existing, section.content, section.marker);
+    assertEnglishOnlyArtifactText(section.content, 'agent');
     await writeFile(claudeMdPath, updated, 'utf-8');
 }
 /**

package/dist/tools/init-project/rules-generator.js

@@ -2,6 +2,7 @@
 // SPEC-263: Autonomous CLAUDE.md that makes Planu mandatory
 import { writeFile, mkdir, access } from 'node:fs/promises';
 import { join } from 'node:path';
+import { assertEnglishOnlyArtifactText } from '../../engine/spec-language/english-only.js';
 const PLANU_WORKFLOW_RULES_PATH = '.claude/rules/planu-workflow.md';
 const PLANU_WORKFLOW_RULES_CONTENT = `# Planu SDD Workflow (MANDATORY)
 
@@ -141,7 +142,9 @@ export async function generateAgentTeamsRules(projectPath) {
     const rulesPath = join(projectPath, AGENT_TEAMS_RULES_PATH);
     const rulesDir = join(projectPath, '.claude/rules');
     await mkdir(rulesDir, { recursive: true });
-    await writeFile(rulesPath, generateAgentTeamsRulesContent(), 'utf-8');
+    const content = generateAgentTeamsRulesContent();
+    assertEnglishOnlyArtifactText(content, 'rule');
+    await writeFile(rulesPath, content, 'utf-8');
 }
 /**
  * Write .claude/rules/agent-teams.md only if it does not exist yet.
@@ -166,6 +169,7 @@ export async function generateWorkflowRules(projectPath) {
     const rulesPath = join(projectPath, PLANU_WORKFLOW_RULES_PATH);
     const rulesDir = join(projectPath, '.claude/rules');
     await mkdir(rulesDir, { recursive: true });
+    assertEnglishOnlyArtifactText(PLANU_WORKFLOW_RULES_CONTENT, 'rule');
     await writeFile(rulesPath, PLANU_WORKFLOW_RULES_CONTENT, 'utf-8');
 }
 /**
@@ -227,6 +231,7 @@ export async function generateModeRulesIfMissing(projectPath) {
     catch {
         const rulesDir = join(projectPath, '.claude/rules');
         await mkdir(rulesDir, { recursive: true });
+        assertEnglishOnlyArtifactText(PLANU_MODES_RULES_CONTENT, 'rule');
         await writeFile(rulesPath, PLANU_MODES_RULES_CONTENT, 'utf-8');
         return true;
     }
@@ -254,6 +259,7 @@ export async function generateResponseStyleRulesIfMissing(projectPath) {
     catch {
         const rulesDir = join(projectPath, '.claude/rules');
         await mkdir(rulesDir, { recursive: true });
+        assertEnglishOnlyArtifactText(RESPONSE_STYLE_RULES_CONTENT, 'rule');
         await writeFile(rulesPath, RESPONSE_STYLE_RULES_CONTENT, 'utf-8');
         return true;
     }

package/dist/tools/init-project/rules-writer.js

@@ -2,6 +2,7 @@ import { generateRules, detectAgentPlatformFromFiles } from '../../engine/skill-
 import { knowledgeStore } from '../../storage/index.js';
 import { writeFile, access, mkdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
+import { assertEnglishOnlyArtifactText } from '../../engine/spec-language/english-only.js';
 /**
  * Detect agent platform, generate rules, and write them to disk.
  * Only writes files that don't exist yet — never overwrites user custom rules.
@@ -22,6 +23,7 @@ export async function runRulesWriter(projectPath, projectId, knowledge, recommen
     }
     catch {
         await mkdir(dirname(rulesFilePath), { recursive: true });
+        assertEnglishOnlyArtifactText(generatedRules.rulesFile.content, 'rule');
         await writeFile(rulesFilePath, generatedRules.rulesFile.content, 'utf-8');
         rulesWritten = true;
     }
@@ -34,6 +36,7 @@ export async function runRulesWriter(projectPath, projectId, knowledge, recommen
         }
         catch {
             await mkdir(dirname(filePath), { recursive: true });
+            assertEnglishOnlyArtifactText(file.content, file.path.includes('skill') ? 'skill' : 'rule');
             await writeFile(filePath, file.content, 'utf-8');
             additionalFilesWritten.push(file.path);
         }

package/dist/tools/init-project/skills-multi-teammate-review-writer.js

@@ -3,6 +3,7 @@
 import { writeFile, mkdir, access, readFile } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { assertEnglishOnlyArtifactText } from '../../engine/spec-language/english-only.js';
 const SKILL_TARGET_PATH = '.claude/skills/planu-multi-teammate-review.md';
 // Resolve the template path relative to this file (works after tsc compilation too)
 function resolveTemplatePath() {
@@ -48,6 +49,7 @@ export async function generateMultiTeammateReviewSkillIfMissing(projectPath) {
         const skillsDir = join(projectPath, '.claude/skills');
         await mkdir(skillsDir, { recursive: true });
         const content = await readTemplate();
+        assertEnglishOnlyArtifactText(content, 'skill');
         await writeFile(skillPath, content, 'utf-8');
         return true;
     }

package/dist/tools/init-project/skills-writer.js

@@ -2,6 +2,7 @@
 // SPEC-519: Generate compact skill file for dense SDD mode
 import { writeFile, mkdir, access } from 'node:fs/promises';
 import { join } from 'node:path';
+import { assertEnglishOnlyArtifactText } from '../../engine/spec-language/english-only.js';
 const COMPACT_SKILL_PATH = '.claude/skills/compact.md';
 const COMPACT_SKILL_CONTENT = `# /compact — Dense SDD Mode
 
@@ -43,6 +44,7 @@ export async function generateCompactSkillIfMissing(projectPath) {
     catch {
         const skillsDir = join(projectPath, '.claude/skills');
         await mkdir(skillsDir, { recursive: true });
+        assertEnglishOnlyArtifactText(COMPACT_SKILL_CONTENT, 'skill');
         await writeFile(skillPath, COMPACT_SKILL_CONTENT, 'utf-8');
         return true;
     }

package/dist/tools/license-gate.d.ts

@@ -7,6 +7,7 @@ export declare function invalidateTierCache(): void;
  * Returns 'enterprise' for owner token, 'pro' if a license key env var is set, 'free' otherwise.
  */
 export declare function getTierSync(): PricingTier;
+export declare function shouldBypassDailyRateLimit(toolName: string): boolean;
 export declare function withLicenseGate<T>(toolName: string, handler: (args: T, extra?: unknown) => Promise<ToolResult>): (args: T, extra?: unknown) => Promise<ToolResult>;
 /**
  * Wraps a handler with rate limiting (free tier only) and usage event recording.

package/dist/tools/license-gate.js

@@ -88,6 +88,10 @@ 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']);
+export function shouldBypassDailyRateLimit(toolName) {
+    return RATE_LIMIT_EXEMPT_TOOLS.has(toolName);
+}
 async function resolveSessionTier(licenseKey) {
     const now = Date.now();
     const cached = sessionTierCache.get(licenseKey);
@@ -151,7 +155,7 @@ export function withUsageTracking(toolName, handler) {
     return async (args, extra) => {
         const tier = await getCurrentTier();
         // During open-access window, skip rate limiting for free tier
-        if (tier === 'free' && !isOpenAccessActive()) {
+        if (tier === 'free' && !isOpenAccessActive() && !shouldBypassDailyRateLimit(toolName)) {
             const today = new Date().toISOString().slice(0, 10);
             const [trialState, callCount, lastCallAt] = await Promise.all([
                 usageStore.ensureTrialState(),

package/dist/tools/list-specs.js

@@ -63,6 +63,19 @@ async function autoDiscoverProject(projectId, projectPath, collector) {
     catch {
         /* best-effort */
     }
+    // SPEC-1017: list_specs enforces the strict planu/ policy in check mode.
+    // Mutating cleanup is handled by init/update/validate/housekeeping; list_specs
+    // stays read-mostly and surfaces exact offenders if any remain.
+    try {
+        const { validateStrictPlanuLayout } = await import('../engine/spec-migrator/index.js');
+        const layout = await validateStrictPlanuLayout(projectPath);
+        if (!layout.ok) {
+            collector.pushOk('strict-planu-layout', `Non-canonical planu/ paths detected:\n${layout.offenders.map((p) => `- ${p}`).join('\n')}`);
+        }
+    }
+    catch {
+        /* best-effort — never block list_specs */
+    }
     // SPEC-715: list_specs is read-only. Migrations are NEVER run here.
     // Drift is detected (read-only) and reported so the LLM can decide to run heal_spec_docs.
     try {

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", "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"];
 export declare function registerSddTools(server: McpServer): void;
 //# sourceMappingURL=register-sdd-tools.d.ts.map

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

@@ -21,6 +21,7 @@ export const OFFICIAL_SDD_TOOL_NAMES = [
     'challenge_spec',
     'check_readiness',
     'update_status',
+    'update_status_batch',
     'package_handoff',
     'validate',
     'reconcile_spec',

package/dist/tools/register-spec-tools/core-spec-tools.js

@@ -10,6 +10,7 @@ import { handleClarifyRequirements } from '../clarify-requirements.js';
 import { handleCreateSpec } from '../create-spec.js';
 import { handleListSpecs } from '../list-specs.js';
 import { handleUpdateStatus } from '../update-status.js';
+import { handleUpdateStatusBatch } from '../update-status/batch.js';
 import { handleEstimate } from '../estimate.js';
 import { handleReverseEngineer } from '../reverse-engineer.js';
 import { handleValidate } from '../validate.js';
@@ -304,6 +305,21 @@ export function registerCoreSpecTools(server) {
                 .describe('SPEC-769: Force-approve a spec that scored below 70 on the readiness gate. Warnings are stored in spec.md frontmatter. Use when the LLM has explicitly confirmed the spec is ready despite a low readiness score.'),
         },
     }, safeTracked('update_status', async (args) => handleUpdateStatus(args)));
+    server.registerTool('update_status_batch', {
+        description: 'Batch update many specs to the same status in one MCP execution. Uses the same transition rules as update_status and reports updated/skipped/failed per spec.',
+        inputSchema: {
+            specIds: z.array(z.string().min(1).max(500)).min(1).describe('Spec IDs to update'),
+            projectId: z.string().max(500).optional().describe('Project ID, if known'),
+            projectPath: z
+                .string()
+                .max(4096)
+                .optional()
+                .describe('Absolute project root. Preferred when projectId is unknown.'),
+            status: SpecStatusEnum.describe('New status for all specs'),
+            dryRun: z.boolean().optional().describe('Preview the batch without mutating any spec.'),
+            reviewNotes: z.string().max(10_000).optional().describe('Optional notes for each transition.'),
+        },
+    }, safeTracked('update_status_batch', async (args) => handleUpdateStatusBatch(args)));
     // 8. estimate
     server.registerTool('estimate', {
         description: t('tools.estimate.description'),

package/dist/tools/spec-lock-handler.js

@@ -107,7 +107,7 @@ export async function handleListLocks(input) {
     try {
         // SPEC-301: legacy manual locks (data/projects/.../locks/*.json)
         const legacyLocks = await listActiveLocks(projectPath);
-        // SPEC-719: cross-process disk locks (planu/.locks/*.lock)
+        // SPEC-719: cross-process disk locks (data/.locks/planu/*.lock)
         const crossProcessLocks = await listActiveCrossProcessLocks(projectPath).catch(() => []);
         const totalCount = legacyLocks.length + crossProcessLocks.length;
         if (totalCount === 0) {