Maintain a project decision ledger with rationale and commit provenance

What feature would you like to see?

Codex should maintain an optional, durable project decision ledger that records important technical decisions, the alternatives considered, the reason for the chosen option, and the code or commits that implemented it.

Long-running projects accumulate decisions across many threads, agents, plans, reviews, and code changes. Codex may later remember the resulting implementation but lose the reason it was chosen. This causes repeated debates, accidental reversals, inconsistent architecture, and plans based on assumptions that are no longer visible.

The ledger should preserve decision provenance without storing private chain-of-thought. It should contain concise, user-reviewable conclusions and observable evidence only.

Example

Decision: Use PostgreSQL advisory locks for job deduplication
Status: active
Date: 2026-08-03
Scope: worker scheduling

Chosen because:
- works across multiple worker processes;
- does not require a new infrastructure dependency;
- transaction-scoped locks fit the current failure model.

Alternatives rejected:
- in-memory mutex: does not coordinate across processes;
- Redis lock: adds an operational dependency;
- unique database row only: awkward for long-running ownership and recovery.

Implemented by:
- src/jobs/lock.ts
- src/workers/runner.ts
- commit d09b34a

Validation:
- concurrent-worker integration test passed

Revisit when:
- jobs are moved out of PostgreSQL;
- cross-region scheduling is introduced.

Proposed behaviour

Codex should be able to create or propose a decision entry when a task produces a material and durable choice, such as:

• architecture or data-model selection;
• public API contract;
• security boundary;
• dependency or framework adoption;
• migration strategy;
• performance trade-off;
• compatibility policy;
• rejected implementation approach likely to be reconsidered later.

Each entry could contain:

• concise decision statement;
• status: proposed, accepted, superseded, deprecated, or rejected;
• scope and affected components;
• rationale stated as conclusions, not hidden reasoning traces;
• alternatives considered and why they were not selected;
• assumptions and constraints;
• implementation files, pull requests, commits, tests, or artifacts;
• links to related decisions;
• conditions that should trigger reconsideration;
• authoring agent/thread and user approval status.

User control and safeguards

• The ledger should be opt-in or enabled per project.
• Codex may propose entries, but significant decisions should be user-reviewable before becoming authoritative.
• Users must be able to edit, reject, merge, or supersede entries.
• The ledger must not silently treat an inferred preference as a ratified decision.
• Avoid recording trivial implementation details that would create noise.
• Do not expose hidden chain-of-thought; store concise rationale suitable for project documentation.
• Sensitive information should follow the repository or workspace's privacy and retention rules.
• If code diverges from the ledger, Codex should flag the discrepancy rather than blindly enforcing an obsolete decision.

Storage and interoperability

The exact storage format can be determined by the maintainers. Useful options include:

• a structured local database with export support;
• repository-backed Markdown or JSON files;
• generated Architecture Decision Records;
• project memory entries linked to Git provenance.

A repository-backed mode would make decisions reviewable in pull requests, while a local mode would avoid modifying repositories that do not want generated documentation. Export between the two would be useful.

Why this is useful

This would improve:

• continuity across threads and context compaction;
• multi-agent consistency;
• onboarding and project handoff;
• architecture review;
• prevention of repeated or contradictory decisions;
• understanding why unusual code exists;
• safe refactoring by revealing constraints that tests alone may not express;
• auditability for enterprise and regulated projects.

Suggested acceptance criteria

• Codex can propose a concise decision entry from a completed task.
• Entries distinguish proposed decisions from user-approved decisions.
• A decision can link to concrete files, commits, tests, issues, or PRs.
• Later decisions can supersede earlier entries without deleting history.
• Codex can retrieve relevant active decisions when planning related work.
• The system avoids injecting the full ledger into every prompt and retrieves only relevant entries.
• Entries survive thread compaction, resume, fork, and agent handoff.
• Users can inspect and correct the source and provenance of each entry.
• The feature works in projects with and without Git.

Potential implementation direction

Codex already has persistent thread metadata, project-scoped memory work, Git awareness, plans, and task history. A decision-ledger layer could store small structured records and retrieve them semantically or by affected path/symbol. Completion reports could propose ledger entries, while workspace-drift checks could identify when implementation no longer matches an active decision.