docs(bss-ledger): add canonical DESIGN.md to fix CFS ref-target-not-in-scope

[diffora]

What

Adds gears/bss/ledger/docs/DESIGN.md as the canonical Constructor Studio DESIGN artifact for the Billing Ledger.

Why

The Billing Ledger kept its technical design as a design/ folder (foundation + per-slice docs) — it is the only gear that does this; every other gear has a single DESIGN.md at the gear docs root. Constructor Studio recognises a DESIGN artifact by that canonical file, so for the ledger system it found no DESIGN artifact in scope. As a result ADR-0001 (cpt-cf-bss-ledger-adr-book-ownership-predicate) had no DESIGN artifact to be referenced from, and cfs validate failed:

gears/bss/ledger/docs/ADR/0001-cpt-cf-bss-ledger-adr-book-ownership-predicate.md:27 [ref-target-not-in-scope]
  `cpt-cf-bss-ledger-adr-book-ownership-predicate` (defined in ADR) requires reference in `DESIGN` artifact
  but no `DESIGN` artifact exists in scope

This surfaced as a red Validate CFS Artifacts check. Note: main itself is green (unchanged artifacts are not hard-failed), but any PR whose diff brings the ledger into strict validation scope inherits the failure — e.g. it is currently one of the CFS errors on the credstore PR.

What the DESIGN.md contains

Modeled on the existing passing gears (e.g. quota-enforcement) so it validates cleanly:

• cpt-cf-bss-ledger-design-main design id + the required principle / constraint / component / seq id definitions under their template sections.
• Architecture overview, driver→response mapping (referencing existing PRD FR ids), architecture layering, and the Key ADRs section that references cpt-cf-bss-ledger-adr-book-ownership-predicate — this is what closes the error.
• Detailed, normative per-slice design continues to live in design/; this document is the canonical index/overview and delegates slice specifics there, so the design set stays the single source of truth.

No component is broken out into a DECOMPOSITION artifact (kept as a design-level factoring), matching the convention of other DESIGN-only gears.

Verification

• make cfs-validate on this branch: 183 artifacts, 0 errors (PASSED).
• Cross-checked against the credstore branch base (credstore + this DESIGN.md, clean tree): the ledger ref-target-not-in-scope error is eliminated and no new ledger error/warning is introduced.

Scope

Ledger only. The remaining two CFS ref-target-not-in-scope errors — gears/model-registry (DESIGN components need a DECOMPOSITION) and gears/system/oagw (cpt-cf-oagw-feature-tenant-hierarchy needs a FEATURE) — are owned by other gears and are intentionally left for their owners.

Summary by CodeRabbit

• Documentation
  • Added a new canonical Billing Ledger technical design document defining the double-entry, post-only/append-only journal approach, invariants, ingestion idempotency, canonical reversals, and key posting/close flows (invoices, payments/AR allocation, adjustments/refunds, recognition scheduling, and FX/reconciliation/export).
  • Rewrote the Billing Ledger design set overview README into a shorter directory-style index, linking to the slice design documents and pointing to the canonical design document for phase/PRD mapping.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 54457eae-6096-4443-8387-ecf61c30f20d

📥 Commits

Reviewing files that changed from the base of the PR and between f54ed0c and a81d1b1.

📒 Files selected for processing (2)

• gears/bss/ledger/docs/DESIGN.md
• gears/bss/ledger/docs/design/README.md

✅ Files skipped from review due to trivial changes (1)

• gears/bss/ledger/docs/design/README.md

---

📝 Walkthrough

Walkthrough

Adds a canonical design index for the BSS Billing Ledger and rewrites the design-set README to point to it and the slice documents. The changes update architecture, constraints, traceability, and directory-level documentation only.

Changes

Ledger Design Documentation

Layer / File(s)	Summary
Document intro and scope gears/bss/ledger/docs/DESIGN.md	Adds title and ownership metadata, table of contents, and the entry point that delegates to the slice design set as the source of truth.
Architecture overview gears/bss/ledger/docs/DESIGN.md	Introduces the double-entry ledger vision, the Repository Foundation and slice-handler split, ownership predicates, and the PRD/ADR-driven architecture drivers and phased design-set diagram.
Ledger-wide principles gears/bss/ledger/docs/DESIGN.md	Documents stable ledger constraints and conventions covering schema ownership, append-only posting, idempotent ingestion, lock ordering, seller and buyer separation, naming discipline, money representation, and the ingestion model.
Technical architecture and traceability gears/bss/ledger/docs/DESIGN.md	Defines the domain model, component IDs, API boundaries, dependency surfaces, main posting and close/export interaction paths, schema ownership, deployment topology, telemetry, future scope, and PRD/ADR traceability.
Design-set README overview gears/bss/ledger/docs/design/README.md	Rewrites the design-set README to describe the folder as slice documents that post through the shared Repository-Foundation and replaces the old index table with per-slice links and a pointer to the canonical design index.

Estimated code review effort: 1 (Trivial) | ~5 minutes

🚥 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 accurately summarizes the main change: adding a canonical DESIGN.md to resolve the CFS ref-target-not-in-scope issue.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/bss-ledger-cfs-design-artifact

---

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