Add goal manager — atomic_agents.goal (closes #3)

[dep0we]

Summary

Implements issue #3 — goal manager per spec/12-goals-and-intent. Lets agents pursue persistent goals across many sessions via decomposition into sub-goals with explicit lifecycle.

This is the v0.4 milestone module. Independent of evals/tuning — pure data model + lifecycle. Stacked on the tuning PR; base auto-updates as PRs land.

What's in this PR

New module: atomic_agents/goal.py (~700 LOC)

Data model + validation:

• Goal, SubGoal, CompletionEvaluation dataclasses matching spec/12 frontmatter
• validate_goal() — required/optional fields, sub-goal status enum, duplicate-id detection, type checks
• validate_agent_mode() — reactive | goal-driven | hybrid
• parse_agent_mode() — reads IDENTITY.md "Operating mode" section; defaults to reactive if not declared

GoalManager class:

• load() / save() — frontmatter round-trip with validation
• has_active_goal() — quick check for hybrid runtimes to switch modes
• next_sub_goal() — finds the next pending, unblocked sub-goal (filters by blocked_by chain)
• Lifecycle transitions (mark_in_progress, mark_complete, mark_blocked, mark_abandoned) — validated state machine, idempotent where it should be (mark_complete on already-complete is a no-op)
• add_sub_goal() — operator action to extend the goal
• evaluate_completion() — all-criteria-met flag, per-status counts, deadline pacing (overdue detection only when active + past deadline)
• archive() — non-destructive move to goal_archive/YYYY-MM-DD_<intent_slug>.md; used for both completion and abandonment
• abandon(reason) — operator-initiated archive with stated reason
• status_summary() — one-screen text output for goal status
• progress_report() — structured periodic check-in (suitable for appending to journal entries); includes pacing analysis with ahead-of-pace / behind-pace flags
• Auto-appended history — every state transition writes a timestamped line to the goal's body History section

CLI: python -m atomic_agents.goal {status|next|advance|abandon|complete|report}

Hard rules (per spec/12) — all enforced:

• Operator-set goals (no auto-generation)
• Operator-set success criteria (no agent-side tuning)
• Missed deadlines surface to operator (overdue flag), never auto-extended
• Locked decisions in policy/ never overridden (out of goal manager's scope; respected by the agent runtime)
• Sequential goals only in v0.4 (one active per agent)

Tests: tests/test_goal.py — 39 tests, all passing

• Validation: 5 cases (valid, missing field, invalid priority, invalid sub_goal status, duplicate id)
• Mode parsing: 5 cases (each mode + missing section + missing file)
• Load + save: round-trip preservation, corrupt YAML rejection, has_active_goal in both states
• Next sub-goal: picks first unblocked, returns None when none dispatchable, respects blocker chain (blocked-by-blocker-not-complete suppresses; completing the blocker unblocks)
• Lifecycle: each transition + idempotency + invalid transitions + add_sub_goal (incl. duplicate id rejection)
• Completion evaluation: in-progress + all-done + overdue
• Archive + abandon with reason (verifies non-destructive move, metadata captured)
• Status summary + progress report formatting (key fields present, overdue flagged, pacing computed)
• Save persistence: changes survive reload, last_progress_check updated, history appended

Total suite: 158/158 passing.

Spec coverage

Per spec/12 acceptance criteria (issue #3):

• ✅ goal.md schema validation
• ✅ Sub-goal lifecycle (pending → in_progress → complete | blocked | abandoned)
• ✅ Decomposition loop (next_sub_goal + lifecycle transitions)
• ✅ Completion criteria evaluator
• ✅ Goal abandonment (non-destructive)
• ✅ Progress check (periodic via goal report; cadence config is operator-driven)
• ✅ Hybrid agent support (parse_agent_mode + has_active_goal)
• ✅ CLI: status / next / advance / abandon / complete / report

What's deferred

• Multi-agent project goals + queue dispatch — the project-level goal.md at <system>/projects/<project>/goal.md and queue handoff to peer roles is part of issue [v0.7] Multi-agent project cascade loader — atomic_agents.agent #6 (multi-agent project cascade loader) where the project structure is the right context. The data model from this PR works identically there.
• Runtime assembly extension at step [3.5] — the AtomicAgent.assemble_system_prompt doesn't yet load goal.md. The change is a one-liner conditional on has_active_goal(). Deferring to issue [v0.7] Multi-agent project cascade loader — atomic_agents.agent #6 (where multi-agent runtime assembly is restructured anyway) to avoid touching agent.py twice.

Both are pure additions; no restructuring of this module needed.

Test plan

• uv run pytest tests/test_goal.py — 39 tests pass
• uv run pytest — full suite (158 tests) passes
• Real-world test: build a Muse Director sample with a multi-chapter goal and walk through a few sub-goal completions (after the multi-agent cascade lands in [v0.7] Multi-agent project cascade loader — atomic_agents.agent #6)

🤖 Generated with Claude Code