From 4e38b0e0d0f26fcf4756dbf47680a30924509a65 Mon Sep 17 00:00:00 2001
From: Brummel <mould@mycelium.de>
Date: Sun, 31 May 2026 12:17:04 +0200
Subject: [PATCH] docs(pipeline): single-source the milestone-close gate

Define the cycle/milestone distinction and the complete-and-functional
close gate once in pipeline.md; rename audit's cycle-close edge to
drift-clean so it no longer reads as a milestone close.
---
 docs/pipeline.md | 53 ++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 51 insertions(+), 2 deletions(-)

diff --git a/docs/pipeline.md b/docs/pipeline.md
index dcba43a..999da7b 100644
--- a/docs/pipeline.md
+++ b/docs/pipeline.md
@@ -7,12 +7,12 @@
  brainstorm  ->  plan  ->  implement                  debug -> implement (mini)
        (per iteration loop)
                   |
-       [cycle close]
+       [cycle close — a loop step, not a milestone close]
                   |
                   v
                 audit  --(drift)--> plan + implement (tidy iteration)
                        --(ratify)-> --update-baseline + ratify paragraph in audit commit body
-                       --(clean)-+
+                       --(drift-clean)-+
                                  |
                        [orchestrator: cycle complete? if surface-touch:]
                                  v
@@ -29,6 +29,55 @@
                                              next cycle
 ```
 
+## Cycle vs. milestone
+
+These are two distinct axes, and conflating them is a bug.
+
+- A **cycle** is one round in the pipeline graph above
+  (`brainstorm → planner → implement → audit → [fieldtest]`).
+  A cycle close is an internal loop step.
+- A **milestone** is a tracker container (Gitea milestone,
+  GitHub milestone, Linear project — whatever the project's
+  tracker calls a long-running work scope). A milestone spans
+  potentially many cycles and closes only when the work it
+  promised is **complete and functional** (see the gate below).
+
+`audit` runs at cycle close and 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
+what `fieldtest` measures. So no `audit` result closes a
+milestone, and neither does a `/boss` done-state.
+
+## Milestone-close gate
+
+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 left.
+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 resolved or
+   ratified into the design ledger.
+
+The milestone fieldtest is the milestone-wide variant of the
+`fieldtest` skill: the same fieldtester agent, a carrier scoped
+to the milestone's promise rather than one cycle's surface. Its
+scenarios are chosen top-down from what the milestone as a whole
+promised, not assembled as the union of per-cycle axes.
+
+A milestone whose entire scope is internal (no user-visible
+surface) is exempt from the functional leg — the milestone
+fieldtest is *not applicable* and the complete leg suffices.
+
+This gate defines *when* a milestone is closeable. The actual
+close stays a deliberate human / orchestrator act (`tea
+milestone close`, or the tracker equivalent); no skill performs
+it automatically.
+
 ## Phase descriptions
 
 ### brainstorm