From c1d4defb00b852d2859740efa43de91304c6d4ff Mon Sep 17 00:00:00 2001 From: ngallodev Date: Thu, 15 Oct 2026 10:39:45 -0700 Subject: [PATCH 1/2] Remove local machine details from public docs Replace home-directory state paths and local checkout paths in the upstream audit, reconciliation report, backlog and handoff with neutral placeholders, and refer to the CI host instead of its machine name. Jenkins helper scripts and job XML contain functional local paths and are left unchanged. --- BACKLOG.md | 2 +- SESSION_HANDOFF.md | 2 +- docs/CLI_MIGRATION_STATUS.md | 2 +- docs/UPSTREAM_308_CANDIDATE_AUDIT_20260912.md | 18 +++++++++--------- .../UPSTREAM_RECONCILIATION_REPORT_20261002.md | 4 ++-- 5 files changed, 14 insertions(+), 14 deletions(-) diff --git a/BACKLOG.md b/BACKLOG.md index 62ffdf6b36..6b067afdc1 100644 --- a/BACKLOG.md +++ b/BACKLOG.md @@ -271,4 +271,4 @@ Native Windows qualification and fresh Jenkins51 result remain separate. ## External Luna worker CLI cache resolution — 2026-10-05 -- [ ] Investigate `codebase-memory-cli: secure CLI coordination could not be created (cache-resolve)` in prepared external Herdr workers. Observed on `cbm status --project ttm-jenkins-repair-20261005 --json` / exact-project status/projects probes in Tax Machine runs `ttm-jenkins-repair-20261005` and `ttm-jenkins-verify-20261005`; installed parent CLI reports `dev`. Both exact worktrees under `/home/nate/.local/share/agent-workflow/worktrees/the-tax-machine/jenkins-{repair,verify}-20261005` were fully indexed with persistence false, ready at 2026-10-05T14:27:42/43Z, source `efa9b0a1971ec6d9a33457401ddeb337c1eeea3b`, and unchanged empty Git porcelain. Parent status/projects succeed; worker calls fail before graph query despite launch args approval never / danger-full-access. Expected workers to access those ready graphs. Runtime/environment cause remains unproven. Workers preserve unchanged porcelain and use exact source/config fallback; issue remains open. Durable evidence: `/home/nate/.local/state/agent-workflow/runs/ttm-jenkins-verify-20261005/output.log` and both runs' `evidence/launch-preflight/`. Do not reset the shared daemon or widen allow-roots as a workaround. +- [ ] Investigate `codebase-memory-cli: secure CLI coordination could not be created (cache-resolve)` in prepared external Herdr workers. Observed on `cbm status --project ttm-jenkins-repair-20261005 --json` / exact-project status/projects probes in Tax Machine runs `ttm-jenkins-repair-20261005` and `ttm-jenkins-verify-20261005`; installed parent CLI reports `dev`. Both exact worktrees under `` were fully indexed with persistence false, ready at 2026-10-05T14:27:42/43Z, source `efa9b0a1971ec6d9a33457401ddeb337c1eeea3b`, and unchanged empty Git porcelain. Parent status/projects succeed; worker calls fail before graph query despite launch args approval never / danger-full-access. Expected workers to access those ready graphs. Runtime/environment cause remains unproven. Workers preserve unchanged porcelain and use exact source/config fallback; issue remains open. Durable evidence: `` and both runs' `evidence/launch-preflight/`. Do not reset the shared daemon or widen allow-roots as a workaround. diff --git a/SESSION_HANDOFF.md b/SESSION_HANDOFF.md index 25e163e8ee..f6e0bcc227 100644 --- a/SESSION_HANDOFF.md +++ b/SESSION_HANDOFF.md @@ -4,7 +4,7 @@ Date: 2026-09-03 ## Repository -- Local path: `/lump/apps/codebase-memory-cli` +- Local path: `/codebase-memory-cli` - Branch: `release-tooling` - HEAD: `fae6ff45` (`docs: deprecate MCP-dependent tests`) - Fork: `https://github.com/ngallodev/codebase-memory-cli` diff --git a/docs/CLI_MIGRATION_STATUS.md b/docs/CLI_MIGRATION_STATUS.md index 11b70dd227..ac76e217e6 100644 --- a/docs/CLI_MIGRATION_STATUS.md +++ b/docs/CLI_MIGRATION_STATUS.md @@ -257,7 +257,7 @@ unoptimized/older binary was used for measurements. See `docs/PERFORMANCE_BASELI - **COMPLETE:** comparative Windows benchmarking is specified around a frozen repository corpus, exact artifact identity, fresh-cache alternating trials, correctness/shape parity, and retained raw evidence. - **COMPLETE:** a standalone Windows qualification-agent runbook defines acquisition, identity verification, frozen-corpus checks, functional/recovery testing, install/update/uninstall validation, benchmarking, failure classification, and evidence summary requirements. - **COMPLETE:** benchmark corpus revisions are immutable within a corpus generation. Any repository revision change creates a new generation and requires a new baseline capture rather than comparison against older results. -- **REMAINING:** finalize the exact `agent-workflow` remote and select/pin the fourth larger open-source repository already available on `r6d12`/the qualification environment. +- **REMAINING:** finalize the exact `agent-workflow` remote and select/pin the fourth larger open-source repository already available on the CI host / the qualification environment. - **REMAINING:** complete Linux consolidation, publish an immutable GitHub release candidate, execute native Windows qualification and comparative baselines, then run agent usability and produce the final product skill. ## CP62 — Frozen benchmark corpus finalization diff --git a/docs/UPSTREAM_308_CANDIDATE_AUDIT_20260912.md b/docs/UPSTREAM_308_CANDIDATE_AUDIT_20260912.md index e6563c4eed..adb9e8c234 100644 --- a/docs/UPSTREAM_308_CANDIDATE_AUDIT_20260912.md +++ b/docs/UPSTREAM_308_CANDIDATE_AUDIT_20260912.md @@ -534,7 +534,7 @@ significant. No earlier agent verdict or Jev answer was supplied to this call. ### Exact remaining limits, evidence and validation Run `CBM-UPSTREAM-SOL-20261002-R2`, under -`/home/nate/.local/state/agent-workflow/runs/CBM-UPSTREAM-SOL-20261002-R2/evidence/`, +`/agent-workflow/runs/CBM-UPSTREAM-SOL-20261002-R2/evidence/`, owns `merge-crosswalk.jsonl`, `nonmerge-crosswalk.jsonl`, `first-parent-history.tsv`, `canonical-reconciliation.jsonl`, `slice-grouping.json`, `next-five-slices.json`, `unresolved-dispositions.tsv`, source/combined diffs, @@ -578,7 +578,7 @@ convert its exit or scoped doc commit into review, acceptance or integration. ## Current fetch — 2026-10-01 PDT CLI `upstream` was refreshed with `git fetch upstream --prune`; MCP `main` was -fast-forwarded with `git pull --ff-only` in `/lump/apps/codebase-memory-mcp`. +fast-forwarded with `git pull --ff-only` in `/codebase-memory-mcp`. No CLI pull was performed. | Item | Value | @@ -864,7 +864,7 @@ completion; its documentation commit `fd2aca2a` is separate from these slices. ## 2026-10-01 recovery evidence and outstanding work The independent parity audit is available at -`/home/nate/.local/state/agent-workflow/runs/CBM-MCP-CLI-PARITY-20260930/evidence/parity-report.md`. +`/agent-workflow/runs/CBM-MCP-CLI-PARITY-20260930/evidence/parity-report.md`. It found no operation-name absence, but `manage_adr` is compatibility-only: there is no top-level `manage-adr` alias/help route, and CLI omits MCP's `outline` mode while using a different default. The report prioritizes adding @@ -1152,7 +1152,7 @@ shared Jenkins job; workers may format, inspect diffs and commit regression sour The requested Herdr right-hand panes could not be launched because this caller is outside a Herdr-managed pane (`HERDR_ENV` unset). No Herdr control was attempted and no headless fallback was substituted. The durable launch handoff is -`/home/nate/.local/state/agent-workflow/handoffs/CBM-THREE-VERTICALS-20261002/README.md`. +`/agent-workflow/handoffs/CBM-THREE-VERTICALS-20261002/README.md`. Preparation is not running, implementation completion, review or acceptance. ### Interactive Herdr launch verified — 2026-10-02T04:52Z @@ -1222,7 +1222,7 @@ Previously implemented daemon/cache/ReScript candidates remain unmerged and unvalidated; do not confuse their surviving branch commits with accepted ports. Compact handoff, frozen universes, index/process receipts, native launch and acknowledgement evidence are retained at -`/home/nate/.local/state/agent-workflow/handoffs/CBM-UPSTREAM-AUDIT-20261002/`. +`/agent-workflow/handoffs/CBM-UPSTREAM-AUDIT-20261002/`. ## Three-candidate integration review resumed — 2026-10-02 @@ -2192,7 +2192,7 @@ successor lineage without rewriting sealed evidence. Exact full-hash remainders and immutable worker checkpoints remain under the four run evidence directories. Cleanup inventory SHA256s, before/after pane receipts, and external exits are saved at -`/home/nate/.local/state/agent-workflow/handoffs/CBM-LUNA-CLEANUP-20261003/`. +`/agent-workflow/handoffs/CBM-LUNA-CLEANUP-20261003/`. No local builds/tests, Jenkins, independent acceptance, push or main integration occurred in this cleanup. Overall audit remains incomplete. @@ -2202,7 +2202,7 @@ User authorized a different20-commit comparison with Luna medium. Run `CBM-RECON-LUNA-MEDIUM20-20261003` owns20 independently unreviewed runtime hashes, disjoint from the previous pilot20 and six parent-reviewed rows. Exact assignment, prepared prompt and launch receipts: -`/home/nate/.local/state/agent-workflow/handoffs/CBM-LUNA-MEDIUM20-20261003/`. +`/agent-workflow/handoffs/CBM-LUNA-MEDIUM20-20261003/`. Worker uses interactive Herdr `wC:pK`, `codex - luna-review-medium20`, with GPT-6-Luna medium, sourced Jev environment and batched primary-evidence guidance. @@ -2227,7 +2227,7 @@ live worker Jev credential inheritance confirmed without values. New evidence must remain in successor run; prior evidence is immutable. Renamed pane/worker `codex - deepseek-pilot20-continue`, durably steered and resumed with mandatory acknowledgement. Recovery receipts/prompt at -`/home/nate/.local/state/agent-workflow/handoffs/CBM-DEEPSEEK-PILOT20-CONTINUE-20261003/`. +`/agent-workflow/handoffs/CBM-DEEPSEEK-PILOT20-CONTINUE-20261003/`. No source closure, Jenkins, review or acceptance credited from recovery. ### Finished pilot20 independent verification and new ops20 — 2026-10-03 UTC @@ -2271,7 +2271,7 @@ wC:pJ as prepared run `CBM-RECON-DEEPSEEK-BATCH2-20-20261003`. Exact20 hashes are disjoint from pilot20 and Luna medium runtime20. Same clean frozen indexed worktree reused; direct shell/CBM/Jev guidance and mandatory durable acknowledgement retained. Assignment/prompt/launch receipts at -`/home/nate/.local/state/agent-workflow/handoffs/CBM-DEEPSEEK-BATCH2-20-20261003/`. +`/agent-workflow/handoffs/CBM-DEEPSEEK-BATCH2-20-20261003/`. No builds/tests/Jenkins, runtime validation, acceptance or main integration claimed. ## Finished ops20 and Luna medium20 independent reviews — 2026-10-03 UTC diff --git a/docs/UPSTREAM_RECONCILIATION_REPORT_20261002.md b/docs/UPSTREAM_RECONCILIATION_REPORT_20261002.md index 181817d7c0..32deca52df 100644 --- a/docs/UPSTREAM_RECONCILIATION_REPORT_20261002.md +++ b/docs/UPSTREAM_RECONCILIATION_REPORT_20261002.md @@ -584,7 +584,7 @@ User authorized a different20-commit comparison with Luna medium. Run `CBM-RECON-LUNA-MEDIUM20-20261003` owns20 independently unreviewed runtime hashes, disjoint from the previous pilot20 and six parent-reviewed rows. Exact assignment, prepared prompt and launch receipts: -`/home/nate/.local/state/agent-workflow/handoffs/CBM-LUNA-MEDIUM20-20261003/`. +`/agent-workflow/handoffs/CBM-LUNA-MEDIUM20-20261003/`. Worker uses interactive Herdr `wC:pK`, `codex - luna-review-medium20`, with GPT-6-Luna medium, sourced Jev environment and batched primary-evidence guidance. @@ -609,7 +609,7 @@ live worker Jev credential inheritance confirmed without values. New evidence must remain in successor run; prior evidence is immutable. Renamed pane/worker `codex - deepseek-pilot20-continue`, durably steered and resumed with mandatory acknowledgement. Recovery receipts/prompt at -`/home/nate/.local/state/agent-workflow/handoffs/CBM-DEEPSEEK-PILOT20-CONTINUE-20261003/`. +`/agent-workflow/handoffs/CBM-DEEPSEEK-PILOT20-CONTINUE-20261003/`. No source closure, Jenkins, review or acceptance credited from recovery. ### Pilot20 verification and ops20 successor — 2026-10-03 UTC From 9312ab2ccaf4888a608e2f77574fc997dcfb4e18 Mon Sep 17 00:00:00 2001 From: ngallodev Date: Thu, 15 Oct 2026 10:40:44 -0700 Subject: [PATCH 2/2] Move internal notes out of the visitor path Delete fork-added working artifacts: the session handoff, backlog, memlab run report, self-hosting UX report, full-suite failure log, CI recovery plan, consolidated source reconciliation and the first vertical-slice plan. Move the dated upstream candidate audit and reconciliation report, the runtime assurance plan, the migration status log and the upstream-next-three specs into docs/internal/ with a README stating they are history. Kept in place: README, attribution and security files, AGENTS.md, configuration and reference docs, the qualification plan, runbooks and protocols, and docs/agents (a contract test reads them). Updated the README migration status link and cross-references in the moved reports. No upstream-authored files were touched. --- BACKLOG.md | 274 -------- MEMLAB_ANALYSIS_AND_RUN_REPORT_2026-09-05.md | 141 ---- README.md | 2 +- SESSION_HANDOFF.md | 43 -- ...IRST_VERTICAL_SLICE_IMPLEMENTATION_PLAN.md | 647 ------------------ docs/CLI_SELF_HOSTING_UX_REPORT_20260912.md | 98 --- ...IDATED_SOURCE_RECONCILIATION_2026-09-01.md | 27 - docs/FULL_SUITE_FAILURES_2026-09-04.md | 75 -- docs/GITHUB_CI_RECOVERY_PLAN_2026-09-08.md | 132 ---- docs/{ => internal}/CLI_MIGRATION_STATUS.md | 0 docs/internal/README.md | 1 + docs/{ => internal}/RUNTIME_ASSURANCE_PLAN.md | 0 .../UPSTREAM_308_CANDIDATE_AUDIT_20260912.md | 4 +- ...UPSTREAM_RECONCILIATION_REPORT_20261002.md | 2 +- .../upstream-next-three/cache-stores/SPEC.md | 0 .../cache-stores/spec.json | 0 .../daemon-ownership/SPEC.md | 0 .../daemon-ownership/spec.json | 0 .../upstream-next-three/rescript-hang/SPEC.md | 0 .../rescript-hang/spec.json | 0 20 files changed, 5 insertions(+), 1441 deletions(-) delete mode 100644 BACKLOG.md delete mode 100644 MEMLAB_ANALYSIS_AND_RUN_REPORT_2026-09-05.md delete mode 100644 SESSION_HANDOFF.md delete mode 100644 docs/CLI_FIRST_VERTICAL_SLICE_IMPLEMENTATION_PLAN.md delete mode 100644 docs/CLI_SELF_HOSTING_UX_REPORT_20260912.md delete mode 100644 docs/CONSOLIDATED_SOURCE_RECONCILIATION_2026-09-01.md delete mode 100644 docs/FULL_SUITE_FAILURES_2026-09-04.md delete mode 100644 docs/GITHUB_CI_RECOVERY_PLAN_2026-09-08.md rename docs/{ => internal}/CLI_MIGRATION_STATUS.md (100%) create mode 100644 docs/internal/README.md rename docs/{ => internal}/RUNTIME_ASSURANCE_PLAN.md (100%) rename docs/{ => internal}/UPSTREAM_308_CANDIDATE_AUDIT_20260912.md (99%) rename docs/{ => internal}/UPSTREAM_RECONCILIATION_REPORT_20261002.md (99%) rename docs/{ => internal}/specs/upstream-next-three/cache-stores/SPEC.md (100%) rename docs/{ => internal}/specs/upstream-next-three/cache-stores/spec.json (100%) rename docs/{ => internal}/specs/upstream-next-three/daemon-ownership/SPEC.md (100%) rename docs/{ => internal}/specs/upstream-next-three/daemon-ownership/spec.json (100%) rename docs/{ => internal}/specs/upstream-next-three/rescript-hang/SPEC.md (100%) rename docs/{ => internal}/specs/upstream-next-three/rescript-hang/spec.json (100%) diff --git a/BACKLOG.md b/BACKLOG.md deleted file mode 100644 index 6b067afdc1..0000000000 --- a/BACKLOG.md +++ /dev/null @@ -1,274 +0,0 @@ -# Backlog - -## Five-slice upstream merge trial — 2026-10-03 - -- [x] Validate and integrate the first five upstream PR milestones through - `4d8ac9e1cea0d645a02f876f47536c54a5bfa406`. Isolated merge source is reconciled: - native trace representation, numeric daemon admission logging, EINTR-safe - backoff, native help and registry selector filtering. Three branch-sync merges - accompany five PR merges/five non-merges (13 ancestry commits total). - Full Jenkins #54 passed at `d3e2ac40` (7,528 tests, zero failures; TSan 671 - passed). Main was fast-forwarded after validation. Final origin publication - and branch receipts are recorded in run evidence `final-promotion.json`. - The ancestry gap is 665, reduced by 13; the global semantic audit remains open. - Canonical full-hash dispositions and acceptance are in the 308 audit's - “Five-slice upstream ancestry trial” section; evidence is in the existing - CBM-UPSTREAM-SOL-20261002-R2 run's `five-slice-merge-trial/` directory. - - -## Resolved - -- [x] Installer fork defaults and AST/watcher/macro/COUNT integration landed via - PR #12; Windows/macOS repairs via PR #13 (`bbabc073`). PR #14 is merged on - current main; historical release claims below remain revision-specific. - - -- [x] Release-tooling implements deferred npm/PyPI/public publication, - removes Claude automation, enables CodeRabbit, adds Linux-only prerelease - selection. Package migration is deferred until exact fork assets and checksums - exist; the previously merged package revisions are retained. PR #14 is merged; real artifact - qualification remains open; these are implementation-complete tasks only. - -- [x] Reconciled completed upstream verticals: COUNT/status, persisted LSP - decode (PR #4), Cypher semantics (PR #5), XML admission (PR #6), TypeScript - await (PR #7), properties scanner cleanup, macro coverage, watcher backoff - and all AST walker stacks are represented on main. See the canonical ledger - for exact commits and remaining scheduler/allocation-failure evidence gaps. -- [x] Removed stale upstream candidates: `77a0c7d9` empty-graph sort and - `04ba2fa3`/`98899ba5` Cypher capacity checks already exist in current source. -- [x] One-shot index metrics are implemented (`0f5a84bc`). Neutral operation/ - daemon test source lists supersede the historical MCP link-time blocker. - -- [x] Resolve application-teardown ownership omission for neutral session - state. `cbm_daemon_application_free()` now calls - `cbm_operation_session_state_free()` before freeing each session. Valgrind - identified the omission through `test_daemon_application_free_releases_live_watch_once` - as 80 direct + 107 indirect lost bytes. -- [x] Validated local `release-tooling` through Jenkins job #34 (full gate - passed at `37dd63ba`). PR #12 merged with installer fix `c9841610` - (install.sh and install.ps1 default to `ngallodev/codebase-memory-cli`). - Resolved thread `PRRT_kwDORjrg5c6n5KE9` 2026-10-01. -- [x] Validated complete AST slice `77ab4bea` / `7707c9d7` in shared - release-tooling Jenkins job #34 (full gate passed at `37dd63ba`); all - definition and auxiliary stacks ported to main. -- [x] Added opt-in, single-run index metrics for performance diagnosis via - `index --metrics-out` flag (`0f5a84bc`). Coverage in src/operations/index.c - and tests/test_index_resilience.c. Merged via PR #12. -- [x] Fixed the PR #12 Windows/macOS CI failures in `bbabc073` (PR #13). - The Windows hook-lifecycle test now uses the fork's installed binary name - (`tests/test_cli.c`), and the macOS connection-cap test gets a 30 s server - hello deadline (`tests/test_daemon_runtime.c`). Jenkins #35 and full GitHub - CI passed. The pre-commit hook also clang-formatted both files. - -## Open - -- [ ] Complete semantic reconciliation of all frozen upstream merges and - constituent commits. Sol R2 inventories all 923 merges / 2,429 non-merges; - 311 merges / 367 non-merges differ by ancestry. It reconciles the older 87 - canonical rows, but 356 non-merge whole-commit remainders and all 311 merge - dispositions remain unresolved. Census, patch ID and titles are not coverage. - See [the canonical source audit](docs/UPSTREAM_308_CANDIDATE_AUDIT_20260912.md). -- [ ] Finish independent reconciliation of the Luna team evidence. All R3 - handoffs were partial; all 40 declared checksums and exact 111/170/86 assignments - were verified and archived. R4 successors continue interactively in Herdr - `wC:pB` / `wC:pC` / `wC:pD`. The 2026-10-02T23:53Z checkpoint contains 54 - non-unresolved worker claims and 313 unresolved claims; no whole-commit coverage - or completion is inferred. Parent retains 356 whole non-merge / 311 merge - remainders pending exact source/test review. Full hashes are in the canonical - ledger; the [consolidated report](docs/UPSTREAM_RECONCILIATION_REPORT_20261002.md) - records provenance, source corrections, scope and validation limits. - Parallel split followup: `CBM-RECON-ADAPTER-LOW-20261003` ran Luna low in - Herdr `wC:pE` on 16 explicitly released, previously unreviewed runtime hashes; - all 16 were source-reviewed, 8 closing as adapter-only and 8 retaining - shared-semantic remainders. The consolidation auditor verified the run's - 67-file manifest, confirmed every changed path is `src/mcp/**` or - `tests/test_mcp.c` (that subtree exists upstream and is absent from - production and both QA trees), and confirmed the 16 are upstream ancestors - absent from those three CLI trees. - After the Phase1 transfer, original runtime retains 39 hashes; all 367 hashes still have one - effective primary owner. The transfer, acknowledgement, index and launch - receipts are in the new run's evidence. Completed work was not reassigned. - Phase1 successor plan now transfers 115 still-unreviewed runtime hashes to - three prepared DeepSeek Flash assignments (39/26/50 disjoint groups), preserving the - exact releases and completed work. Unstarted low2 was retired; corrected low1 - finished partial with detailed handoff and its pane closed. See the canonical - Phase1 plan. Native assignment delivery failed: all three returned predecessor - reports, including after persisted steering and direct follow-ups. Sessions - were stopped; zero assigned comparisons or correlated worker acknowledgements - were established by that failed attempt. Interactive recovery now runs Codex - `--model deepseek-flash` in Herdr `wC:pF` / `wC:pG` / `wC:pH`, with correct - worker-issued run/cwd/count launch acknowledgements and actual process Jev-token - inheritance verified. The same 115 hashes remain the comparison scope; see the - canonical interactive recovery section. No completion/acceptance is inferred. -- [ ] Review additional bounded missing behaviors: malformed confidence parsing - `62b44519c68b403ea44d9a85ba8ee74cddee66e6` (first additional localized candidate), - route handler position `592894a4387a50e1d128ff6a2695ff48f8cc32a5`, late annotation - arguments `c36b4fbc446f9085704a6073b81ec743fd4180fc`, and client-registry selection - `1e25d962d69999438229b0562d44ea60e97f5456`. Group route followups with slice 5; - review full tests/dependencies before broadening implementation scope. -- [ ] Resolve daemon memory policy before selecting active-job division - `21591d51168d26f931f64d62edc36013cd1f6249`. Fork uses fixed worker-capacity - division; upstream active divisor is not represented. Review aggregate - reservation invariants, separate Windows job-memory capability hunks from - MCP adapter policy in merge `2b8bd0c065c1d2728994fddc1683a66f70745748`. -- [x] Daemon/cache/ReScript candidates and ADR alias/outline are integrated - in local QA `559214af28ce2d6f5d6ec86662f6871316d28b45`, per acknowledged - parent steering and source comparison. Candidate implementation is separate - from runtime validation, acceptance and production-main integration. -- [ ] Finish parent review and shared Jenkins validation for that QA revision - and its later repairs. No current Jenkins success or acceptance is established - by Sol R2. The pre-commit candidate retains formatting-only behavior; candidate - ancestry does not establish production Git-child environment isolation. -- [ ] NEW upstream slice 1: Cypher OPTIONAL relationship fallback growth, - `2fabaa2b877986bdededb4f4f78e9a31014c6fdf`; existing append helper avoids - the per-binding overflow. Jenkins `cypher`. -- [ ] NEW upstream slice 2: SQLite zero-cell trailing interior-page packing, - `e7324bb6904c6d0a295b956e83c8585219198358`. - Jenkins `sqlite_writer,graph_buffer,pipeline`. -- [ ] NEW upstream slice 3: Swift scanner shift widths, regression and integrity, - `3f831936b5f3012d13175e7c97326165efecefad` -> - `a2ea711c29560511eb8467bea7ad309ebf500d6e` -> - `e8204092333ee1c38cd681a81abb36f125288894`. - Jenkins `language,extraction,grammar_regression` and vendored integrity; - preserve QA's ReScript manifest/checksum row. -- [ ] NEW upstream slice 4: ancestor ignore chain with correct anchoring, - `c8184ed94887a6b5e130726885b44a07c63a47b7` -> - `282fbfcdabfec79c19c36f5bec5f75c22eb36df5`. - Jenkins `discover,gitignore,git_context,pipeline`. -- [ ] NEW upstream slice 5: deterministic route selection and >64 proto services, - `6b48097471e8d1a3e5cf16447304899a21e12d7a`; adapt route hunks without - importing upstream memory core or unrelated tests. Jenkins `pipeline,parallel`. - Ranking is bounded by inspected source; unresolved work can change priorities. -- [ ] Evaluate GitHub ancestry reconciliation after semantic review. Adapted - commits have different IDs; documentation cannot alter GitHub's behind count. - An upstream ancestry merge requires explicit review of missing/excluded changes - and merge-resolution behavior. Do not use an `ours` merge to conceal unresolved - work, rewrite published history, or declare the fork globally caught up. -- [ ] Clarify CLI coverage array syntax and missing-path results. At dev CLI / - project `tmp-cbm-upstream-sol-20261002`, generation `2026-10-02T17:30:32Z`, - JSON/comma `--paths` values became literal nonexistent paths with - `no_recorded_issue` / `freshness=missing`. Repeated `--paths` / `--scopes` - flags work. Document this spelling and make missing paths prominent. -- [ ] Align trace truncation with documented pagination. `extract_func_def` - both-direction trace at limit 100 returned 127 total callees and truncation - without a next cursor; limit 300 returned all 127 callees / four callers. - Emit a cursor or document the limit restriction. Exact receipts are in Sol R2 - evidence; these are observed CLI issues, with no source fix in this audit. -- [ ] Retain validation gaps: live watcher scheduler integration and AST - allocation-failure injection are not established by completed helper tests. -- [ ] PR #14 at `1ce4e164` has failing GitHub diagnostic, macOS LSan, - Unix/Windows test and shard-completeness checks (2026-10-02T04:14Z snapshot). - Diagnose and pass required checks before merge/release; no release is qualified. - -- [ ] Qualify native Windows/WSL and real fork package installations. Fork - endpoints and a Linux-only prerelease route are implemented on release-tooling - (`1ce4e164`), but implementation is not artifact qualification or publication. - -- [ ] Selectively evaluate remaining upstream fixes from - `../codebase-memory-mcp` before merging into the CLI fork. Do not - cherry-pick MCP-only changes or overwrite CP89/release-tooling work; apply - compatible patches into a temporary worktree, run focused suites, then - review the resulting diff before integration. - - `9846c3f1` and `c1b9c451` Windows daemon/session-root separator - handling; port daemon-only hunks and omit MCP hunks. - - `92725a5e` Windows stdio parent-death cleanup; verify relevance to the - CLI-only process model before porting. - - `e5c17de6` and `b04f5450` coverage correctness/performance; manually - reconcile against the fork's changed coverage implementation. - - Exclude direct MCP-only adapter imports at the source seam; shared neutral - capability parity still requires source verification. Historical exclusions - are superseded by the canonical audit where mixed hunks were found. - -- [ ] Assess a lightweight path for store-only test execution. Run just the - store test binaries after shared prerequisites are built, while keeping the - existing incremental suite selection and full-suite gates intact. First - inspect the runner's configuration and targets to determine whether this is - already supported. The `cbm-upstream-count-20260929` focused run passed 96 - store tests, but a cold worktree spent several minutes compiling shared - prerequisites including `lsp_all.c`. - -- [ ] Classify residual Heaptrack allocations in the neutral daemon test path. - - Baseline evidence: Heaptrack reported 91 leaked allocations across the - daemon application and IPC suites. Valgrind reported 538 bytes from - `cbm_daemon_ipc_endpoint_new()` in the forked crash-simulation child of - `test_daemon_ipc_posix_current_generation_crash_cleanup_requires_startup_lock` - (`src/daemon/ipc.c:889`, test at `tests/test_daemon_ipc.c:3735`). - - Remediation applied: the child now frees its inherited endpoint object - before `_exit()`; it still bypasses `listener_close`, so kernel-released - descriptors/locks and crash artifacts remain part of the test. - - Current evidence: fresh `scripts/analyze-memory.sh` reports no static - findings and Valgrind reports 0 definite, 0 indirect, and 0 possible lost - bytes. Heaptrack reports 87 leaked allocations, which require attribution - as still-reachable allocator/process-lifetime state before any further - cleanup is attempted. - - Next path: inspect the saved Heaptrack allocation call trees; only add - teardown code for allocations proven to be owned by the neutral daemon - rather than allocator or test-process lifetime state. - -- [ ] Finish exact-revision Jenkins evaluation and independent review of the - 2026-10-02 daemon/cache/ReScript integration candidate. Parent corrected the - premature maintenance signal and ReScript child assertion; runtime claims, - remote push and main integration remain pending. See the canonical 308 ledger. -- [ ] Reconcile the GPT-6.1-Sol full upstream merge/constituent audit - `CBM-UPSTREAM-SOL-20261002-R2`, including ungrouped verticals and the next - five recommended slices. Do not count running audit work as coverage. - -- [ ] Complete DeepSeek Phase1 independent source review. All115 assignments and - 342 evidence-manifest entries pass integrity checks; six bounded semantic - questions were reviewed in three batched Jev requests. Documentary result is - changes requested: narrow runtime `9724d903046626df0640ced218259cb58070e4e8` - committed-counter/budget claim, preserve operations - `b04f54506ab42eddcbd89232a0d47d8355edd596` mechanism remainder and - `f6afd6138e605365a76d065d04521ec2037bed3d` title-policy question, and classify - integration `00411ce7bc41995783bfb16aada673515585446d` changed Linux alias - behavior as missing. Other109 hashes remain independently unreviewed; integration -29 partial rows plus1 unresolved row require function-level work. Exact hashes, -requests, full distributions and source corrections are in the canonical308 review -section and consolidated report; machine crosswalk stays handoff evidence. No -completion/acceptance or semantic-closure counter advanced. - -- [x] Gather Luna low pilot and successor source evidence; independent review is - recorded in canonical308. Remaining16 full-hash whole-commit reviews are tracked - below; former launch-only20-unverified snapshot is superseded. - -- [ ] Complete Luna medium runtime20 whole-commit source review: documentary - changes requested; manifest31 passes, two bounded source dispositions verified, -18 exact full-hash remainders in parent evidence/medium20-independent-review/review.json. - Group262ab012 telemetry with3507d955 Windows OS hard cap; no runtime/acceptance credit. - Canonical308 finished-batch review owns corrections. -- [ ] Diagnose generic full-index pipeline failure for clean frozen worktree - `/tmp/cbm-recon-luna-medium20-20261003`; logs preserved in medium20 staging. - Worker safely uses verified existing runtime graph; no daemon changes made. - -- [x] Review resumed DeepSeek pilot20 submission; four bounded source dispositions - verified and16 retained unresolved (see following task). Worker completion is not acceptance. - -- [ ] Resolve prior DeepSeek pilot20 independent review changes:16 exact full-hash - whole-commit remainders in parent evidence/pilot20-independent-review/review.json. - Correct false absent-alias/YAML/fd-guard/Codex claims, map missing CLI regressions, - and preserve stale worker checksum failure; four source reviews credited, no - runtime/acceptance claims. Canonical308 verification section owns corrections. -- [ ] Complete remaining17 DeepSeek ops20 whole-commit source reviews, exact hashes - in parent evidence/ops20-followup-v4-review/review.json. Three source dispositions - verified, including missing Scala route composition d4931241. Preserve56516eff - recursive-grep fallback correction,26650255/f339aa62 dependencies, separate - e5c17de6 unchanged cap context and canonical SQL/stale refusal policy obligations. -- [x] Review followup-v2/v3 evidence and record their semantic limits; v3 hunk - inventory is discovery only. Followup-v4 corrects wrong-function/test exclusion - for d4931241; other17 full-hash semantic mappings remain pending above. -- [x] Independently verify d4931241adaef732066afb5ebf1cb225e2474403 source comparison: - all3 hunks missing across production and both frozen QA refs. Applicable shared - Scala regression/harness verified; prerequisite041eb99c11692b93d43ea72c884cc50c51285db5 - present. Future implementation/Jenkins/acceptance remain unperformed. - -- [x] Confirm ten historical merged/adapted tasks against current release-tooling -327dccc0 source and regression contracts: Go selector binding; daemon UI/Unicode; -Cypher scope/star; registry receiver chains; cohort retry; Windows YAML guards; -cache-root cohort handoff; complexity determinism; Razor; embedded sibling hosts. -10/10 source confirmed, selected remainder0. Canonical308 owns evidence/limits; -no subtraction from678 ancestry or separate35 ops/runtime pending reviews. -Native Windows qualification and fresh Jenkins51 result remain separate. - -## External Luna worker CLI cache resolution — 2026-10-05 - -- [ ] Investigate `codebase-memory-cli: secure CLI coordination could not be created (cache-resolve)` in prepared external Herdr workers. Observed on `cbm status --project ttm-jenkins-repair-20261005 --json` / exact-project status/projects probes in Tax Machine runs `ttm-jenkins-repair-20261005` and `ttm-jenkins-verify-20261005`; installed parent CLI reports `dev`. Both exact worktrees under `` were fully indexed with persistence false, ready at 2026-10-05T14:27:42/43Z, source `efa9b0a1971ec6d9a33457401ddeb337c1eeea3b`, and unchanged empty Git porcelain. Parent status/projects succeed; worker calls fail before graph query despite launch args approval never / danger-full-access. Expected workers to access those ready graphs. Runtime/environment cause remains unproven. Workers preserve unchanged porcelain and use exact source/config fallback; issue remains open. Durable evidence: `` and both runs' `evidence/launch-preflight/`. Do not reset the shared daemon or widen allow-roots as a workaround. diff --git a/MEMLAB_ANALYSIS_AND_RUN_REPORT_2026-09-05.md b/MEMLAB_ANALYSIS_AND_RUN_REPORT_2026-09-05.md deleted file mode 100644 index efca1d429a..0000000000 --- a/MEMLAB_ANALYSIS_AND_RUN_REPORT_2026-09-05.md +++ /dev/null @@ -1,141 +0,0 @@ -# Memlab Analysis and Build/Test Run Report - -Date: 2026-09-05 -Repository: `codebase-memory-cli` -Branch: `release-tooling` -Source state: CP72 overlay applied on the working tree; repository baseline -reported by the overlay is `4f0d7b9`. - -## Executive result - -The clean production build passed. The canonical full test leg did not reach -test execution because it hung in the venue-parity preflight. Memory analysis -completed its static scan and debug build, but the dynamic run was non-green: -Heaptrack reported 85 leaked allocations and the analyzed test runner had -three daemon IPC failures. Valgrind reported no lost memory, with only -still-reachable allocations. - -## Build run - -Command: - -```text -scripts/build.sh -``` - -Result: PASS (exit 0). - -The clean production binary was built at: - -```text -build/c/codebase-memory-cli -``` - -The build used GCC on Linux x86_64 and completed the full production object -and link step after CP72 changes. - -## Canonical full test run - -Command: - -```text -scripts/test.sh -``` - -Result: BLOCKED before suite execution. - -Passed preflight checks included build-directory safety, Windows VM worktree -manifest, UI proxy security, daemon soak recovery, Windows bundle, tree-sitter -dependencies, security fuzz self-test, smoke fixture, parallel scheduler, and -venue parity checks. - -The run then stalled in the venue-parity check while invoking: - -```text -scripts/ci/generate-sbom.py --help -``` - -The child process stopped at `import datetime`, consistent with the existing -shell-versus-Python invocation defect. The stalled process was terminated; -the canonical sanitizer build and full suite were therefore not reached. - -## Memory analysis run - -Command: - -```text -scripts/analyze-memory.sh -``` - -Suites: - -```text -daemon_application daemon_ipc -``` - -Results directory: - -```text -memlab-memory-analysis/20260905-170357-91427 -``` - -### scan-build - -Result: PASS. No findings were reported in the targeted sources: - -- `src/operations/session_state.c` -- `src/operations/store_host.c` -- `src/operations/mutation.c` -- `src/daemon/application.c` - -### Plain debug build - -Result: PASS. The dedicated test runner linked successfully in the temporary -memory-analysis build directory. - -### Heaptrack - -Result: FAIL under the script's leak policy. - -- Allocations: 35,173 -- Leaked allocations: 85 -- Temporary allocations: 1,174 -- Total memory leaked in the Heaptrack analysis: 8.53 KiB - -The complete capture and analysis are included in `heaptrack.zst`, -`heaptrack.analysis`, and the corresponding stdout/stderr files. - -### Valgrind Memcheck - -Result: FAIL as a test-runner result, not as a lost-memory result. - -The runner reported 84 passed and 3 failed tests. The failures were: - -- `daemon_ipc_posix_startup_lock_is_cross_process` -- `daemon_ipc_posix_lifetime_reservation_rejects_fork_inheritance` -- `daemon_ipc_posix_child_participant_handoff_retains_legacy_bridge` - -Leak summary: - -- Definitely lost: 0 bytes -- Indirectly lost: 0 bytes -- Possibly lost: 0 bytes -- Still reachable: 2,816 bytes in 16 blocks -- Valgrind error contexts: 0 - -The complete Memcheck log is `valgrind.log`. - -## Qualification state - -This evidence does not establish a green full-suite or leak-free release -state. The next useful work is to fix the venue-parity Python invocation, -classify the three daemon IPC failures, and attribute Heaptrack's 85 retained -allocations before adding teardown code. - -## Included files - -This report is packaged with the complete run directory, including: - -- Heaptrack compressed capture and analysis; -- Heaptrack stdout/stderr; -- Valgrind log and stdout/stderr. diff --git a/README.md b/README.md index e02f87d8d4..16d3303094 100644 --- a/README.md +++ b/README.md @@ -332,7 +332,7 @@ See [`SECURITY.md`](SECURITY.md) and [`docs/SECURITY-DISCLOSURE.md`](docs/SECURI ## Migration documents -- [`docs/CLI_MIGRATION_STATUS.md`](docs/CLI_MIGRATION_STATUS.md) — current port and qualification status. +- [`docs/internal/CLI_MIGRATION_STATUS.md`](docs/internal/CLI_MIGRATION_STATUS.md) — current port and qualification status. - [`docs/RELEASE_QUALIFICATION_PLAN.md`](docs/RELEASE_QUALIFICATION_PLAN.md) — build, platform, benchmark, and release gates. - [`docs/CLI_ONLY_MIGRATION_PLAN.md`](docs/CLI_ONLY_MIGRATION_PLAN.md) — historical rationale and scope of the MCP removal. diff --git a/SESSION_HANDOFF.md b/SESSION_HANDOFF.md deleted file mode 100644 index f6e0bcc227..0000000000 --- a/SESSION_HANDOFF.md +++ /dev/null @@ -1,43 +0,0 @@ -# Developer Handoff - -Date: 2026-09-03 - -## Repository - -- Local path: `/codebase-memory-cli` -- Branch: `release-tooling` -- HEAD: `fae6ff45` (`docs: deprecate MCP-dependent tests`) -- Fork: `https://github.com/ngallodev/codebase-memory-cli` - -## Completed - -- Applied the cumulative `codebase-memory-cli-production-mcp-unlinked` overlay. -- Production `MCP_SRCS` is empty; neutral JSON arguments, result wire, - operation catalog, index admission, session state, and store host own the - production paths. -- Deleted the daemon MCP frontend, its test, and MCP index-supervisor sources. -- Preserved focused incremental local build rules and neutral session teardown. -- Added `scripts/analyze-memory.sh` and maintained `BACKLOG.md`. -- Marked all detected MCP-dependent test and repro sources deprecated in - `tests/DEPRECATED_MCP_TESTS.md`. - -## Validation - -- `scripts/build-dev.sh`: passed; production binary linked without MCP. -- `scripts/test.sh --suites daemon_application,daemon_ipc`: blocked at the - test-runner link because legacy MCP-dependent tests and repro harnesses still - reference `cbm_mcp_*` while `MCP_SRCS` is empty. These remnants are outside - the CLI test scope and are recorded in `BACKLOG.md`. -- `git diff --check`: passed before commit. - -## Working-tree policy - -- The overlay archives and `.codebase-memory/` are intentionally untracked and - preserved; they are not included in the source handoff archive. -- No push was performed. - -## Next work - -1. Retire or migrate the remaining MCP-dependent test/repro source lists. -2. Classify residual neutral daemon Heaptrack allocations in `BACKLOG.md`. -3. Complete native Windows release evidence and full phase-end CI validation. diff --git a/docs/CLI_FIRST_VERTICAL_SLICE_IMPLEMENTATION_PLAN.md b/docs/CLI_FIRST_VERTICAL_SLICE_IMPLEMENTATION_PLAN.md deleted file mode 100644 index 68fc36a33e..0000000000 --- a/docs/CLI_FIRST_VERTICAL_SLICE_IMPLEMENTATION_PLAN.md +++ /dev/null @@ -1,647 +0,0 @@ -# Codebase Memory CLI-First Migration — First Vertical Slice Implementation Plan - -Status: implementation plan and pre-implementation critical review -Date: 2026-09-01 -Authoritative source: `codebase-memory-mcp-cli-only-handoff-17786374.tar.zst` - -## 1. Objective - -Deliver the first usable CLI-first vertical slice without rewriting the graph engine. - -At the end of this slice: - -- normal product invocation is CLI-only; -- running the binary with no command does **not** start JSON-RPC/MCP or a daemon-backed MCP session; -- the primary exploration loop is available as ordinary named commands; -- machine-readable output remains available; -- skills teach the named CLI, not MCP tools; -- supported hooks continue to provide useful discovery/coverage context while pointing agents at the CLI; -- installers stop creating new MCP server registrations for the integrations touched by the slice; -- legacy `cli ` remains only as a temporary compatibility/parity surface; -- the internal MCP dispatcher may remain temporarily as a private execution kernel for unmigrated business logic, but there is no supported MCP server surface. - -This slice intentionally separates **external MCP disablement** from the larger follow-on job of extracting every tool handler out of `src/mcp/mcp.c`. - -## 2. Why this boundary - -The current code couples three different concerns: - -1. JSON-RPC/MCP transport and session behavior; -2. tool metadata/schema/argument parsing; -3. graph/index business logic. - -The CLI, hook augmenter, daemon application, generated client adapters, and installer all depend on pieces currently named `mcp`. -Attempting to physically delete `src/mcp` in the first slice would therefore require a broad horizontal rewrite before the user receives any useful CLI product. - -The first slice instead makes the **product contract** CLI-first now, then leaves a clearly documented private compatibility kernel to extract in subsequent slices. - -## 3. User-visible vertical slice - -### 3.1 Canonical commands - -The first slice exposes: - -```text -codebase-memory-cli index [PATH] [options] -codebase-memory-cli status [options] -codebase-memory-cli search [QUERY] [options] -codebase-memory-cli trace [options] -codebase-memory-cli snippet [options] -codebase-memory-cli coverage [PATH] [options] -codebase-memory-cli projects [options] -``` - -The binary name remains `codebase-memory-mcp` during this slice to avoid coupling functional migration to packaging/rename work. A later phase renames it to `codebase-memory` with `cbm` as an optional alias. - -### 3.2 Compatibility commands - -The existing form remains temporarily: - -```text -codebase-memory-cli cli ... -``` - -It is not shown as the recommended interface. It exists for parity, old scripts, generated adapters not yet migrated, and characterization during extraction. - -### 3.3 Command mapping - -| CLI | Existing operation | -|---|---| -| `index` | `index_repository` | -| `status` | `index_status` | -| `search` | `search_graph` | -| `trace` | `trace_path` | -| `snippet` | `get_code_snippet` | -| `coverage` | `check_index_coverage` | -| `projects` | `list_projects` | - -Aliases are declared centrally rather than implemented as separate business logic. - -## 4. Agent and human interface contract - -### 4.1 Humans - -Interactive/default output stays readable. Help shows examples and maps ordinary nouns/verbs to behavior. Errors go to stderr and return non-zero. - -### 4.2 Agents - -Every canonical command accepts `--json`. JSON stdout must contain no progress prose. Progress/diagnostics remain on stderr. - -Agents should be able to discover the product with: - -```text -codebase-memory-cli --help -codebase-memory-cli search --help -codebase-memory-cli projects --json -``` - -### 4.3 Positional convenience - -Named commands add only thin positional sugar: - -- `index PATH` -> `--repo-path PATH` -- `search QUERY` -> a safe name-pattern query suitable for ordinary discovery -- `trace SYMBOL` -> `--function SYMBOL` -- `snippet SYMBOL` -> `--qualified-name SYMBOL` -- `coverage PATH` -> `--path PATH` - -Explicit flags remain available and authoritative. Positional sugar must not create a second schema. - -## 5. Phase plan through Vertical Slice 1 - -## Phase 0 — Baseline and migration guardrails - -### Purpose - -Record what is being changed and prevent accidental engine/security simplification. - -### Work - -1. Preserve the archive untouched as the source baseline. -2. Add this implementation plan and decision ledger. -3. Inventory every path that can currently start MCP: - - default process role; - - daemon MCP frontend; - - installer-created MCP configs; - - generated client adapters; - - docs/help/examples. -4. Record mechanisms that must survive: - - project mutation locks; - - version-cohort admission; - - secure runtime/cache validation; - - indexing worker supervision; - - cancellation/maintenance observation; - - allowed-root human authorization; - - hook fail-open behavior; - - existing graph/index format compatibility. -5. Do not change the graph parser, store, Cypher engine, extraction pipeline, or index format. - -### Exit - -The plan and guardrails exist in-tree and all first-slice product entry points are identified. - -## Phase 1 — Make process startup CLI-first - -### Purpose - -Remove the externally reachable/default MCP server behavior before adding convenience commands. - -### Work - -1. Change process-role classification so an invocation with no product command is not an MCP client. -2. Make no-argument invocation print top-level CLI help and exit successfully. -3. Ensure unknown top-level commands fail with an actionable CLI error instead of falling into MCP startup. -4. Keep hidden daemon/worker roles only for implementation mechanisms still required by the first slice. -5. Keep `daemon` as an internal/compatibility lifecycle mechanism only if existing named CLI execution still needs it; do not advertise it as a primary product workflow. -6. Update help so MCP server startup, `--tool-profile`, prompts, and MCP-client language are not presented as product features. - -### Exit - -There is no supported argv shape where “normal usage” enters the MCP JSON-RPC frontend. - -## Phase 2 — Add the canonical named CLI surface - -### Purpose - -Make the product useful without requiring agents/humans to know MCP tool identifiers or JSON argument objects. - -### Work - -1. Add a small command descriptor table containing: - - canonical command; - - underlying compatibility operation ID; - - short description; - - positional argument mapping; - - whether command mutates/indexes; - - examples. -2. Route the seven first-slice commands to the existing one-shot execution path. -3. Reuse current schema-derived flag parsing/help to avoid a parallel parser. -4. Teach `run_cli` whether it is operating under: - - legacy `cli ` mode; or - - canonical named-command mode. -5. Preserve `--json`, `--progress`, `--args-file`, and schema-driven flags. -6. Improve command-specific usage without changing underlying operation semantics. -7. Keep raw JSON accepted only on the legacy compatibility form. - -### Exit - -All seven canonical commands work through ordinary argv and expose useful `--help`. - -## Phase 3 — Reframe skills around the CLI - -### Purpose - -Make agents use Codebase Memory as a shell capability instead of an MCP capability. - -### Work - -1. Update the canonical generated `SKILL.md` content: - - replace MCP/tool-call wording with shell command examples; - - preserve Scout / Verify / Auditor tiers; - - preserve graph-first discovery; - - preserve exact source verification; - - preserve trace direction discipline; - - preserve pagination discipline; - - preserve coverage verification and direct-source fallback. -2. Rewrite tiered agent/subagent profile text to reference named commands. -3. Keep the skill focused on *when and how* to use Codebase Memory; do not turn it into a CLI manual. -4. Ensure examples use `--json` when machine parsing matters and ordinary text when an agent simply needs concise evidence. - -### Exit - -A newly generated skill contains no instruction telling the agent to call MCP tools or open an MCP session. - -## Phase 4 — Preserve useful hooks, remove MCP assumptions from their user contract - -### Purpose - -Keep the agent ergonomics that add value without treating hooks as an MCP transport. - -### Work - -1. Preserve search augmentation and post-read coverage warnings. -2. Preserve fail-open and time-budget behavior. -3. Update lifecycle/reminder text to point at canonical CLI commands. -4. Remove notices that tell users to “open an MCP session”. -5. Do **not** broadly rewrite `hook_augment.c` in this slice: it currently calls the private compatibility dispatcher directly, and extracting it is part of the next internal-kernel slice. -6. Ensure hook installation can stand on its own as a CLI/skill integration. - -### Exit - -Hooks remain useful and no longer teach or require an externally reachable MCP product surface. - -## Phase 5 — Stop creating new MCP registrations - -### Purpose - -Prevent a CLI-first installation from re-enabling the old product contract in coding-agent configuration. - -### Work - -1. Change default agent configuration so it installs only CLI-oriented assets that are safe/useful: - - skills/instructions; - - supported hooks; - - tiered agent profiles where they add value. -2. Do not write new `mcpServers`, `mcp_servers`, or equivalent registrations. -3. Preserve MCP removal code temporarily so uninstall/migration can clean entries owned by older Codebase Memory installations. -4. Generated adapters that exist solely to create MCP-like tool registrations are not installed by default in this slice. -5. Installation plan output should describe skill/hook/CLI integration rather than MCP registration. - -### Exit - -A clean first-slice install creates no new MCP server configuration. - -## Phase 6 — First-slice docs and executable acceptance - -### Purpose - -Close the loop and prove the new public contract. - -### Work - -1. Update README quick start to CLI-first. -2. Mark MCP as disabled/legacy migration internals where references must temporarily remain. -3. Add/adjust focused CLI acceptance checks for: - - no-arg help; - - unknown command error; - - command help; - - canonical-to-operation mapping; - - `--json` stdout cleanliness; - - no default MCP startup; - - installed skill wording; - - no new MCP registration in a clean install plan/configuration path. -4. Run the normal build plus a narrow high-value E2E path only after implementation is assembled. - -### Vertical Slice 1 user story - -From a repository: - -```text -codebase-memory-cli index . -codebase-memory-cli status -codebase-memory-cli search ClaimValidator -codebase-memory-cli snippet ClaimValidator.validate -codebase-memory-cli trace ClaimValidator.validate --direction both -codebase-memory-cli coverage src/Claims/ClaimValidator.cs -``` - -An agent can learn the same flow from the installed skill, and useful hooks can augment searches/reads without asking the user to start MCP. - -## 6. Critical review before implementation - -The following review changes the earlier, more ambitious proposal. - -### 6.1 Risk: confusing “MCP disabled” with “MCP code deleted” - -The first proposal made “no migrated command calls `cbm_mcp_handle_tool()`” an exit criterion for the first vertical slice. In this source tree that turns the first slice into a broad internal rewrite because search, trace, snippet, coverage, hooks, schema/help, worker supervision, and daemon request state all share MCP-named structures. - -**Decision:** Vertical Slice 1 disables the MCP *product surface* and establishes the canonical CLI. Physical extraction of the private dispatcher is Vertical Slice 2. The temporary dependency is documented, fenced, and not presented as a finished architecture. - -### 6.2 Risk: deleting daemon/coordination too early - -The archive's initial CLI-only note proposes removing the daemon. Current source shows the daemon family also owns exact-build coordination, index-worker budgeting/coalescing, watcher lifecycle, and safe mutation behavior. - -**Decision:** Do not delete daemon/coordination in Slice 1. Remove its role as the public MCP product mechanism first. Later distinguish protocol-neutral runtime coordination from optional long-lived services. - -### 6.3 Risk: hooks become slower if they shell out recursively - -Rewriting `hook-augment` to spawn the CLI for every graph query would add process startup, identity hashing, coordination, and potentially recursion to a latency-sensitive fail-open path. - -**Decision:** Keep in-process private dispatch inside hooks for this slice. Change the hook's *contract and guidance* now; extract its execution dependency only after a protocol-neutral operation API exists. - -### 6.4 Risk: duplicate CLI schemas - -A hand-built getopt implementation for seven commands would immediately drift from the existing registry and tool schemas. - -**Decision:** Named commands remain thin aliases over the existing schema parser during Slice 1. The operation registry replaces MCP metadata in Slice 2/3. - -### 6.5 Risk: search positional sugar changes semantics - -`search_graph` accepts many filters and a regex-like `name_pattern`; blindly inserting raw user input into that field can change regex semantics or produce unexpected results. - -**Decision:** positional `search QUERY` must escape literal input into the existing pattern contract, while advanced callers may still provide explicit flags. If safe escaping cannot be implemented without changing semantics, require `--name-pattern` in the first checkpoint and add literal positional search in a subsequent checkpoint. - -### 6.6 Risk: installer cleanup destroys user-owned configuration - -Stopping new MCP installs is safe; deleting all old MCP config on update is not. Config files may contain user changes or foreign server entries. - -**Decision:** Slice 1 stops adding registrations. Existing ownership-aware removal functions stay for uninstall/migration and continue preserving modified/foreign entries. - -### 6.7 Risk: renaming the binary multiplies the migration - -Renaming `codebase-memory-mcp` affects installer targets, updater, hooks, skills, scripts, release metadata, process identity, and potentially external package managers. - -**Decision:** do not rename the executable in Slice 1. Functional CLI-first behavior lands first. Rename is a later release phase. - -### 6.8 Risk: claiming protocol neutrality too early - -A new `operations/` wrapper that simply calls `cbm_mcp_handle_tool()` would make dependency diagrams look cleaner without changing the dependency. - -**Decision:** do not add a fake operation layer in Slice 1. Keep the temporary compatibility call explicit so it is easy to find and remove. The real operation layer begins only when handlers/results stop depending on MCP types/envelopes. - -## 7. Implementation checkpoints - -Work is checkpointed cumulatively from the authoritative archive. Each overlay must be: - -- self-applying; -- deletion-aware; -- repository-context validated; -- path-safe (no absolute paths or `..` deletion entries); -- cumulative so the latest checkpoint can be applied directly to the authoritative archive. - -Expected checkpoints: - -1. **CP1 — CLI startup + named command skeleton** - - no default MCP startup; - - named command dispatch table; - - top-level help revised. -2. **CP2 — complete first-slice named command ergonomics** - - positional mappings where safe; - - machine/human output behavior retained; - - command-specific help/examples. -3. **CP3 — skills and hook guidance** - - generated skill/profile text rewritten; - - lifecycle notices rewritten; - - useful hook behavior retained. -4. **CP4 — install surface disables new MCP registration** - - default config path installs CLI-oriented integrations only; - - ownership-aware legacy removal preserved. -5. **CP5 — docs + focused acceptance fixes** - - README/docs aligned; - - build and high-value E2E acceptance completed; - - final first-slice overlay. - -Checkpoint numbering may compress or expand based on what the source reveals, but no implementation interval should exceed the requested checkpoint cadence without emitting an overlay first. - -### Checkpoint status - -- CP1 complete: CLI startup + named command skeleton. -- CP2 complete: canonical help + MCP-envelope-free canonical JSON output. -- CP3 complete: CLI-first skill, agent guidance, and lifecycle hook messaging. -- CP4 complete: new install paths are gated against MCP config/profile/adapter creation while ownership-aware legacy cleanup remains compiled. -- CP5 partially complete: primary docs/setup surfaces are CLI-first and executable acceptance exposed a canonical read-path hang. -- CP6 complete: local-read/product-rename boundary established. -- CP7 complete: canonical stdin deadlock resolved and canonical read loop verified. -- CP8 complete: product/distribution rename and Windows build contract migrated. -- CP9 complete: active release containers are CLI-only; MCPB production/publication removed. -- CP10 complete: Windows source-build path is native MSYS2 Clang and produces `codebase-memory-cli.exe`. -- CP11 complete: final product-surface audit and focused compile/link/install checks passed. -- CP12 complete: fresh cold-repository E2E and generated Claude/Gemini/Aider integration fixtures passed; Vertical Slice 1 is closed. - -## 8. Deferred immediately after Vertical Slice 1 - -The next vertical slice begins the architectural extraction: - -```text -CLI / hooks / runtime - | - v -protocol-neutral operation registry + context + result - | - v -engine -``` - -Its first targets should be `list_projects`, `index_status`, `check_index_coverage`, then `search_graph`, because those are heavily used by both the CLI and hooks and create a real seam quickly. - -Only after that seam exists should we: - -- move index supervision out of `src/mcp`; -- convert daemon `REQUEST_MCP` / `REQUEST_TOOL` into `REQUEST_OPERATION`; -- delete `daemon/frontend.*`; -- remove JSON-RPC/MCP schemas/prompts/tool profiles; -- delete `src/mcp`; -- retire legacy `cli `; -- finish distribution/package migration after the product binary has been renamed in Vertical Slice 1. - -## 9. Definition of done for Vertical Slice 1 - -The slice is complete when all are true: - -1. No-argument invocation prints CLI help and does not start MCP. -2. Unknown top-level commands fail as CLI errors and do not fall into MCP. -3. `index`, `status`, `search`, `trace`, `snippet`, `coverage`, and `projects` are canonical named commands. -4. `--json` remains script/agent usable and stdout-clean. -5. Legacy `cli ` still works only as a compatibility surface. -6. Generated skill text teaches the CLI and preserves Scout/Verify/Auditor evidence discipline. -7. Hook lifecycle/search/coverage guidance no longer tells users to start or use MCP. -8. Clean installation paths touched by this slice do not create new MCP registrations. -9. Existing ownership-aware uninstall/migration code remains capable of removing old Codebase Memory MCP entries without deleting foreign/modified entries. -10. Build succeeds and the focused end-to-end CLI story succeeds. -11. No graph/index schema rewrite is required and existing indexes remain readable. -12. The remaining internal `cbm_mcp_handle_tool()` dependency is explicitly documented as temporary private compatibility debt for the next slice, not hidden behind a fake abstraction. -13. The canonical executable/build artifact is named `codebase-memory-cli` (`codebase-memory-cli.exe` on Windows). -14. Windows 10/11 x86-64 remains a supported native executable target; Windows build/release configuration must produce the renamed `.exe`, not depend on WSL. - -## 10. Caveats added during implementation — 2026-09-01 - -Two requirements were promoted into Vertical Slice 1 acceptance criteria during implementation: - -1. **Product rename now:** the user-facing application and executable are `codebase-memory-cli`. Internal `cbm_*` C symbols, `CBM_*` environment variables, cache/database locations, and persisted index formats stay unchanged in this slice so the rename does not become a storage migration. -2. **Windows is a first-class build target:** the application must compile as a native Windows 10/11 executable. The existing MinGW/Clang compatibility code, Windows UTF-8 argv handling, process/lock implementation, and Windows CI architecture are preserved. Renamed Windows release targets must emit `codebase-memory-cli.exe`. - -Implementation consequence: the current read-path hang is being fixed without POSIX-only shortcuts. Canonical one-shot reads use the existing cross-platform coordination/runtime primitives; indexing retains the supervised worker path. The Windows requirement will be checked at both source/build-configuration level and, where the local environment lacks a Windows cross-compiler, through the repository's Windows CI build recipe rather than being treated as a packaging afterthought. - -### CP6 scope in progress - -- defer creation of the legacy in-memory MCP store for canonical one-shot CLI reads; -- infer the current repository project when canonical read commands omit `--project`, while preserving explicit project selectors; -- rename the runtime/help identity and primary build target to `codebase-memory-cli`; -- validate the local-read hang fix before extending the rename across installer/release/Windows packaging surfaces. - -## 11. CP7 acceptance finding — canonical stdin deadlock resolved - -Executable acceptance identified the apparent read-path "daemon hang" as an implicit-stdin deadlock in the shared CLI parser. In non-interactive environments, stdin can be an open pipe with no writer/EOF. Canonical commands whose legacy tool schema had optional properties (`projects`, `status`, and similar forms) therefore entered `cli_slurp_stream()` and waited indefinitely before dispatch. - -Resolution: - -- canonical named commands do **not** read stdin implicitly; -- canonical machine callers use flags or `--args-file`; -- legacy `cli ` retains the historical piped-JSON channel during migration; -- canonical one-shot reads use deferred store initialization and infer the current-repository project when no explicit project selector is supplied. - -Verified with the renamed acceptance executable against an isolated indexed C repository: - -```text -codebase-memory-cli projects --json PASS -codebase-memory-cli status --json PASS -codebase-memory-cli search helper --json PASS -codebase-memory-cli snippet helper --json PASS -codebase-memory-cli trace helper --direction both --json PASS -codebase-memory-cli coverage main.c --json PASS -``` - -The next checkpoint carries the product rename through install/setup/release artifacts and the native Windows build configuration. - -## 12. CP8 checkpoint — product/distribution rename and Windows build contract - -The first distribution pass now treats `codebase-memory-cli` as the product artifact while retaining the current repository URL and legacy MCP/storage identifiers where they are needed for compatibility or cleanup. - -Changed in this checkpoint: - -- the primary Makefile target remains `build/c/codebase-memory-cli`; -- Unix and Windows setup/install scripts install `codebase-memory-cli` / `codebase-memory-cli.exe` and request release archives named `codebase-memory-cli-...`; -- Nix installs and exposes `codebase-memory-cli` as the main program; -- Windows x86-64 (`CLANG64` on `windows-latest`) and Windows ARM64 (`CLANGARM64` on `windows-11-arm`) build jobs now stage `build/c/codebase-memory-cli.exe`; -- release-candidate selection/staging expects the renamed executable; -- Windows product-surface tests point at `build/c/codebase-memory-cli.exe`; -- the legacy monolithic skill cleanup path remains `codebase-memory-mcp` intentionally so upgrades can remove historical owned state. - -Compatibility boundaries deliberately *not* renamed here: - -- GitHub repository coordinates such as `DeusData/codebase-memory-mcp`; -- `CBM_*` environment variables and internal `cbm_*` symbols; -- existing cache/database locations such as `~/.cache/codebase-memory-mcp`; -- MCP-era configuration keys/ownership markers needed to recognize and remove legacy registrations. - -Validation at this checkpoint: - -- modified shell installer/build scripts pass `bash -n`; -- the Makefile retains native `_WIN32` detection and Windows system-link dependencies (`ws2_32`, `psapi`, `shell32`, `advapi32`, `bcrypt`) with a static Windows link path; -- the CI build matrix continues to use native MSYS2 Clang toolchains for Windows x86-64 and ARM64, now targeting the renamed executable. - -Remaining rename work before Vertical Slice 1 closes: release-container/archive naming and smoke/soak workflows still contain MCP-era artifact names, and MCPB release production must be explicitly disabled rather than silently carried forward into a CLI-only release. - -## 13. CP9 checkpoint — CLI-only release containers - -The active release path no longer produces or publishes MCP bundles. Canonical release containers are now eight CLI archives named `codebase-memory-cli-.tar.gz` or `.zip`, each containing exactly the renamed executable plus LICENSE, the platform installer, and third-party notices. - -Changes include: - -- `scripts/package-release.sh` emits only CLI archives and has no MCPB builder; -- the release workflow no longer includes `*.mcpb` in checksums, signing, upload, download, or verification; -- the MCP Registry publication job is removed from the active release workflow; -- release verification expects eight archives/eight selected executables/24 non-executable runtime members rather than the former archive+MCPB matrix; -- canonical smoke/soak/PR/test workflows now reference `build/c/codebase-memory-cli[.exe]` and the new archive names; -- the all-tests driver no longer invokes the obsolete MCPB packaging/registry contract tests. - -Focused packaging acceptance used the linked CLI acceptance executable to build a Linux amd64 release archive. The archive inventory was exactly: - -```text -codebase-memory-cli -LICENSE -install.sh -THIRD_PARTY_NOTICES.md -``` - -The executable SHA-256 inside the archive matched the selected input byte-for-byte, and no `.mcpb` file was produced. - -Legacy MCP cleanup identifiers and historical test/helper files may still exist in-tree during the migration; they are no longer part of the active install or release product surface. Deleting those remaining implementation artifacts belongs to the protocol-extraction/deletion phase rather than this first vertical slice. - -## 14. CP10 checkpoint — native Windows source-build path - -The Windows source installer previously violated the Windows caveat: `setup-windows.ps1 -FromSource` built a Linux executable inside WSL. That path has been removed. - -A new `scripts/build-windows.ps1` provides an explicit native build entry point: - -- Windows x64 selects MSYS2 `CLANG64`; -- Windows ARM64 selects MSYS2 `CLANGARM64`; -- the script requires the matching native Clang and zlib libraries plus GNU make; -- it invokes `Makefile.cbm` with `SANITIZE=` and the native Windows compiler; -- it requires and executes `build\\c\\codebase-memory-cli.exe --version` before reporting success. - -`setup-windows.ps1 -FromSource` now clones/updates the source on the Windows filesystem, invokes this native build script, and installs the resulting `.exe`. It no longer presents WSL as a Windows source-build implementation. - -The current Linux execution environment does not contain a Windows SDK/MinGW sysroot, and network package bootstrap was unavailable within the bounded checkpoint interval, so this checkpoint does not falsely claim an on-box Windows link. Native proof remains represented by the repository's `windows-latest` CLANG64 and `windows-11-arm` CLANGARM64 jobs; the next native Windows runner must execute the renamed build and Windows product guards. The important product correction is complete: the supported source-build path itself now produces a Windows PE executable rather than a WSL ELF binary. - -## 15. CP11 checkpoint — final product-surface audit - -A fresh product-surface audit found and corrected two remaining usability leaks: - -- the active Aider instructions now use canonical `codebase-memory-cli status/search/trace/snippet/coverage/index/projects` commands rather than the legacy generic `cli ` form; -- current Gemini hook/session payloads now teach the same CLI-first workflow. Separate arrays containing previously released MCP hook command strings remain unchanged solely so upgrades/uninstalls can identify and remove historical owned hooks safely. - -Additional acceptance in this checkpoint: - -- all modified C translation units (`main`, CLI/profile/hook, daemon bootstrap/application, MCP compatibility dispatcher) compile under the production `-Wall -Wextra -Werror` gate; -- the acceptance executable links successfully with the cached production vendored objects and reports `codebase-memory-cli dev`; -- no-argument invocation displays CLI help; -- explicit `mcp`, `--mcp-profile`, and `--tool-profile` top-level probes fail as unknown CLI commands rather than starting an MCP server; -- the canonical `projects -> status -> search -> snippet -> trace -> coverage` loop still passes against the indexed fixture without an explicit `--project` and without MCP content envelopes; -- `install --dry-run` in an isolated HOME produces no MCP-registration language and performs no filesystem mutation; -- `install --help` is now a real human-facing help surface and explicitly states that new installs do not create MCP registrations; -- all edited GitHub workflow YAML parses successfully; -- active build/smoke/soak/workflow references no longer expect `build/c/codebase-memory-mcp[.exe]` or MCP-era canonical platform archive names. - -At this point the remaining first-slice work is closeout: run a completely fresh cold-repository index loop with the latest linked executable, audit generated skill/hook output using detected-client fixtures rather than prose/source inspection alone, and reconcile the definition-of-done/remaining-debt sections. Native Windows execution remains delegated to the repository's native Windows runner because this Linux environment has no usable Windows sysroot; the source-build and CI paths now both target the renamed native `.exe`. - -## 16. CP12 closeout — Vertical Slice 1 complete - -The final closeout reran the first-slice story from a genuinely cold repository with a private isolated HOME/cache and the latest linked `codebase-memory-cli` executable. The complete loop passed without an explicit project selector: - -```text -codebase-memory-cli index . --json PASS -codebase-memory-cli projects --json PASS -codebase-memory-cli status --json PASS -codebase-memory-cli search helper --json PASS -codebase-memory-cli snippet helper --json PASS -codebase-memory-cli trace helper --direction both --json PASS -codebase-memory-cli coverage main.c --json PASS -``` - -The index was created from scratch in this run. `projects` resolved the new project, subsequent commands automatically bound the current repository, search returned the indexed `helper` function, snippet returned its exact source, trace returned the `main -> helper` caller relation, and coverage returned current metadata for `main.c`. Canonical JSON remained free of the MCP `content` envelope. - -Generated integration output was then exercised rather than inferred from source text. In an isolated HOME with detected Claude Code, Gemini CLI, and Aider fixtures, `install -y --force --skip-binary --clients=claude,gemini,aider` produced: - -- Claude CLI-first skill plus fail-open search/read/session/subagent hooks that invoke `codebase-memory-cli`; -- Gemini CLI-first `GEMINI.md` plus BeforeTool, AfterTool coverage, and SessionStart hooks using the renamed executable; -- Aider CLI-first `CONVENTIONS.md` plus loader configuration; -- no `mcpServers`, `tools/list`, `tools/call`, MCP profile, or tool-profile registration. - -The historical `codebase-memory-mcp:start/end` comment markers remain in some owned instruction blocks intentionally. They are non-executable ownership markers used to recognize/remove prior Codebase Memory-managed content safely during upgrades and uninstall; renaming them in this slice would weaken cleanup compatibility. - -### Definition-of-done reconciliation - -All Vertical Slice 1 criteria are satisfied at the source/product-contract level: - -1. no-argument startup is CLI help; -2. unknown/MCP-only top-level probes fail as CLI commands; -3. `index`, `status`, `search`, `trace`, `snippet`, `coverage`, and `projects` are canonical commands; -4. canonical machine output is stdout-clean JSON without MCP envelopes; -5. legacy generic dispatch remains private/compatibility debt rather than the advertised interface; -6. generated skills preserve Scout/Verify/Auditor evidence discipline while teaching CLI use; -7. generated hook guidance/invocation is CLI-first and fail-open; -8. clean installs create no MCP registrations; -9. ownership-aware legacy cleanup remains intact; -10. modified C units pass the production warning gate, the acceptance executable links, and the fresh E2E loop passes; -11. existing index/store compatibility is preserved; -12. `cbm_mcp_handle_tool()` remains explicitly documented temporary internal debt for Vertical Slice 2; -13. the canonical executable and release artifact are `codebase-memory-cli` / `codebase-memory-cli.exe`; -14. Windows 10/11 is represented by a native MSYS2 Clang build path and native Windows CI/release jobs rather than WSL. - -The only proof not executable in this Linux environment is the final native PE compile/run itself because no Windows SDK/MinGW sysroot is installed. That is not being represented as locally verified. The repository's Windows build path, workflow targets, product guards, installer, and release staging all now require `codebase-memory-cli.exe`; the first native Windows runner is the authoritative execution proof. - -### Remaining architectural debt — next slice - -Vertical Slice 1 intentionally disables MCP as a product surface before deleting its internal compatibility kernel. The next slice should now extract protocol-neutral operations in this order: - -1. `list_projects`; -2. `index_status`; -3. `check_index_coverage`; -4. `search_graph`; -5. `get_code_snippet`; -6. `trace_path`; -7. remaining operations, then indexing supervision. - -The target remains: - -```text -CLI / hooks / daemon - | - v -protocol-neutral operations - | - v -engine -``` - -Only after consumers use that seam should `src/mcp`, daemon MCP request kinds/frontends, JSON-RPC framing, MCP schemas/prompts/profiles, and legacy generic `cli ` dispatch be deleted. - - -## Runtime Assurance / Concurrency Safety Track - -Added during Vertical Slice 2 in response to the concurrency risks of a CLI-first process model. The authoritative detailed plan lives in `docs/RUNTIME_ASSURANCE_PLAN.md`. - -Architectural decision: the daemon is retained as the authoritative coordinator for substantive writes. Canonical local execution is restricted by the neutral operation registry to operations marked `read_only=true`; mutating operations must route through daemon/project-lock coordination. SQLite WAL/transactions remain the final integrity layer, and BUSY/LOCKED outcomes are contention, never corruption evidence. - -Planned product surfaces are `codebase-memory-cli doctor` (fast and deep integrity/coordination verification) and `codebase-memory-cli benchmark` plus a real-process concurrency eval runner. The release gate will include same-project concurrent index requests, reader-during-write, different-project parallel writes, worker/daemon crash injection, WAL-starvation observation, and explicit proof that forced BUSY/LOCKED conditions cannot trigger quarantine/rebuild. Windows 10/11 process/file-lock behavior is part of the required matrix. diff --git a/docs/CLI_SELF_HOSTING_UX_REPORT_20260912.md b/docs/CLI_SELF_HOSTING_UX_REPORT_20260912.md deleted file mode 100644 index 8da29993f3..0000000000 --- a/docs/CLI_SELF_HOSTING_UX_REPORT_20260912.md +++ /dev/null @@ -1,98 +0,0 @@ -# CLI self-hosting usability report — 2026-09-12 - -## Scope - -Exercised the locally built `build/c/codebase-memory-cli` against this checkout. -The trial used a disposable directory outside the repository for both cache and -runtime state, with `--persistence false`; it created no new repository index -state. - -```bash -trial_dir=$(mktemp -d) -mkdir -m 700 "$trial_dir/cache" "$trial_dir/run" -export CBM_CACHE_DIR="$trial_dir/cache" -export CBM_RUNTIME_DIR="$trial_dir/run" -build/c/codebase-memory-cli index . --mode moderate \ - --name codebase-memory-cli-ux --persistence false --json -``` - -## Result summary - -| Area | Result | Notes | -|---|---|---| -| `--help` and command help | works | Clear command list and detailed option descriptions. | -| `doctor --deep --json` | works | Healthy after secure directories were pre-created; useful structured diagnosis. | -| Index | works | Moderate index completed; project appeared in `projects --json`. | -| Search | works | BM25 search returned ranked symbols with source location. | -| Architecture | works | Overview reported 20,646 nodes, 130,806 edges, a ten-language mix, and package rollups. | -| Outline, schema, snippet | works | JSON output is machine-friendly; ambiguous short names provide useful suggestions. | -| Cypher query | works | Simple node-count query returned expected rows. | -| Changes | works, with caveat | Correctly reports uncommitted files, but that can mask the previous-commit comparison. | -| Semantic search | accepts input; relevance needs work | The documented JSON-array form worked but `secure`/`endpoint` ranked unrelated cgroup tests. | - -## First-run issue and recovery - -The initial index attempt failed immediately with: - -```text -codebase-memory-cli: secure CLI coordination could not be created (endpoint) -``` - -`doctor --deep --json` also showed an absent, insecure cache directory and an -unreachable daemon. The cause was the trial configuration: the runtime and -cache parent directories did not yet exist. Creating both beforehand with mode -`0700` resolved the condition; a subsequent deep doctor was `healthy` and the -index completed. - -This is safe behavior, but the setup friction is high: a first-time user can -reasonably expect the CLI to create an owner-only directory or print the exact -recovery command in the failure itself. The current short `(endpoint)` label -does not identify the missing secure parent. - -## Discovery observations - -The core discovery loop is practical once a project name is known: - -```bash -build/c/codebase-memory-cli search --project codebase-memory-cli-ux \ - --query 'secure endpoint' --format json --limit 5 -build/c/codebase-memory-cli architecture --project codebase-memory-cli-ux --aspects overview -build/c/codebase-memory-cli outline --project codebase-memory-cli-ux --file-path src/main.c -build/c/codebase-memory-cli snippet --project codebase-memory-cli-ux \ - --qualified-name codebase-memory-cli-ux.src.main.main --include-neighbors true -``` - -`search`, `architecture`, and `outline` are easy to discover from help and -give compact, actionable output. `snippet main` deliberately refuses to guess -and supplies qualified-name choices; that is a good safety/usability tradeoff. -The `--project` flag is marked required in help even though its introductory -text says inference may be possible; consistently showing the current project -or accepting a session default would make the normal path clearer. - -`query` is powerful but necessarily specialist-facing: it requires Cypher and -the separate `schema` lookup. This is appropriate, but it is not the easiest -entry point for ordinary source discovery. - -`changes --since HEAD~1` included untracked workspace artifacts as changed -files and consequently found no indexed seed symbols. This is accurate for a -working-tree view but unexpected for a user who reads `--since` as a pure Git -commit comparison. The command should make the working-tree inclusion explicit -in its result/help, or offer a committed-only switch. - -## Follow-up implemented - -The immediate setup and discovery clarity fixes are now in the working tree: - -1. A missing `CBM_RUNTIME_DIR` override is created with the existing secure, - no-follow owner-private path. Existing directories remain fail-closed and - are never re-owned or permission-modified. -2. Command help now consistently says that `--project` selects the indexed - project, matching its required flag. -3. `changes` help and JSON output explicitly say that the working tree is - included (`working_tree_included: true`). - -Semantic ranking remains a separate relevance-quality task; no ranking -heuristic was changed based on one exploratory query. - -No product changes were made by this exercise. The disposable cache/runtime -directory can be removed after the session. diff --git a/docs/CONSOLIDATED_SOURCE_RECONCILIATION_2026-09-01.md b/docs/CONSOLIDATED_SOURCE_RECONCILIATION_2026-09-01.md deleted file mode 100644 index 969b07b42f..0000000000 --- a/docs/CONSOLIDATED_SOURCE_RECONCILIATION_2026-09-01.md +++ /dev/null @@ -1,27 +0,0 @@ -# Consolidated Source Reconciliation — 2026-09-01 - -This note records the pre-edit reconciliation of the authoritative consolidated archive against the CLI-first engineering handoff. - -## Confirmed - -- The neutral operation registry contains the six expected reads: `projects`, `status`, `coverage`, `search`, `snippet`, and `trace`. -- Canonical CLI reads execute through `cbm_operation_execute()` locally rather than through MCP. -- Hook augmentation calls neutral operations directly. -- The daemon's legacy tool request path checks the operation registry before falling back to the MCP dispatcher. -- MCP's six migrated read entry points are compatibility adapters to neutral operations; the former authoritative handler bodies are absent. -- The product/build/install surfaces use `codebase-memory-cli`; Windows workflows explicitly validate `codebase-memory-cli.exe`. -- Native Windows x64 uses MSYS2/CLANG64; an experimental Windows ARM64 path is also present. -- `docs/RUNTIME_ASSURANCE_PLAN.md` already records the daemon-authoritative mutation invariant, BUSY/LOCKED-not-corruption rule, doctor/benchmark direction, stable event names, and real-process concurrency scenarios. - -## Discrepancies / remaining migration debt - -- The daemon wire vocabulary still exposed `REQUEST_MCP` and `REQUEST_TOOL`; neutral operations were reached only as a branch inside `REQUEST_TOOL` and their daemon response was re-wrapped as an MCP text result. -- `main_local_cli_daemon_execute()` is still a legacy-tool path for commands whose behavior has not yet been extracted. This is legitimate transition debt and must not become the neutral operation API. -- Daemon session/context and bootstrap naming still contains MCP concepts (`cbm_mcp_server_t`, MCP tool profiles, MCP client role). These are broader extraction tasks; removing them in the operation-wire checkpoint would mix protocol cleanup with behavior migration. -- Index worker execution still intentionally uses the historical MCP dispatcher until `index_repository` is extracted. - -## Checkpoint decision - -Introduce a distinct `REQUEST_OPERATION` wire request with canonical operation payloads and no MCP envelope. Keep `REQUEST_MCP` and a separately numbered transitional `REQUEST_TOOL` only for unextracted compatibility behavior. New/extracted daemon callers must use the operation request; legacy tool fallback must not be reachable from it. - -The runtime-assurance event vocabulary is also promoted into source as stable identifiers so subsequent coordinator/store instrumentation does not invent incompatible names ad hoc. diff --git a/docs/FULL_SUITE_FAILURES_2026-09-04.md b/docs/FULL_SUITE_FAILURES_2026-09-04.md deleted file mode 100644 index 1e26a17232..0000000000 --- a/docs/FULL_SUITE_FAILURES_2026-09-04.md +++ /dev/null @@ -1,75 +0,0 @@ -# Full Suite Failure Details - -Date: 2026-09-04 -Branch: `release-tooling` -Baseline: `4f0d7b9` - -## Status - -The full sanitized suite is not green. The production incremental build and -sanitized test-runner build completed successfully, but the direct full-run -execution ended with 12 assertion failures and an AddressSanitizer heap-buffer-overflow. - -The focused memory suite remains separate: 52/52 tests passed with -`ASAN_OPTIONS=detect_leaks=1`. - -## Canonical runner preflight failures - -`scripts/test.sh` did not reach the suite execution because two preflight -contracts failed: - -1. The build-directory safety contract failed. -2. The Windows VM worktree manifest contract reported stale expectations for - the maintained driver and the old `codebase-memory-mcp.exe`. - -The full result below therefore came from the direct sanitized runner, not a -successful canonical `scripts/test.sh` gate. - -## Assertion failures - -| Location | Test | Assertion | -|---|---|---| -| `tests/test_subprocess.c:551` | `subprocess_quiet_timeout_kills_ignoring_tree` | `ASSERT(ready)` | -| `tests/test_daemon_runtime.c:3813` | daemon runtime test | `ASSERT(second_usable_before)` | -| `tests/test_daemon_application.c:707` | `daemon_application_requires_immutable_explicit_context` | `ASSERT(operation_response)` | -| `tests/test_daemon_application.c:1887` | `initialize_coalesces_auto_index_for_full_sessions` | `ASSERT(restricted_started_nothing)` | -| `tests/test_daemon_application.c:2026` | `sensitive_root_blocks_auto_index` | `ASSERT(sensitive_blocked)` | -| `tests/test_daemon_application.c:2149` | `sensitive_root_blocks_watch` | `ASSERT(ordinary_watched)` | -| `tests/test_daemon_application.c:2228` | `auto_index_honors_tracked_file_limit` | `ASSERT(limit_prevented_admission)` | -| `tests/test_daemon_application.c:2383` | `auto_index_retries_transient_busy_admission` | `ASSERT(initially_deferred)` | -| `tests/test_daemon_application.c:2461` | `update_generation_notifies_initial_and_late_sessions_once` | `ASSERT(initial_notified)` | -| `tests/test_daemon_application.c:2506` | `update_generation_retries_worker_start_failure` | `ASSERT(failed_generation_started)` | -| `tests/test_daemon_application.c:2570` | `update_generation_retries_cancelled_check` | `ASSERT(first_started)` | -| `tests/test_daemon_application.c:2644` | `final_disconnect_cancels_and_joins_update_generation` | `ASSERT(generation_started)` | - -## Sanitizer failure - -After the assertion failures, AddressSanitizer reported a heap-buffer-overflow -while executing the daemon application tests: - -- Reported read: `strstr()` read 58 bytes. -- Test location: `tests/test_daemon_application.c:2744`. -- Allocated buffer: 57 bytes. -- Allocation site: `src/daemon/application.c:2545`. -- Relevant dispatch path: `application_operation_request()` through daemon - application request dispatch. - -This is an active correctness and memory-safety failure. The report does not -yet establish whether the length mismatch is in the producer, the response -buffer contract, or the test's string handling; reproduce it in the smallest -daemon-application invocation before changing ownership or bounds logic. - -## Follow-up - -- Reproduce the ASan overflow with only the daemon-application suite. -- Classify the ten daemon-application assertions as setup, timing, protocol, - or implementation failures; several concern auto-index/update-generation - admission and retry behavior. -- Re-run `subprocess_quiet_timeout_kills_ignoring_tree` independently to check - whether its readiness failure is flaky. -- Repair or update the two stale `scripts/test.sh` preflight contracts before - treating that script as the full-suite gate. -- Re-run the canonical full suite, focused foundation runner, and LeakSanitizer - memory suite after remediation. - -No assertion or sanitizer failure is marked resolved by this artifact. diff --git a/docs/GITHUB_CI_RECOVERY_PLAN_2026-09-08.md b/docs/GITHUB_CI_RECOVERY_PLAN_2026-09-08.md deleted file mode 100644 index b3395d1d8d..0000000000 --- a/docs/GITHUB_CI_RECOVERY_PLAN_2026-09-08.md +++ /dev/null @@ -1,132 +0,0 @@ -# GitHub CI Recovery Plan — 2026-09-08 - -Status: **BLOCKED — upstream Actions reruns require repository administrator permission** - -## Execution record — 2026-09-09 - -- Prepared durable Agent Run `ci-recovery-20260908` against local source - `bed05b9947bb10959cbf112b8051b80450145304`. -- Confirmed PR #2115 includes commit `92cb3b9`, which bounds the activation - fixture's readiness/reap waits. That commit is not present in this local - checkout, so this worktree cannot supply source-level acceptance for it. -- Confirmed the current `apt.llvm.org` Noble LLVM 22 index contains `clang-22`, - `libclang-rt-22-dev`, and `llvm-22`; the MSan package outage is no longer - reproducible from the configured source. -- A focused local `scripts/test.sh --suites cli` run on `bed05b99` remained - incomplete after 204 seconds and was stopped. It made no worktree changes. -- GitHub rejected reruns of failed workflow runs `34288397854` and - `34282381014`: `Must have admin rights to Repository`. -- Direct GitHub CLI verification confirms `ngallodev` has `pull` only (no - push, maintain, or admin) on `DeusData/codebase-memory-mcp`; both affected - PR branches are owned by `DeusData`. - -Required upstream action: an administrator must rerun the failed jobs (or push -a new commit to each PR) and inspect the fresh `MSan`, Windows guards, ARM -Unix shard, and `ci-ok` results. Until those runs pass on their current merge -SHAs, this plan is not complete. - -## Scope and evidence - -This plan resolves the failures seen in the required `PR` workflows, then -verifies fresh GitHub Actions results. It does not weaken or bypass a test. - -| Failure | Evidence | Classification | -| --- | --- | --- | -| Windows concurrent cold start | Runs [34288397854](https://github.com/DeusData/codebase-memory-mcp/actions/runs/34288397854) and [34282381014](https://github.com/DeusData/codebase-memory-mcp/actions/runs/34282381014) both fail `test-windows-guards`: a cold-storm client reports `secure CLI coordination could not be created (endpoint)`. | Shared product/coordination defect; the same failure crosses unrelated PRs. | -| ARM CLI suite | Run [34288397854](https://github.com/DeusData/codebase-memory-mcp/actions/runs/34288397854) exhausts the 900-second `cli` suite limit after `ASSERT(host_serving)` in `cli_install_into_host_namespace_still_drains_host_cohort`. | Product or test-contract regression specific to PR #2115's activation-guard change. | -| MSan image build | Run [34282381014](https://github.com/DeusData/codebase-memory-mcp/actions/runs/34282381014) cannot install `clang-22`, `libclang-rt-22-dev`, or `llvm-22` from its configured LLVM apt source. | CI image/toolchain provisioning defect, before product tests run. | - -`ci-ok` is an aggregate failure and requires no separate repair. - -## Order of work - -1. Record a fresh failure matrix before editing: workflow run, merge SHA, failed - job/step, runner image, and exact first error. Keep this evidence with the - repair PR. Do not use historical logs as pass evidence. -2. Repair MSan provisioning first because it is isolated from product behavior. -3. Repair the Windows cold-start race on a branch based on current `main`. -4. Rebase the activation-guard PR onto that baseline, then resolve its ARM CLI - hang without changing the suite timeout. -5. Rerun required checks on the resulting merge SHAs and inspect each job, - rather than treating a successful workflow dispatch as success. - -## 1. MSan provisioning - -1. In the exact failing Docker build context, capture `apt-get update` output - and `apt-cache policy` for all three LLVM 22 packages. Confirm the - repository suite, key, architecture, and package names actually published - by apt.llvm.org for the runner's Ubuntu release. -2. Replace the unavailable source with one reproducible LLVM 22 provisioning - route already compatible with the MSan image. Prefer the repository's - existing source-built runtime path if it supplies the required compiler and - runtimes; otherwise use the correct published LLVM repository. Pin the - selected compiler/runtime version together. -3. Run `scripts/ci/msan-lane.sh build`, then `scripts/ci/msan-lane.sh run`. - Retain the build output proving the compiler and MSan runtimes are present. - -Acceptance: the MSan image builds without retries masking a missing package, -and the MSan test job reaches and passes its intended suite. - -## 2. Windows concurrent cold start - -1. Reproduce the existing six-client scenario from - `tests/windows/test_daemon_stability.py` on the Windows runner or the - authoritative Windows host. Repeat it enough to distinguish deterministic - failure from a timing-only flake. -2. Instrument only the shared endpoint/coordination creation failure path: - capture the platform error code, operation, and safe runtime-path category. - Do not log endpoint secrets, user paths, or broaden the test's deadlines. -3. Trace endpoint construction, startup-lock acquisition, generation probing, - spawn handoff, and cleanup as one state transition. Fix the shared state - handoff that permits a racing client to observe an unusable endpoint; do not - add per-client retries that merely conceal a failed handoff. -4. Add or extend the smallest deterministic regression assertion at the shared - boundary if the current cold-storm test cannot distinguish the broken state. - -Acceptance: repeated cold storms succeed, all clients either share the valid -ephemeral daemon or receive the defined recoverable state, and the daemon -retires as the existing guard requires. Run the focused Windows guard followed -by the complete Windows test matrix. - -## 3. ARM activation-guard hang - -1. Run the `cli` suite alone with its normal 900-second ceiling, preserving its - captured output. On the stall, collect the host/target daemon status, cohort - claims, startup-lock state, and child-process tree before cleanup. -2. Compare the install target's `HOME`/runtime namespace with the host namespace - used by `cli_install_into_host_namespace_still_drains_host_cohort`. Establish - whether the test's expectation is still valid or the activation guard now - fails to drain a legitimate host cohort. -3. Repair the lifecycle ownership at the common activation/cohort boundary. A - sandbox install must not drain an unrelated host daemon, while an explicit - host-target install must complete its expected drain and restore service. -4. Add a bounded regression test for both namespaces. Do not solve the failure - by skipping the test, extending its timeout, or serializing unrelated suites. - -Acceptance: the focused `cli` suite completes under its current limit on ARM -and x86 Linux; the exact host and sandbox cases pass; the full Unix shard matrix -has no timed-out suite. - -## Integration and evidence gate - -1. Keep MSan, shared Windows coordination, and activation-guard changes in - reviewable commits. Rebase dependent PRs after the shared repair merges. -2. Before push, run the smallest relevant local checks: - - - `scripts/ci/msan-lane.sh all` for the image repair; - - the focused Windows daemon stability guard on Windows; - - `scripts/test.sh --suites cli` for the activation path. - -3. For each changed branch, inspect the new `PR` workflow's individual jobs: - MSan, Windows guards/matrix, Unix ARM shards, diagnostics, lint, security, - and final `ci-ok`. -4. Declare the work complete only when every required job is `success` on the - post-repair merge SHA. Attach the URLs, SHAs, command output, and any - remaining environmental limitation to the PR or a durable handoff. - -## Explicit non-solutions - -- Do not rerun until green without identifying the failing transition. -- Do not suppress Windows cold-storm coverage. -- Do not raise the ARM suite timeout or mark the CLI suite optional. -- Do not make `ci-ok` ignore a failed `test` job. diff --git a/docs/CLI_MIGRATION_STATUS.md b/docs/internal/CLI_MIGRATION_STATUS.md similarity index 100% rename from docs/CLI_MIGRATION_STATUS.md rename to docs/internal/CLI_MIGRATION_STATUS.md diff --git a/docs/internal/README.md b/docs/internal/README.md new file mode 100644 index 0000000000..0e9ee61f96 --- /dev/null +++ b/docs/internal/README.md @@ -0,0 +1 @@ +Working notes kept for history; not maintained as user documentation. diff --git a/docs/RUNTIME_ASSURANCE_PLAN.md b/docs/internal/RUNTIME_ASSURANCE_PLAN.md similarity index 100% rename from docs/RUNTIME_ASSURANCE_PLAN.md rename to docs/internal/RUNTIME_ASSURANCE_PLAN.md diff --git a/docs/UPSTREAM_308_CANDIDATE_AUDIT_20260912.md b/docs/internal/UPSTREAM_308_CANDIDATE_AUDIT_20260912.md similarity index 99% rename from docs/UPSTREAM_308_CANDIDATE_AUDIT_20260912.md rename to docs/internal/UPSTREAM_308_CANDIDATE_AUDIT_20260912.md index adb9e8c234..c7586ceba4 100644 --- a/docs/UPSTREAM_308_CANDIDATE_AUDIT_20260912.md +++ b/docs/internal/UPSTREAM_308_CANDIDATE_AUDIT_20260912.md @@ -1135,7 +1135,7 @@ package installation/runtime qualification is separate. Specifications are finalized in SpecGen `agent-workflow` mode (zero readiness blockers), committed on release-tooling at `51aa7a86`. Each defines five must requirements, acceptance/evaluation links, preservation boundaries and structured -worker evidence. See `docs/specs/upstream-next-three/{daemon-ownership,rescript-hang,cache-stores}/spec.json` +worker evidence. See `docs/internal/specs/upstream-next-three/{daemon-ownership,rescript-hang,cache-stores}/spec.json` and their derived `SPEC.md` projections. | Vertical | Durable Agent Run | Independent branch | Execution state | @@ -1268,7 +1268,7 @@ R4 worker verdicts below are **checkpoint claims pending parent whole-hunk revie not accepted dispositions. Source-only findings and machine crosswalks are retained in `CBM-UPSTREAM-CONSOLIDATE-20261002` evidence. The dated [synthesis report](UPSTREAM_RECONCILIATION_REPORT_20261002.md) explains this snapshot; -this ledger and `BACKLOG.md` retain task authority. +this ledger and the (removed) backlog retained task authority. ### Adapter-only source-reviewed batch — 2026-10-03 UTC diff --git a/docs/UPSTREAM_RECONCILIATION_REPORT_20261002.md b/docs/internal/UPSTREAM_RECONCILIATION_REPORT_20261002.md similarity index 99% rename from docs/UPSTREAM_RECONCILIATION_REPORT_20261002.md rename to docs/internal/UPSTREAM_RECONCILIATION_REPORT_20261002.md index 32deca52df..b458f0c651 100644 --- a/docs/UPSTREAM_RECONCILIATION_REPORT_20261002.md +++ b/docs/internal/UPSTREAM_RECONCILIATION_REPORT_20261002.md @@ -52,7 +52,7 @@ remainder or credit thirteen commits as thirteen newly implemented features. **The history inventory is complete; the semantic audit is partial.** This report collects the Sol source audit, Luna handoffs, corrections, QA delta and remaining -limits. It is a dated synthesis, subordinate to [BACKLOG.md](../BACKLOG.md) and +limits. It is a dated synthesis, subordinate to the project backlog (not retained) and [the canonical 308 ledger](UPSTREAM_308_CANDIDATE_AUDIT_20260912.md). It creates no second implementation queue and establishes no review, acceptance or publication. diff --git a/docs/specs/upstream-next-three/cache-stores/SPEC.md b/docs/internal/specs/upstream-next-three/cache-stores/SPEC.md similarity index 100% rename from docs/specs/upstream-next-three/cache-stores/SPEC.md rename to docs/internal/specs/upstream-next-three/cache-stores/SPEC.md diff --git a/docs/specs/upstream-next-three/cache-stores/spec.json b/docs/internal/specs/upstream-next-three/cache-stores/spec.json similarity index 100% rename from docs/specs/upstream-next-three/cache-stores/spec.json rename to docs/internal/specs/upstream-next-three/cache-stores/spec.json diff --git a/docs/specs/upstream-next-three/daemon-ownership/SPEC.md b/docs/internal/specs/upstream-next-three/daemon-ownership/SPEC.md similarity index 100% rename from docs/specs/upstream-next-three/daemon-ownership/SPEC.md rename to docs/internal/specs/upstream-next-three/daemon-ownership/SPEC.md diff --git a/docs/specs/upstream-next-three/daemon-ownership/spec.json b/docs/internal/specs/upstream-next-three/daemon-ownership/spec.json similarity index 100% rename from docs/specs/upstream-next-three/daemon-ownership/spec.json rename to docs/internal/specs/upstream-next-three/daemon-ownership/spec.json diff --git a/docs/specs/upstream-next-three/rescript-hang/SPEC.md b/docs/internal/specs/upstream-next-three/rescript-hang/SPEC.md similarity index 100% rename from docs/specs/upstream-next-three/rescript-hang/SPEC.md rename to docs/internal/specs/upstream-next-three/rescript-hang/SPEC.md diff --git a/docs/specs/upstream-next-three/rescript-hang/spec.json b/docs/internal/specs/upstream-next-three/rescript-hang/spec.json similarity index 100% rename from docs/specs/upstream-next-three/rescript-hang/spec.json rename to docs/internal/specs/upstream-next-three/rescript-hang/spec.json