Blacksite/docs/workflow/codex-workflow.md

Codex Workflow

Blacksite uses a repository-local workflow to keep implementation fast without weakening acceptance. The compact operating rules live in AGENTS.md; procedural details live in repository Skills and the policies indexed here.

Task lifecycle

1. Confirm the canonical repository path, branch, HEAD, dirty state, and active processes.
2. Resume .codex/session/STATE.md when valid instead of rediscovering the repository.
3. Read docs/authority.toml, the smallest relevant current docs, and exact linked tracker items.
4. Define one bounded slice with acceptance criteria, non-goals, and a verification tier.
5. Record material user steering as a scope delta, including which evidence remains valid.
6. Run selective verification, then update canonical docs at the slice boundary.
7. Treat native acceptance and release-candidate gates as separate states from engineering checks.

Ignored .codex/session/, .codex/logs/, .codex/cache/, and .codex/evidence/ data is working state, not documentation. It exists to make reconnects and compaction cheap and must not become a second source of product truth.

Policies

• Documentation authority
• Selective verification
• Build storage
• Gitea tracking

The workflow distinguishes Implementing, Engineering-complete, Acceptance-in-progress, Candidate-ready, and Accepted/closed. “Complete” is reserved for the acceptance state actually proven; a dirty worktree or source-only check is not closure evidence.