docs(plan): codemap audit --base <ref> — worktree + reindex strategy (v1.x backlog)

[SutuSebastian]

Summary

Plan for codemap audit --base <ref> — the v1.x backlog item that closes the highest-frequency agent loop left open after PR #50: PR-review structural diff.

Today, comparing the working tree to `origin/main` is a 3-step `--baseline` dance (switch branches, reindex, save baselines, switch back). `--base ` collapses it to one verb that:

1. Resolves `` via `git rev-parse --verify` (clean error on non-git or unresolvable ref)
2. Materialises the ref via `git worktree add` to a sha-keyed cache dir under `.codemap/audit-cache/` (does NOT touch the user's working tree)
3. Runs `runCodemapIndex` against the worktree (full mode; cache miss only)
4. Runs the same canonical SQL the existing audit deltas already use, on both DBs
5. Diffs row-sets via the same `diffRows` helper PR feat: codemap audit v1 (B.5) — structural-drift command with per-delta baselines #33 already ships
6. Returns the same `{head, deltas: {key: {base, added, removed}}}` envelope, with `base.source: "ref"` (new value) + `base.ref` (new field)

Why

PR #50 just shipped `codemap impact` — the "blast radius" loop. The remaining high-frequency agent loop without a one-verb solution is "what changed structurally in this PR?" `--base ` reuses 90% of the audit infrastructure (only new piece is the worktree + reindex snapshot path) and lights up MCP + HTTP automatically via the existing `tool-handlers.ts` dispatcher.

See `docs/plans/audit-base.md` for the full design — sketched API, output envelope, 10 decisions (D1-D10), 5 tracers, perf considerations, alternatives rejected, and out-of-scope list.

Test plan

• CodeRabbit reviews the design choices (especially D1 — worktree vs in-place checkout, D2 — sha-keyed cache + LRU eviction, D4 — non-git hard error, D7 — per-delta override composition)
• Once approved + merged, follow-up PR implements Tracers 1-5

Summary by CodeRabbit

Release Notes

• Documentation
  • Added design documentation outlining the audit --base feature specification
  • Updated project roadmap with reference to new design plan

[changeset-bot]

⚠️ No Changeset found

Latest commit: 9c92b05

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Warning

Rate limit exceeded

@SutuSebastian has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 36 seconds before requesting another review.

To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c95fc21a-d005-465f-9e76-cf9fdf351bd8

📥 Commits

Reviewing files that changed from the base of the PR and between 61eec22 and 9c92b05.

📒 Files selected for processing (1)

• docs/plans/audit-base.md

📝 Walkthrough

Walkthrough

Added a comprehensive design plan (docs/plans/audit-base.md) for the codemap audit --base <ref> feature, specifying CLI interface, output shape, git resolution strategy, cache behavior, error handling, acceptance criteria, and alternatives. Updated roadmap to reference the new plan.

Changes

Documentation: audit --base Feature Plan

Layer / File(s)	Summary
Feature Design Plan docs/plans/audit-base.md	New design document defining the --base <ref> CLI flag, output envelope structure with base.source="ref" and base.ref metadata, worktree + reindex strategy, sha-keyed caching, ref resolution, error cases, mutual exclusivity with --baseline, and acceptance tracers.
Roadmap Update docs/roadmap.md	Backlog item for codemap audit --base <ref> (v1.x) rewritten to remove parenthetical deferral note and link directly to plans/audit-base.md.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• docs: codemap-audit (B.5) plan + adopt grill-me & improve-codebase-architecture skills #32: Adds and updates design documentation for the same codemap audit --base <ref> feature across plans and roadmap.

Poem

A rabbit sketches audits fine,
With base refs in a grand design,
From worktrees spawned and caches blessed,
The diff-catching plan is manifest. 🐰📋

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and accurately summarizes the main change: it introduces a design plan for the codemap audit --base <ref> feature with a worktree and reindex strategy as a v1.x backlog item.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/plan-audit-base

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 0/1 reviews remaining, refill in 36 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[SutuSebastian]

@coderabbitai full review

[coderabbitai]

✅ Actions performed

Full review triggered.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (2)

docs/plans/audit-base.md (2)

55-78: ⚡ Quick win

Clarify backwards-compat/type changes needed for AuditBase (source: "ref" + new base.ref).

The plan correctly states base.source becomes an enum extension with "ref" (Lines 77-78) and adds base.ref (Lines 63-66). However, to prevent downstream breakage, it would help to explicitly call out that the TypeScript AuditBase/AuditEnvelope types must be updated so source accepts "baseline" | "ref" and base.ref exists for "ref" audits (or is optional).

Without that, consumers that currently assume only source: "baseline" may fail compilation or mishandle runtime shapes.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/plans/audit-base.md` around lines 55 - 78, Update the TypeScript types
for AuditBase/AuditEnvelope so the per-delta discriminator base.source accepts
the union "baseline" | "ref" and ensure base.ref is present (or at least
optional) on the shape used when base.source === "ref"; convert AuditBase to a
discriminated union (or widen the interface) that includes a variant with
base.source: "ref" and base.ref: string (and keep the existing baseline variant)
so consumers that narrow on base.source handle the new shape without type
errors.

---

109-110: ⚡ Quick win

Document CODEMAP_AUDIT_CACHE_SIZE semantics (or remove the mention).

You mention CODEMAP_AUDIT_CACHE_SIZE (Line 109-110) as “defer to env var + sane defaults” but don’t specify:

• whether it’s a hard cap or soft limit,
• format (MiB? bytes?),
• default value,
• units, and how it interacts with the “5 entries OR 500 MiB” eviction (Line 84, 109-110).

Given the repo’s docs guidelines for config options in *.md, please either fully document it (with an example) or drop the env-var detail until v1.x+ when it’s actually implemented.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/plans/audit-base.md` around lines 109 - 110, Update the docs to either
fully specify CODEMAP_AUDIT_CACHE_SIZE or remove its mention: if keeping it, add
semantics for CODEMAP_AUDIT_CACHE_SIZE (environment variable), stating whether
it is a hard cap or soft target, the accepted format/units (e.g., integer bytes
or suffixes like MiB/GiB), the default value, how it interacts with the existing
“5 entries OR 500 MiB” eviction policy (which wins when limits conflict), and a
small example export line; if you prefer to defer, remove the reference to
CODEMAP_AUDIT_CACHE_SIZE entirely so the doc doesn’t promise an unimplemented
config option.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/plans/audit-base.md`:
- Around line 83-91: Clarify and reconcile D1/D2/D8 by specifying that the
worktree created via `git worktree add` is ephemeral and removed immediately
after producing a cached index: on cache miss create worktree at
`<projectRoot>/.codemap/audit-cache/<sha>/worktree-<tmp>` run
`runCodemapIndex({mode: "full"})` to build a temp `.codemap.db` stored as
`<projectRoot>/.codemap/audit-cache/<sha>/.codemap.db`, then `git worktree
remove --force <path>` in a `finally` while leaving the cached `.codemap.db` and
metadata (LRU timestamp/size) intact for future cache hits; explain that cache
hits use the cached `.codemap.db` (no worktree present) to skip reindexing, and
that eviction (LRU after 5 entries or 500 MiB) removes both the cached DB file
and any stale worktree dirs if present.
- Line 84: The sha-keyed cache can race when two processes resolve the same sha
and both create/populate <projectRoot>/.codemap/audit-cache/<sha>/; implement an
atomic per-sha strategy: acquire a per-sha lockfile (e.g., .lock inside the
<sha> directory or a global lockdir with atomic mkdir) before any populate,
write the temp DB/artifacts to a temp path (e.g., <sha>.tmp.<pid>), fsync/close
them, then atomically rename into the final <sha> directory so readers never see
partial state; readers should treat a missing final dir as a cache miss and, if
they encounter a lockfile, either wait with timeout/retry or single-flight by
checking the lock and then re-checking the final dir after lock release; apply
this for the code that resolves the cache key (the --base → resolved sha logic)
and the cache eviction routine (LRU/size checks) to avoid races during eviction.

---

Nitpick comments:
In `@docs/plans/audit-base.md`:
- Around line 55-78: Update the TypeScript types for AuditBase/AuditEnvelope so
the per-delta discriminator base.source accepts the union "baseline" | "ref" and
ensure base.ref is present (or at least optional) on the shape used when
base.source === "ref"; convert AuditBase to a discriminated union (or widen the
interface) that includes a variant with base.source: "ref" and base.ref: string
(and keep the existing baseline variant) so consumers that narrow on base.source
handle the new shape without type errors.
- Around line 109-110: Update the docs to either fully specify
CODEMAP_AUDIT_CACHE_SIZE or remove its mention: if keeping it, add semantics for
CODEMAP_AUDIT_CACHE_SIZE (environment variable), stating whether it is a hard
cap or soft target, the accepted format/units (e.g., integer bytes or suffixes
like MiB/GiB), the default value, how it interacts with the existing “5 entries
OR 500 MiB” eviction policy (which wins when limits conflict), and a small
example export line; if you prefer to defer, remove the reference to
CODEMAP_AUDIT_CACHE_SIZE entirely so the doc doesn’t promise an unimplemented
config option.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 044362b6-cb36-4975-9538-304f36120ea0

📥 Commits

Reviewing files that changed from the base of the PR and between 90092ae and 61eec22.

📒 Files selected for processing (2)

• docs/plans/audit-base.md
• docs/roadmap.md

[SutuSebastian]

Triaged the 4 findings (1 Major + 3 Quick wins) per `pr-comment-fact-check`. All 4 had merit — applied in 9c92b05.

Applied (4 of 4):

• ✅ Major — race on sha-keyed cache populate. Added D11 ('Atomic cache populate'): per-pid temp dir + POSIX `rename` gives free single-flight semantics, no lock files needed. Same pattern for LRU eviction. Concurrent CI matrix runs against the same sha now safe by construction.
• ✅ Major (lifecycle ambiguity). Rewrote D1/D2/D8 — the earlier text said both 'cache by sha' AND 'cleanup in finally' which was self-contradictory. Now: worktree IS the cache entry, kept until LRU evicts; cleanup runs only on reindex failure rollback OR LRU eviction.
• ✅ Nitpick — `AuditBase` TS type widening. Added explicit callout above the Decisions table that `AuditBase` becomes a discriminated union (`{source: 'baseline', name, ...} | {source: 'ref', ref, ...}`) shipped in Tracer 1.
• ✅ Nitpick — `CODEMAP_AUDIT_CACHE_SIZE` underspecified. Dropped the env var mention. v1 hardcodes the limits; defer config surface to v1.x+ if real consumers ask. Plan no longer promises an unimplemented knob.

Plan PR ready for re-review or merge.