WO-018 — Autonomous Run Lifecycle & Context Lock Foundation

Classification: NECESSARY — HIVE V0.1
Status: READY FOR EXTERNAL EXECUTOR / IMPLEMENTATION NOT YET EXECUTED
Authorized base: 5e699f1315638a4e767a94bcf6536cd52988ee3b
Review Evidence compatibility: PASS — ordinary WO-018 uses the supported generic Work Order path; no checkpoint-promotion registration is required.

OBJECTIVE

Implement the smallest trustworthy foundation of HIVE autonomous execution by creating a durable, project-scoped run identity/lifecycle that binds an already-ingested task to exact Git state and already-existing HIVE context evidence before any external executor dispatch.

The increment must connect existing foundations rather than duplicate them:

Task Intake → Project/Git identity → Context Manager → durable Run / Context Lock → future executor dispatch → existing Local Verified Runner.

WHY THIS IS NEXT

The canonical checkpoint now requires the smallest necessary autonomous execution pipeline increment.

Existing capabilities already provide:

• durable project/task identity;
• Git-aware project inspection;
• deterministic Context Manager;
• progressive disclosure/token budget/fingerprints/delta;
• memory/provenance;
• Local Verified Runner staged mutation/tool evidence;
• read-only MCP core.

The missing architectural seam is durable canonical structured state for runs, which the approved architecture assigns to PostgreSQL. Dispatching an executor before this seam exists would weaken restart safety, provenance, project isolation and auditability.

SCOPE

Implement a bounded Run Orchestration Foundation that:

1. creates a durable run bound to exactly one project_id and one task_id;
2. records exact repository/Git identity required to detect stale execution;
3. builds/reuses the existing Context Manager rather than implementing a second retrieval/context path;
4. records deterministic context identity/fingerprint and the minimum provenance necessary to audit what an eventual executor was given;
5. has a closed, explicit run state machine with fail-closed transitions;
6. supports inspection of run status and immutable preparation evidence after process/API restart;
7. keeps executor/model output staged and non-canonical;
8. preserves project isolation and rejects cross-project task/run access;
9. survives Redis loss because PostgreSQL is canonical;
10. exposes a minimal provider-independent application/API seam suitable for the later executor adapter;
11. emits or stores only the minimum run event/evidence needed by this foundation, without implementing the full telemetry program;
12. integrates with the existing Local Verified Runner by contract/identity only where needed, without duplicating its mutation/tool-policy logic.

OUT OF SCOPE

• actual LLM/executor provider dispatch;
• Codex/Cursor automation;
• autonomous code mutation beyond the existing Local Verified Runner;
• automatic Git commit/PR/merge;
• canonical memory/checkpoint promotion;
• full event bus / near-real-time telemetry;
• full Control Center run UI;
• billing/cost accounting;
• broad MCP write surface;
• speculative planner/router framework;
• queue/distributed workers;
• new cache architecture;
• unrelated refactors.

FILES / SOURCES TO READ FIRST

Canonical order:

1. docs/project-brain/13-CHECKPOINT.md
2. docs/project-brain/16-DECISIONS-LEDGER.md
3. docs/project-brain/03-SCOPE.md
4. docs/project-brain/15-DEFINITION-OF-DONE.md
5. docs/project-brain/04-ARCHITECTURE.md
6. docs/project-brain/02-REQUIREMENTS.md
7. docs/project-brain/08-AUTONOMOUS-EXECUTION.md
8. docs/project-brain/10-SECURITY-GOVERNANCE.md
9. docs/project-brain/11-TEST-PLAN.md
10. existing implementation, especially backend/app/task_intake.py, backend/app/context_manager.py, backend/app/runner.py, project registry/Git inspection and migrations.

Inspect the repository before deciding exact implementation files.

ARCHITECTURE RULES

• PostgreSQL is canonical durable structured truth for runs.
• Redis may be used only for reconstructible HOT state.
• Git remains canonical source/code-history identity.
• Context summaries/fingerprints are derived and must not replace source.
• deterministic logic before LLM calls;
• provider-independent internal contract;
• project scope on every run/context/evidence access;
• staged executor claims never become canonical automatically;
• reuse existing Context Manager and Local Verified Runner contracts;
• no duplicate persistence engine.

REQUIRED RUN INVARIANTS

The implementation must prove, at minimum:

• task belongs to the same project as the run;
• project is in an executable/usable state required by policy;
• prepared run records exact Git identity;
• later stale HEAD/source mutation is detectable and fails closed where the prepared identity is required;
• context identity can be deterministically rebuilt/verified from canonical inputs;
• invalid state transitions fail closed;
• terminal states cannot silently return to executable states;
• restart and Redis loss do not erase canonical run state;
• cross-project access is rejected;
• secrets/raw credentials are not persisted in run evidence;
• no automatic canonical promotion occurs.

Allow the executor to choose the smallest sensible state vocabulary compatible with these invariants. Do not over-engineer a workflow engine.

MIGRATION

A new migration is allowed only if needed for the canonical run state. It must extend the current migration head 0006_memory_lifecycle_provenance cleanly and preserve restart/upgrade integrity.

API / CONTRACT

Provide the smallest useful application/API contract for:

• prepare/create a run from an existing project + task;
• read one run;
• list bounded recent runs for a project, only if this is required to make the foundation operable/testable.

Do not expose arbitrary executor dispatch in this increment.

TESTS

At minimum:

• unit tests for run-state transitions and deterministic identity;
• PostgreSQL integration for durable run lifecycle;
• same-project task/run constraint;
• cross-project rejection;
• stale Git HEAD/source fail-closed case;
• missing/invalid task/project cases;
• restart persistence;
• Redis-loss/rebuild behavior when Redis is touched;
• Context Manager reuse/provenance;
• no executor/provider/LLM call in this foundation;
• no automatic canonical promotion;
• migration upgrade test;
• existing full backend/dashboard/CI regression gates.

Add real-Git integration coverage where Git identity is material.

UADS EXECUTION REQUIREMENT

When this WO is executed externally, use the globally installed UADS runtime and return bootstrap/routing/verification evidence. UADS does not override HIVE scope, architecture, tests, canonical governance or Sol review.

ACCEPTANCE CRITERIA

WO-018 is acceptable only when objective evidence proves:

1. one durable run can be prepared from an existing project/task;
2. its exact project/task/Git/context identity is inspectable and stable;
3. run truth survives process/container restart;
4. Redis loss cannot destroy canonical run truth;
5. cross-project and stale-Git cases fail closed;
6. no external executor/provider is required or silently called;
7. no executor claim is promoted canonically;
8. existing Local Verified Runner remains the mutation/tool evidence primitive rather than being duplicated;
9. migration, tests, lint/typecheck/build and integration gates pass;
10. no unrelated V0.1 scope expansion occurred.

EVIDENCE / REVIEW FORMAT

Executor final review must be in Brazilian Portuguese and include:

• resumo;
• exact base/head SHA;
• arquivos alterados/criados;
• decisões locais;
• migration/schema evidence if applicable;
• testes and exact results;
• lint/typecheck/build;
• integration/restart/Redis-loss evidence;
• project isolation/stale-Git evidence;
• UADS evidence;
• LLM/provider call count for this foundation;
• errors found/fixed;
• risks/pending items;
• evidence/diff;
• proposed checkpoint delta.

STOP CONDITION

Stop with a Ready PR and all required evidence. Do not merge, promote the checkpoint, start executor dispatch, implement telemetry/Control Center, or begin WO-019. Sol audits the exact PR HEAD first.