Skip to content

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

AI/Codex Workflow

This page defines how Codex should be used for BooksPlus development.

Codex can accelerate implementation, review, and documentation, but it must not be treated as an authority for accounting meaning. Product truth remains in bp3-wiki; code implements it; tests prove it; humans approve changes to meaning.

Task levels

Use the smallest task level that fits the work.

Level Codex role Expected human review
Ask Explain code, find files, summarize behavior, compare docs and implementation. No edits. Light
Plan Inspect truth, code, and tests; propose implementation steps. No edits. Moderate
Patch Make a bounded code, doc, or test change from accepted truth. Strong
Refactor Change structure across modules, repositories, persistence, or app workflow orchestration. Very strong

Most accounting, security, audit, workflow, posting, close, source-document, and permission work should move through Ask -> Plan -> Patch. Tiny fixes may go directly to Patch only when the governing truth is already accepted and the scope is narrow.

Truth gate

Codex may implement from:

  • canonical truth pages under docs/truth/;
  • accepted ADRs under docs/truth/decisions/accepted/;
  • implementation contracts under docs/truth/contracts/;
  • planning and developer pages that cite matching source truth.

Codex must not implement new accounting, security, audit, close, posting, source-document, permission, backup, support-access, or workflow-taxonomy meaning from chat discussion alone.

When a requested change needs new product meaning:

  1. Update the relevant canonical truth page, or create a proposed ADR.
  2. Keep proposed and draft material non-binding until accepted.
  3. Revise implementation prompts only after the governing meaning is captured.

Authority status stays simple:

  • Binding: canonical, accepted.
  • Non-binding: draft, proposed, derived, and planning pages unless they cite matching binding truth.
  • Add Implementation status only to planning or slice-tracking pages when it helps coordination. Do not add heavy lifecycle metadata to every truth page.

Standard prompt checklist

For implementation work, Codex prompts should ask the agent to:

  1. Read the relevant truth pages, contracts, accepted ADRs, developer guidance, and current implementation code.
  2. Identify ambiguity, missing truth, or truth/code conflicts before editing.
  3. Keep the change scoped to the requested behavior and existing project patterns.
  4. Add or update tests for every behavior change.
  5. Update derived documentation only when behavior changes.
  6. Summarize assumptions, risks, files changed, and tests run.

If truth and implementation disagree, Codex must flag the conflict instead of silently reconciling it in code.

Review gates

High-risk areas require explicit tests and human review:

  • accounting posting and reversal;
  • financial period close, reopen, waivers, and close-generated work;
  • source-document identity, evidence linkage, and supersession;
  • company context and company-scoped persistence;
  • authorization, protected actions, roles, permissions, and step-up;
  • security audit events;
  • backup, export, restore, company-data encryption, and support access.

Refactors require a prior plan when they touch:

  • domain boundaries;
  • repository contracts or persistence mapping;
  • PostgreSQL schema or migrations;
  • app workflow orchestration;
  • shared security, audit, posting, period, or source-document behavior.

Implementation baseline

Use the existing bp3 patterns as the default implementation style:

  • domain services own durable business behavior;
  • repositories have in-memory and PostgreSQL implementations where persistence matters;
  • app workflow classes coordinate UI-facing behavior without redefining domain rules;
  • protected-action authorization uses the central registry and policy checks;
  • consequential behavior emits audit events according to the security contracts;
  • PostgreSQL integration tests use the opt-in BP3_RUN_POSTGRES_TESTS=1 convention.

Verification

For docs-only process changes:

python3 -m mkdocs build --strict --site-dir /tmp/bp3-wiki-site

For code changes:

dotnet test BooksPlus.sln

For persistence changes:

./scripts/apply-database-migrations.sh
BP3_RUN_POSTGRES_TESTS=1 BP3_POSTGRES_TEST_CONNECTION="Host=localhost;Port=5432;Database=booksplus;Username=booksplus;Password=change-me" dotnet test BooksPlus.sln

Run focused tests first when a change is narrow, then broaden verification when the change touches shared contracts or workflow behavior.