goal-contract-capture
Capture a FlowGoal contract as `.flow/goals/<id>.goal.yaml` — outcome, acceptance criteria with verification commands, specification (non-goals, failure modes, interface contracts, risk map), constrai
SKILL.mdplugins/flow/skills/goal-contract-capture/SKILL.md
GitHubGoal Contract Capture
Contract
Iron law: no .flow/goals/<id>.goal.yaml without an evaluator binding, and no contract element invented: every specification element is lifted from the journal or escalated. Invoked by /flow:start (Phase 1, after the Spec Validation Gate), /flow:goal create, and /flow:debug (after the confirmed hypothesis) with a goal id, scope, source, and invocation reason (start | goal-create | review | address | debug). Returns the written goal path plus a goal-created journal artifact; the caller then invokes goal-lifecycle. Permitted skips: review and address invocations skip the specification block (they inherit the issue's capture); goal-create with no linked issue skips the journal artifact. Nothing else may be skipped.
Inputs
- Goal id:
issue-{N},pr-{N}-review,pr-{N}-address, or an ad-hoc slug matching^[a-z0-9][a-z0-9-]{0,63}$. - Scope:
repo,branch, optionalissue/pr, optionaljournalpath (<journal dir>/issue-{N}.md, the journal dir being whatbin/journal-dir.shprints). - Source: issue body, PR description, or user-supplied outcome.
- Invocation reason: selects the outcome template and
evaluator.type.
Outputs
.flow/goals/<id>.goal.yaml conforming to plugins/flow/schemas/v1/goal.schema.json, written only through bin/flow-goal-record.sh --create --goal-file <composed.yaml> (atomic, O_NOFOLLOW-defended, schema-validated), plus bin/journal-record.sh --issue {N} --type goal-created --metadata goal_id=<id> --metadata source=<src>.
Workflow
- Pre-flight: if the goal file exists with
lifecycle.statusoutside{cancelled, failed}, stop and raise the six-field escalation (references/escalation-format.md). Never overwrite an active goal. metadata:id,created_at(ISO-8601 UTC),created_by(invoking command),owner(gituser.emailor@me).scope: from inputs; leaverun_idunset (run-state-management fills it).objective:outcomeby reason:start: "Issue #{N} is implemented and verified.";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.";goal-create: AskUserQuestion;debug: the caller's template. Each AC comes fromcriterion-verification-mapoutput withstatus: pending,evidence_ref: null, and itsverification_commandwhen one exists.specification: lift from the journal's## Specificationsection written byspecification-capture:non_goalsfrom### Non-goals,failure_modesfrom### Failure modes,interface_contractsfrom### Interface contracts, andrisk_mapfrom the### Risk maptable, where each rowArea | Plausible wrong version | Discriminating checkbecomes{area, plausible_wrong_version, discriminating_check}. When the journal has no### Risk map, omit therisk_mapkey. Never invent rows or fill an empty block with placeholders; an empty non-goals, failure-modes, or interface-contracts block is a six-field escalation.constraints:tdd_required,require_all_pass,no_calendar_estimates,no_tier3_without_confirmationalltrue;denied_pathsfromflow.goals.denied_paths;allowed_pathsonly when the goal narrows scope.evaluator:type: flow_verdict_judge(hybridwhen fuzzy criteria exist,deterministicwhen every AC has a command),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].continuation:mode: flow_managed,on_incomplete: continue_next_activity,on_blocked: six_field_escalation,on_complete: mark_achieved,max_iterationsfrom settings (default 20).lifecycle:status: active,current_phaseby reason (start: explore,review: fan-out,address: categorize,debug: fix),current_activity,turns_evaluated: 0,last_evaluation: {result: incomplete, reason: "Goal created; evidence not yet collected.", at: <now>}. Neverachievedat creation.- Write, record, verify: run the helper, surface any non-zero exit with its stderr, append the journal artifact, then read the file back and confirm it parses and matches the schema.
Trust
bin/flow-goal-record.sh --create also records the goal in the per-user trust ledger (goal-trust.jsonl in the per-user state directory bin/cascade-resolve.sh --state-dir names, via bin/flow-goal-trust.sh record). The Stop hook executes a goal's verification commands only when the goal is trusted or flow.goals.executeVerificationCommands is true. A goal is trusted only when it was created through flow in this user's environment; a goal that arrived with a checkout is not. Editing a verification_command by hand changes the hash and untrusts the goal until you run bin/flow-goal-trust.sh record --goal-file .flow/goals/<id>.goal.yaml.
References
plugins/flow/skills/specification-capture/SKILL.md: the journal headings lifted in step 5.plugins/flow/skills/criterion-verification-map/SKILL.md: AC verification-command shape.plugins/flow/references/flow-goals.md: full YAML example and settings.