Skills/docs/specs/2026-05-31-milestone-close-gate-design.md

# Milestone-close gate: separating `cycle` from `milestone`

**Date:** 2026-05-31
**Status:** approved (design)
**Topic:** make `audit` unable to imply a milestone is finished;
add a milestone-wide fieldtest as the closing gate.

## Problem

`audit` runs at cycle close and emits a "clean" signal whose
commit body reads `cycle <X> tidy (clean)`. `audit` only proves
*drift-clean* — the code matches the design ledger. It is blind
to whether the work is *functional* from a downstream
consumer's point of view; that is exactly what `fieldtest`
measures, and `fieldtest` runs *after* `audit`.

Two defects follow:

1. **Conflation of `cycle` and `milestone`.** `README.md`
   ("AILang calls a cycle a *milestone*") and
   `templates/project-profile.yml:41` (`cycle: # what a
   top-level work unit is called`) treat a cycle as the
   top-level work unit. It is not. A **milestone** is a tracker
   (Gitea) container that closes only when the work is
   *completely implemented and functional*. A **cycle** is one
   round in the pipeline graph — a step in the loop. A milestone
   spans potentially many cycles.

2. **An audit-clean signal can leak into a milestone close.**
   Because `audit`'s "clean" reads like "done", an orchestrator
   can be led to close a Gitea milestone on the strength of an
   audit, before any fieldtest has demonstrated the work is
   functional. No skill closes a milestone today, so this is a
   conceptual hazard rather than a code path — but the wording
   actively invites the mistake.

The fix is **not** to swap the `audit → fieldtest` order:
`fieldtest` needs the drift-clean state to test against, so
`audit` must stay first. The fix is to **decouple the gate** —
`audit`'s "clean" never closes anything, and a separate,
explicitly defined milestone-close gate requires both
completeness and functional validation.

## Conceptual model

### Two distinct axes

- **Cycle** — one round in the pipeline graph
  (`brainstorm → planner → implement → audit → [per-cycle
  fieldtest]`). A cycle close is an internal loop step. Many
  cycles per milestone.
- **Milestone** — a tracker (Gitea) container. Closes **only**
  when *complete* (every cycle drift-clean / ratified, no open
  iterations) **and** *functional* (milestone fieldtest green).

### Three disentangled "clean" terms

| Term | Owner | Means | Closes a milestone? |
|------|-------|-------|---------------------|
| `drift-clean` | `audit` | code matches the ledger | never |
| cycle functionally validated | per-cycle `fieldtest` | cycle-local surface usable | never |
| milestone closeable | milestone-close gate | complete ∧ functional | yes (manual act) |

### Two fieldtest scopes

The milestone fieldtest is a **scope variant** of the existing
`fieldtest` skill — same `fieldtester` agent, a different
carrier. No new skill; keeps the surface DRY.

- **Per-cycle fieldtest** (existing, unchanged): carrier carries
  `cycle_id` / `cycle_scope`; dispatched after a
  surface-touching cycle's audit; catches cycle-local friction
  early; optional / orchestrator-dispatched as today.
- **Milestone fieldtest** (new variant): carrier carries
  `milestone_id` and `milestone_promise` — the milestone's
  stated goal / acceptance in the tracker (and its spec, if one
  exists). The fieldtester derives a small set of **curated
  end-to-end scenarios** that, run as a downstream consumer,
  prove the shipped implementation delivers **what the milestone
  as a whole promised**. Scenarios are chosen *top-down from the
  milestone's promise*, not assembled bottom-up as the
  mechanical union of per-cycle axes — the per-cycle fieldtests
  already cover axis-local surface; the milestone fieldtest's
  job is to demonstrate the promise end to end. Its green status
  roll-up is the closing gate.

## The milestone-close gate (authoritative)

A milestone may be closed in the tracker only when **both** legs
hold:

1. **Complete** — every cycle filed under the milestone is
   `audit` drift-clean (or its drift explicitly ratified), and
   the milestone container has no open iterations / issues
   remaining.
2. **Functional** — the milestone fieldtest has run its curated
   end-to-end scenarios against the milestone's promise and its
   status roll-up is `clean`: every scenario demonstrably
   delivers what the milestone promised; no open `bug` findings;
   `friction` / `spec_gap` findings either resolved or
   explicitly ratified into the design ledger.

No `audit` result, and no `/boss` done-state, closes a milestone
on its own. `/boss` done-state means "this `/boss` run has
nothing left to dispatch" — it is **not** a milestone close.

The actual close (`tea milestone close`, or the tracker
equivalent) stays a **deliberate human / orchestrator act**,
performed only after the gate reads green. This design defines
*when* a milestone is closeable; it does **not** mechanise the
close. (`issue/SKILL.md` is out of scope here.)

### Edge cases

- **Non-surface milestone.** A milestone whose entire scope is
  internal (refactor, infra, docs) touches no user-visible
  surface. The milestone fieldtest is then *not applicable*
  (same skip logic as the per-cycle fieldtest, lifted to
  milestone level). The "functional" leg is satisfied vacuously;
  the "complete" leg (audit-clean across cycles) suffices.
- **Single-cycle milestone.** Nothing special: the milestone
  fieldtest still runs (if surface-touching), proving the
  milestone's promise end to end even though that promise
  happened to ship in a single cycle. The per-cycle and
  milestone fieldtests may coincide in surface but remain
  conceptually distinct gates — axis-local validation versus
  promise-level proof.
- **Ratified drift.** A cycle whose drift was ratified
  (`--update-baseline` + ratify paragraph) counts as satisfying
  the "complete" leg for that cycle — ratification is the
  documented form of "complete".

## Per-file changes

Single-source discipline (consistent with the recent
carrier/handoff single-sourcing): the gate is **defined once**
in `docs/pipeline.md`; every other file **references** it rather
than restating it, so the files cannot drift.

### `docs/pipeline.md` (single source)

- ASCII graph: rename `audit --(clean)` to `audit
  --(drift-clean)`; annotate `[cycle close]` explicitly as a
  loop step, not a milestone end.
- New subsection **"Cycle vs. milestone"** — defines the two
  axes authoritatively (a milestone spans many cycles; a cycle
  is one loop round).
- New subsection **"Milestone-close gate"** — the authoritative
  gate definition above (complete ∧ functional), names the
  milestone fieldtest as a mandatory precondition for
  surface-touching milestones, and states plainly that no
  `audit` and no `/boss` done-state closes a milestone.

### `audit/SKILL.md`

- Step 2 table: "Audit can close" → drift-gate wording. `audit`
  clears the *cycle drift check*; it does not close the cycle or
  the milestone.
- Close-commit wording (`cycle <X> tidy (clean)`): kept, but
  annotated explicitly as *drift-clean, not a milestone signal*.
- New **Red Flag**: "Declaring a milestone closeable on the
  strength of an audit-clean, while the milestone fieldtest has
  not run green." Cross-reference the gate in `docs/pipeline.md`.
- Overview: clarify `audit` ↔ cycle close (never milestone).

### `fieldtest/SKILL.md`

- Document the second trigger variant — the **milestone
  fieldtest** (milestone-wide, end-to-end): carrier carries
  `milestone_id` and `milestone_promise`; the fieldtester
  derives curated end-to-end scenarios from the milestone's
  promise (top-down, not a union of per-cycle axes) and proves
  the shipped implementation delivers it; its green status
  roll-up is the closing gate. Reference the gate in
  `docs/pipeline.md` rather than restating it.
- The "audit first" precondition stays, for both variants.
- The milestone-fieldtest skip logic mirrors the per-cycle one,
  lifted to milestone level (non-surface milestone → exempt).

### `boss/SKILL.md`

- Done-state: reference the `docs/pipeline.md` gate instead of
  restating the formula. Clarify that a `/boss` done-state is
  **not** an automatic milestone close — the milestone close
  needs the milestone fieldtest green and is a manual act.

### `README.md`

- **Root fix**: correct the `cycle ≡ milestone` conflation
  (the "AILang calls a cycle a *milestone*" lines). Cycle = a
  pipeline round; milestone = a tracker container spanning many
  cycles, closed only when complete ∧ functional.
- `fieldtest` row: per-cycle fieldtest stays optional; note the
  milestone fieldtest as the mandatory gate before a
  surface-touching milestone closes.

### `templates/project-profile.yml`

- Fix the `cycle:` comment ("top-level work unit" is wrong — a
  cycle is the pipeline round).
- Add a `milestone:` vocabulary field for the tracker container.
- Add the milestone-fieldtest phase to the pipeline config (so a
  project can name / gate it), consistent with the existing
  `pipeline:` configuration model.

### `docs/profile-schema.md`

- Same root conflation lives here: the `vocabulary` table
  (`cycle` = "top-level work unit", with `milestone` as an
  example value) and the minimal-profile example (`cycle:
  milestone`). Correct both — document `cycle` as the pipeline
  round and add the `milestone` vocabulary field as the tracker
  container.
- Document the milestone-fieldtest phase in the `pipeline`
  section alongside the existing `fieldtest` phase.

## Scope boundaries

**In scope:** the gate definition and the wording/decoupling
across `docs/pipeline.md`, `audit`, `fieldtest`, `boss`,
`README.md`, `templates/project-profile.yml`; the milestone
fieldtest as a carrier-scope variant of the existing skill.

**Out of scope:** mechanising the tracker close (no
`issue/SKILL.md` change, no automated `tea milestone close`);
reordering `audit → fieldtest`; any change to the per-cycle
fieldtest's existing behaviour beyond naming it "per-cycle".

## Verification

- Grep sweep: no remaining file equates `cycle` with
  `milestone`; the only authoritative gate definition lives in
  `docs/pipeline.md`, and `audit` / `fieldtest` / `boss`
  reference it without restating it.
- `audit/SKILL.md` carries the new Red Flag and drift-gate
  wording; its close-commit example is annotated as drift-clean.
- `fieldtest/SKILL.md` documents both carrier scopes and the
  milestone-level skip rule.
- `templates/project-profile.yml` parses (YAML) with the new
  `milestone:` vocabulary field and the milestone-fieldtest
  phase, and `docs/profile-schema.md` stays consistent with it.