Workflow Ledger & DB
Relevant source files
The following files were used as context for generating this wiki page:
The Workflow Ledger & DB provides durable continuity for repository-scoped production changes. It records accepted transitions, logical evidence, and workflow phases across process restarts using a SQLite event ledger. This system functions as agent-writable continuity rather than a Git boundary or security attestation.
Sources: skills/repo-production-workflow/SKILL.md:16-20, skills/repo-production-workflow/WORKFLOW-MAP.md:15-18
System Architecture
The architecture separates private storage mechanics from a public semantic interface. A repository-scoped SQLite ledger stores events, while a disposable active projection exposes state to external hooks and automation.
The diagram shows how policy mutations in workflow_state.py utilize _workflow_db.py to persist events in SQLite, which are then surfaced via a JSON projection.
Sources: skills/repo-production-workflow/WORKFLOW-MAP.md:32-35, skills/repo-production-workflow/INVARIANT-OWNERSHIP.md:19-23
Component Roles
| Component | Responsibility |
|---|---|
| SQLite Ledger | Records accepted transitions and logical evidence identities. |
_workflow_db.py | Owns the database schema and transaction mechanics. |
workflow_state.py | Implements shared transitions and policy mutations. |
| JSON Projection | Exposes schemaVersion: 1 semantic facts for automation. |
Sources: skills/repo-production-workflow/WORKFLOW-MAP.md:15-20, skills/repo-production-workflow/INVARIANT-OWNERSHIP.md:19-23
State Interface and Lifecycle
The workflow status command provides the canonical public Interface. It emits a JSON projection containing the active workflowId, current phase, and nextAction.
Workflow Phases
- Begin: Assigns a random
workflowIdand initializes state. - Context: Repo Context Forge records packet graph evidence.
- Preflight: Records the Behavior Map and Advisor findings.
- TDD: Mapped RED/GREEN runs.
- Verification: Quality gates and test execution.
- Review: Delegate and Final Advisor reviews.
- Complete: Terminal state validation.
The workflow follows a mandatory order where each stage must record logical evidence before moving to the next phase.
Sources: skills/repo-production-workflow/WORKFLOW-MAP.md:4-28, skills/repo-production-workflow/SKILL.md:16-25
Completion Requirements
The complete operation executes inside a transaction and validates the following:
- Context: Forge completed with producer graph evidence.
- Advisor: Preflight findings are dispositioned or marked unavailable.
- TDD: Every Behavior Map item is
GREEN,already-satisfied, orwithdrawn. - Verification: Final-tree quality gate passed with producer evidence.
- Manifest: The reviewable working tree matches the manifest from the lead review.
Sources: skills/repo-production-workflow/WORKFLOW-MAP.md:65-80
Ledger Persistence and Schema
The SQLite ledger uses logical evidence identities rather than raw data paths. Transitions record the session's repository association and logical references (SHAs, OIDs).
Data Retention and Cleanup
state_prune.py manages estate retention by interacting with the ledger's private inventory Interface. Completed workflows are terminal; every mutation except begin is rejected once a workflow is closed.
Sources: hooks/lib/_workflow_db.py, hooks/lib/state_store.py, skills/repo-production-workflow/INVARIANT-OWNERSHIP.md:19-21
Event Validation Logic
- Logical Evidence: Producers (TDD, review, preflight) record native validated documents.
- Tree Freshness: The ledger stores per-path manifests (file mode and content hash) to detect drift between review and completion.
- Invalidation: Production edits invalidate
verification,codeReview, andfinalReviewreadiness, resetting them topending.
Sources: skills/repo-production-workflow/WORKFLOW-MAP.md:40-50, skills/repo-production-workflow/WORKFLOW-MAP.md:86-90
Hook Integration
Hooks consume the semantic fields of the ledger projection to enforce sequencing without Git awareness.
Hooks advise rather than refuse; they update the ledger to reflect that downstream steps (like verification) are no longer ready after an edit.
Sources: skills/repo-production-workflow/WORKFLOW-MAP.md:104-108, skills/repo-production-workflow/WORKFLOW-MAP.md:120-125
Summary
The Workflow Ledger & DB maintains the integrity of the production process by strictly sequencing transitions and recording logical proof. By separating the private SQLite storage from the public JSON projection, it allows automation to verify work progress while ensuring persistence across agent sessions. The system relies on producer-validated evidence and working-tree manifests to prevent completions on drifted or unverified codebases.
Sources: skills/repo-production-workflow/WORKFLOW-MAP.md:15-18, skills/repo-production-workflow/INVARIANT-OWNERSHIP.md:19-23