@planu/cli 4.10.4 → 4.10.6

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [4.10.6] - 2026-07-07
+
+### Bug Fixes
+- fix(SPEC-1111): stabilize update_status done gates and evidence state transitions
+- fix(SPEC-1112): preserve validation-report lint evidence during done gate
+
+### Improvements
+- refactor(SPEC-1110): reduce MCP token payloads with local-first tool classification
+
+
+## [4.10.5] - 2026-07-07
+
+### Bug Fixes
+- fix(SPEC-1109): resolve audit backlog
+
+
 ## [4.10.4] - 2026-07-06
 
 ### Bug Fixes
@@ -4183,4 +4199,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/version.js

@@ -1,4 +1,4 @@
-// version.ts — reads from package.json at runtime; updated automatically by semantic-release
+// version.ts — reads from package.json at runtime; updated by the local release flow
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';

package/dist/config/version.ts

@@ -1,4 +1,4 @@
-// version.ts — reads from package.json at runtime; updated automatically by semantic-release
+// version.ts — reads from package.json at runtime; updated by the local release flow
 
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';

package/dist/engine/compact/tool-list-compactor.d.ts

@@ -3,5 +3,5 @@ export declare function compactToolList(tools: unknown[]): Record<string, unknow
 /** Returns true when an outgoing JSON-RPC message is a tools/list result. */
 export declare function isToolsListResponse(message: unknown): boolean;
 /** Compact a tools/list JSON-RPC response message. Returns a new object. */
-export declare function compactToolsListMessage(message: Record<string, unknown>): Record<string, unknown>;
+export declare function compactToolsListMessage<T extends Record<string, unknown>>(message: T): T;
 //# sourceMappingURL=tool-list-compactor.d.ts.map

package/dist/engine/evidence-gates/lifecycle-gate.js

@@ -114,9 +114,25 @@ export function checkDoneEvidenceGate(spec, criteria, artifacts) {
             !hasText(row.validationEvidence) ||
             !hasText(row.reviewerEvidence));
         if (incompleteRows.length > 0) {
+            const rowDetails = incompleteRows.map((row) => {
+                const missing = [];
+                if (!rowHasEvidence(row)) {
+                    missing.push('scenario/testEvidence/contractEvidence/manualEvidence');
+                }
+                if (row.changedFiles.length === 0) {
+                    missing.push('changedFiles');
+                }
+                if (!hasText(row.validationEvidence)) {
+                    missing.push('validationEvidence');
+                }
+                if (!hasText(row.reviewerEvidence)) {
+                    missing.push('reviewerEvidence');
+                }
+                return `${row.acceptanceCriterion}: missing ${missing.join(', ')}`;
+            });
             issues.push({
                 code: 'traceability_incomplete_rows',
-                message: 'Traceability rows must include scenario/test/contract/manual evidence, changed files, validation evidence, and reviewer evidence.',
+                message: `Traceability rows must include evidence, changed files, validation evidence, and reviewer evidence. Incomplete rows: ${rowDetails.join('; ')}`,
             });
         }
     }

package/dist/engine/evidence-index/done-drift.js

@@ -33,9 +33,12 @@ export function checkDoneDriftContract(args) {
                 .map((record) => `${entry.criterion}: ${record.value}`);
         });
         if (unapproved.length > 0) {
+            const groundedHint = args.groundedTechnicalPaths.length > 0
+                ? ` Grounded technical paths: ${args.groundedTechnicalPaths.join(', ')}.`
+                : ' No grounded technical paths were found in the approved spec.';
             issues.push({
                 code: 'done_drift_unapproved_scope',
-                message: `Done drift check found changed files outside grounded spec scope: ${unapproved.join('; ')}`,
+                message: `Done drift check found changed files outside grounded spec scope: ${unapproved.join('; ')}.${groundedHint} Add the file to approved technical references or include reviewerEvidence with an approved scope amendment.`,
             });
         }
     }

package/dist/engine/local-first/tool-classification.d.ts

@@ -0,0 +1,6 @@
+import type { ToolClassification } from '../../types/tool-classification.js';
+export declare function getToolClassification(toolName: string): ToolClassification;
+export declare function isLocalFirstTool(toolName: string): boolean;
+export declare function requiresLlmByDefault(toolName: string): boolean;
+export declare function listToolClassifications(): ToolClassification[];
+//# sourceMappingURL=tool-classification.d.ts.map

package/dist/engine/local-first/tool-classification.js

@@ -0,0 +1,119 @@
+const TOOL_CLASSIFICATIONS = new Map([
+    [
+        'create_spec',
+        {
+            toolName: 'create_spec',
+            executionClass: 'llm-required',
+            tokenPolicy: 'llm-product',
+            reason: 'Generates the primary spec artifact and needs language synthesis.',
+        },
+    ],
+    [
+        'validate',
+        {
+            toolName: 'validate',
+            executionClass: 'local',
+            tokenPolicy: 'summarize-first',
+            reason: 'Compares repository state and spec artifacts with deterministic validators.',
+        },
+    ],
+    [
+        'audit',
+        {
+            toolName: 'audit',
+            executionClass: 'local',
+            tokenPolicy: 'summarize-first',
+            reason: 'Runs deterministic checks and returns issue summaries.',
+        },
+    ],
+    [
+        'package_handoff',
+        {
+            toolName: 'package_handoff',
+            executionClass: 'local',
+            tokenPolicy: 'summarize-first',
+            reason: 'Packages existing spec and project context into an artifact reference.',
+        },
+    ],
+    [
+        'list_specs',
+        {
+            toolName: 'list_specs',
+            executionClass: 'local',
+            tokenPolicy: 'summarize-first',
+            reason: 'Lists indexed spec metadata and must stay read-only.',
+        },
+    ],
+    [
+        'summarize_spec',
+        {
+            toolName: 'summarize_spec',
+            executionClass: 'local',
+            tokenPolicy: 'summarize-first',
+            reason: 'Extracts bounded decision fields from an existing spec.',
+        },
+    ],
+    [
+        'generate_tests',
+        {
+            toolName: 'generate_tests',
+            executionClass: 'hybrid',
+            tokenPolicy: 'summarize-first',
+            reason: 'Can generate deterministic scaffolds locally; novel test design may need LLM input.',
+        },
+    ],
+    [
+        'recommend_model',
+        {
+            toolName: 'recommend_model',
+            executionClass: 'local',
+            tokenPolicy: 'no-llm',
+            reason: 'Uses local heuristics and project metadata for routing advice.',
+        },
+    ],
+    [
+        'multi_agent_review',
+        {
+            toolName: 'multi_agent_review',
+            executionClass: 'hybrid',
+            tokenPolicy: 'summarize-first',
+            reason: 'Local orchestration and evidence collection precede any LLM review synthesis.',
+        },
+    ],
+    [
+        'audit_specs_drift',
+        {
+            toolName: 'audit_specs_drift',
+            executionClass: 'local',
+            tokenPolicy: 'summarize-first',
+            reason: 'Diffs spec and implementation artifacts locally.',
+        },
+    ],
+    [
+        'orchestrate_runtime',
+        {
+            toolName: 'orchestrate_runtime',
+            executionClass: 'local',
+            tokenPolicy: 'no-llm',
+            reason: 'Selects runtime behavior from local state and explicit policy.',
+        },
+    ],
+]);
+export function getToolClassification(toolName) {
+    return (TOOL_CLASSIFICATIONS.get(toolName) ?? {
+        toolName,
+        executionClass: 'hybrid',
+        tokenPolicy: 'summarize-first',
+        reason: 'Unregistered tools default to local preprocessing with bounded summaries.',
+    });
+}
+export function isLocalFirstTool(toolName) {
+    return getToolClassification(toolName).executionClass !== 'llm-required';
+}
+export function requiresLlmByDefault(toolName) {
+    return getToolClassification(toolName).executionClass === 'llm-required';
+}
+export function listToolClassifications() {
+    return [...TOOL_CLASSIFICATIONS.values()].sort((a, b) => a.toolName.localeCompare(b.toolName));
+}
+//# sourceMappingURL=tool-classification.js.map

package/dist/engine/project-graph/extractors/decision-store-extractor.js

@@ -1,6 +1,6 @@
 import { safeJsonParse } from '../../../storage/base-store.js';
 import { hashText } from '../cache.js';
-import { redactGraphText } from '../query.js';
+import { redactGraphText } from '../redaction.js';
 function isDecision(value) {
     return (value !== null &&
         typeof value === 'object' &&

package/dist/engine/project-graph/extractors/git-extractor.js

@@ -1,6 +1,6 @@
 import { promisify } from 'node:util';
 import { hashText } from '../cache.js';
-import { redactGraphText } from '../query.js';
+import { redactGraphText } from '../redaction.js';
 export async function extractGitGraph(args) {
     try {
         const childProcess = await import('node:child_process');

package/dist/engine/project-graph/extractors/handoff-extractor.js

@@ -1,5 +1,5 @@
 import { hashText } from '../cache.js';
-import { redactGraphText } from '../query.js';
+import { redactGraphText } from '../redaction.js';
 function specIdFromPath(path) {
     return path.split('/').find((part) => /^SPEC-\d+$/i.test(part));
 }

package/dist/engine/project-graph/extractors/spec-extractor.js

@@ -1,6 +1,6 @@
 import YAML from 'yaml';
 import { hashText } from '../cache.js';
-import { redactGraphText } from '../query.js';
+import { redactGraphText } from '../redaction.js';
 function frontmatter(content) {
     if (!content.startsWith('---')) {
         return {};

package/dist/engine/project-graph/extractors/validation-extractor.js

@@ -1,5 +1,5 @@
 import { hashText } from '../cache.js';
-import { redactGraphText } from '../query.js';
+import { redactGraphText } from '../redaction.js';
 function specIdFromPath(path) {
     return path.split('/').find((part) => /^SPEC-\d+$/i.test(part));
 }

package/dist/engine/project-graph/index.d.ts

@@ -1,4 +1,5 @@
 export { buildProjectKnowledgeGraph } from './builder.js';
-export { queryProjectGraphSlice, formatProjectGraphContext, getProjectGraphFreshnessHint, redactGraphText, } from './query.js';
+export { queryProjectGraphSlice, formatProjectGraphContext, getProjectGraphFreshnessHint, } from './query.js';
+export { redactGraphText } from './redaction.js';
 export { getProjectGraphFreshness, loadProjectGraphPolicy, projectGraphPath, projectGraphCachePath, } from './cache.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/engine/project-graph/index.js

@@ -1,4 +1,5 @@
 export { buildProjectKnowledgeGraph } from './builder.js';
-export { queryProjectGraphSlice, formatProjectGraphContext, getProjectGraphFreshnessHint, redactGraphText, } from './query.js';
+export { queryProjectGraphSlice, formatProjectGraphContext, getProjectGraphFreshnessHint, } from './query.js';
+export { redactGraphText } from './redaction.js';
 export { getProjectGraphFreshness, loadProjectGraphPolicy, projectGraphPath, projectGraphCachePath, } from './cache.js';
 //# sourceMappingURL=index.js.map

package/dist/engine/project-graph/query.d.ts

@@ -1,5 +1,4 @@
-import type { ProjectGraphPolicy, ProjectGraphQueryInput, ProjectGraphSlice } from '../../types/project-knowledge-graph.js';
-export declare function redactGraphText(text: string, policy: ProjectGraphPolicy, maxChars?: number): string;
+import type { ProjectGraphQueryInput, ProjectGraphSlice } from '../../types/project-knowledge-graph.js';
 export declare function queryProjectGraphSlice(input: ProjectGraphQueryInput): Promise<ProjectGraphSlice | null>;
 export declare function formatProjectGraphContext(slice: ProjectGraphSlice): Promise<string>;
 export declare function getProjectGraphFreshnessHint(args: {

package/dist/engine/project-graph/query.js

@@ -1,16 +1,7 @@
 import { hashProjectPath } from '../../storage/base-store.js';
 import { buildProjectKnowledgeGraph } from './builder.js';
 import { getProjectGraphFreshness, loadProjectGraphPolicy, readProjectGraph } from './cache.js';
-function escapeInert(text) {
-    return text.replace(/</g, '&lt;').replace(/>/g, '&gt;');
-}
-export function redactGraphText(text, policy, maxChars = policy.redaction.maxSnippetChars) {
-    const truncated = text.slice(0, maxChars);
-    return policy.redaction.redactPatterns.reduce((current, pattern) => {
-        const re = new RegExp(pattern, 'gi');
-        return current.replace(re, '[redacted]');
-    }, truncated);
-}
+import { escapeInert, redactGraphText } from './redaction.js';
 function sanitizeLabel(label, policy) {
     return escapeInert(redactGraphText(label, policy));
 }

package/dist/engine/project-graph/redaction.d.ts

@@ -0,0 +1,4 @@
+import type { ProjectGraphPolicy } from '../../types/project-knowledge-graph.js';
+export declare function escapeInert(text: string): string;
+export declare function redactGraphText(text: string, policy: ProjectGraphPolicy, maxChars?: number): string;
+//# sourceMappingURL=redaction.d.ts.map

package/dist/engine/project-graph/redaction.js

@@ -0,0 +1,11 @@
+export function escapeInert(text) {
+    return text.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+export function redactGraphText(text, policy, maxChars = policy.redaction.maxSnippetChars) {
+    const truncated = text.slice(0, maxChars);
+    return policy.redaction.redactPatterns.reduce((current, pattern) => {
+        const re = new RegExp(pattern, 'gi');
+        return current.replace(re, '[redacted]');
+    }, truncated);
+}
+//# sourceMappingURL=redaction.js.map

package/dist/engine/qa-gate.js

@@ -20,7 +20,19 @@ function runCheck(name, command, args, cwd) {
     const durationMs = Date.now() - start;
     const passed = result.status === 0 && !result.error;
     const output = [result.stdout, result.stderr].join('\n').trim().slice(0, 2000);
-    return { name, passed, output, durationMs };
+    const errorCode = result.error && 'code' in result.error
+        ? String(result.error.code)
+        : undefined;
+    const timedOut = errorCode === 'ETIMEDOUT' || result.signal === 'SIGTERM';
+    return {
+        name,
+        passed,
+        output,
+        durationMs,
+        command: [command, ...args].join(' '),
+        timedOut,
+        errorMessage: result.error?.message,
+    };
 }
 export function runQaGate(spec, projectPath) {
     const coverageThreshold = extractCoverageThreshold(spec);

package/dist/engine/scope-boundaries/scope-validator.js

@@ -11,11 +11,23 @@ function normalize(text) {
 /**
  * Extract keywords from an out-of-scope item phrase (>3 chars).
  */
-const STOP_WORDS = new Set(['the', 'and', 'for', 'with', 'that', 'this', 'from', 'will']);
+const STOP_WORDS = new Set(['the', 'and', 'for', 'with', 'that', 'this', 'from', 'will', 'every']);
+const GENERIC_SCOPE_TOKENS = new Set([
+    'code',
+    'file',
+    'files',
+    'module',
+    'modules',
+    'mcp',
+    'response',
+    'responses',
+    'tool',
+    'tools',
+]);
 function keywords(phrase) {
     return normalize(phrase)
         .split(' ')
-        .filter((w) => w.length > 3 && !STOP_WORDS.has(w));
+        .filter((w) => w.length > 2 && !STOP_WORDS.has(w) && !GENERIC_SCOPE_TOKENS.has(w));
 }
 /**
  * Determine whether a file path matches an out-of-scope item.

package/dist/engine/validator/validation-report-writer.js

@@ -1,15 +1,16 @@
-import { appendArtifact } from '../handoff-artifacts/io.js';
+import { appendArtifact, readArtifact } from '../handoff-artifacts/io.js';
 import { runSpecCompliance, } from './spec-compliance-runner.js';
 export async function writeImplementationReviewReport(input) {
     const specCompliance = await runSpecCompliance(input.spec, input.projectPath);
     const gates = buildGates({
         score: input.score,
-        lintPassed: input.lintPassed ?? true,
+        lintPassed: input.lintPassed,
         conventionRegression: input.conventionRegression ?? false,
         specCompliance,
         minimalityReport: input.minimalityReport,
     });
-    const passed = gates.every((gate) => gate.passed);
+    const mergedGates = await preserveUnobservedGates(input, gates);
+    const passed = mergedGates.every((gate) => gate.passed);
     const reviewer = {
         kind: 'implementation-review-agent',
         agent: 'planu-implementation-reviewer',
@@ -20,7 +21,7 @@ export async function writeImplementationReviewReport(input) {
         schema_version: '1.0.0',
         specId: input.specId,
         passed,
-        gates,
+        gates: mergedGates,
         reviewer,
         specCompliance: reportCompliance,
         minimalityReport: input.minimalityReport,
@@ -40,7 +41,7 @@ export async function writeImplementationReviewReport(input) {
             sha: artifact.sha,
             reviewer,
             passed,
-            gates,
+            gates: mergedGates,
             specCompliance: reportCompliance,
         };
     }
@@ -50,11 +51,37 @@ export async function writeImplementationReviewReport(input) {
             error: err instanceof Error ? err.message : String(err),
             reviewer,
             passed,
-            gates,
+            gates: mergedGates,
             specCompliance: reportCompliance,
         };
     }
 }
+async function preserveUnobservedGates(input, nextGates) {
+    const currentGateNames = new Set(nextGates.map((gate) => gate.name));
+    const explicitlyObserved = new Set([
+        ...(input.lintPassed !== undefined ? ['lint'] : []),
+        ...(input.conventionRegression !== undefined ? ['convention-regression'] : []),
+        ...(input.minimalityReport !== undefined ? ['minimal-implementation'] : []),
+    ]);
+    const existing = await readArtifact({
+        projectId: input.projectId,
+        specId: input.specId,
+        kind: 'validation-report',
+    }).catch(() => null);
+    if (!existing?.ok) {
+        return nextGates;
+    }
+    const preserved = existing.payload.gates.filter((gate) => currentGateNames.has(gate.name) &&
+        !explicitlyObserved.has(gate.name) &&
+        (gate.name === 'lint' ||
+            gate.name === 'convention-regression' ||
+            gate.name === 'minimal-implementation'));
+    if (preserved.length === 0) {
+        return nextGates;
+    }
+    const preservedByName = new Map(preserved.map((gate) => [gate.name, gate]));
+    return nextGates.map((gate) => preservedByName.get(gate.name) ?? gate);
+}
 function buildGates(args) {
     return [
         {
@@ -66,8 +93,12 @@ function buildGates(args) {
         },
         {
             name: 'lint',
-            passed: args.lintPassed,
-            reason: args.lintPassed ? undefined : 'Configured lint command failed.',
+            passed: args.lintPassed === true,
+            reason: args.lintPassed === true
+                ? undefined
+                : args.lintPassed === false
+                    ? 'Configured lint command failed.'
+                    : 'Lint result was not provided; report cannot claim lint passed.',
         },
         {
             name: 'convention-regression',

package/dist/tools/design-schema-sql/migrations.js

@@ -63,11 +63,16 @@ export function generateMigrations(tables, indexes, rlsPolicies, engine) {
         }
         for (const policy of rlsPolicies) {
             const rolesClause = policy.roles?.length ? ` TO ${policy.roles.join(', ')}` : '';
-            const usingClause = `USING (${policy.using})`;
-            const withCheckClause = policy.withCheck ? ` WITH CHECK (${policy.withCheck})` : '';
+            const usingClause = policy.operation === 'INSERT' ? '' : ` USING (${policy.using})`;
+            const withCheckClause = policy.withCheck || policy.operation === 'INSERT'
+                ? ` WITH CHECK (${policy.withCheck ?? policy.using})`
+                : '';
+            const policyClauses = [rolesClause, usingClause, withCheckClause]
+                .filter((clause) => clause.length > 0)
+                .join('');
             migrations.push({
                 order: order++,
-                sql: `CREATE POLICY ${policy.name} ON ${policy.table} FOR ${policy.operation}${rolesClause} ${usingClause}${withCheckClause};`,
+                sql: `CREATE POLICY ${policy.name} ON ${policy.table} FOR ${policy.operation}${policyClauses};`,
                 reversible: true,
                 reverseSql: `DROP POLICY IF EXISTS ${policy.name} ON ${policy.table};`,
                 dataLoss: false,

package/dist/tools/design-schema-sql/tables.js

@@ -210,12 +210,28 @@ export function generateRLSPolicies(tables) {
         }
         else {
             policies.push({
-                name: `${table.name}_all_authenticated`,
+                name: `${table.name}_insert_authenticated`,
                 table: table.name,
-                operation: 'ALL',
+                operation: 'INSERT',
+                roles: ['authenticated'],
+                using: 'true',
+                withCheck: 'true',
+                justification: 'Authenticated users can insert records',
+            }, {
+                name: `${table.name}_update_authenticated`,
+                table: table.name,
+                operation: 'UPDATE',
+                roles: ['authenticated'],
+                using: 'true',
+                withCheck: 'true',
+                justification: 'Authenticated users can update records',
+            }, {
+                name: `${table.name}_delete_authenticated`,
+                table: table.name,
+                operation: 'DELETE',
                 roles: ['authenticated'],
                 using: 'true',
-                justification: 'All CRUD operations require authentication',
+                justification: 'Authenticated users can delete records',
             });
         }
     }

package/dist/tools/list-specs.js

@@ -4,16 +4,15 @@ import { buildListSpecsSummary } from '../engine/human-summary.js';
 import { dirname } from 'node:path';
 import { checkBundledVersionGap } from '../engine/version-detector/bundled-version-checker.js';
 import { readLastModifiedTimestamp, formatRelativeDate } from '../engine/spec-changelog/index.js';
-import { discoverAndFlattenSpecs, filterUnprefixedSpecs, importFilesystemSpecs, migrateSpecFolderNames, reconcileSpecPaths, scanForAmbiguousCriteria, } from '../engine/spec-migrator.js';
+import { scanForAmbiguousCriteria } from '../engine/spec-migrator.js';
 import { detectDrift, formatDriftMessage } from '../engine/spec-migrator/drift-detector.js';
 import { AutopilotSummaryCollector } from '../engine/autopilot/summary-collector.js';
-import { withAudit } from '../engine/autopilot/audit-logger.js';
 import { trackCost } from '../engine/cost-tracking/operation-tracker.js';
-import { refreshProjectStatus } from '../engine/autopilot/state-updater.js';
 import { resolveProjectIdOrAutoDetect } from './resolve-project-id.js';
 import { isNativeActive, fastScanSpecs } from '../engine/core-bridge.js';
 /** Track which projects have been auto-discovered this session (once per project). */
 const discoveredProjects = new Set();
+const MAX_STRUCTURED_SPECS = 50;
 /** Build markdown table rows for summary mode */
 function buildSummaryTable(specs) {
     const header = '| ID | Title | Status | Type | Tags |';
@@ -21,48 +20,11 @@ function buildSummaryTable(specs) {
     const rows = specs.map((s) => `| ${s.id} | ${s.title} | ${s.status} | ${s.type} | ${s.tags.join(', ')} |`);
     return [header, divider, ...rows].join('\n');
 }
-async function autoDiscoverProject(projectId, projectPath, collector) {
+async function collectReadOnlyProjectSignals(projectId, projectPath, collector) {
     if (discoveredProjects.has(projectId)) {
         return;
     }
     discoveredProjects.add(projectId);
-    try {
-        await withAudit(projectPath, 'list_specs', 'discoverAndFlattenSpecs', () => discoverAndFlattenSpecs(projectPath));
-    }
-    catch {
-        /* best-effort — don't fail list_specs */
-    }
-    try {
-        await withAudit(projectPath, 'list_specs', 'importFilesystemSpecs', () => importFilesystemSpecs(projectPath, {
-            listSpecs: specStore.listSpecs,
-            createSpec: specStore.createSpec,
-        }, projectId), (imported) => ({ imported: Array.isArray(imported) ? imported.length : 0 }));
-    }
-    catch {
-        /* best-effort */
-    }
-    try {
-        await withAudit(projectPath, 'list_specs', 'reconcileSpecPaths', () => reconcileSpecPaths(projectPath, {
-            listSpecs: specStore.listSpecs,
-            updateSpec: specStore.updateSpec,
-        }, projectId));
-    }
-    catch {
-        /* best-effort */
-    }
-    try {
-        const allStoredSpecs = await specStore.listSpecs(projectId);
-        const unprefixed = filterUnprefixedSpecs(allStoredSpecs);
-        if (unprefixed.length > 0) {
-            await withAudit(projectPath, 'list_specs', 'migrateSpecFolderNames', () => migrateSpecFolderNames(projectPath, unprefixed, {
-                listSpecs: specStore.listSpecs,
-                updateSpec: specStore.updateSpec,
-            }), (migrated) => ({ count: Array.isArray(migrated) ? migrated.length : 0 }));
-        }
-    }
-    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.
@@ -88,21 +50,6 @@ async function autoDiscoverProject(projectId, projectPath, collector) {
     catch {
         /* best-effort — never block list_specs */
     }
-    try {
-        const { configureGitignoreForPlanu } = await import('./init-project/git-setup.js');
-        await withAudit(projectPath, 'list_specs', 'configureGitignoreForPlanu', () => configureGitignoreForPlanu(projectPath));
-        collector.pushOk('gitignore', 'Updated .gitignore with planu/ rules');
-    }
-    catch {
-        /* best-effort */
-    }
-    // SPEC-493: Silently repair status.json totalSpecs count from actual store data
-    try {
-        await withAudit(projectPath, 'list_specs', 'refreshProjectStatus', () => refreshProjectStatus(projectPath, projectId));
-    }
-    catch {
-        /* best-effort */
-    }
 }
 export async function handleListSpecs(params) {
     // SPEC-584: list_specs is read-mostly and its migration-issue questions are opt-in.
@@ -152,9 +99,10 @@ export async function handleListSpecs(params) {
             if (isNativeActive() && knowledge.projectPath) {
                 nativeBriefs = fastScanSpecs(knowledge.projectPath);
             }
-            // Auto-discover, flatten, rename, and fix specs (once per session per project)
+            // Read-only project signals only. Mutating discovery/migration/repair belongs
+            // to init, validate, housekeeping, or explicit migration tools.
             if (knowledge.projectPath) {
-                await autoDiscoverProject(projectId, knowledge.projectPath, collector);
+                await collectReadOnlyProjectSignals(projectId, knowledge.projectPath, collector);
             }
             // Get all specs
             let specs = await specStore.listSpecs(projectId);
@@ -247,6 +195,8 @@ export async function handleListSpecs(params) {
                     updatedAt: s.updatedAt,
                     lastModified: lastModifiedMap.get(s.id) ?? '\u2014',
                 }));
+            const structuredSpecs = specsData.slice(0, MAX_STRUCTURED_SPECS);
+            const specsOmitted = Math.max(0, specsData.length - structuredSpecs.length);
             // Build text content: markdown table in summary mode, JSON in full mode
             let textContent;
             if (detail === 'summary') {
@@ -262,7 +212,13 @@ export async function handleListSpecs(params) {
                     },
                     count: specs.length,
                     totalCount: allSpecs.length,
-                    specs: specsData,
+                    specs: structuredSpecs,
+                    pagination: {
+                        limit: MAX_STRUCTURED_SPECS,
+                        returned: structuredSpecs.length,
+                        total: specsData.length,
+                        omitted: specsOmitted,
+                    },
                     summary: {
                         byStatus: statusCounts,
                         byType: typeCounts,