docs(accounting-rerun): align accounting and journal contracts - #87
Merged
Conversation
Why: - the implemented economics, reconciliation, and checkpoint slice still needed an explicit durable-doc handoff so later work would not keep treating downstream completion detail as planning-only context - the journal branch needed that downstream handoff to land first so the new journal planning would build on the bounded downstream owner docs instead of absorbing that retirement work indirectly What: - add explicit implemented-slice routing from the bounded economics, reconciliation, and checkpoint contract to current state, architecture, migration, and workspace placement docs - tighten the architecture, migration, and product-output docs so the current bounded downstream authorities and retained compatibility views read as durable implemented surfaces - keep the wording neutral and contract-focused so the completed downstream slice stays documented on durable docs instead of planning-only prose Checks: - make docs-check - make naming-check - make docs-audit
Why: - journal planning still pointed to an undefined backend choice, which left the first journal slice without a stable downstream boundary - the planning anchors needed a durable owner page for the journal contract so later implementation would not have to recover those decisions from planning prose What: - rewrite the journal and tax planning anchors around authoritative Journal ownership, ledger_cli as the first backend id, and the no-journal-ref tax boundary - add the bounded Journal contract page with the replaceable backend seam, backend artifact layout, validation lanes, and replay rules - sync the docs homepage reference section so the new durable contract is routed with the other target references Checks: - make docs-check - make naming-check - make docs-audit
Why: - the journal planning docs still left cross-surface ambiguity around backend ownership, artifact layout, and the tax boundary - the naming catalog still forced the stale check_id slot on the shared Journal contract surface, which blocked the required entry_check_id contract from validating cleanly What: - align the architecture, stage contract, ids, and persistence owner pages around Journal authority, the replaceable journal backend seam, and ledger_cli as the first backend id - normalize the shared Journal contract surface on entry_check_id and clarify that backend-specific rendering and validation stay outside the backend-neutral kernel - update the target-naming catalog so the owning docs validator accepts the revised Journal identifier contract Checks: - make docs-check - make naming-check - make docs-audit
Why: - the supporting migration and routing docs still left the journal backend cutover implicit even after the owner pages were updated - the durable journal contract needed to be visible from the main overview and workspace routes so later implementation would not fall back to the retired placeholder model What: - align migration and cutover guidance around Journal authority, ledger_cli as the first backend reader, replay from Journal alone, and the no-journal-ref tax boundary - add the Journal contract to the top-level docs routes and architecture overview with the replaceable backend seam called out directly - add a target-direction workspace note for planned journal artifact placement without presenting those paths as current runtime fact Checks: - make docs-check - make naming-check - make docs-audit
Why: - ordinary product behavior still read too close to replay or rebuild-oriented validation, which left rerun guarantees and the calculation fast path underspecified - the docs audit rule still required the obsolete replay-gates heading, which blocked the intended contract wording What: - define deterministic rerun, calculation fast-path, and safe full-rebuild override policy across planning, migration, engineering, status, and guide surfaces - reclassify rebuild validation as developer-only and refresh the evidence and economics contract wording plus generated docs home copy - update the docs-audit rule to require the new idempotent rerun heading on the bounded contract pages Checks: - make docs-check - make naming-check - make docs-audit - make quality
Why: - forward docs still split accounting semantics across retired journal-root package paths and older future-family naming, which left ownership, backend seams, and persistence boundaries inconsistent - the naming catalog and docs-audit rules needed to move with the owner docs so repo checks protect the corrected architecture instead of the superseded package roots What: - align planning, migration, concept, reference, and standards docs on `accounting` as the owning capability and `Journal` as the canonical accounting product - replace the retired visualization family with performance, update the target naming catalog and docs-audit expectations, and strengthen the catalog test coverage for the new canonical package set - define the accounting backend seam, bounded `ledger-cli` operations, durable versus on-demand artifacts, and backend-storage boundaries in the journal and persistence references Checks: - make docs-check - make naming-check - make docs-audit - make quality
Why: - the forward-contract docs-audit rules had grown into oversized catch-all modules, which violated the repo's refactor expectations and made the new journal-contract checks harder to maintain - the red-team loop also needed the editor-facing rule modules and the repo runners to agree on imports, line lengths, and forward-target classification updates What: - split the forward-contract docs-audit rules into foundations, evidence-claim, reconciliation-checkpoint, boundary, and journal modules and update the docs-audit catalog to load the new rule sets - keep the accounting boundary, rerun policy, and journal contract review checks aligned while removing the current-state workspace planning leak - keep the forward-target naming and docs-audit classifiers aligned with the accounting, performance, and journal contract surfaces Checks: - make docs-check - make naming-check - make docs-audit - make quality - make pr-review
c-wri
marked this pull request as ready for review
April 21, 2026 07:01
c-wri
enabled auto-merge
April 21, 2026 07:01
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
1 participant
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.
Why:
What:
Checks:
Issue linkage:
Included checkpoints:
docs(products): relocate downstream planning into durable docsdocs(journal): anchor journal planning to ledger-clidocs(journal): define replaceable backend contractdocs(journal): align migration and routing guidancedocs(rerun-policy): align deterministic rerun guidancedocs(accounting-contracts): align journal ownership modelrefactor(docs-audit): split forward contract rule domains