Current Product Disposition
This is the canonical v0.6.0 interface-stabilization issue. MCP remains a first-class ProjectAtlas transport; no removal, fallback-only policy, or CLI-first doctrine is accepted without ProjectAtlas-specific packaged evidence and an explicit compatibility/release decision.
Before changing the surface, compare MCP-first, CLI-first, and mixed funnels on identical version-matched tasks. Measure successful completion and freshness correctness, total context including skill plus discovery/schema bytes, calls, subprocess/startup latency, wall time, wrong reads, backtracking, and recovery. Preserve stable selector chaining, definitive empty states, structured errors, and concrete typed inputs across every retained transport. Use the smallest surface that wins the evidence; do not infer a transport decision from another product's benchmark.
Issue #445 is consolidated here for those empirical and contract requirements. Its useful requirements do not justify a separate skill or a pre-decided transport hierarchy.
Problem or opportunity ProjectAtlas currently advertises 40 MCP tools. The inventory mixes day-to-day agent navigation, source retrieval, graph inspection, purpose curation, and health work with installer, configuration, compatibility, migration, recovery, watcher, and release operations. That has three costs: 1. Every advertised schema consumes agent context and expands tool-selection ambiguity. 2. Administrative and destructive operations are presented beside the normal atlas-first workflow even though they are rarely needed during coding. 3. Compatibility tests, plugin skills, runtime routing, and real MCP E2E must maintain a larger surface than the agent workflow requires. The graph and freshness work planned in #308 should remain automatic behind normal calls. Agents should not need extra orchestration tools merely because ProjectAtlas has a richer internal graph. ## Delivery order This issue is deliberately after #308 and #309. - #308 must first finish and publish the v0.4 repository-intelligence behavior against its currently frozen compatibility baseline. - #309 must then finish the repository-wide test, coverage, mutation, and IssueOps gates. - Only then should this issue create its own OpenSpec change, freeze the packaged v0.4 baseline, and change the public MCP inventory. No v0.4 implementation or compatibility task is changed by opening this issue. ## Current evidence The checked-in REQUIRED_MCP_TOOL_NAMES inventory contains exactly 40 tools. The current ProjectAtlas skill also describes several installer, migration, recovery, and release operations as MCP calls even though those workflows already have CLI ownership. The proposed boundary is: - MCP: operations an agent reasonably selects during repository orientation, coding, refactoring, purpose correction, or bounded diagnostics. - CLI: installation, host configuration, repository administration, migration, recovery, continuous watching, compatibility export, and release verification. - Automatic backend behavior: graph construction, freshness checks, and dependency enrichment needed by normal search/summary/navigation calls. ## Independent audit evidence The task-7.2 pre-composition v0.4 candidate advertises the same 40 tool names. Its compact serialized tools/list tool array is 37,155 bytes, approximately 9,289 heuristic four-byte tokens, compared with 28,933 bytes and 7,234 heuristic tokens for frozen v0.3.26. This 28.4% discovery growth is the current post-v0.4 rationalization baseline and must be refreshed if #308 task 7.3.1 selects any compatible additive surface change. An earlier independent agent-first/KISS audit measured 32,379 characters under its narrower metadata method and estimated a 24-tool candidate at 5,291 heuristic tokens; that remains directional design evidence, not permission to remove a useful workflow. The local usage record contains 3,751 observed MCP funnel events dominated by slice, search, summary, files, outline, folders, and overview. Administrative calls are not present in that event model, so this is directional evidence for the core funnel, not proof that every unobserved tool is unused. The audit also found two contracts that require explicit decisions: - atlas_purpose_review is typed internally, but the connected public schema currently exposes items as Array; retained schemas must remain concrete and agent-readable. - atlas_task_status and atlas_task_cancel have no real work-producing operation today; registry state changes do not currently cancel running work. ## Proposed MCP surface ### Retain: 21 clear normal agent tools | Workflow | Tools | Rationale | |---|---|---| | Bootstrap and project selection | atlas_init, atlas_set_project_path, atlas_session_brief, atlas_settings | One-call setup, multi-project routing, startup orientation, and bounded diagnostics are agent-facing. | | Freshness and atlas navigation | atlas_scan, atlas_overview, atlas_folders, atlas_files | These are the atlas-first funnel and the explicit recovery/refresh path. | | Focused retrieval | atlas_file_summary, atlas_outline, atlas_search, atlas_slice | These replace broad source reads and are the primary token-saving workflow. | | Symbols and graph | atlas_symbols, atlas_symbol_relations | Agents sometimes need explicit symbol or relation inspection, while normal calls should consume graph intelligence automatically. | | Repository quality | atlas_health, atlas_health_resolve, atlas_lint | Agents need bounded findings, intentional-resolution support, and check-in diagnostics. | | Purpose curation | atlas_purpose_queue, atlas_purpose_set, atlas_purpose_review | Queue, immediate single-path correction, and reviewed batch application are distinct useful workflows. atlas_purpose_set must remain; forcing a one-item batch through atlas_purpose_review would make the common correction path worse. | | Value telemetry | atlas_token_report | This is the direct evidence surface when a user asks what ProjectAtlas saved. | ### Evidence-gated decision candidates: 4 tools - atlas_config: the independent audit recommends retaining this bounded read-only policy view because scan, purpose, output, and exclusion configuration is distinct from runtime settings. Remove it only if a tested, bounded atlas_settings response replaces the exact agent need without becoming oversized. - atlas_next: default recommendation is to merge its task-ranked candidates and next-call guidance into atlas_session_brief, because both accept a task query and rank folders/files. Retain it only if comparative agent evaluation proves the smaller mid-session call materially improves completion or token cost. - atlas_watch_once: retain temporarily only until real edit-to-query E2E proves automatic freshness and incremental graph refresh are reliable. Once that contract passes, move one-shot and continuous watcher control to CLI. - atlas_runtime_info: retain only if a real installed-plugin flow needs a project-independent MCP probe before initialization and session/settings cannot report the necessary compatibility identity. Otherwise keep the installer/CLI probe. ### Conditional retention: 2 task tools - atlas_task_status - atlas_task_cancel Retain these only if the packaged v0.4 runtime exposes a real, bounded, cancellable background-task workflow used by normal agent operations. If all relevant MCP operations remain synchronous and no real task ID can be produced in E2E, remove both rather than preserving speculative surface area. These tools cannot be replaced by CLI commands because their identifiers are MCP-session-local. ### Remove from default MCP / keep through CLI or merged owner: 13 tools | Ownership | Tools | Replacement or consolidation | |---|---|---| | Ignore administration | atlas_ignore_list, atlas_ignore_init_gitignore, atlas_ignore_add, atlas_ignore_remove | Keep the established CLI commands. If atlas_config remains, its bounded read-only policy may include effective ignore state without retaining a separate list route. | | Host/runtime setup | atlas_mcp_config, atlas_root, atlas_root_set | Keep installer and CLI ownership. Project identity belongs in atlas_session_brief/settings; process selection remains atlas_set_project_path. | | Compatibility, release, migration, and recovery | atlas_map, atlas_parity_report, atlas_strip_legacy_purpose, atlas_reset_index | Keep explicit CLI workflows, dry-run/confirmation behavior, and CI/release coverage. Destructive recovery should not be in the routine agent tool list. | | Index maintenance | atlas_symbols_build, atlas_watch_status | atlas_scan remains the explicit full refresh operation. Normal navigation and retrieval must enforce freshness and graph maintenance automatically; continuous watch stays a CLI process workflow. | Do not replace removed calls with a catch-all atlas_admin(action = ...) tool. That would hide schemas, reintroduce stringly typed routing, and preserve the same conceptual surface under one name. ## Consolidation rules 1. atlas_session_brief owns selected-project identity and startup readiness. 2. atlas_settings owns bounded, read-only runtime/config diagnostics needed during agent work. 3. atlas_scan owns explicit refresh; graph and symbol refresh required by normal operations happens automatically behind stable calls. 4. atlas_set_project_path selects an active process default; per-call project_path remains the concurrency-safe option. 5. atlas_purpose_set remains the simple single-path mutation; atlas_purpose_review remains preview/apply for batches. 6. Removed administrative behavior stays in typed CLI commands. No functionality is silently discarded unless the conditional task-tool evaluation proves it has no real producer or consumer. ## Scope - Measure the packaged v0.4 tools/list schema size, schema-token cost, selection behavior, and real call coverage. - Ratify every one of the 40 current tools as retained, conditional, CLI-only, merged into an existing read-only response, or removed. - Update the Rust MCP router and frozen inventory. - Update the ProjectAtlas plugin skill, installer/runtime compatibility checks, generated host configuration expectations, and public documentation together. - Preserve CLI access and tests for moved administrative operations. - Add migration/release notes for the intentional breaking MCP surface change. ## Non-goals - Do not implement this before #308 and #309 close. - Do not change the v0.4 graph architecture or expose graph orchestration to everyday users. - Do not rename retained tools without a separate evidence-backed reason. - Do not add a generic admin multiplexer. - Do not remove CLI capabilities merely because their MCP adapters are removed. - Do not add network telemetry; usage evidence must come from local deterministic tests/evaluations or explicitly supplied local telemetry. ## Acceptance criteria - [ ] A post-v0.4 OpenSpec change is created, added to openspec/issue-map.json, strictly validated, and mirrored into this issue under an OpenSpec Task Checklist heading before implementation starts. - [ ] The OpenSpec task list includes an owning unit test and recorded test run for every implementation task, plus real packaged MCP E2E and smoke coverage. - [ ] The packaged v0.4 release is pinned as the baseline, including all 40 tool names, exact input schemas, tools/list bytes/tokens, and representative agent-workflow results. - [ ] Every current tool has one explicit reviewed disposition; there are no unclassified routes, aliases, skills, fixtures, or compatibility expectations. - [ ] The final MCP surface contains no more than 24 tools, retains all 21 clear normal-agent tools above, and records evidence-backed decisions for atlas_config, atlas_next, atlas_watch_once, atlas_runtime_info, atlas_task_status, and atlas_task_cancel. - [ ] atlas_task_status and atlas_task_cancel remain only if real packaged E2E proves a normal operation produces a bounded cancellable task; otherwise both are removed and all stale recommendations are deleted. - [ ] The serialized tools/list schema is at least 30% smaller in bytes and estimated tokens than the pinned packaged v0.4 baseline. - [ ] Every retained input schema is concrete and agent-readable; atlas_purpose_review.items exposes its typed path, purpose, and confirmation fields rather than Array. - [ ] Agent evaluations show no regression in successful completion of startup, orientation, bounded search, exact retrieval, graph inspection, health/lint, purpose correction, and token-report workflows. - [ ] Normal search, summary, file-selection, and symbol workflows use fresh graph intelligence automatically without requiring atlas_symbols_build, atlas_watch_once, or any new orchestration call. - [ ] Real stdio MCP E2E uses the packaged executable, project-local SQLite databases, real indexed repositories, JSON-RPC transport, and both TOON/JSON behavior for every retained tool. - [ ] Real CLI E2E proves every MCP-to-CLI administrative move still works, including failure cases, dry-run/confirmation semantics, path containment, and explicit timeouts. - [ ] tools/list no longer advertises removed tools, and calling an old name fails as a standard unknown-tool response without routing to a hidden compatibility alias. - [ ] Plugin runtime, skill, generated host configuration, frozen contract fixture, release notes, and documentation are updated atomically so no installed agent is taught to call a removed tool. - [ ] Windows, Linux, macOS arm64, and macOS x86-64 packaged smoke runs pass for the retained MCP surface and moved CLI workflows. - [ ] Rust gates remain strict: formatting, workspace/all-target check, Clippy with -D warnings, tests, rustdoc warnings, security/advisory checks, and the applicable #309 coverage/mutation gates all pass. - [ ] The change ships only in a documented post-v0.4 release with a clear compatibility note and rollback path. - [ ] Every pre-mortem mitigation below is represented by an owned OpenSpec task and test/evidence row. ## Pre-mortem | Failure mode | Early signal | Required mitigation | |---|---|---| | A removed tool was actually needed during normal coding | Packaged workflow evaluation needs CLI escape for a routine repository question | Capture baseline calls and agent outcomes before ratification; restore the smallest typed tool only when evidence shows a normal agent need. | | Skill/runtime drift teaches nonexistent calls | Installed plugin skill names a tool absent from tools/list | Make skill, runtime, fixtures, and installer validation one atomic release gate; E2E the clean-host installed plugin. | | Removing explicit maintenance produces stale graph answers | A source edit is not reflected in subsequent search/summary/relation output | Make freshness and incremental graph refresh a backend contract of normal calls; test edit-to-query behavior with real files and SQLite. | | The task tools survive without a real task workflow | No packaged E2E can obtain a task ID | Require a producer/consumer E2E or remove status/cancel together. | | Tool count falls but schema cost does not | tools/list token reduction misses the target | Measure serialized schemas, shorten only accurate descriptions, and keep parameter models bounded; do not game the result by hiding actions in strings. | | CLI-only recovery becomes unsafe or undiscoverable | Agents invoke shell commands without dry-run or path guards | Preserve typed CLI commands, dry-run/confirmation behavior, containment tests, and concise skill guidance for exceptional admin work. | | Breaking removal strands older installations | Old skill/plugin calls removed names after runtime update | Version the change, update plugin/runtime together, validate installer convergence, publish migration notes, and retain a documented rollback release. | | Surface reduction creates one oversized replacement tool | A proposal introduces an action enum/string with unrelated schemas | Reject admin multiplexers in architecture review and enforce one responsibility per retained MCP tool. | ## OpenSpec planning OpenSpec change: not created yet by design. After #308 and #309 close, create the change, add the issue mapping, convert the acceptance and pre-mortem mitigations into ordered test-owned tasks, and mirror those tasks into this issue before changing implementation code.
Current Product Disposition
This is the canonical v0.6.0 interface-stabilization issue. MCP remains a first-class ProjectAtlas transport; no removal, fallback-only policy, or CLI-first doctrine is accepted without ProjectAtlas-specific packaged evidence and an explicit compatibility/release decision.
Before changing the surface, compare MCP-first, CLI-first, and mixed funnels on identical version-matched tasks. Measure successful completion and freshness correctness, total context including skill plus discovery/schema bytes, calls, subprocess/startup latency, wall time, wrong reads, backtracking, and recovery. Preserve stable selector chaining, definitive empty states, structured errors, and concrete typed inputs across every retained transport. Use the smallest surface that wins the evidence; do not infer a transport decision from another product's benchmark.
Issue #445 is consolidated here for those empirical and contract requirements. Its useful requirements do not justify a separate skill or a pre-decided transport hierarchy.
Problem or opportunity ProjectAtlas currently advertises 40 MCP tools. The inventory mixes day-to-day agent navigation, source retrieval, graph inspection, purpose curation, and health work with installer, configuration, compatibility, migration, recovery, watcher, and release operations. That has three costs: 1. Every advertised schema consumes agent context and expands tool-selection ambiguity. 2. Administrative and destructive operations are presented beside the normal atlas-first workflow even though they are rarely needed during coding. 3. Compatibility tests, plugin skills, runtime routing, and real MCP E2E must maintain a larger surface than the agent workflow requires. The graph and freshness work planned in #308 should remain automatic behind normal calls. Agents should not need extra orchestration tools merely because ProjectAtlas has a richer internal graph. ## Delivery order This issue is deliberately after #308 and #309. - #308 must first finish and publish the v0.4 repository-intelligence behavior against its currently frozen compatibility baseline. - #309 must then finish the repository-wide test, coverage, mutation, and IssueOps gates. - Only then should this issue create its own OpenSpec change, freeze the packaged v0.4 baseline, and change the public MCP inventory. No v0.4 implementation or compatibility task is changed by opening this issue. ## Current evidence The checked-in REQUIRED_MCP_TOOL_NAMES inventory contains exactly 40 tools. The current ProjectAtlas skill also describes several installer, migration, recovery, and release operations as MCP calls even though those workflows already have CLI ownership. The proposed boundary is: - MCP: operations an agent reasonably selects during repository orientation, coding, refactoring, purpose correction, or bounded diagnostics. - CLI: installation, host configuration, repository administration, migration, recovery, continuous watching, compatibility export, and release verification. - Automatic backend behavior: graph construction, freshness checks, and dependency enrichment needed by normal search/summary/navigation calls. ## Independent audit evidence The task-7.2 pre-composition v0.4 candidate advertises the same 40 tool names. Its compact serialized
tools/listtool array is 37,155 bytes, approximately 9,289 heuristic four-byte tokens, compared with 28,933 bytes and 7,234 heuristic tokens for frozen v0.3.26. This 28.4% discovery growth is the current post-v0.4 rationalization baseline and must be refreshed if #308 task 7.3.1 selects any compatible additive surface change. An earlier independent agent-first/KISS audit measured 32,379 characters under its narrower metadata method and estimated a 24-tool candidate at 5,291 heuristic tokens; that remains directional design evidence, not permission to remove a useful workflow. The local usage record contains 3,751 observed MCP funnel events dominated by slice, search, summary, files, outline, folders, and overview. Administrative calls are not present in that event model, so this is directional evidence for the core funnel, not proof that every unobserved tool is unused. The audit also found two contracts that require explicit decisions: - atlas_purpose_review is typed internally, but the connected public schema currently exposes items as Array; retained schemas must remain concrete and agent-readable. - atlas_task_status and atlas_task_cancel have no real work-producing operation today; registry state changes do not currently cancel running work. ## Proposed MCP surface ### Retain: 21 clear normal agent tools | Workflow | Tools | Rationale | |---|---|---| | Bootstrap and project selection | atlas_init, atlas_set_project_path, atlas_session_brief, atlas_settings | One-call setup, multi-project routing, startup orientation, and bounded diagnostics are agent-facing. | | Freshness and atlas navigation | atlas_scan, atlas_overview, atlas_folders, atlas_files | These are the atlas-first funnel and the explicit recovery/refresh path. | | Focused retrieval | atlas_file_summary, atlas_outline, atlas_search, atlas_slice | These replace broad source reads and are the primary token-saving workflow. | | Symbols and graph | atlas_symbols, atlas_symbol_relations | Agents sometimes need explicit symbol or relation inspection, while normal calls should consume graph intelligence automatically. | | Repository quality | atlas_health, atlas_health_resolve, atlas_lint | Agents need bounded findings, intentional-resolution support, and check-in diagnostics. | | Purpose curation | atlas_purpose_queue, atlas_purpose_set, atlas_purpose_review | Queue, immediate single-path correction, and reviewed batch application are distinct useful workflows. atlas_purpose_set must remain; forcing a one-item batch through atlas_purpose_review would make the common correction path worse. | | Value telemetry | atlas_token_report | This is the direct evidence surface when a user asks what ProjectAtlas saved. | ### Evidence-gated decision candidates: 4 tools - atlas_config: the independent audit recommends retaining this bounded read-only policy view because scan, purpose, output, and exclusion configuration is distinct from runtime settings. Remove it only if a tested, bounded atlas_settings response replaces the exact agent need without becoming oversized. - atlas_next: default recommendation is to merge its task-ranked candidates and next-call guidance into atlas_session_brief, because both accept a task query and rank folders/files. Retain it only if comparative agent evaluation proves the smaller mid-session call materially improves completion or token cost. - atlas_watch_once: retain temporarily only until real edit-to-query E2E proves automatic freshness and incremental graph refresh are reliable. Once that contract passes, move one-shot and continuous watcher control to CLI. - atlas_runtime_info: retain only if a real installed-plugin flow needs a project-independent MCP probe before initialization and session/settings cannot report the necessary compatibility identity. Otherwise keep the installer/CLI probe. ### Conditional retention: 2 task tools - atlas_task_status - atlas_task_cancel Retain these only if the packaged v0.4 runtime exposes a real, bounded, cancellable background-task workflow used by normal agent operations. If all relevant MCP operations remain synchronous and no real task ID can be produced in E2E, remove both rather than preserving speculative surface area. These tools cannot be replaced by CLI commands because their identifiers are MCP-session-local. ### Remove from default MCP / keep through CLI or merged owner: 13 tools | Ownership | Tools | Replacement or consolidation | |---|---|---| | Ignore administration | atlas_ignore_list, atlas_ignore_init_gitignore, atlas_ignore_add, atlas_ignore_remove | Keep the established CLI commands. If atlas_config remains, its bounded read-only policy may include effective ignore state without retaining a separate list route. | | Host/runtime setup | atlas_mcp_config, atlas_root, atlas_root_set | Keep installer and CLI ownership. Project identity belongs in atlas_session_brief/settings; process selection remains atlas_set_project_path. | | Compatibility, release, migration, and recovery | atlas_map, atlas_parity_report, atlas_strip_legacy_purpose, atlas_reset_index | Keep explicit CLI workflows, dry-run/confirmation behavior, and CI/release coverage. Destructive recovery should not be in the routine agent tool list. | | Index maintenance | atlas_symbols_build, atlas_watch_status | atlas_scan remains the explicit full refresh operation. Normal navigation and retrieval must enforce freshness and graph maintenance automatically; continuous watch stays a CLI process workflow. | Do not replace removed calls with a catch-all atlas_admin(action = ...) tool. That would hide schemas, reintroduce stringly typed routing, and preserve the same conceptual surface under one name. ## Consolidation rules 1. atlas_session_brief owns selected-project identity and startup readiness. 2. atlas_settings owns bounded, read-only runtime/config diagnostics needed during agent work. 3. atlas_scan owns explicit refresh; graph and symbol refresh required by normal operations happens automatically behind stable calls. 4. atlas_set_project_path selects an active process default; per-call project_path remains the concurrency-safe option. 5. atlas_purpose_set remains the simple single-path mutation; atlas_purpose_review remains preview/apply for batches. 6. Removed administrative behavior stays in typed CLI commands. No functionality is silently discarded unless the conditional task-tool evaluation proves it has no real producer or consumer. ## Scope - Measure the packaged v0.4 tools/list schema size, schema-token cost, selection behavior, and real call coverage. - Ratify every one of the 40 current tools as retained, conditional, CLI-only, merged into an existing read-only response, or removed. - Update the Rust MCP router and frozen inventory. - Update the ProjectAtlas plugin skill, installer/runtime compatibility checks, generated host configuration expectations, and public documentation together. - Preserve CLI access and tests for moved administrative operations. - Add migration/release notes for the intentional breaking MCP surface change. ## Non-goals - Do not implement this before #308 and #309 close. - Do not change the v0.4 graph architecture or expose graph orchestration to everyday users. - Do not rename retained tools without a separate evidence-backed reason. - Do not add a generic admin multiplexer. - Do not remove CLI capabilities merely because their MCP adapters are removed. - Do not add network telemetry; usage evidence must come from local deterministic tests/evaluations or explicitly supplied local telemetry. ## Acceptance criteria - [ ] A post-v0.4 OpenSpec change is created, added to openspec/issue-map.json, strictly validated, and mirrored into this issue under an OpenSpec Task Checklist heading before implementation starts. - [ ] The OpenSpec task list includes an owning unit test and recorded test run for every implementation task, plus real packaged MCP E2E and smoke coverage. - [ ] The packaged v0.4 release is pinned as the baseline, including all 40 tool names, exact input schemas, tools/list bytes/tokens, and representative agent-workflow results. - [ ] Every current tool has one explicit reviewed disposition; there are no unclassified routes, aliases, skills, fixtures, or compatibility expectations. - [ ] The final MCP surface contains no more than 24 tools, retains all 21 clear normal-agent tools above, and records evidence-backed decisions for atlas_config, atlas_next, atlas_watch_once, atlas_runtime_info, atlas_task_status, and atlas_task_cancel. - [ ] atlas_task_status and atlas_task_cancel remain only if real packaged E2E proves a normal operation produces a bounded cancellable task; otherwise both are removed and all stale recommendations are deleted. - [ ] The serialized tools/list schema is at least 30% smaller in bytes and estimated tokens than the pinned packaged v0.4 baseline. - [ ] Every retained input schema is concrete and agent-readable; atlas_purpose_review.items exposes its typed path, purpose, and confirmation fields rather than Array. - [ ] Agent evaluations show no regression in successful completion of startup, orientation, bounded search, exact retrieval, graph inspection, health/lint, purpose correction, and token-report workflows. - [ ] Normal search, summary, file-selection, and symbol workflows use fresh graph intelligence automatically without requiring atlas_symbols_build, atlas_watch_once, or any new orchestration call. - [ ] Real stdio MCP E2E uses the packaged executable, project-local SQLite databases, real indexed repositories, JSON-RPC transport, and both TOON/JSON behavior for every retained tool. - [ ] Real CLI E2E proves every MCP-to-CLI administrative move still works, including failure cases, dry-run/confirmation semantics, path containment, and explicit timeouts. - [ ] tools/list no longer advertises removed tools, and calling an old name fails as a standard unknown-tool response without routing to a hidden compatibility alias. - [ ] Plugin runtime, skill, generated host configuration, frozen contract fixture, release notes, and documentation are updated atomically so no installed agent is taught to call a removed tool. - [ ] Windows, Linux, macOS arm64, and macOS x86-64 packaged smoke runs pass for the retained MCP surface and moved CLI workflows. - [ ] Rust gates remain strict: formatting, workspace/all-target check, Clippy with -D warnings, tests, rustdoc warnings, security/advisory checks, and the applicable #309 coverage/mutation gates all pass. - [ ] The change ships only in a documented post-v0.4 release with a clear compatibility note and rollback path. - [ ] Every pre-mortem mitigation below is represented by an owned OpenSpec task and test/evidence row. ## Pre-mortem | Failure mode | Early signal | Required mitigation | |---|---|---| | A removed tool was actually needed during normal coding | Packaged workflow evaluation needs CLI escape for a routine repository question | Capture baseline calls and agent outcomes before ratification; restore the smallest typed tool only when evidence shows a normal agent need. | | Skill/runtime drift teaches nonexistent calls | Installed plugin skill names a tool absent from tools/list | Make skill, runtime, fixtures, and installer validation one atomic release gate; E2E the clean-host installed plugin. | | Removing explicit maintenance produces stale graph answers | A source edit is not reflected in subsequent search/summary/relation output | Make freshness and incremental graph refresh a backend contract of normal calls; test edit-to-query behavior with real files and SQLite. | | The task tools survive without a real task workflow | No packaged E2E can obtain a task ID | Require a producer/consumer E2E or remove status/cancel together. | | Tool count falls but schema cost does not | tools/list token reduction misses the target | Measure serialized schemas, shorten only accurate descriptions, and keep parameter models bounded; do not game the result by hiding actions in strings. | | CLI-only recovery becomes unsafe or undiscoverable | Agents invoke shell commands without dry-run or path guards | Preserve typed CLI commands, dry-run/confirmation behavior, containment tests, and concise skill guidance for exceptional admin work. | | Breaking removal strands older installations | Old skill/plugin calls removed names after runtime update | Version the change, update plugin/runtime together, validate installer convergence, publish migration notes, and retain a documented rollback release. | | Surface reduction creates one oversized replacement tool | A proposal introduces an action enum/string with unrelated schemas | Reject admin multiplexers in architecture review and enforce one responsibility per retained MCP tool. | ## OpenSpec planning OpenSpec change: not created yet by design. After #308 and #309 close, create the change, add the issue mapping, convert the acceptance and pre-mortem mitigations into ordered test-owned tasks, and mirror those tasks into this issue before changing implementation code.