stack/skills/ms-goal/SKILL.md

name, description

name	description
ms-goal	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 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:

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.