Epic/RFC: goal-directed task graph for my-pi

[spences10]

Summary

Build a goal-directed task graph for my-pi. A goal defines the outcome and completion contract. A validated directed acyclic graph (DAG) defines the work, dependencies, verification requirements, and evidence needed to reach that outcome.

This is not a general workflow orchestrator. The package owns goal and graph state. Direct Pi, @spences10/pi-harness, and Team Mode remain responsible for execution and peer coordination.

Research baseline

The design is informed by:

• Claude Code /goal: one active completion condition, automatic continuation, and separate completion evaluation.
• harms-haus/pi-tasks: atomic graph edits, missing-reference and cycle validation, deterministic ready-task selection, and session persistence.
• tmonk/pi-goal-x and izzzzzi/pi-goal-pro: structured goal plans, evidence, budgets, recovery, no-progress detection, and independent review.
• nicobailon/pi-coordination: task graphs, contracts, worker scheduling, and review cycles. Its orchestration surface is intentionally outside this epic.

These projects are prior art, not implementation dependencies. License and source reuse must be checked before adapting code.

Product model

Goal
 ├─ objective
 ├─ completion contract
 ├─ lifecycle and limits
 └─ task DAG
      ├─ dependencies
      ├─ verification contract
      ├─ lifecycle state
      └─ evidence

The graph answers which work is ready. The goal answers whether the complete outcome is proven. Graph state does not execute work and must not treat an agent claim as proof.

Proposed v1 scope

• One active goal per session.
• Goal objective and explicit completion requirements.
• Task states: pending | ready | active | blocked | done | failed.
• Dependency edges with missing-reference, self-edge, duplicate-edge, and cycle validation.
• Deterministic ready-task calculation and deadlock reporting.
• Atomic graph mutations: validate the complete proposed state before persistence.
• Verification contract and evidence required before a task reaches done.
• Independent final goal audit before completion.
• Session persistence and branch-aware reconstruction through Pi session entries.
• Commands to create, inspect, pause, resume, and clear goals.
• Agent tools to inspect and update the graph.
• Optional bounded auto-continuation, disabled by default.
• Compact interactive status without replacing the existing footer.

Explicit non-goals for v1

• Worker or child-session spawning.
• A second harness or execution framework.
• Multiple active goals.
• Global or project-wide goal databases.
• File reservations or path ownership.
• Adaptive routing or model selection.
• General workflow templates.
• New telemetry schemas.
• Automatic Team Mode dispatch.

Architecture boundaries

@spences10/pi-goal

Owns the goal aggregate, graph invariants, state transitions, session persistence, commands/tools, completion audit, continuation policy, and compact status UI. The graph engine must be pure and independently testable.

@spences10/pi-harness

May later consume one ready task and its verification contract as a bounded execution contract. Goal must not duplicate harness path restrictions, validation scripts, review runtime, or enforcement.

Team Mode

May later let authorized peers claim independent ready tasks. Goal must not spawn, supervise, or assign peers in v1.

Factory and upstream convergence

Factory remains paused and excludes workflow graphs. This work must not depend on it. Track #471 so released upstream AgentHarness or telemetry primitives can replace local adapters where appropriate.

Core invariants

1. At most one active goal exists in a session branch.
2. Every dependency refers to an existing task in the same goal.
3. The dependency graph is acyclic.
4. A task is ready only when all dependencies are done.
5. A task cannot become done without evidence accepted by its verification contract.
6. Goal completion requires all required tasks and the goal completion contract to pass an independent audit.
7. Graph mutations are atomic and append a reconstructable session snapshot or event.
8. Auto-continuation cannot run after pause, abort, budget exhaustion, user interruption, or terminal state.
9. Resume and branch reconstruction produce deterministic state.
10. UI and telemetry are projections of authoritative state, never alternate state stores.

Proposed user surface

/goal <objective>
/goal status
/goal pause
/goal resume
/goal clear

Initial tool capabilities should cover reading state, atomic graph updates, ready-task claims, blocker/evidence recording, and completion-audit requests. Use one action-based tool if provider schema portability makes many narrow tools harder to maintain.

Persistence and evaluation

Use Pi session entries as the v1 source of truth. Reconstruct from the current branch so resume and branching follow Pi semantics. Do not add JSON or SQLite fallback storage until a demonstrated cross-session requirement exists.

Completion evaluation must distinguish deterministic checks from model review. A model must not claim that a command passed unless the evidence contains its result. Evaluator calls should use Pi's model registry credentials and @earendil-works/pi-ai, without changing the active session model.

Delivery gates

• Pure graph invariants have focused unit and property-style tests.
• Lifecycle tests cover resume, branching, interruption, abort, re-entry, and duplicate continuation.
• No graph mutation can partially persist after validation failure.
• A task cannot self-certify completion without accepted evidence.
• A goal cannot complete while required tasks remain unresolved.
• Package checks, root integration checks, and LSP diagnostics pass.
• Dogfood cases show benefit over a plain prompt and do not require manual state repair.
• Default auto-continuation remains off until the evaluation issue passes.

Sub-issues

• Define the pi-goal domain model and pure DAG engine #477
• Add branch-aware pi-goal session persistence and recovery #478
• Expose pi-goal commands and graph-management tools #479
• Implement evidence contracts and independent completion auditing #480
• Add bounded pi-goal continuation and interruption control #481
• Add compact pi-goal status UI and observability integration #482
• Package and register @spences10/pi-goal as an opt-in extension #483
• Dogfood the goal-directed task graph and decide default behavior #484

[spences10]

Tracking update — 2026-08-20

Rechecked the epic against the repository and current upstream Pi 0.84.2. All sub-issues #477–#484 remain open and packages/pi-goal does not yet exist. Upstream AgentHarness progress does not block the pure goal/DAG model because this epic owns goal state and completion evidence rather than execution.

Recommended next gate: implement #477 as a pure, independently tested graph/domain package only. Keep persistence, commands, UI, continuation, Team Mode, harness integration, and default enablement out of that first slice. Continue only if the pure model remains distinct from orchestration and later dogfood shows value over a plain prompt.