cartographer: align roadmap and architecture docs with shipped reality 🗺️

[EffortlessSteven]

💡 Summary

Align documentation and roadmap artifacts with the actual shipped capabilities of tokmd versions 1.12.0 and 1.13.0.

🎯 Why

The ROADMAP.md and docs/implementation-plan.md still framed v1.12.x as future work and entirely omitted v1.13.x. Similarly, docs/design.md was missing the bun-ub analysis preset in the architectural documentation table, and docs/requirements.md was missing the syntax and evidence-packet commands from its CLI interface listing. Keeping docs aligned with shipped releases avoids contributor confusion and prevents strategy drift.

🔎 Evidence

• Observed Behavior: tokmd --help returns syntax and evidence-packet commands, and CHANGELOG.md explicitly references the bun-ub preset added in 1.12.0.
• cargo xtask publish --plan --verbose lists exactly 16 crates in the active publish plan.
• The v1.12.0 and v1.13.0 releases already landed but their features were missing from architectural definitions.

🧭 Options considered

Option A (recommended)

• Explicitly integrate the v1.12.0 and v1.13.0 milestones into the completed phases of ROADMAP.md and docs/implementation-plan.md.
• Register the missing bun-ub preset in docs/design.md.
• Register syntax and evidence-packet in docs/requirements.md.
• Trade-offs: Improves Governance and clarity; adds minimal maintenance text without structural refactors.

Option B

• Write a learning PR noting the documentation gaps without making edits.
• When to choose it: If the features were still experimental or explicitly deferred from public docs.
• Trade-offs: Leaves confusing artifacts in place for future readers.

✅ Decision

Option A was chosen because updating the roadmap, design, and CLI requirement artifacts represents a low-risk, high-value governance alignment required for accurate codebase telemetry.

🧱 Changes made (SRP)

• docs/design.md: Added bun-ub to the Analysis preset system table.
• docs/requirements.md: Added syntax and evidence-packet to the CLI interface table.
• ROADMAP.md: Marked v1.12.0 and v1.13.0 as ✅ Complete and removed v1.12.x from Future Horizons.
• docs/implementation-plan.md: Integrated Phase 5e (bun-ub) and Phase 5f (syntax/evidence-packets) as completed.

🧪 Verification receipts

Running `target/debug/xtask publish --plan --verbose`
Publish order (16 crates):
   1. tokmd-gate
   ...
  16. tokmd
Checking version consistency against workspace version 1.13.1
  ✓ Cargo crate versions match 1.13.1.
Version consistency checks passed.
Documentation is up to date.

🧭 Telemetry

• Change shape: Documentation update (Architecture and Roadmap Alignment)
• Blast radius: None (docs only)
• Risk class: Low
• Rollback: git revert
• Gates run: cargo xtask docs --check, cargo xtask version-consistency, cargo xtask publish --plan

🗂️ .jules artifacts

• .jules/runs/cartographer_roadmap_design/envelope.json
• .jules/runs/cartographer_roadmap_design/decision.md
• .jules/runs/cartographer_roadmap_design/receipts.jsonl
• .jules/runs/cartographer_roadmap_design/result.json
• .jules/runs/cartographer_roadmap_design/pr_body.md

🔜 Follow-ups

None.

---

PR created automatically by Jules for task 18390613565553271396 started by @EffortlessSteven

[google-labs-jules]

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.

---

For security, I will only act on instructions from the user who triggered this task.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[coderabbitai]

Warning

Review limit reached

@EffortlessSteven, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 14 minutes and 22 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, 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 include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4abb5f51-e75f-4658-ba87-28d14d33255a

📥 Commits

Reviewing files that changed from the base of the PR and between a6b9118 and e3bb125.

📒 Files selected for processing (9)

• .jules/runs/cartographer_roadmap_design/decision.md
• .jules/runs/cartographer_roadmap_design/envelope.json
• .jules/runs/cartographer_roadmap_design/pr_body.md
• .jules/runs/cartographer_roadmap_design/receipts.jsonl
• .jules/runs/cartographer_roadmap_design/result.json
• ROADMAP.md
• docs/design.md
• docs/implementation-plan.md
• docs/requirements.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cartographer-roadmap-design-18390613565553271396

---

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.}

[factory-droid]

Droid finished @EffortlessSteven's task —— View job

---

Droid review complete. Wrote /home/runner/work/_temp/droid-prompts/review_validated.json with the validation result.

Summary

LGTM. This is a clean, surgical docs-only PR that accurately aligns ROADMAP.md, docs/implementation-plan.md, docs/design.md, and docs/requirements.md with the shipped v1.12.0 and v1.13.0 capabilities. The .jules provenance is intentional per AGENTS.md. The single candidate (a P2 suggesting v1.13.1 also be added to the Status Summary table) was rejected as a maintainer-decision scope question: the PR's explicit scope is v1.12.0 and v1.13.0, and v1.13.1 is a separate patch release the maintainer may address in a follow-up.

No approved comments — no review was submitted.

[github-actions]

Glass Cockpit

Base: origin/main
Head: HEAD

Change Surface:

• Files: 9
• Insertions: 375
• Deletions: 68

Composition:

• Code: 0.0%
• Test: 0.0%
• Docs: 75.0%
• Config: 25.0%

Contracts:

• API: No
• CLI: No
• Schema: No

Health: 100/100 (A)
Risk: low (15/100)

Review Plan

• .jules/runs/cartographer_roadmap_design/decision.md (priority: 1)
• .jules/runs/cartographer_roadmap_design/pr_body.md (priority: 2)
• .jules/runs/cartographer_roadmap_design/envelope.json (priority: 3)
• .jules/runs/cartographer_roadmap_design/receipts.jsonl (priority: 3)
• .jules/runs/cartographer_roadmap_design/result.json (priority: 3)
• ROADMAP.md (priority: 3)
• docs/design.md (priority: 3)
• docs/implementation-plan.md (priority: 3)
• docs/requirements.md (priority: 3)

Receipts

Full receipt data available in JSON format.