Context-LSP

Context-LSP is a Codex-centered CLI and skill layer for ContextPack retrieval, Project Brain bootstrap and migration, warning-first guards, architecture drift checks, doc-update recommendations, and advisory diagnostics.

The current Phase 1 MVP implements local hybrid BM25 rag-lite over Markdown planning docs and repository chunks:

• index docs/planning as line-range chunks with frontmatter, headings, wikilinks, paths, and an in-memory BM25 index
• retrieve a token-budgeted JSON ContextPack for planning/code/review tasks
• populate ContextPack.code_refs with ranked path, line range, snippet, score, and matched terms when --root is provided
• split camelCase/snake_case identifiers and add CJK bigrams for lexical retrieval
• extract source-backed must, should, and warn constraints
• run warning-first output guard checks before code generation
• report warning-first vault and code-doc drift findings
• recommend minimal planning doc updates after drift findings
• preview and apply approved Project Brain document patches
• preview and safely migrate existing Project Brain vaults without overwriting user-authored content
• expose verification findings as advisory LSP-style diagnostics
• expose bootstrap/index/retrieve/output-guard/verify/diagnostics/recommend-doc-updates/update-project-brain/migrate-project-brain through a local CLI
• provide repo-local Codex skill scaffolding under skills/

Install

Use directly with npx:

npx context-lsp bootstrap --root . --docs docs/planning

Or install the CLI globally:

npm install -g context-lsp
context-lsp bootstrap --root . --docs docs/planning

For local development from this repository:

npm link

Commands

npm test
npm run verify
node src/cli.js --help
node src/cli.js --version
node src/cli.js bootstrap --root . --docs docs/planning
node src/cli.js index --docs docs/planning
node src/cli.js retrieve --docs docs/planning --task "기능 구현 계획 작성" --type plan
node src/cli.js retrieve --docs docs/planning --root . --task "ContextPack code refs" --type code --concept ContextPack --target src --max-tokens 8000
node src/cli.js retrieve --docs docs/planning --root . --task "Narrow code evidence" --type code --target src/core --limit 6 --code-limit 5 --max-tokens 4000
node src/cli.js output-guard --docs docs/planning --root . --task "ContextPack 기반 코드 생성" --type code --target src/core/retriever.js --plan "Use retrieved ContextPack constraints before editing."
node src/cli.js verify --docs docs/planning
node src/cli.js verify --docs docs/planning --root . --changed src/core/retriever.js
node src/cli.js verify --docs docs/planning --root . --changed src/core/retriever.js --fail-on=warning
node src/cli.js diagnostics --docs docs/planning --root . --changed src/core/retriever.js
node src/cli.js recommend-doc-updates --docs docs/planning --root . --changed src/core/retriever.js
node src/cli.js recommend-doc-updates --docs docs/planning --root . --changed-from-git
node src/cli.js update-project-brain --docs docs/planning --root . --changed-from-git --approve DOCREC-1
node src/cli.js update-project-brain --docs docs/planning --root . --findings findings.json --changed src/core/retriever.js --approve DOCREC-1
node src/cli.js init-project-brain --root . --docs docs/planning --name "My Project" --idea "One sentence product idea"
node src/cli.js init-project-brain --root . --docs docs/planning --name "My Project" --idea "One sentence product idea" --profile full
node src/cli.js reverse-engineer --root . --docs docs/planning
node src/cli.js reverse-engineer --root . --docs docs/planning --profile full
node src/cli.js migrate-project-brain --root . --docs docs/planning --to-profile full
node src/cli.js migrate-project-brain --root . --docs docs/planning --to-profile full --apply
node src/cli.js guarantees
node scripts/evaluate-quality.mjs --root .
node scripts/evaluate-quality.mjs --root . --format text
npm run evaluate

After global install or npm link, replace node src/cli.js with context-lsp.

CI Verification

GitHub Actions runs the same local quality gates on pushes to main and on pull requests:

• npm ci
• npm test
• npm run verify

npm run verify exercises the CLI paths for indexing, retrieval, retrieval quality metrics, output guard checks, vault and drift verification, diagnostics, doc-update recommendations, approved Project Brain update previews, Project Brain initialization, brownfield reverse engineering, safe Project Brain migration, and the implementation guarantee registry.

retrieve defaults to an 8,000 estimated-token budget. The estimate is the pretty-printed ContextPack JSON payload's UTF-8 bytes divided by four, not actual model billing tokens. Routed documents and must constraints are not silently dropped; an irreducible result reports budget.overflow: true. Use budget.truncated, budget.overflow, and budget.omitted to decide whether to narrow the task, concept, target, or result limits.

Cross-Project Testing

Install the CLI from this repository once for local testing:

npm link

Register the repo skills globally. By default this links into ~/.codex/skills; set CONTEXT_LSP_SKILLS_DIR to use a different Codex skills directory.

npm run setup:skills
CONTEXT_LSP_SKILLS_DIR="$PWD/.codex-skills" npm run setup:skills
CONTEXT_LSP_SKILLS_DIR="$PWD/.codex-skills" npm run teardown:skills
node scripts/manage-skills.mjs setup --target-dir "$PWD/.codex-skills" --json

The setup script is idempotent: existing links to this repo are reported as already-linked, broken symlinks are repaired as relinked-broken, and existing files or directories are reported as conflict without being overwritten. npm run teardown:skills removes only symlinks that point back to this repository.

Then open another project and run:

context-lsp bootstrap --root . --docs docs/planning
context-lsp init-project-brain --root . --docs docs/planning --name "My Project" --idea "One sentence product idea"
context-lsp init-project-brain --root . --docs docs/planning --name "My Project" --idea "One sentence product idea" --profile full
context-lsp reverse-engineer --root . --docs docs/planning
context-lsp reverse-engineer --root . --docs docs/planning --profile full
context-lsp migrate-project-brain --root . --docs docs/planning --to-profile full
context-lsp migrate-project-brain --root . --docs docs/planning --to-profile full --apply
context-lsp retrieve --docs docs/planning --root . --task "기능 구현 계획 작성" --type plan
context-lsp output-guard --docs docs/planning --root . --task "기능 구현" --type code --target src
context-lsp verify --docs docs/planning
context-lsp diagnostics --docs docs/planning --root . --changed src
context-lsp recommend-doc-updates --docs docs/planning --root . --changed src
context-lsp recommend-doc-updates --docs docs/planning --root . --changed-from-git
context-lsp update-project-brain --docs docs/planning --root . --changed-from-git --approve DOCREC-1
context-lsp update-project-brain --docs docs/planning --root . --findings findings.json --changed src --approve DOCREC-1

If the other project has no docs/planning vault yet, start with context-lsp bootstrap and create the vault before retrieval/verification. Use --profile full when the goal is a project second brain rather than a minimal bootstrap skeleton.

For an existing Project Brain, inspect bootstrap.project_brain_migration. When needed is true, run migrate-project-brain without --apply first. Review the reported docs root, mode, operations, manifest plan, and conflicts, then apply on a dedicated branch. Migration creates missing full-profile documents and updates only explicit Context-LSP managed blocks; it never uses --overwrite. After apply, require verification.status: passed and re-run the preview until summary.planned_changes is 0.

Planning Vault

Start from:

• docs/planning/00-index.md
• docs/planning/00-agent-retrieval-map.md
• docs/planning/02-architecture/interface-contracts.md

The v1 guard is warning-first. Findings provide evidence and recommended actions but do not hard block changes.

Guarantees

The current implementation guarantee registry is available in two forms:

• human-readable: docs/planning/06-validation/implementation-guarantees.md
• machine-readable: node src/cli.js guarantees

NPM Package

The npm package ships the CLI source, planning docs, and Codex skill scaffolds. Tests and fixtures are excluded from the published tarball.