Skip to content

Commit 88d4dfb

Browse files
committed
Clarify CLI lifecycle ownership
1 parent 960f8d2 commit 88d4dfb

10 files changed

Lines changed: 75 additions & 144 deletions

‎docs/CLI_MIGRATION_STATUS.md‎

Lines changed: 35 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Status markers: **COMPLETE**, **PARTIAL**, **REMAINING**, **BLOCKED/EXTERNAL**.
1515
- **COMPLETE** Canonical exploration loop exists for `index`, `projects`, `status`, `search`, `snippet`, `trace`, and `coverage`.
1616
- **COMPLETE** Neutral graph/source commands now also include `schema`, `query`, `architecture`, `changes`, `source-search`, `outline`, and `compare`.
1717
- **COMPLETE** Existing cache/index/database naming and persisted compatibility-sensitive internals remain unchanged.
18-
- **PARTIAL** Legacy installer/update/uninstall cleanup remains only for ownership-aware removal of MCP-era state; active install paths are structurally CLI-first and no longer carry an MCP-enable transition flag.
18+
- **COMPLETE (CP78/CP80 audit):** active install, hook-install, update, and uninstall paths do not create, migrate, adopt, or remove `codebase-memory-mcp` registrations or MCP-owned assets. Historical MCP recognizers may remain as unreachable compatibility utilities, but the CLI lifecycle treats those artifacts as foreign.
1919

2020
## 2. Neutral operation API / MCP extraction
2121

@@ -207,15 +207,15 @@ No production or retained C behavioral-test source includes `mcp/mcp.h` or calls
207207

208208
- **COMPLETE:** renamed the historical tier/profile renderer source and test surfaces to `legacy_agent_profiles.*`, making their ownership explicit: they reproduce bytes from prior releases solely so update/uninstall can remove exact Codebase Memory-owned documents without deleting modified or foreign files.
209209
- **PRESERVED:** historical `--tool-profile=analysis|scout`, MCP server names, and old agent dialect payloads remain inside that legacy renderer because byte-accurate recognition is a safety mechanism, not an active install capability.
210-
- **COMPLETE:** new OpenClaw compaction augmentation now writes `Codebase Knowledge Graph (codebase-memory-cli)`. Cleanup recognizes and removes both the current CLI label and the historical MCP label.
210+
- **COMPLETE (CP78):** OpenClaw compaction augmentation uses the CLI-owned `Codebase Knowledge Graph (codebase-memory-cli)` label. The CLI lifecycle no longer claims the historical MCP label.
211211
- **COMPLETE:** the durable agent-instructions contract test now validates the actual CLI-first instructions and rejects `codebase-memory-mcp`/`search_graph` leakage from new instructions.
212212
- **COMPLETE:** `doctor` now reports effective watcher state plus UI enabled/port configuration in both human and JSON output, reusing existing configuration sources rather than introducing duplicate health infrastructure.
213213

214214
## CP57 — creation-era test and dead result-helper cleanup
215215

216216
- **COMPLETE:** removed the unused `cbm_cli_mcp_result_is_error()` API. It had no production caller and survived only through a self-test for the retired MCP result envelope.
217217
- **COMPLETE:** removed creation-era CLI tests that expected fresh tiered MCP subagents, per-agent MCP server blocks, or `--tool-profile` registrations. Current install behavior is CLI-first; byte-accurate historical renderers remain tested separately for ownership-aware update/uninstall cleanup.
218-
- **PRESERVED:** durable CLI instructions, skills, hooks, exact legacy cleanup recognition, foreign-file protection, and tier-profile uninstall/migration coverage remain in the active test graph.
218+
- **PRESERVED:** durable CLI instructions, skills, hooks, foreign-file protection, and historical recognition helpers remain where useful for compatibility analysis; CLI lifecycle operations do not use those helpers to remove MCP-owned state.
219219

220220
## CP58 — recovery observability and concurrency evidence audit
221221

@@ -351,4 +351,35 @@ Status: **IMPLEMENTED / REQUIRES EXTERNAL RERUN**
351351
- **COMPLETE:** setup scripts no longer activate repository Git hooks implicitly. Post-install guidance makes agent-hook installation explicitly opt-in.
352352
- **REGRESSION COVERAGE ADDED:** CP78 plan tests assert that asset and hook plans are disjoint, and a Claude coexistence test asserts that explicit CLI hook installation preserves a pre-existing MCP hook command/file while installing separate CLI hook identities.
353353
- **VERIFIED LOCALLY:** changed production CLI and CLI-test translation units compile with the repository's strict `-Wall -Wextra -Werror` production/test policies and ASan/UBSan test instrumentation.
354-
- **PENDING EXTERNAL GATE:** the full sanitizer runner could not be linked within the bounded local compiler windows because the repository-wide grammar/dependency build repeatedly exhausted the command window. No CP78 compile failure surfaced. Run the canonical Jenkins/`scripts/test.sh` gate on the CP78 candidate; reconcile any stale pre-CP78 ownership assertions rather than weakening the MCP/CLI separation contract.
354+
- **VERIFIED LOCALLY (runtime):** the two CP78-specific sanitizer regressions pass 2/2: asset and hook plans are disjoint, and explicit Claude CLI-hook installation preserves pre-existing MCP hook files/settings while adding separate CLI-owned hook identities. The broader CLI suite cannot be treated as local Gate-1 evidence in this sandbox because an older activation/hash test stalls before the CP78 region when the runner is relocated under a private safe path.
355+
- **PENDING EXTERNAL GATE:** run the canonical Jenkins/`scripts/test.sh` gate on the CP78 candidate; reconcile any stale pre-CP78 ownership assertions rather than weakening the MCP/CLI separation contract.
356+
357+
### CP79 — CP78 local qualification closeout
358+
359+
- **COMPLETE:** CP78's focused runtime qualification is green under ASan/UBSan (2/2). The coexistence regression was corrected to snapshot file contents with allocating reads rather than aliasing the test helper's static buffer.
360+
- **COMPLETE:** a fresh incremental CLI runner was linked successfully after the repository-wide sanitizer dependency graph completed. Running from `/mnt/data` correctly triggers the installer's unsafe-ancestor guard; relocating the runner beneath a private `0700` directory gets past that guard but an unrelated pre-existing activation/hash test stalls before the CP78 assertions. No product workaround was added.
361+
- **QUALIFICATION LIMITATION:** an optimized production build progressed through all ordinary production objects and grammar objects but the monolithic `prod_lsp_all.o` compilation alone exceeds the sandbox's maximum uninterrupted command window (including a 240-second attempt). No production compiler error surfaced.
362+
- **PENDING EXTERNAL GATE:** Jenkins remains the authoritative Gate-1 venue for the complete clean sanitizer suite and optimized production link. CP79 makes no runtime/product architecture changes beyond the CP78 candidate.
363+
364+
### CP80 — Static side-by-side ownership audit
365+
366+
- **FIXED:** KiloCode asset installation once again installs the CLI-owned `codebase-memory-cli.md` durable instruction and registers only that instruction reference; the CP78 reconstruction had accidentally left uninstall operations in the install branch.
367+
- **FIXED:** KiloCode uninstall now removes only the CLI-owned instruction reference/file and leaves both current and historical MCP configuration/rules untouched.
368+
- **FIXED:** shell PATH persistence is labeled `codebase-memory-cli install` rather than the retired MCP product name.
369+
- **RECONCILED:** migration-status language now matches the CP78 side-by-side contract: active CLI lifecycle operations do not use historical MCP cleanup as a migration mechanism.
370+
- **STATIC AUDIT ONLY:** per user direction, CP80 was reviewed by source/diff inspection only. No compilation or tests were run for this checkpoint.
371+
372+
### CP81 — Static lifecycle ownership closeout
373+
374+
- **FIXED:** VS Code profile uninstall no longer enumerates profile `mcp.json` files or removes any MCP registration; profile MCP state is foreign under the CP78 side-by-side contract.
375+
- **FIXED:** hook-augment timeout breadcrumbs now use the CLI-owned `~/.cache/codebase-memory-cli/logs` namespace rather than writing diagnostics into the MCP cache namespace. The compatibility-sensitive graph/index cache remains unchanged.
376+
- **RECONCILED:** `cli.h`, agent-client source comments, `docs/llms.txt`, configuration guidance, and Windows/Linux qualification instructions now describe the actual split lifecycle: `install` writes assets only, `install-hooks` is explicit, and MCP state is preserved.
377+
- **STATIC AUDIT ONLY:** no compilation or tests were run for CP81 by explicit instruction. Package verification is limited to source/diff/overlay integrity checks.
378+
379+
### CP82 — Static lifecycle wording and legacy-fingerprint audit
380+
381+
- **STATIC AUDIT ONLY:** no compilation or tests were run for CP82.
382+
- **RECONCILED:** generic asset installation now reports that hooks require the explicit `codebase-memory-cli install-hooks` surface instead of describing the asset-only path as “instructions/hooks”.
383+
- **RECONCILED:** `uninstall --help` now explicitly limits removal to CLI-owned agent assets/hooks and states that MCP registrations/assets are preserved.
384+
- **CLARIFIED:** legacy MCP SessionStart/SubagentStart payload constants are named and documented as byte-for-byte recognition fingerprints only; current CLI hook generation continues to invoke `codebase-memory-cli hook-augment`.
385+
- **REVIEWED:** release-facing `codebase-memory-mcp` repository URLs remain intentional historical-repository-slug references; compatibility cache/config paths retaining the historical name are likewise unchanged.

‎docs/CONFIGURATION.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -195,7 +195,7 @@ not name is permitted.
195195

196196
## 5. Agent and Editor Integration Files
197197

198-
The CLI-first `install` path can write Codebase Memory skills, durable CLI instructions, and compatible lifecycle/context hooks for detected agents. It does **not** create new MCP registrations or MCP-bound tier profiles/extensions. Legacy ownership-aware editors/removers remain present so update/uninstall can safely remove older Codebase Memory-owned MCP entries without deleting foreign or modified configuration.
198+
The CLI-first `install` path can write Codebase Memory skills and durable CLI instructions for detected agents. Hooks are a separate explicit opt-in via `codebase-memory-cli install-hooks`. Neither lifecycle surface creates, migrates, adopts, or removes MCP registrations or MCP-owned assets; existing MCP state is treated as foreign for side-by-side safety.
199199

200200
Those target paths vary by tool and platform, so the easiest way to inspect the exact files for your machine is:
201201

‎docs/LINUX_RELEASE_QUALIFICATION.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -193,7 +193,7 @@ CP76 reconciles that evidence rather than treating 59 assertions as independent
193193
2. hook project lookup could open a nonexistent derived-name DB during its fast probe and thereby shadow an existing custom-named index discoverable by canonical `root_path`;
194194
3. Claude's exact-owned gate-script migration did not recognize the released MCP-era sibling binary basename after the product executable rename.
195195

196-
The incremental assertions now follow the neutral operation-result wire shape. CLI installer assertions require supported CLI-first configuration, durable instructions/skills, and lifecycle hooks while preserving explicit legacy ownership/cleanup contracts where compatibility requires them.
196+
The incremental assertions now follow the neutral operation-result wire shape. CLI installer assertions require supported CLI-first durable instructions/skills from `install`, explicit CLI-owned hooks only from `install-hooks`, and preservation of MCP registrations/assets across CLI lifecycle operations.
197197

198198
Focused sanitizer verification of the final eight-case CLI cluster passes 8/8 with ASan/UBSan and leak detection enabled. Changed production and test objects compile under the normal strict sanitizer and production warning flags. The sandbox cannot execute the full incremental fixture because that fixture performs an outbound GitHub clone; its changed assertions were reconciled against the captured real-run response shapes and compile successfully.
199199

@@ -241,4 +241,3 @@ evidence once those assertions are corrected.
241241
**Gate status:** CP77 requires one final external `scripts/test.sh` rerun because
242242
it changes `src/operations/search.c`. The memory-analysis leg does not need to
243243
be repeated unless that rerun exposes new memory evidence.
244-

‎docs/WINDOWS_RELEASE_VALIDATION.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -126,8 +126,9 @@ Required scenarios:
126126
- basic index/search/doctor workflow;
127127
- update handoff where supported;
128128
- uninstall;
129-
- cleanup of Codebase Memory-owned legacy MCP configuration without deleting foreign/modified entries;
130-
- no clean-install creation of MCP server registrations or retired executable names.
129+
- preservation of existing MCP configuration and MCP-owned assets across CLI install/update/uninstall;
130+
- no clean-install creation of MCP server registrations or retired executable names;
131+
- hooks installed only after an explicit `codebase-memory-cli install-hooks` invocation.
131132

132133
Capture before/after filesystem/config evidence for install and uninstall tests.
133134

‎docs/agents/WINDOWS_RELEASE_QUALIFICATION_AGENT.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,7 @@ Exercise supported install/update/uninstall paths separately from the portable b
105105

106106
Verify installed executable identity matches the candidate.
107107

108-
Pay particular attention to ownership-aware legacy cleanup: Codebase Memory-owned historical MCP configuration may be removed, but foreign or modified configuration must remain intact. Clean install must not create new MCP registrations.
108+
Pay particular attention to side-by-side ownership: existing MCP configuration and MCP-owned assets must remain unchanged across CLI install/update/uninstall. Clean install must not create new MCP registrations, and CLI-owned hooks must appear only after an explicit `codebase-memory-cli install-hooks` invocation.
109109

110110
## Step 8 — Comparative benchmarking
111111

‎docs/llms.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
- Machine output: canonical commands support deterministic `--json` output and non-zero exit status on operational failure.
1313
- Semantic search: local bundled embeddings; no API key or hosted inference required.
1414
- Cross-repo intelligence: graph relationships and architecture queries across indexed repositories.
15-
- Install integration: `install` may add CLI-first skills, durable instructions, and compatible lifecycle/context hooks for detected coding agents. Clean installs do not create MCP registrations.
15+
- Install integration: `install` may add CLI-first skills and durable instructions for detected coding agents. Hooks require the separate explicit `install-hooks` command. Neither lifecycle surface creates, migrates, adopts, or removes MCP registrations or MCP-owned assets.
1616
- Distribution: native release archives plus npm, PyPI, Homebrew, Scoop, Winget, Chocolatey, AUR, and Go packaging.
1717

1818
## Agent use

‎src/cli/agent_clients.c‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
/*
2-
* agent_clients.c — Agent-client discovery and legacy MCP cleanup.
2+
* agent_clients.c — Agent-client discovery and historical MCP recognizers.
33
*
4-
* Active installation is CLI-first. This module retains legacy MCP path
5-
* resolution and ownership-preserving removal solely so upgrades/uninstalls
6-
* can clean configurations created by older releases.
4+
* Active installation and lifecycle cleanup are CLI-owned only. Historical
5+
* MCP path/ownership helpers remain for compatibility analysis and tests;
6+
* current install/update/uninstall flows must treat MCP artifacts as foreign.
77
*/
88
#include "agent_clients.h"
99

0 commit comments

Comments
 (0)