docs: retire planning/ — keep design docs in docs/design/, backlog in Issues - #71
Merged
Merged
Conversation
… Issues The planning/ folder had grown into a mix of the normative design spec and a large body of shipped-build history, research notes, and a stale working queue. Retire it: - Relocate the three canonical design docs to docs/design/: invariants.md (the "why" / invariant register), data-model.md (the "what"), index-engine.md (the "how"). invariants.md is now the single source of "why". - Delete the completed build specs, research notes, tasks.md, vision-and-scope.md, user-stories.md, and eval-strategy.md. Their pending/unstarted work is now tracked in GitHub Issues (#65-#70); shipped build history stays in git. - Rewire every code and doc citation that pointed at a moved or deleted doc: planning/... paths become docs/design/...; deleted-doc pointers redirect to the surviving design docs or the relevant issue, or are dropped where no accurate target exists. No dangling references remain (verified repo-wide). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FF24esquxCnSStbgPQFswH
📝 WalkthroughWalkthroughThe pull request migrates repository documentation references from removed ChangesDocumentation source migration
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
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 `@CLAUDE.md`:
- Line 225: Update the Markdown text around the issue reference so it does not
begin with the bare “#38” sequence; keep the reference inline with surrounding
text or rewrite it as “GitHub issue 38” while preserving the original meaning.
In `@docs/discovery.html`:
- Around line 245-247: The claims in docs/discovery.html contradict the
canonical invariants: at docs/discovery.html lines 245-247, update the
typed-body-link instructions around Lines 254-256 so body links remain untyped
and typed relations are placed in b2_relations; at docs/discovery.html lines
301-305, replace the closed 10-verb palette with the closed three-verb stance
core and the tolerated tails defined by invariant G3.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: efad4bfd-ffe7-4cd3-97d8-d3f6b5d80b55
📒 Files selected for processing (83)
.gitignoreCLAUDE.mdCargo.tomlREADME.mdcrates/b2-cli/src/main.rscrates/b2-cli/tests/cli.rscrates/b2-core/src/add.rscrates/b2-core/src/chunk.rscrates/b2-core/src/db.rscrates/b2-core/src/discover.rscrates/b2-core/src/embed.rscrates/b2-core/src/error.rscrates/b2-core/src/graph.rscrates/b2-core/src/ingest.rscrates/b2-core/src/lib.rscrates/b2-core/src/link.rscrates/b2-core/src/mv.rscrates/b2-core/src/note.rscrates/b2-core/src/relation.rscrates/b2-core/src/resource.rscrates/b2-core/src/search.rscrates/b2-core/src/vault.rscrates/b2-core/tests/cancel.rscrates/b2-core/tests/chunks.rscrates/b2-core/tests/common/mod.rscrates/b2-core/tests/discover.rscrates/b2-core/tests/embed.rscrates/b2-core/tests/frontmatter.rscrates/b2-core/tests/graph.rscrates/b2-core/tests/ingest_resolver.rscrates/b2-core/tests/links.rscrates/b2-core/tests/mv.rscrates/b2-core/tests/project_embed.rscrates/b2-core/tests/read.rscrates/b2-core/tests/resources.rscrates/b2-core/tests/search.rscrates/b2-core/tests/substrate.rscrates/b2-core/tests/vault.rscrates/b2-core/tests/write.rscrates/b2-desktop/CLAUDE.mdcrates/b2-desktop/Cargo.tomlcrates/b2-desktop/capabilities/default.jsoncrates/b2-desktop/src/commands.rscrates/b2-desktop/src/error.rscrates/b2-desktop/src/main.rscrates/b2-desktop/src/watch.rscrates/b2-embed/Cargo.tomlcrates/b2-embed/evals/queries.jsoncrates/b2-embed/evals/similar.jsoncrates/b2-embed/examples/eval.rscrates/b2-embed/src/lib.rsdocs/architecture.htmldocs/design/data-model.mddocs/design/index-engine.mddocs/design/invariants.mddocs/discovery.htmldocs/index.htmldocs/indexing.htmlfixtures/README.mdplanning/research/discovery-scan-strategy.mdplanning/research/file-type-support.mdplanning/research/vector-store-alternatives.mdplanning/specs/completed/async-indexing.mdplanning/specs/completed/desktop-editing.mdplanning/specs/completed/desktop-live-preview.mdplanning/specs/completed/desktop-ui-mvp.mdplanning/specs/completed/index-engine-build.mdplanning/specs/completed/projection-embedding-split.mdplanning/specs/completed/qmd-chunker.mdplanning/specs/eval-strategy.mdplanning/specs/resources-inventory-graph.mdplanning/tasks.mdplanning/user-stories.mdplanning/vision-and-scope.mdui/package.jsonui/src/api.tsui/src/livepreview.tsui/src/main.tsui/src/render.tsui/src/state.tsui/src/types.tsui/style.cssui/vite.config.ts
💤 Files with no reviewable changes (15)
- planning/specs/completed/async-indexing.md
- planning/tasks.md
- planning/research/file-type-support.md
- planning/specs/eval-strategy.md
- planning/user-stories.md
- planning/research/discovery-scan-strategy.md
- planning/specs/completed/projection-embedding-split.md
- planning/research/vector-store-alternatives.md
- planning/specs/completed/desktop-live-preview.md
- planning/vision-and-scope.md
- planning/specs/completed/desktop-editing.md
- planning/specs/resources-inventory-graph.md
- planning/specs/completed/qmd-chunker.md
- planning/specs/completed/index-engine-build.md
- planning/specs/completed/desktop-ui-mvp.md
| has an embedding space" signal the projected-but-unembedded fallbacks key on. Every distance is | ||
| computed **in-process** (`embed::l2_sq`, one sequential scan statement; rationale: | ||
| `research/discovery-scan-strategy.md`, #38). `meta` records `(embed_model_id, | ||
| #38). `meta` records `(embed_model_id, |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Avoid a bare #38 at the start of the Markdown line.
markdownlint reports MD018 because this line is parsed as an ATX heading without a space after #. Keep the issue reference inline or rewrite it as GitHub issue 38.
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 225-225: No space after hash on atx style heading
(MD018, no-missing-space-atx)
🤖 Prompt for 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.
In `@CLAUDE.md` at line 225, Update the Markdown text around the issue reference
so it does not begin with the bare “#38” sequence; keep the reference inline
with surrounding text or rewrite it as “GitHub issue 38” while preserving the
original meaning.
Source: Linters/SAST tools
Comment on lines
245
to
+247
| <section id="link"> | ||
| <h2><span class="num">3</span>From the list to a link — <span class="eq">b2 link</span></h2> | ||
| <div class="files">planning/user-stories.md — Story 3 · planning/data-model.md §4</div> | ||
| <div class="files">docs/design/invariants.md · docs/design/data-model.md §4</div> |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Keep docs/discovery.html consistent with the canonical contracts it now cites.
The migration updates the references but leaves two user-facing claims that contradict docs/design/invariants.md:
docs/discovery.html#L245-L247: correct the typed-body-link instructions at Lines 254-256; body links must remain untyped and typed relations belong inb2_relations.docs/discovery.html#L301-L305: replace the closed 10-verb palette with the closed three-verb stance core plus tolerated tails from invariant G3.
📍 Affects 1 file
docs/discovery.html#L245-L247(this comment)docs/discovery.html#L301-L305
🤖 Prompt for 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.
In `@docs/discovery.html` around lines 245 - 247, The claims in
docs/discovery.html contradict the canonical invariants: at docs/discovery.html
lines 245-247, update the typed-body-link instructions around Lines 254-256 so
body links remain untyped and typed relations are placed in b2_relations; at
docs/discovery.html lines 301-305, replace the closed 10-verb palette with the
closed three-verb stance core and the tolerated tails defined by invariant G3.
This was referenced Aug 3, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The planning/ folder had grown into a mix of the normative design spec and a
large body of shipped-build history, research notes, and a stale working queue.
Retire it:
"why" / invariant register), data-model.md (the "what"), index-engine.md (the
"how"). invariants.md is now the single source of "why".
user-stories.md, and eval-strategy.md. Their pending/unstarted work is now
tracked in GitHub Issues (Resources slice 1 (inventory & graph): complete desktop dogfood, promote spec #65-Post-v1 parking lot (sync · multiple vaults · large-scale perf · agent-maintained structure) #70); shipped build history stays in git.
planning/... paths become docs/design/...; deleted-doc pointers redirect to the
surviving design docs or the relevant issue, or are dropped where no accurate
target exists. No dangling references remain (verified repo-wide).
Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01FF24esquxCnSStbgPQFswH
Summary by CodeRabbit