Studio Goal Progress

Studio Goal Progress

Overview

Operate an explicitly opted-in KIT Goal from one portable append-only event stream. Percentage is verified weighted work; ETA is a separate range and confidence forecast. Compact and full GUI views read the same reduced state and never control the Goal.

When to use

Use to preflight or initialize an explicit KIT-managed Goal, append a meaningful workflow event, recover current state from progress.jsonl, report verified percentage and ETA, or handle an operator request to Open Progress.

When NOT to use

Do not use for arbitrary Codex tasks, packet planning, speculative progress, durable session transfer, or automatic dashboard opening. Route packet construction to feature-to-work-packets and durable transfer to studio-handoff.

Required inputs and context discovery

Require an explicit Goal opt-in, one goal ID, repository root and snapshot, plan version, scope and do-not-touch paths, ordered packets, final verification requirements, and max_active_timed_packets: 1. Runtime bindings are optional; declared bindings must identify a Codex thread or Hermes session. Every packet requires workflow_id, owner, positive integer progress_weight, dependencies, completion criteria, evidence kinds, and may omit or null its low/high duration estimate.

Safety and risk level

The helpers write only beneath the selected ignored goal root. Run preflight before init. Because init may launch a detached private writer runtime, obtain explicit service-start approval immediately before invoking it; Goal opt-in and a passing preflight are not approval. One writer appends validated events; workflows submit candidates instead of editing JSONL. GUI, context, and handoff consumers are read-only. Never expose raw logs, unrestricted paths, credentials, runtime keys, reusable session tokens, or mutation controls. Browser or panel opening separately requires an explicit Open Progress request.

Workflow

1. Confirm explicit KIT Goal participation and run report-only preflight against the manifest and bounded goal root before initialization. Completion criterion: schema, root, snapshot, packet ownership, positive weights, dependencies, required evidence, any declared runtime bindings, and timing policy are valid; otherwise initialization is BLOCKED.
2. Immediately before init, obtain explicit approval to start or reuse the private writer service, then initialize one goal-local writer from the accepted preflight inputs. Do not open a GUI. Completion criterion: without immediate service-control approval initialization remains BLOCKED; with approval, goal.started is accepted into progress.jsonl, reduced state is reproducible, and the Goal remains separate from other local sessions.
3. Submit candidate events only at meaningful boundaries: Goal start, packet transition, evidence observation, plan revision, context refresh, terminal state, or an explicitly bounded heartbeat for a long operation. Completion criterion: ordinary commentary, elapsed wall time, raw tool output, and optional runtime observations never become completion evidence.
4. Reduce the full append-only stream and calculate percentage from verified weight divided by active planned weight. Recalculate on approved plan revision without changing retained verified weight. Completion criterion: packet verification cites accepted matching Verified evidence, incomplete Goals display below 100%, and replay restores current state.
5. Calculate ETA as a low/high seconds range with basis, calibration, confidence, and warnings. Missing estimates return Calculating...; waiting_input, blocked, or stale state pauses ETA; unsupported parallel timing is BLOCKED. Completion criterion: ETA remains forecast rather than evidence and no inactive time or commentary implies completion.
6. On Open Progress, accept an explicit goal root, or first resolve one unique nonterminal Goal from the caller's declared manifest runtime binding before repository-level ambiguity fallback. Reuse a healthy authenticated dashboard runtime without new service approval. Starting a stopped or missing runtime requires immediate explicit service-control approval. Python returns one one-time localhost URL and separate server, panel, and browser statuses; it never invokes UI or browser APIs. After URL generation, the host agent uses its panel tool when available, otherwise instructs the operator to open the URL manually. Completion criterion: one top-level one-time URL, host-panel instruction, manual-browser instruction, and independent integration statuses are returned without reusable credentials; ambiguous selection, missing service approval, failed server start, unavailable panel/browser, or unavailable App Server is labeled BLOCKED while portable progress remains usable.
7. At terminal completion, require every active packet and every final verification requirement to have accepted matching evidence, then return a final evidence card. Completion criterion: the card records goal ID, plan version, verified percentage, ETA status, event and reduced-state artifacts, commands and exit codes, integration limitations, evidence labels, final verdict, and next action.

Evidence and output contract

Treat progress.jsonl as sole canonical recovery authority; goal.json, state.json, context files, runtime descriptors, and GUI output are derived. Report Goal state, verified and planned weights, exact percentage, display percentage, ETA status/range/confidence, current packet, latest evidence, next action, staleness, warnings, integration status, and artifact paths. Missing authority or evidence is BLOCKED, never simulated PASS.

Handoff contract

Record goal root, manifest hash, plan version, last accepted sequence, current packet, verified weights, ETA status, relevant commands, integration blockers, and next action. Use studio-handoff for durable cross-session transfer.

Pitfalls and anti-rationalization

• “Work feels almost done” is not verified weight.
• “It has run for an hour” is not percentage or evidence.
• Missing packet weights do not justify equal-weight defaults.
• App Server failure does not invalidate the portable KIT stream, but enrichment remains BLOCKED.
• Goal opt-in and preflight do not authorize init; service approval is required immediately before that command.
• Open Progress never invokes a panel or browser from Python. It reuses a healthy runtime, and starts a missing runtime only with immediate explicit service-control approval; neither path authorizes Goal mutation or reusable token disclosure.

Verification checklist

• Explicit Goal opt-in and preflight preceded initialization, with separate service approval immediately before init.
• Packets have positive weights and matching evidence requirements.
• Only meaningful-boundary events were submitted through one writer.
• Percentage comes only from verified active weight.
• ETA is a labeled range or honest Calculating, Paused, or BLOCKED state.
• GUI opening was manual and views remain read-only.
• Final evidence card separates Verified, Snapshot, Unverified, and BLOCKED facts.

References and scripts

Load commands and interpretation before running helpers. The standalone skill bundles scripts/goal_progress.py, scripts/goal_progress_core.py, scripts/goal_progress_store.py, scripts/goal_progress_server.py, and scripts/goal_progress_app_server.py together with the Goal manifest, event, state, and context projection schemas.