Context
The parent-owned lifecycle model and SQLite journal are implemented and tested,
but contributors currently have to reconstruct phase rules, ownership, replay,
and the boundary between implemented and pending behavior from source and
several broad documents.
Outcome
Add one concise contributor guide explaining the lifecycle domain, legal phase
flow, parent-versus-worker ownership, persistence/replay model, artifact
references, cancellation/recovery semantics, and the implementation status that
exists on main when the documentation is merged.
Scope
- Document the legal
explore -> implement -> test -> review -> verify -> apply
sequence and terminal states.
- Explain parent-owned transitions and the typed result each phase worker may
return.
- Explain frozen profile, test-plan, source, budget, artifact, approval, and
state-digest identities.
- Describe the SQLite event journal and deterministic replay with links to
source and focused tests.
- Verify the status at merge time: distinguish the implemented domain/store from
whichever executor, read API, and timeline UI slices are still pending then.
- Link the guide from existing architecture or verified-change documentation
without copying their full content.
Non-goals
- Changing Rust or TypeScript behavior, inventing future APIs, documenting
non-Codex execution, or presenting offline tests as provider-backed evidence.
- A tutorial that performs provider calls or modifies a real worktree.
Acceptance criteria
Starting points
crates/needle-core/src/lifecycle.rs
crates/needle-core/src/lifecycle/model.rs
crates/needle-core/src/lifecycle/tests.rs
crates/needle-runtime/src/store/lifecycles.rs
crates/needle-runtime/src/store/lifecycles/tests.rs
PROJECT_STATUS.md
Validation
Run git diff --check and verify each relative link against the current
checkout. No Cargo, frontend, provider, or workspace mutation is required for
this documentation-only issue.
Context
The parent-owned lifecycle model and SQLite journal are implemented and tested,
but contributors currently have to reconstruct phase rules, ownership, replay,
and the boundary between implemented and pending behavior from source and
several broad documents.
Outcome
Add one concise contributor guide explaining the lifecycle domain, legal phase
flow, parent-versus-worker ownership, persistence/replay model, artifact
references, cancellation/recovery semantics, and the implementation status that
exists on
mainwhen the documentation is merged.Scope
explore -> implement -> test -> review -> verify -> applysequence and terminal states.
return.
state-digest identities.
source and focused tests.
whichever executor, read API, and timeline UI slices are still pending then.
without copying their full content.
Non-goals
non-Codex execution, or presenting offline tests as provider-backed evidence.
Acceptance criteria
source and tests.
mainat mergetime, including any concurrently completed issue.
numbers.
without contradictory status text.
git diff --checkpasses and manual review confirms every repository linkresolves.
Starting points
crates/needle-core/src/lifecycle.rscrates/needle-core/src/lifecycle/model.rscrates/needle-core/src/lifecycle/tests.rscrates/needle-runtime/src/store/lifecycles.rscrates/needle-runtime/src/store/lifecycles/tests.rsPROJECT_STATUS.mdValidation
Run
git diff --checkand verify each relative link against the currentcheckout. No Cargo, frontend, provider, or workspace mutation is required for
this documentation-only issue.