Skip to content

Add the parent-owned lifecycle execution kernel with injected phase adapters #21

Description

@Punisheroot

Context

Needle has a durable lifecycle domain, digest-CAS transitions, deterministic
event replay, frozen profile/test-plan anchors, and typed repair/apply
operations. It has no parent execution loop. Concrete Codex workers, verified
changes, and provider enablement should not be coupled to the kernel contract.

Outcome

Add a runtime-owned lifecycle execution kernel that loads and replays one
lifecycle, selects its current phase, invokes exactly one injected phase
adapter, and commits the resulting typed transition through the existing store.
The kernel is proven with deterministic fake adapters and stops at the explicit
apply-approval boundary.

Scope

  • Define bounded phase-adapter request/result contracts for explore, implement,
    test, review, and verify using existing lifecycle identities and transition
    types.
  • Load and replay the current projection before work; reject corruption, stale
    state digests, and a phase/profile mismatch.
  • Invoke at most one depth-one adapter for the active phase and let only the
    parent kernel write lifecycle transitions.
  • Track aggregate budget/usage, cancellation, adapter failure, cleanup result,
    and bounded terminal reasons.
  • Handle the single transactional repair reservation through the existing
    change/lifecycle store operation, then resume from the legal phase.
  • On successful verification, stop in the existing apply
    awaiting_approval state. Do not approve or mutate the active worktree.
  • Resume deterministically after restart without repeating a completed
    transition or adapter side effect.
  • Add fake-adapter tests for success through awaiting approval, rejection and
    repair, phase mismatch, stale CAS, cancellation, budget exhaustion, adapter
    failure, cleanup failure, corruption, and restart replay.

Non-goals

  • Concrete RuntimeEngine, Codex patcher, test, reviewer, verifier, or apply
    adapters; those are a dependent integration issue.
  • HTTP/UI, native provider execution, credentials, active-worktree mutation,
    nested workers, fan-out, commit, push, PR, merge, or publication.
  • Changing lifecycle, role-profile, TestPlan, or verified-change semantics.

Acceptance criteria

  • The kernel selects work only from the current validated lifecycle phase
    and frozen LifecycleSpec.
  • Adapters receive no store transition capability; only the parent commits
    with the expected state digest.
  • Exactly one logical depth-one adapter is represented by each completion.
  • Budget exhaustion, cancellation, stale CAS, invalid output, and cleanup
    failure produce bounded fail-closed outcomes.
  • Repair is reserved at most once through the existing transactional change
    operation.
  • Restart never repeats a committed phase or advances an uncommitted result.
  • A successful fake lifecycle stops at apply awaiting explicit approval.
  • Tests are deterministic and provider-free.

Starting points

  • crates/needle-core/src/lifecycle.rs
  • crates/needle-core/src/lifecycle/model.rs
  • crates/needle-runtime/src/store/lifecycles.rs
  • crates/needle-runtime/src/store/changes.rs
  • crates/needle-runtime/src/changes.rs

Validation

Run focused lifecycle domain, lifecycle-store, repair reservation, executor
kernel, cancellation, and restart tests in needle-runtime. No
needle-platform-codex or provider process is required.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area: agentsSubagent roles and orchestrationarea: runtimeCore runtime and execution lifecyclecodex-firstCodex-first development scopeenhancementNew feature or requesthelp wantedExtra attention is needed

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions