Orchestrata Ultimate › Plans › spec-023-goal-consolidation-plan

SPEC-023 Goal-System Consolidation Plan

Source: plans/spec-023-goal-consolidation-plan.md at 8a2cb42ad · last changed 2026-07-27 · first committed 2026-07-14 · 70 lines.

Prose pending.

Plan text

SPEC-023 Goal-System Consolidation Plan

Current state (audited 2026-07-14)

Three overlapping goal implementations exist:

SPEC-023 requirements vs reality

specs/023-goal-system/spec.md expects:

• Goal-driven sessions with exit criteria.
• Automatic evaluation of exit criteria (verify_command / verify_pattern).
• Goal status checked before stopping (check_goal_before_stop).
• Audio alarm on blocked/complete.

Reality:

• The CLI lets users set/view/update a goal, but no code runs the criterion verification.
• GoalMixin.check_goal_before_stop exists but is never called.
• GoalCriterion.verify_command and verify_pattern are dead fields.
• Audio alarm system is absent.

Decision fork

Before any wiring, choose ONE canonical goal surface:

1. Make the CLI SessionController canonical (recommended)

   • Keep the singular session goal in state.goal.
   • Move the duplicate GoalMixin methods into the CLI SessionController (or delete GoalMixin if the CLI already covers them).
   • Implement real criterion evaluation in session/cli/lifecycle.py (_run_end_* path) or session/session.py.
   • Wire check_goal_before_stop into session end / SessionController.end().
   • Delete session/controller/_goals.py.
   • Keep portfolio goals as a separate PM concern (do not merge).

2. Make session/controller/_goals.py canonical and delete the CLI duplication

   • Less attractive: the CLI is the user-facing surface and is actively used.

3. Merge singular session goal into the PM portfolio-goal model

   • Overkill for a simple session objective; portfolio goals are multi-item, PM-managed, and optional.

Proposed minimal execution plan (if Option 1 is chosen)

1. Delete src/orchestrata_ultimate/session/controller/_goals.py and remove its import/composition from any SessionController.
2. Add criterion execution to the live SessionController:
   • GoalCriterion.verify_command: run as a subprocess (like the CLI already runs git/pytest); capture returncode.
   • GoalCriterion.verify_pattern: match stdout/stderr or a file against the regex.
   • Update criterion status to met/failed.
3. Wire check_goal_before_stop:
   • Call from SessionController.end() (and the session end CLI) when a goal is active and not yet achieved.
   • Return/echo the remaining-criteria message and abort the end operation (or require --force).
4. Audio alarm (SPEC-023 FR-006/013):
   • Add a small session/alarm.py utility that tries paplay/aplay/ffplay and falls back to the terminal bell.
   • Call from goal-completion and blocker paths.
5. Tests:
   • Real subprocess criterion execution with a passing/failing shell command.
   • Pattern matching against command output.
   • session end blocked when criteria unmet; allowed when all met or --force.
   • Alarm utility tries each backend without crashing when absent.

Blocker

This work requires choosing between the three implementations above and deciding the behavior of session end when criteria are unmet (abort vs warn vs require --force). That is a product/UX decision, not a unilateral code change.

Suggested next step

Confirm Option 1 (CLI SessionController canonical, delete GoalMixin, keep portfolio goals separate) and the desired session end behavior. Then execute the plan above.

Related

• Plans
• Orchestrata Ultimate — project index
• Workflow
• Tasks