ospec-goal

# OSpec Goal

Use this skill for complex work that needs the full OSpec workflow. A goal is intentionally heavier than a change and is the place to use design docs, implementation planning, task graph dispatch, worker/reviewer handoffs, and durable evidence.

Every rule you need in order to act is in this file. `for-ai/execution-protocol.md` is the authoritative detail behind those rules — open it only when a named situation actually comes up (per-harness wait primitives, lease expiry, repair convergence, cross-task finding scope, worker-report repair binding, allowlist CAS semantics, deferred external acceptance, force-archive detail), never on goal entry and never on every turn. That file is the goal profile's reference; a classic change reads `for-ai/change-protocol.md` instead and must never be sent here.

## Loop Model

`ospec goal` creates a **session-bound Loop** automatically (`artifacts/loop/loop.json` + `state.json` + `run-log.jsonl`). There is no separate init step.

- **OSpec is the durable state-machine brain.** `ospec loop run --once` first observes the previous task, review, or verification evidence, then emits a bounded batch of action items from `task-graph.json`. Execute each one only through the model-native subagent primitive named by its target-bound `runtimeAdapter`, then record durable evidence.
- **IDE controller auto-dispatch is mandatory.** Never stop at "Loop initialized" or ask the user to run Loop commands. Run `ospec loop run <goal-path> --once --compact-json`, consume every returned action, record evidence as each executor finishes, and tick again without another user prompt. Stop only for a required user decision, an unavailable independent/isolated executor, a blocking safety gate, a configured guard/STOP, a terminal failure that needs user authority, an explicit user pause, or `done`.
- **One batched call per controller round.** `ospec loop step <goal> --batch-file <path|->` applies every claim and every result and ticks in ONE process, then emits the next action batch as compact JSON. It replaces `loop heartbeat` x N + `loop finalize` x N + `loop run --once`; at the default concurrency of 3 that is a measured 7 controller calls down to 2. The ceiling is `2C+1` in the DECLARED capacity C (C=5 measures 11), not in the task count, so the win does not grow as the goal gets more tasks. Send `{"claims":[...]}` with `--no-tick` right after dispatching, then `{"results":[...]}` when the children finish. A missing or mis-keyed envelope key is a hard error, never an empty batch; a partial failure stops, does not tick, and prints exactly which items are already durable.
- **Executor lifecycle is durable and bounded.** Claim each dispatched child once (the `claims` array of `ospec loop step`, or `ospec loop heartbeat` per item), run `ospec loop poll <goal> --json` between native waits (it refreshes every lease and reports `tickNow`), and full-tick only on `tickNow=true` or right after dispatching. Never make one indefinite wait: stay inside `maxWaitMs` (60s) while other work is dispatchable; the single `idleMaxWaitMs` (10min) wait is only for the last outstanding batch. Commit each finished child with its emitted `ospec loop finalize ...` command, and use `ospec loop recover --force` only when the prior session or child is known to be gone.
- **Match execution shape to graph shape.** Maximize task-graph width: every `depends_on` must be semantically necessary, and the planning review treats an unjustified fully serial chain as a finding. On a reported `serialBottleneck` the controller may implement that one task inline (executor id `controller-inline`); reviews stay independent subagents. `--review-gating optimistic` fits low-risk goals; keep the strict default for `high_risk`/`security_related` work.
- **Planning quality is fast and bounded.** Design preflight, then plan preflight — never launch a reviewer child for either — then the derived task graph, then one independent combined planning review. `NEEDS_CHANGES` permits one grouped repair and at most one delta-scoped re-review; a repeated semantic failure is a stable blocker, never an open-ended loop.
- **Progress documents track reality.** Tick each proposal.md acceptance criterion as its evidence passes; tag acceptance lines `[verify:<id>]` and record `ospec execute verify ... --satisfies <id>` so `ospec execute sync` auto-ticks them. Archiving blocks on unchecked items. review.md is derived by sync from the final review — never edit it by hand.
- **Required decisions always block.** Present every required decision to the user, never auto-select the recommendation, and record it with `--answered-by user` before the loop proceeds. Brainstorm resolutions need the same provenance.
- **`/goal` is capability-probed, not inferred from a target name.** `ospec execute launch --primitive goal` emits a native-`/goal` instruction only when the harness explicitly reports support; otherwise the same controller runs the verify-driven loop through native subagents.
- **Scheduling is session-bound.** Unknown native capacity uses the default implementation concurrency of three while keeping conflict-safe review batches under the configured limit. Raise `maxParallel` only from an authoritative current-session capacity report — never from a provider name or a stale session — and never over dependencies, file conflicts, token funding, or the configured maximum.
- **Progress is artifact-backed, and `state.json` is the status source of truth.** Task status, review decisions, repair waves, evidence, `state.json`, and `run-log.jsonl` carry progress between fresh contexts, and process exit alone does not complete an action. When a document and `state.json` disagree, reconcile toward `state.json` instead of reporting the document's value. Dispatch only items returned in `actions`; a durable `pending` record with an empty action list is observation state, not work.
- **Manual artifact edits need a sync.** After hand-editing the task g