docs(plan): codemap apply <recipe-id> — Q1–Q10 locked

[SutuSebastian]

Summary

Plan PR for codemap apply <recipe-id> — substrate-shaped fix engine that consumes the existing --format diff-json row contract from any recipe. Recipe SQL describes the transformation; codemap is the executor. No code yet — this PR ships only docs/plans/codemap-apply.md. Implementation lands in subsequent slice PRs (Slice 1–5 outlined in the plan).

Pre-locks (L.1–L.9)

Lifted from roadmap.md § Backlog. Moat-A (substrate, not verdict) and the "no fix engine" floor are the load-bearing anchors. Reuses the DiffJsonPayload row contract verbatim — no schema delta, no new SQL primitives.

Headline decisions (Q1–Q10)

Q	Lock	Why
Q1	Apply-by-default; --dry-run opts into preview	Verb-name semantics + ecosystem precedent (git apply / terraform apply)
Q2	Per-recipe-run, all-or-nothing	Cross-file invariants matter (rename touches def + imports)
Q3	Scan-and-collect conflicts in phase 1	Free under Q2's two-phase impl; better remediation UX
Q4	Positional verb (codemap apply <recipe-id>)	Matches show / snippet / impact shape; query --recipe is the exception
Q5	Standalone ApplyJsonPayload, single shape across modes	Decouples write semantics from read-only DiffJsonPayload
Q6	TTY prompt + --yes; non-TTY rejects without --yes	gh / cargo / npm uninstall precedent
Q7	Conflict-only path (no separate already-applied state for v1)	Simpler state machine; promotion path additive
Q8	Exact byte-match (multi-line via \n in before_pattern)	Moat-A clean; recipe-author controls normalization
Q9	Three-layer tests; no TOCTOU / FS-DI / clock-injection	Mirrors recipe-recency precedent; matches coverage-engine.ts
Q10	Boundary SQL kit + delete-on-ship lifecycle	Same write-path discipline as recipe_recency

Test plan

This PR ships docs only. Implementation slices:

• Slice 1: engine + dry-run path + unit tests
• Slice 2: write path + atomic temp-rename + failure-mode tests
• Slice 3: CLI + --params plumbing + TTY prompt + subprocess tests
• Slice 4: MCP/HTTP apply tool
• Slice 5: docs lockstep + plan-file deletion (per docs/README.md Rule 3)

References

• docs/roadmap.md § Backlog — codemap apply entry (deleted by Slice 5)
• application/output-formatters.ts DiffJsonPayload — input contract reused verbatim
• templates/recipes/rename-preview.{sql,md} — exemplar parametrised recipe
• recipe_recency PR (#dfbf4e1) — boundary discipline + plan-lifecycle precedent

Summary by CodeRabbit

• Documentation
  • Added comprehensive planning documentation for the codemap apply feature, outlining design decisions, system architecture, implementation strategy, test approach, and risk assessment.

[changeset-bot]

⚠️ No Changeset found

Latest commit: a6bba33

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 45 minutes and 34 seconds before requesting another review.

To continue reviewing without waiting, purchase usage credits in the billing tab.

⌛ 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: d8cac71e-56ab-4d00-be16-77df0ef5cd59

📥 Commits

Reviewing files that changed from the base of the PR and between ba42971 and a6bba33.

📒 Files selected for processing (1)

• docs/plans/codemap-apply.md

📝 Walkthrough

Walkthrough

A comprehensive planning document for the codemap apply feature has been added, outlining status, motivations, design decisions, architecture, implementation slices, test strategy, and risk indicators to guide development and coordination.

Changes

Codemap Apply Plan

Layer / File(s)	Summary
Planning Documentation docs/plans/codemap-apply.md	New plan document establishing the codemap apply feature scope, architecture (engine, CLI, MCP/HTTP transport), pre-locked and open design decisions, implementation slices, test approach, risks, cross-references, and lifecycle management.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 A map of code awaits its fate,
With plans so clear, both grand and great,
From engine's core to CLI's call,
The codemap apply will apply to all!
Design decisions locked in place,
Let features flow at brisk pace. 🗺️

🚥 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 'docs(plan): codemap apply — Q1–Q10 locked' directly and clearly summarizes the main change: addition of a planning document for the codemap apply feature with Q1–Q10 design decisions locked in.
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 plan/codemap-apply

---

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

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/plans/codemap-apply.md`:
- Around line 202-209: The fenced code block showing the prompt starting with
"apply rename-preview: 3 files, 5 rows" needs a language tag to satisfy markdown
linting; update the opening fence from ``` to ```text (or another appropriate
language) in the block containing that exact prompt so the docs render and lint
correctly while preserving the block contents.
- Line 320: The doc currently reintroduces a conflicting "--apply" flag for the
MCP/HTTP apply tool; update the documentation and the description of
application/tool-handlers.ts to match the v1 flag contract that the tool applies
by default and only supports "--dry-run" for preview (i.e., remove or mark
"--apply" as invalid), ensure the MCP/HTTP apply tool's args envelope
description (same as query_recipe: recipe id + params + format) explicitly
states apply-by-default with only "--dry-run" supported, and update the v1 flag
table and any references to query_recipe/apply tool to use consistent
terminology.

🪄 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: d53414c0-91d6-4249-8a7a-de627980030e

📥 Commits

Reviewing files that changed from the base of the PR and between dfbf4e1 and ba42971.

📒 Files selected for processing (1)

• docs/plans/codemap-apply.md