ultragoal

# Ultragoal — the closed loop for goals too big to ship in one run

An **ultragoal** is the term for a north-star that spans many sessions: fork the repos, combine the strong parts, ship one product. A `/closed-loop` run is one task through the loop. An ultragoal is a *chain of phases*, each of which is its own full closed-loop run, tracked so any cold session can resume.

**Core rule (from dwarves-kit, adopted fully): the worker never grades its own homework, and wrongness compounds across sessions — so verify every phase, not just the end.**

## When to use

- `/ultragoal <name>` — resume or advance an existing ultragoal
- `/ultragoal new "<north-star>"` — charter a new one
- `/ultragoal status` — report all ultragoals from the registry
- Trigger phrases: "make this an ultragoal", "this is a long-running goal", "combine these into one product over time"

Do **not** use for single-run work (that is `/closed-loop`), and do not start one on a request that never asked for one. Rule of thumb: if it needs a phase decomposition and won't finish today, it is an ultragoal.

## Files (one goal = one folder)

| File | Role |
|---|---|
| `04-projects/harness/ultragoals.md` | Registry: every ultragoal, status, current phase |
| `04-projects/<goal>/spec.md` | Contract: north-star + `AC-n` acceptance criteria + phases `P0…Pn` + traceability matrix |
| `04-projects/<goal>/STATUS.md` | Living ledger: phase state, current phase, open `AC-n`, next action (resume from here) |
| `04-projects/<goal>/evidence/P<n>/` | Per-phase evidence bundle (ledger.md + CP-* files) |

Code, if any, lives outside the vault (e.g. `~/code/<goal>/`) — the spec/status/evidence stay in the vault.

## Phase 0 — Charter (`/ultragoal new`)

1. Interview the user for the **north-star** in one sentence (what "done" looks like).
2. Write `04-projects/<goal>/spec.md` from `../closed-loop/references/spec-template.md`:
   - North-star statement
   - Falsifiable `AC-n` acceptance criteria (these define done for the *whole* goal)
   - Phase decomposition `P0…Pn` — each phase is a shippable increment mapped to a subset of `AC-n`
   - Traceability matrix (`AC-n` ↔ phase ↔ status)
3. Create `STATUS.md` (see template below) and add a row to the registry.

Record: `bash .claude/lib/checkpoint.sh record 04-projects/<goal>/evidence/P0 CP-1 PASS "N criteria, M phases"`

## The phase loop (every phase, no lane downgrade)

Each phase runs the **full** closed loop. Do not shortcut with `tiny`. Ultragoals are `full` lane by construction.

```
select next phase from STATUS.md
        │
        ▼
CP-2 PLAN     tasks for this phase ↔ AC-n   → evidence/P<n>/CP-2-plan.md
        │
        ▼
CP-3 BUILD    worker implements (traced to AC-n); returns paths only
        │
        ▼
CP-3v VERIFY  task-verifier (fresh context, read-only) → evidence rows per AC-n
        │       ├── FAIL:fixable → fix-agent (max 2) → re-verify
        │       └── FAIL:escalate → stop, escalate to the user
        ▼
CP-4 INTEGRATE  integration-verifier → does this phase wire correctly with prior phases?
        │        (always run for ultragoals — cross-phase regression is the main risk)
        ▼
CP-5 ACCEPT   observe the artifact (curl / screenshot / re-fetch), not the tool return
        │       EVIDENCE AC-n | CP-5 | PASS | <observation> | <artifact>
        ▼
CP-6 SHIP     external mutation? → Review Gate: you approve. Internal? → auto.
        │
        ▼
update STATUS.md (phase → done, advance current phase, log open AC-n)
        │
        ▼
CP-7 RETRO    /retro 04-projects/<goal>/evidence/P<n>  → harvest + STATUS
```

Merge every verifier's `EVIDENCE` rows into `evidence/P<n>/ledger.md`.

## The two acceptance gates

1. **Per-phase (CP-5):** every `AC-n` this phase claims has a PASS row before the phase is marked done.
2. **North-star (final):** before the ultragoal is declared complete, spawn a fresh-context verifier whose only job is to check the spec matrix — **every** `AC-n` across all phases has ≥1 PASS evidence row. Any `AC-n` without one is a gap, not a ship. This is the ultragoal-level analogue of CP-5.

```
North-star acceptance:
  read spec.md matrix (all AC-n)
  read every evidence/P*/ledger.md
  for each AC-n: assert ≥1 PASS row exists, artifact re-observed
  any miss → list open AC-n, STATUS stays "in progress", do NOT declare done
```

## The HTML report (regenerate at every phase gate + final)

Every ultragoal carries a single self-contained HTML report that **covers everything**: north-star, live status, all phases, the full `AC-n` traceability table with pass/open/fail, evidence rows per phase (with screenshots embedded as `data:` URIs), and the open-items / next-action block. It is the human-readable face of the evidence ledger.

- **Template:** `../closed-loop/references/report-template.html` (theme-aware, rows-not-cards). Copy it, then fill every `{{token}}` and `<!-- FILL -->` / `<!-- REPEAT -->` block from `spec.md` + `STATUS.md` + `evidence/P*/`. You fill it by editing; do not build a parser.
- **Deliverable path:** `04-projects/<goal>/report.html`. One file, overwritten each phase (it always reflects current truth).
- **When:** regenerate at each phase gate (CP-6) and again at final north-star acceptance. The final report must show every `AC-n` with a PASS row — if any pill is `open`, the goal is not done.
- **Self-contained only:** inline everything, embed screenshots as `data:` URIs, so it also works when published as an Artifact (external hosts are blocked). Before publishing as an Artifact, load the `artifact-design` skill.
- **Surface it:** `SendUserFile 04-projects/<goal>/report.html` (display: render) so the user can open it, or publish via `Artifact` for a shareable link.

## STATUS.md template

```markdown
# <Goal> — status ledger

North-star: <one sentence>
Spec: 04-projects/<goal>/spec.md · Registry: 04-projects/harness/ultragoals.md
Current phase: P<n> · Overall: <not-started|in-progress|blocked|done>

## Phases
| Phase | AC covered