docs: add deployment scenarios & usage envisioning to PLAN.md#98
Merged
Conversation
…weep Phase 110 — Fusion: - Add planCascade() (src/core/graph/cascade.ts): FTS filter → vector expand → graph traversal → merge/rerank, behind the hybrid lens; semantic lens is a byte-identical short-circuit. - Add `gitsema hotspots` (CLI + MCP tool + POST /api/v1/graph/hotspots): architectural risk = co-change × call-coupling × churn, geometric mean of the signals the lens selects (default hybrid). - Structural enrichment of code-review/triage/explain/guide via --lens (default semantic, output unchanged): structuralContextForPath() facts, cascade-planner section for triage, and call_graph/blast_radius/hotspots tools added to GUIDE_TOOLS. Phase 111 — Lens coverage & parity sweep: - Apply shared addLensOption() uniformly (blast-radius/similar/relate/hotspots → hybrid; impact/triage/code-review/explain/guide → semantic), enforcing the §7.3 defaults; per-hit lens labels across renderers. - interpretations.ts entries for call_graph/blast_radius/hotspots; regenerate skill (gen:skill); update features.md/README/CLAUDE.md/PLAN.md. - tests/lensParity.test.ts: mechanical guarantee (Commander + GUIDE_TOOLS + MCP/HTTP introspection) that every lens-capable surface exposes lens. - tests/graphFusion.test.ts: cascade, hotspots, churnByPath, structural context. https://claude.ai/code/session_01AkYEN6EofWfscZGBMRYAVL
Add cross-reference comments so maintainers know where each half lives: - interpretations.ts (how to READ results) header now documents that the how-to-USE half lives in guideTools.ts definitions + MCP registerTool, and why the files are kept separate (dependency-free prose for the skill generator / narrators). - guideTools.ts ToolDefinition documents description = how-to-USE, pointing at interpretations.ts for result interpretation. - mcp/registerTool.ts notes the server injects only how-to-USE; interpretation reaches MCP clients only via the generated skill. No behavior change (comments only). https://claude.ai/code/session_01AkYEN6EofWfscZGBMRYAVL
The generated "Interpreting gitsema tool results" skill block now shows BOTH halves per tool: Usage (description) + Parameters, joined from the GUIDE_TOOLS definitions, plus the existing Result shape + How to read it from interpretations.ts. gen-skill.mjs joins the two registries by tool name (and MCP aliases); all interpretation entries resolve a usage def (0 gaps). interpretations.ts stays dependency-free — only the build-time generator (which the docsSync test already loads alongside GUIDE_TOOLS) imports the definitions. Regenerated skill/gitsema-ai-assistant.md + .github/skills/gitsema.md; updated CLAUDE.md "Tool interpretations" note. https://claude.ai/code/session_01AkYEN6EofWfscZGBMRYAVL
- get_skill (MCP-only, src/mcp/tools/infrastructure.ts): returns the packaged skill/gitsema-ai-assistant.md so MCP clients can fetch gitsema's usage + result-interpretation playbook. Resolved relative to the module (works in dist and src layouts). - docsSync: new mechanical assertion that every TOOL_INTERPRETATIONS entry resolves a GUIDE_TOOLS usage def (mirrors gen-skill's join), so an interpretation can never silently lose its usage half in the skill. - Register get_skill in server.ts doc block; bump CLAUDE.md MCP tool count (37 → 38) and add the table row. Changeset (minor). https://claude.ai/code/session_01AkYEN6EofWfscZGBMRYAVL
Add docs/deploy.md to the README "Further documentation" table and a callout in the Protocol Servers section pointing at the Docker/compose/systemd guide and the postgres/qdrant compose files. (Docs only.) https://claude.ai/code/session_01AkYEN6EofWfscZGBMRYAVL
Document the three primary deployment scenarios: - Scenario 1: Single-dev, local (zero infra, SQLite) - Scenario 2: Single-dev, self-hosted (multi-location, incremental, multiple repos) - Scenario 3: Multi-dev, hosted (shared infrastructure, Postgres/Qdrant) Clarify Model A architecture (client repos, server index), explain incremental indexing strategy via --since and hash-based deduplication, and outline web UI tier to be built. Define MCP over HTTP (no SSE), specify test strategy per scenario, and envision actual developer/team workflows (onboarding, feature dev, incident response, cross-team collaboration). Include implementation roadmap through Phase 116+. https://claude.ai/code/session_01AkYEN6EofWfscZGBMRYAVL
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Added comprehensive deployment scenarios and usage envisioning section to
docs/PLAN.md.Content:
--sinceArchitecture clarification:
--since+ content-addressed blobs enables multi-location development without re-embeddingTest plan
claude/knowledge-graph-phases-110-111-1h4aixhttps://claude.ai/code/session_01AkYEN6EofWfscZGBMRYAVL
Generated by Claude Code