Skip to content

Add a contributor guide for the durable Codex lifecycle contract #19

Description

@Punisheroot

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

  • Every phase, terminal outcome, and ownership statement matches current
    source and tests.
  • Implemented and pending lifecycle capabilities reflect main at merge
    time, including any concurrently completed issue.
  • Source links target current files or symbols and avoid fragile line
    numbers.
  • Existing architecture and verified-change documents link to the guide
    without contradictory status text.
  • git diff --check passes and manual review confirms every repository link
    resolves.

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area: agentsSubagent roles and orchestrationcodex-firstCodex-first development scopedocumentationImprovements or additions to documentationgood first issueGood for newcomers

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions