Skip to content

Source truth: - Vision and Product Principles - Canonical Accounting Model Is Source of Truth - Kernel Contract - ADR 0020: Initial Release Scope and Financial Workflow Taxonomy

Wiki Truth Maintenance

This checklist keeps bp3-wiki useful without turning derived documentation into a second source of truth.

docs/truth/ remains canonical. User, sysadmin, developer, and planning pages may explain or operationalize truth, but they must not redefine product, accounting, security, workflow, or implementation-contract behavior.

Truth checklist

Use this checklist when reviewing or changing docs/truth/:

  • State durable product, accounting, security, workflow, or contract behavior.
  • Keep normative rules short, direct, and visible outside examples.
  • Update related contracts when implementation-facing behavior changes.
  • Add or update an ADR for major irreversible product or architecture decisions.
  • Keep proposed ADRs clearly proposed until accepted.
  • Treat conflicts as findings to resolve; do not silently reconcile contradictions.

Derived documentation checklist

Use this checklist for docs/user/, docs/sysadmin/, docs/developer/, and docs/planning/:

  • Include Status, Audience, and Source truth at the top of each page.
  • Link to the canonical truth pages or accepted ADRs that govern the content.
  • Explain what the audience needs to do, operate, implement, or verify.
  • Do not introduce behavior that is absent from or contrary to the truth section.
  • Mark uncertain or future behavior as draft, proposed, planned, or deferred.
  • Keep workflow names aligned with ADR 0020.
  • Do not document deferred workflow nodes as active workflows.

Overload controls

Derived documentation is useful only while it stays traceable and compact.

  • Keep derived pages when they support current release use, administration, implementation, or a near-term planned slice.
  • Avoid empty pages for future taxonomy nodes.
  • Merge very small pages when they do not provide distinct audience value.
  • Prefer links to truth over copying large rule sections into derived pages.
  • Keep source-of-truth and derived docs in bp3-wiki for now. Consider a separate generated docs site only when publication or audience volume makes that necessary.

Review procedure

  1. Start with the vision, relevant accounting truth pages, contracts, and accepted ADRs.
  2. Review derived docs afterward and check each normative claim against its source truth.
  3. Compare active application surfaces in src/BooksPlus.App with launch workflow docs.
  4. Classify mismatches as implementation lag, documentation drift, or proposed future taxonomy.
  5. Produce findings as conflicts or cleanup items. Do not rewrite canonical meaning during a consistency review.

Text checks

Useful review searches:

rg -n "^Status:|^Audience:|^Source truth:" docs/user docs/sysadmin docs/developer docs/planning
rg -n "\b(must|should|active|deferred|planned)\b" docs/user docs/sysadmin docs/developer docs/planning
rg -n "\b(tax|payroll|banking|budgeting|funding|capex|compliance|migration|perpetual inventory)\b" docs/user docs/sysadmin docs/developer docs/planning

Search results are prompts for review, not automatic defects. A result becomes a defect when derived documentation states a rule without matching truth, presents deferred work as active, or conflicts with the canonical section.