Goal contract capture

Goal Contract Capture

You produce a FlowGoal contract — a durable completion contract that turns acceptance criteria + specification into a machine-readable, file-backed artifact. This skill is the 5th invoker of the existing specification-capture pattern; it wraps that skill (does NOT replace it) and adds the goal-specific fields needed for evaluator/Stop-hook enforcement.

Iron Law

No /flow:goal create without a complete contract. No .flow/goals/<id>.goal.yaml without an evaluator binding. The contract is the source of truth for the Stop hook and /flow:goal evaluate; gaps here cascade into silent premature completion.

Relationship to existing skills

This skill is a wrapper, not a fork:

Existing skill	What it gives us	What this skill adds
specification-capture	non-goals, failure modes, interface contracts	the specification block in the goal YAML
criterion-verification-map	per-AC verification commands + expected evidence	the objective.acceptance_criteria[].verification_command field
evidence-based-development	ASSERTION/EVIDENCE/VERIFIED discipline	the evidence_ref linking the AC back to a FlowEvidence sidecar

If those skills have already produced their outputs (decision journal manifest entries), this skill reads from them rather than re-asking the user.

Inputs

The invoking command MUST pass:

1. Goal id — typically issue-{N}, pr-{N}-review, pr-{N}-address, or an ad-hoc slug. Validated against the schema's ^[a-z0-9][a-z0-9-]{0,63}$ pattern.
2. Scope — repo, branch, optionally issue and/or pr, optionally a journal path (.decisions/issue-{N}.md).
3. Source — typically the GitHub issue body (parsed for AC) or the PR description (parsed for review/address scope).
4. Invocation reason — start | goal-create | review | address. Used to choose the right outcome template and the right evaluator.type.

Outputs

Single file: .flow/goals/<id>.goal.yaml conforming to plugins/flow/schemas/v1/goal.schema.json. Written via bin/flow-goal-record.sh (atomic, O_NOFOLLOW-defended).

Plus: one goal-created artifact appended to the linked decision journal via bin/journal-record.sh --type goal-created --metadata goal_id=<id> --metadata source=<src>.

Workflow

1. Pre-flight check — refuse if .flow/goals/<id>.goal.yaml already exists and lifecycle.status is not in {cancelled, failed}. Surface the existing goal to the user via the six-field escalation; never silently overwrite an active goal.

2. Compose metadata:

   metadata:
     id: <derived-from-invocation>
     created_at: <ISO-8601 UTC now>
     created_by: <invoking command, e.g. /flow:start>
     owner: <git user.email or @me>
   

3. Compose scope — from inputs. Set journal to the linked decision journal path. Leave run_id empty until run-state-management wires FlowRun creation.

4. Compose objective — pull AC text + verification commands from the existing criterion-verification-map output. Each AC is one entry with status: pending and evidence_ref: null initially. The outcome is a one-sentence statement derived from invocation reason:

   • start → "Issue #{N} is implemented and verified."
   • goal-create → user-supplied via AskUserQuestion.
   • review → "PR #{N} review completed with findings posted or no-finding evidence recorded."
   • address → "All unresolved findings on PR #{N} are resolved, commented, or escalated."

5. Compose specification — lift from specification-capture's journal entries:

   • non_goals from the ## Specification > ### Non-goals body
   • failure_modes from ### Failure modes
   • interface_contracts from ### Interface contracts

   If any block is empty, raise the six-field escalation per references/escalation-format.md — do NOT silently fill with placeholders.

6. Compose constraints — default to tdd_required: true, require_all_pass: true, no_calendar_estimates: true, no_tier3_without_confirmation: true. Add denied_paths from settings (flow.goals.denied_paths cascade key); add allowed_paths only if the goal narrows the tier model (e.g., a focused refactor).

7. Compose evaluator:

   evaluator:
     type: flow_verdict_judge          # hybrid for fuzzy criteria; deterministic for command-only
     command: /flow:goal evaluate
     judge_agent: goal-evaluator-judge
     evidence_bundle_format: plugins/flow/references/evidence-bundle-format.md
     denied_context:
       - implementation_rationale
       - self_review_findings
   

8. Compose continuation — defaults: mode: flow_managed, on_incomplete: continue_next_activity, on_blocked: six_field_escalation, on_complete: mark_achieved, max_iterations: <from settings, default 20>.

9. Compose lifecycle — initial state:

   lifecycle:
     status: active
     current_phase: <derived; start→explore, review→fan-out, address→categorize>
     current_activity: <first activity id>
     turns_evaluated: 0
     last_evaluation:
       result: incomplete
       reason: "Goal created; evidence not yet collected."
       at: <now>
   

10. Write atomically — call bin/flow-goal-record.sh with the composed YAML. Verify exit 0; surface stderr on any failure.

11. Record journal artifact — bin/journal-record.sh --issue {N} --type goal-created --metadata goal_id=<id> --metadata source=<src>.

12. Verify the artifact — read back .flow/goals/<id>.goal.yaml and validate against the schema (Python jsonschema if available). A schema mismatch here means the skill or the schema is broken; fail hard.

Per-invoker scope

Invoker	Captures	Skips
start	All blocks; outcome derived from issue title	nothing
goal-create	All blocks; outcome from AskUserQuestion	journal manifest if no issue
review	Outcome + AC (= review checklist) + constraints	specification (use issue's existing capture)
address	Outcome + AC (= one per unresolved PR comment) + constraints	specification (inherit from review goal)

Anti-patterns

• ❌ Silently overwriting an active goal — always surface and escalate.
• ❌ Filling in empty specification blocks with placeholders — escalate via six-field.
• ❌ Bypassing bin/flow-goal-record.sh for "speed" — atomicity + symlink defense matters.
• ❌ Setting lifecycle.status: achieved at creation — the only way to achieved is through /flow:goal evaluate.

Reuse map

• plugins/flow/skills/specification-capture/SKILL.md — read the per-invoker scope table; this skill adds row 5 (goal-create).
• plugins/flow/skills/criterion-verification-map/SKILL.md — read for the AC verification-command shape.
• plugins/flow/schemas/v1/goal.schema.json — the canonical schema this skill writes against.
• plugins/flow/bin/flow-goal-record.sh — atomic writer.
• plugins/flow/bin/journal-record.sh — for the goal-created manifest artifact.
• plugins/flow/references/escalation-format.md — six-field escalation for any empty/ambiguous block.