managed-codebase-context · diff
git:20260505.f537f95 to git:20260515.2096379
35 added, 13 removed. Audit A to A.
---
name: managed-codebase-context
description: Use when connecting to a managed codebase-context MCP/session service, checking stale maps, or safely using MCP-provided repository context.
---
# Managed Codebase Context
## When to use
- Use when managing persistent sessions, dynamic codebase mappings, or managed context states using a dedicated codebase-context MCP server.
+ Use when a persistent codebase-context MCP server is available and the task requires broad architectural context, symbol inventory, or cross-file navigation that would be expensive to reconstruct from scratch on each turn.
## Requirements / Checks
- - Check whether MCP is configured through stdio or HTTP.
- - Do not run `npx -y` or start servers without user approval.
- - Verify server cwd, env, timeout, and workspace path scope.
- - Confirm cleanup behavior for spawned stdio processes before long-running tasks.
+ - Check MCP transport type: stdio (local, one-off) vs HTTP (requires a running server).
+ - Do not run `npx -y` or start server processes without user approval.
+ - Verify server `cwd`, env variables, timeout, and workspace path scope.
+ - Confirm cleanup behavior for spawned stdio processes before starting long-running tasks.
## Workflow
- 1. **Select transport**: Use stdio for local one-off sessions; use HTTP only when an existing local server is already running.
- 2. **Connect with timeout**: Avoid hanging the agent if the server never initializes.
- 3. **Read map**: Retrieve current codebase map, symbols, or architectural summary.
- 4. **Validate freshness**: Compare map timestamp/source paths against current git status when available.
- 5. **Update state**: Trigger context refresh only when source changes make existing map stale.
- 6. **Close session**: Ensure client and transport close; kill spawned process tree if it does not exit.
+ 1. **Select transport**:
+ - **stdio**: suitable for local, ephemeral sessions started per task.
+ - **HTTP**: use only when a local server is already confirmed to be running.
+
+ 2. **Connect with timeout** — set a connection timeout; do not let the agent hang indefinitely if the server never initializes.
+
+ 3. **Retrieve context** — fetch the current codebase map, symbol index, or architectural summary as available.
+
+ 4. **Validate freshness** — a map is stale if any of the following are true:
+ - Map timestamp predates the last `git commit` that touched relevant files.
+ - Map references files that no longer exist.
+ - Map is missing files present in the current workspace.
+ - The user reports recent significant refactoring.
+
+ 5. **Refresh when stale** — trigger a context refresh only when the map is demonstrably stale. Do not refresh on every request — refreshes are expensive.
+
+ 6. **Use context, then close** — read what you need, then close the session. Ensure the client and transport close cleanly. If the server was spawned as a stdio process, kill the process tree if it does not exit within a few seconds.
+
+ ## Staleness Signals
+
+ | Signal | Check |
+ |---|---|
+ | Map timestamp | Compare to `git log --format="%ci" -1` for recently changed files |
+ | Missing files | Cross-reference map file list with `git ls-files` |
+ | Stale symbols | Check if key function/class names in the map exist in current source |
+ | User-reported | Accept the user's word; trigger refresh without verification |
+
## Safety Constraints
- Only interact with paths scoped to the current workspace.
- Do not overwrite existing architectural documents without user confirmation.
- - Do not import user/global MCP configs implicitly.
+ - Do not import user-level or global MCP configs implicitly.
- Do not leave background server processes running after a failed connection.
## Validation / Done Criteria
- - The agent retrieves scoped context and reports freshness.
+ - Context retrieved is confirmed to be within the current workspace scope.
+ - Freshness was validated or a refresh was triggered with reason.
- Any spawned MCP process is closed or explicitly left running by user choice.
## References
- `references/managed-session-checklist.md`