goals

# /goals — Fitness Goal Maintenance

> Maintain GOALS.yaml and GOALS.md fitness specifications. Use `ao goals` CLI for all operations.

**YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.**

## Quick Start

```bash
/goals                    # Measure fitness (default)
/goals init               # Bootstrap GOALS.md interactively
/goals steer              # Manage directives
/goals add                # Add a new goal
/goals drift              # Compare snapshots for regressions
/goals history            # Show measurement history
/goals export             # Export snapshot as JSON for CI
/goals meta               # Run meta-goals only
/goals validate           # Validate structure
/goals prune              # Remove stale gates
/goals migrate            # Migrate YAML to Markdown
/goals trace              # Render/audit the executable-spec chain
/goals render             # Export directive scenarios as Gherkin
```

## Format Support

| Format | File | Version | Features |
|--------|------|---------|----------|
| YAML | GOALS.yaml | 1-3 | Goals with checks, weights, pillars |
| Markdown | GOALS.md | 4 | Goals + mission + north/anti stars + directives |

When both files exist, GOALS.md takes precedence.

## Mode Selection

Parse the user's input:

| Input | Mode | CLI Command |
|-------|------|-------------|
| `/goals`, `/goals measure`, "goal status" | **measure** | `ao goals measure` |
| `/goals init`, "bootstrap goals" | **init** | `ao goals init` |
| `/goals steer`, "manage directives" | **steer** | `ao goals steer` |
| `/goals add`, "add goal" | **add** | `ao goals add` |
| `/goals drift`, "goal drift" | **drift** | `ao goals drift` |
| `/goals history`, "goal history" | **history** | `ao goals history` |
| `/goals export`, "export goals" | **export** | `ao goals export` |
| `/goals meta`, "meta goals" | **meta** | `ao goals meta` |
| `/goals validate`, "validate goals" | **validate** | `ao goals validate` |
| `/goals prune`, "prune goals", "clean goals" | **prune** | `ao goals prune` |
| `/goals migrate`, "migrate goals" | **migrate** | `ao goals migrate` |
| `/goals scenarios`, "directive scenarios", "link a scenario" | **scenarios** | `ao goals scenarios` |
| `/goals trace`, "trace lineage", "orphan audit" | **trace** | `ao goals trace` |
| `/goals render`, "export gherkin", "feature file" | **render** | `ao goals render` |

`ao goals scenarios` links each directive to behavioral scenarios (the
`ao scenario` family) so GOALS.md is an executable BDD spec: bare lists every
directive's linked scenarios with link health; `--create "<goal>" --directive N`
scaffolds and bidirectionally links a scenario; `--lint` checks the link graph.
See `docs/adr/ADR-0003`.

`ao goals trace` and `ao goals render` render and audit the executable-spec
chain; `ao goals steer recommend`/`apply` drive the auto re-steer loop. Their
contracts are documented in `references/executable-spec-chain.md`.

## Measure Mode (default) — Observe

### Step 1: Run Measurement

```bash
ao goals measure --json
```

Parse the JSON output. Extract per-goal pass/fail, overall fitness score.

### Step 2: Directive Gap Assessment (GOALS.md only)

If the goals file is GOALS.md format:

```bash
ao goals measure --directives
```

For each directive, assess whether recent work has addressed it:
- Check git log for commits mentioning the directive title
- Check beads/issues related to the directive topic
- Rate each directive: addressed / partially-addressed / gap

### Step 2b: Scenario Satisfaction (executable-spec fitness)

`ao goals measure` also gates on **scenario satisfaction** — the fraction of a
directive's linked behavioral scenarios that currently pass. Each directive in
the `--json` / `--directives` output carries a `scenario_satisfaction` block:

```jsonc
"scenario_satisfaction": {
  "linked": 4,            // scenarios linked to this directive
  "satisfied": 3,         // scenarios whose latest result is PASS
  "ratio": 0.75,          // satisfied / linked
  "threshold": 0.8,       // directive's required ratio
  "status": "RED"         // GREEN | YELLOW | RED — RED when ratio < threshold
}
```

A directive below its threshold is `RED` and drags overall fitness down.

Use `--scenarios-only` to evaluate just the executable-spec layer and skip the
shell gate-command execution — fast feedback while iterating on scenarios:

```bash
ao goals measure --scenarios-only -o json
```

Scenario results are read from the scenario result artifacts (see
`ao scenario` family); the exact aggregation path and exit-code semantics are
in `references/executable-spec-chain.md`.

### Step 3: Report

Present fitness dashboard:
```
Fitness: 5/7 passing (71%)

Gates:
  [PASS] build-passing (weight 8)
  [FAIL] test-passing (weight 7)
    └─ 3 test failures in pool_test.go

Directives:
  1. Expand Test Coverage — gap (no recent test additions)
  2. Reduce Complexity — partially-addressed (2 refactors this week)
```

## Init Mode

```bash
ao goals init
```

Or with defaults:
```bash
ao goals init --non-interactive
```

Creates a new GOALS.md with mission, north/anti stars, first directive, and auto-detected gates. Error if file already exists.

### Post-Init Enrichment

After `ao goals init` creates the scaffold, enrich it with product-aware content that the CLI cannot auto-detect:

#### Enrich North Stars with Outcomes

Review the generated north stars. If they are all feature-focused (e.g., "skills work across 4 runtimes"), nudge toward outcome-focused stars:

- **Feature-focused (weaker):** "Skills work across 4 runtimes"
- **Outcome-focused (stronger):** "A new user goes from install to first validated workflow in under 5 minutes"

Ask the user: "Your north stars describe features. What user outcome would tell you the product is actually working?" Add at least one outcome-focused star.

#### Enrich Anti-Stars from Failure Modes

Scan for proven failure patterns:
1. Check `.agents/retro/` — extract failure themes from retrospectives
2. Check