stack/skills/ms-goal/SKILL.md

---
name: ms-goal
description: Maintain a durable goal, acceptance criteria, task pointers, and pause/resume state for an authorized continuing Mosaic assignment. Use with ms-proactive-agent for dev testing before the goal extension is integrated; this skill provides no automatic wake mechanism.
---

# Mosaic Goal

Manage the work record for a continuing assignment. Use
[ms-proactive-agent](../ms-proactive-agent/SKILL.md) to select and execute its tasks.
This is a file-based instruction protocol, not an implemented Stack API or project schema.
It does not register `/goal`, supply `goal_report`, launch agents, or force another turn.
Use ordinary requests such as "continue this goal" or "pause this goal" in dev tests.

## Establish or recover a goal

1. Use the user's authorized assignment and applicable mission constraints. Do not create
   a standing goal from a role description, casual question, or review of this skill.
   Preserve existing authorization; make reasonable implementation choices within it.
2. Resolve the workspace and its authoritative work records before writing. Reuse an
   existing goal/task system rather than creating a competing source of truth. A separate
   test goal must not replace the repository's queued project work.
3. For a dev fixture with no declared records, use `work/goals/<goal-id>/` beneath the
   explicitly selected writable workspace. Check for existing records first. Create
   `GOAL.md`, `TASKS.md`, and append-only `HISTORY.md` there; this is a local test convention,
   not a claim that workspace registration or isolation has been implemented. Give the
   user the goal path so a later conversation can find it. Do not guess among multiple
   goals or reuse another workspace's goal.
4. Establish observable acceptance criteria, completion owner, allowed scope, exclusions,
   applicable approvals, budget, and initial next action. Derive these from the request
   when clear; ask only for missing decisions that materially change execution. Ordinary
   task acceptance can use the request's criteria; preserve explicit human sign-off.
5. On resume, read the goal, relevant tasks, history since the last checkpoint, and linked
   approvals. Verify workspace, ownership, current permissions, budget, and live outcomes.
   If a known record is missing or corrupt, report a recovery blocker; absence does not
   authorize a replacement goal or a fresh budget.

## State transitions

| State | Meaning and next transition |
|---|---|
| `active` | Authorized work can proceed. Continue in the same turn through useful checkpoints. |
| `waiting` | No ready work; a named dependency or decision is pending. Record automatic or manual wake and the exact return condition. A matching event permits reconciliation, then `active` if work is ready. |
| `paused` | User stop, budget limit, or another explicit hold. Preserve the goal and reason. Only authorized resumption that resolves the hold permits `active`. |
| `blocked` | No ready work and no usable current route to resolve a required capability, invalid state, or unknown outcome. Record the blocker, owner if known, and recovery condition. Reconcile supplied recovery evidence before returning to `active`. |
| `satisfied` | Every acceptance criterion has verified evidence and all required acceptance owners have approved. Preserve the record and stop selecting work for this goal. |
| `canceled` | The user ended the assignment. Preserve evidence and obligations; do not restart without explicit authorization. |

A task may wait while the overall goal stays active because another task can proceed.
Goal state and task state are separate. Preserve pauses through compaction and restart.
An unrelated message, receipt, or wake event never lifts a pause or cancellation. A status
request is read-only with respect to control state. Scope corrections change only the
affected work; they do not silently replace the goal or revoke unrelated authorization.
A satisfied goal stays closed unless the user authorizes follow-up work or new evidence
invalidates its acceptance; record the reason and recheck authority before reopening.

On pause/cancel, stop initiating work promptly. Reconcile already-running actions when
possible and report any still running or unknown. Retire owned watches and delegated work
only through authorized cancellation mechanisms; never claim that changing this file
canceled a process, message, or external operation.

## Minimal durable record

Use existing schema fields when available. For the dev convention, `GOAL.md` contains:

```yaml
id: <stable id>
revision: <monotonically increasing record revision>
context: <agent, declared project if any, absolute workspace, execution/session if known>
objective: <authorized outcome>
authorization: <user request/mission/decision reference and relevant scope>
scope: <allowed work and exclusions>
acceptance: <criterion ids, observable checks, evidence pointers, completion owner>
state: <active|waiting|paused|blocked|satisfied|canceled>
state_reason: <why, and the condition/authority needed for the next transition>
tasks: <authoritative task record path>
ownership: <assigned writer, coordinator claim reference if available>
budget: <limits, consumed/remaining, measurement source or labeled estimate/unavailable>
checkpoint: <last verified result and evidence pointers>
next_action: <task id and concrete action, or none with reason>
obligations: <open request ids and their durable record pointers, or none>
wait: <condition, last observation, auto/manual wake, owner, deadline and escalation or none>
uncertain_actions: <action/request ids requiring reconciliation, or none>
updated_at: <timestamp>
history: <durable transition/action history path>
```

Each task records id, goal criterion, owner, dependencies, status, next action, and evidence.
Use `ready`, `in-flight`, `waiting`, `blocked`, `done`, or `canceled`; retain historical
tasks and the reason for cancellation. Goal acceptance must still be checked independently
of task statuses. The next-action field is a checkpoint, not a scheduling instruction.

History records changed decisions, transitions, and action intent/results with timestamp,
task/action id, relevant revision, evidence, and reason. Record intent before an external
effect and its result afterward. If interrupted between them, mark the outcome unknown and
reconcile against the live system before retrying. Do not invent exactly-once guarantees.

Use the runtime's authoritative transaction/claim mechanism if present. The Markdown
fallback requires one assigned writer; a revision field alone does not enforce exclusion.
Before replacing a snapshot, check that its read revision/content has not changed and use
an atomic file replacement where supported. Append history first and record the matching
revision in the snapshot. After interruption, reconcile any mismatch before new effects.
This reduces torn writes; it is not a multi-file transaction or concurrency guarantee.
If safe recording or exclusive ownership cannot be established, block affected mutations.
Preserve history and unresolved obligations when compacting snapshots.

## Completion and handoff

An empty queue is not evidence of satisfaction. Check each acceptance criterion against
the actual artifacts/system and required owner verdicts. Missing necessary work is a
planning input to ms-proactive-agent; missing acceptance is a wait. Completion evidence
must match the delivered revision or resource, not an earlier successful check.

For a wait without a scheduler, record `manual` and tell the user the unresolved condition
and the goal path to resume. Do not spin, poll a person, or emit repeated progress reports.
For an involuntary turn limit, preserve incomplete state and the next action; explain
whether a user invocation or a verified runtime continuation will resume it.

## Future extension integration

Do not call unavailable goal tools or edit an extension's private state. When a supported
extension is integrated, first establish its actual API, context binding, pause semantics,
wait suspension, restart recovery, and budget behavior. Choose one authoritative lifecycle
record and explicitly reconcile existing file goals; do not silently run two goal loops.
Map states only through supported operations. An `in_progress` report alone does not prove
that the runtime suspends checks while waiting. Keep file mode until the target integration
passes the [execution checks](references/execution-checks.md).