docs(topics): expand comprehensive topic map

[flyingrobots]

Linked Issue

Release gate context: #625. This PR expands docs/topics/ before v0.2.0 so the topic surface is comprehensive enough for the release-gate accuracy and coverage standard.

Branch / Issue-Title Check

• Exception: docs/comprehensive-topic-map is a release-gate documentation branch, not a single issue-title slug.

Summary

Expands docs/topics/ from a narrow minimum release map into a comprehensive task-oriented operator and contributor map.

Why

The existing topic directory had only a small set of pages and did not give an obvious task path for many current Wesley capabilities. The release rule says docs/topics/ must cover release-relevant contributor and operator workflows or link clearly to the authoritative page. This PR makes that rule operational by adding topic paths for the current compiler, extension, assurance, CI, and documentation-maintenance surfaces.

Changes

• Reorganized docs/topics/README.md into categories for compiler use, boundaries/extension, assurance/CI/release, and contributor process.
• Added topic pages for native CLI, schema/IR, operations, weslaw, emitters, directives, artifacts/cache, CI workflows, assurance evidence, extension modules, legacy Node retirement, docs maintenance, and invariants.
• Added all new topic pages to docs/truth-manifest.json so docs checks keep them in the maintained surface.
• Added an explicit rule that public capability, workflow, invariant, release procedure, or extension-boundary changes must update the topic map or justify existing coverage.

Method Evidence

• Design doc linked or not required: not required; this is documentation coverage work.
• Tests or validation evidence included.
• Playback/witness included or not required.
• Retro or closeout evidence included or not required: release gate Release gate: current minor release #625 remains open until v0.2.0 is tagged and published.

Tracker Hygiene

• Linked issue had work-in-progress while active, or no single linked implementation issue applies.
• Linked issue lane/status/legend labels are current: Release gate: current minor release #625 remains the v0.2.0 release gate.
• Follow-up work is captured as GitHub Issues, not hidden in chat or local-only backlog files.

Risk

Low implementation risk: docs-only. Release-gate risk is positive: this reduces the chance of shipping v0.2.0 with undocumented operator paths or stale topic coverage.

Backout

Revert this PR before tagging v0.2.0 and document the reduced topic coverage as an explicit release-gate exception in #625. Preferred path is to keep this correction and tag from the resulting main commit.

Testing

• cargo xtask docs-check
• git diff --check
• pnpm exec prettier --check docs/topics/*.md docs/topics/contributing/triage.md docs/truth-manifest.json
• BATS_LIB_PATH=test/vendor bats -t test/release-governance.bats
• node scripts/check-doc-cli-commands.mjs
• cargo run --bin wesley -- --help
• pre-push cargo xtask preflight

EvidenceMap / SourceMap (if applicable)

N/A.

Screenshots / Logs (optional)

N/A.

Merge Strategy

• Merge commit only; no rebase.
• Delete branch after merge.

Checklist

• One-topic PR with tight diff
• Rust-native preflight passes (cargo xtask preflight via pre-push)
• Legacy package preflight not required for docs-only change
• No widened permissions/secrets in workflows
• Docs updated if behavior changed

[coderabbitai]

Warning

Review limit reached

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

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

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

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

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 79dbcf49-10a9-497c-8485-ffcb1e0bcc8c

📥 Commits

Reviewing files that changed from the base of the PR and between 95506be and fdbcc67.

📒 Files selected for processing (16)

• docs/topics/README.md
• docs/topics/artifacts-and-cache.md
• docs/topics/assurance-evidence.md
• docs/topics/ci-workflows.md
• docs/topics/directives.md
• docs/topics/docs-maintenance.md
• docs/topics/emitters.md
• docs/topics/extension-modules.md
• docs/topics/invariants.md
• docs/topics/legacy-node.md
• docs/topics/native-cli.md
• docs/topics/operations.md
• docs/topics/schema-ir.md
• docs/topics/weslaw.md
• docs/truth-manifest.json
• test/release-governance.bats

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/comprehensive-topic-map

---

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

[flyingrobots]

@codex Code Lawyer self-audit found two documentation precision issues before merge.

#	Severity	Source	File	Lines	Issue	Planned handling
1	P5	Self	docs/topics/README.md	L21	Weslaw authority uses wildcard docs/design/0019-* instead of an exact authoritative path.	Add a regression guard against wildcard docs authority paths and replace the cell with the exact design directory.
2	P4	Self	docs/topics/directives.md	L12-L27	The directives topic tells readers to use database-shaped @wes_* directives as generic examples, which risks confusing current compatibility facts with Wesley domain ownership.	Add a regression guard for the stale phrasing and rewrite the section to frame existing core directives as compatibility/structure facts, not domain semantics.

[flyingrobots]

Code Lawyer Activity Summary

#	Source	Severity	File	Commit	Outcome
1	Self	P5	docs/topics/README.md	65f4e8f2	Added a Bats guard rejecting wildcard docs/...* authority paths and replaced docs/design/0019-* with docs/design/0019-weslaw-semantic-law-ir/.
2	Self	P4	docs/topics/directives.md	fdbcc672	Added a Bats guard for stale directive phrasing and rewrote the section to frame current core directive names as compatibility structure, not Wesley domain ownership.

Verification:

Gate	Result
Review threads	0 unresolved threads by GraphQL.
RED evidence	test/release-governance.bats failed before each targeted docs fix.
Focused regression	BATS_LIB_PATH=test/vendor bats -t test/release-governance.bats passed after each fix.
Docs checks	cargo xtask docs-check passed.
Markdown format	pnpm exec prettier --check docs/topics/*.md docs/topics/contributing/triage.md docs/truth-manifest.json passed.
CLI docs guard	node scripts/check-doc-cli-commands.mjs passed.
Full local gate	cargo xtask preflight passed.
Pre-push gate	Full Rust product preflight plus repo Bats smoke suite passed during git push.
Remote CI	All required checks passed; HOLMES generation/investigation/report matrix jobs were skipped after schema detection, which is expected for this docs/test-only change.

Merge gate note: CI is green and unresolved review threads are zero. The repository still reports REVIEW_REQUIRED, no human approvals are present, and CodeRabbit's PR comment remains a review-limit/usage-credit warning despite the status context being green.

[chatgpt-codex-connector]

Summary

• Replaced the wildcard weslaw authority path in the topic map with the exact authoritative design directory. docs/topics/README.mdL15-L23
• Rewrote the directives topic to frame current @wes_* directives as compatibility and structure-preservation facts, not generic Wesley-owned domain semantics. docs/topics/directives.mdL14-L32
• Added a cargo xtask docs-check regression guard that rejects wildcard authority paths in the topic map and catches the stale directive phrasing. xtask/src/main.rsL1888-L1948
• Committed the changes with 30d3819 docs(topics): tighten precision guards.
• Created the follow-up PR with title docs(topics): tighten precision guards.

Testing

• ✅ cargo xtask docs-check
• ✅ git diff --check
• ✅ pnpm exec prettier --check docs/topics/README.md docs/topics/directives.md
• ✅ cargo fmt --check
• ⚠️ pnpm run preflight — blocked by npm audit endpoint returning 403 Forbidden for pnpm audit --prod=false --json.
• ⚠️ BATS_LIB_PATH=test/vendor bats -t test/release-governance.bats — blocked because bats is not installed in this environment.

View task →