Goals

A goal is the durable unit of work in ASF50. It is Git-tracked (a contract under goals/<GOAL_ID>/), it is materialised into the runtime store, and it advances through a fixed state machine until it reaches a terminal state.

Anatomy of a goal

Every normal goal has three Git-tracked files:

File	Purpose
goals/<GOAL_ID>/GOAL_RECORD.yaml	The contract: state, role, paths, gates, tasks.
goals/<GOAL_ID>/CONTEXT.yaml	Human-readable metadata.
goals/<GOAL_ID>/PROMPT.md	The master-goal prompt received by the planner/builder role.

A Program Goal adds PHASE_EXECUTION_CROSSWALK.yaml, PROGRAM_ROADMAP.yaml, IMPLEMENTATION_GOAL_MATRIX.yaml, and HUMAN_GATE_POLICY.yaml.

Goal types

goal_type	Meaning	Example
PROGRAM	A long-running program goal that orchestrates IMPs.	ASF50_PROGRAM_COMPLETION_001
IMPLEMENTATION_PHASE	A normal executable IMP goal.	ASF50_IMP_11_IMPLEMENTATION_001
INDEPENDENT_CODE_AUDIT	A separate auditor goal (fresh context).	ASF50_IMP_03_INDEPENDENT_CODE_AUDIT_001
INDEPENDENT_REAUDIT	An auditor re-run of a prior audit.	ASF50_GOAL_RUNNER_POWERSHELL_ENTRYPOINT_INDEPENDENT_REAUDIT_R3_001
REPAIR_GOAL	A bounded repair goal.	ASF50_DERIVED_STATE_RECONCILIATION_REPAIR_001
DOCUMENTATION_PORTAL	A docs-only bounded goal (used by this site).	ASF50_DOCS_PORTAL_001

Program vs IMP

ASF50 keeps two distinct layers and never collapses them:

• Program layer (PHASE-00..PHASE-20) — the product/roadmap coverage layer. Each PHASE-XX represents a program-roadmap concept that may span multiple execution phases.
• Execution layer (IMP-00..IMP-11) — the executable implementation-phase layer. Each IMP-XX is a single bounded goal that the Program Controller can dispatch.

The Program Controller reads goals/ASF50_PROGRAM_COMPLETION_001/PHASE_EXECUTION_CROSSWALK.yaml to map roadmap PHASE-XX concepts to executable IMP-XX goals. The two layers must never be merged: collapsing them destroys the crosswalk and breaks the controller.

See Phases for the full state model.

Required contract fields

Every normal goal contract must satisfy goal_registry.REQUIRED_FIELDS:

goal_id, parent_goal_id, goal_type, current_state, required_role,
audit_target, worktree_policy, clean_checkout_policy, allowed_paths,
forbidden_paths, acceptance_gates, evidence_requirements, model_class,
preferred_model, fallback_model, owner_gates, next_action_policy,
required_terminal_states, context, prompt, tasks

Program Goals have their own program_contracts.PROGRAM_REQUIRED_FIELDS set, validated by ProgramContractValidator.

Tasks

A goal's tasks is a non-empty list. Each task declares:

- task_id: <unique>
  role: PLANNER | BUILDER | TEST_ENGINEER | INDEPENDENT_AUDIT_HIGH | …
  state: PENDING
  description: >
    <what this task does>
  allowed_paths:
    - <globs the role may touch>
  forbidden_paths:
    - <globs the role must not touch>

The orchestrator advances tasks in declared order. A task may declare its own allowed_paths/forbidden_paths independent of the goal's defaults.

Runs

A run is a single dispatched attempt to complete a task. Runs are recorded in runtime_store.runs. A run has a run_id, a role, an adapter, a model_class, a subject_sha (the HEAD at dispatch time), and a status (PASS, FAIL, TIMEOUT, BLOCKED, …).

Materialization

When the orchestrator runs, GoalRegistry.materialize(goal_id):

1. Reads the contract from goals/<goal_id>/GOAL_RECORD.yaml.
2. Validates the contract against REQUIRED_FIELDS.
3. Resolves provenance (the dispatch root, the audit root, the audit subject SHA).
4. Inserts/updates the goals row in the runtime DB.
5. Inserts each declared task as a tasks row.
6. Writes a next_actions record describing the next dispatch.

Materialization is idempotent; running the orchestrator twice does not duplicate state.

Terminal states

A goal is terminal when its state matches one of required_terminal_states. The canonical terminal states are PASS and FROZEN_PASS. The Program Goal's terminal state is PROGRAM_PRODUCTION_CERTIFIED.

Once a goal is terminal, the orchestrator refuses to re-dispatch it. To revise a terminal goal, you must open a bounded repair goal.