hashintel/milestone

Horizon Milestone

Create or maintain a milestone — a bounded phase map that defines which invariant bundle to establish through multiple pragma cycles. A milestone is a learning/control point, not a delivery batch.

See The Invariant Threshold for the governing principle. A milestone answers: which invariants are we establishing in this phase, and what acceleration does crossing this threshold unlock? The milestone identifies invariant bundles for this phase; capsule documents remain the authority for invariant wording.

Input

Mode + context: $ARGUMENTS

Modes:

• create — define a new milestone from roadmap direction
• update — revise after slices land, assumptions change, or phase status shifts
• review — assess milestone health and readiness to advance or complete

When to Use

• A roadmap direction needs decomposing into a bounded multi-slice campaign
• Multiple pragma cycles need coordination toward a phase-level outcome
• Migration state, legacy surfaces, or cutover readiness need tracking
• You need to determine whether the project is ready for pragma acceleration

When Not to Use

• You need to define one thin slice → /pragma:card
• You need shared vocabulary and invariants → /pragma:capsule
• Direction itself is unclear → /pragma:roadmap

Milestone Location

Default: docs/milestone.md for the active milestone. Completed milestones move to docs/milestones/[name].md. Only one milestone should be active at a time.

Milestone Sections

1. Outcome

One observable phase-level result. What is true when this milestone is complete that is not true now?

2. Why Now

Which roadmap item(s) this advances. Link to docs/roadmap.md decisions, constraints, or strategic intent.

3. Invariant Bundle to Establish

The invariant bundles this milestone must establish. This is the core section — it defines what the phase is for without duplicating capsule law text.

Format:

Invariant bundles:
- IB-01: [bundle name]
  Capsule refs: [docs/capsule.md#... | docs/capsule-<feature>.md#... | not yet formalized]
  Threshold evidence: [how we'll know this bundle now holds]
- IB-02: [bundle name]
  Capsule refs: [...]
  Threshold evidence: [...]

Acceleration unlocked:
- [what becomes safe to delegate/accelerate once these hold]

Rules:

• Bundle entries are labels + references, not copied law text. Durable wording lives in capsule artifacts.
• Stable term and invariant wording must be authored in a capsule, not here.
• not yet formalized is allowed only while creating a pre-capsule milestone. During update or review, any active bundle still marked this way must route to /pragma:capsule update before recommending /pragma:card or /pragma:slice.

4. Ready for Pragma? (Gate)

A two-part checklist that separates semantic readiness from execution readiness. Assess honestly.

Ready to formalize/update capsule?
- [ ] Key nouns are stable enough for a capsule
- [ ] 3–7 invariants can be stated clearly
- [ ] One happy path is concrete and specific

Ready to accelerate slices in this phase?
- [ ] Relevant capsule is linked for every active invariant bundle
- [ ] High-risk unknowns are isolated to spikes or assumptions
- [ ] The next slice can be verified cheaply

If most boxes are unchecked, the right action is not more implementation planning — it is more narrowing, spiking, or reframing.

5. In Scope

Phase-level outcomes. Not individual cards — those emerge during pragma execution. These are the boundaries of what this phase covers.

6. Deferred Beyond This Phase

Work intentionally sequenced after this milestone. This is a temporary sequencing boundary, not a permanent project exclusion.

7. Authoritative Capsules

Capsule documents this milestone depends on.

Format:

- Project capsule: docs/capsule.md
- Feature capsule(s): docs/capsule-<feature>.md

If no capsule exists for an active bundle, mark it and route to /pragma:capsule before carding.

8. Entry Assumptions

Link to specific assumption IDs from docs/assumptions.md that this milestone depends on. If any are invalidated, the milestone must be reviewed.

Format:

- A-001: [statement] (confidence: NN%)
- A-003: [statement] (confidence: NN%)

9. Exit Criteria

Falsifiable, observable criteria for phase completion. These are phase-level, not slice-level — they describe the state of the system, not individual behaviors.

Format:

- [ ] [observable criterion]
- [ ] [observable criterion]

10. Candidate Sequence

Candidate spikes, cards, and supporting actions. This is a suggested ordering, not a locked delivery plan. Resequence when evidence changes.

Format:

1. [spike | card | characterize | contract | harden]: [description]
2. [spike | card | characterize | contract | harden]: [description]
3. ...

Rules:

• Maximum 6 candidates. If more are needed, the milestone is too broad.
• Candidates are reordered after spikes/slices when evidence changes.
• No candidate directly authorizes coding — each must become a card first.

11. Phase Status

Current state of each major work area within the milestone. Use completion markers and brief status notes.

Format:

- [area]: COMPLETE | IN PROGRESS | NOT STARTED — [brief status]

12. Phase Stability Boundaries

Stability boundaries — components, schemas, interfaces, or behaviors that this milestone explicitly preserves. This prevents collateral damage and makes the change surface visible.

13. Phase Risks

Risks specific to this phase, with mitigation strategies.

Format:

- [risk] (source: A-### | D-### | R-### | local) → [mitigation: spike | assumption tracking | fallback plan]

14. Open Design Questions

Unresolved questions that may affect sequencing or scope. Each should have a path to resolution (spike, prototype, stakeholder input).

Format:

- [capsule-gap | roadmap-decision | assumption | spike]: [question]
  Resolution path: [/pragma:capsule update | /pragma:roadmap update | /pragma:assumptions update | /pragma:spike]

15. Active Legacy Surfaces (optional — migration milestones)

For migration milestones, track what legacy components are still live and what coexistence constraints exist.

Format:

- [legacy component]: [status: active | deprecated | removed]
  Coexistence constraint: [what must remain true while both exist]
  Cutover readiness: [criteria for retirement]

16. Review Triggers

When this milestone should be re-examined, even if no explicit review is scheduled.

Default triggers (always include):

• An entry assumption is invalidated
• 2–3 slices complete without reviewing phase progress
• An exit criterion becomes unreachable
• A major external constraint changes

Validation

After writing or updating, check:

1. Does the outcome describe observable system state, not internal components?
2. Does every active invariant bundle link to capsule refs or explicitly note not yet formalized?
3. Is the "Ready for Pragma?" gate assessed honestly for both capsule and execution readiness?
4. Do exit criteria differ from individual card definitions of done?
5. Are candidate sequences bounded (≤ 6 items)?
6. Does "Phase Stability Boundaries" identify real stability boundaries?
7. Is "Deferred Beyond This Phase" clearly temporary (not a permanent non-goal)?
8. Are open design questions tagged with their owning authority lane?
9. During update/review, are all active bundles capsule-formalized (no lingering not yet formalized)?

Constraints

• One active milestone at a time. If two milestones compete, one must be scoped down or sequenced after the other.
• Milestones hold candidates, not binding tasks. The candidate sequence is advisory. Cards are created through /pragma:card during execution.
• No direct milestone → slice jump. Candidates must become cards first. Cards feed slices.
• Capsule remains the only authority for vocabulary and formal invariants. The milestone identifies invariant bundles and links capsule refs; it does not author durable law wording.
• Deferred is temporary; non-goals are permanent. Durable exclusions belong in capsule non-goals, not in milestone deferments.
• Exit criteria are phase-level. Individual slice definitions of done live in their cards.
• Resequence freely. When a spike or slice produces new evidence, update the candidate sequence immediately.
• Milestone is control-plane, not authority sink. If semantics, strategy, assumptions confidence, or enforcement readiness changed, propagate those deltas to their authority artifact before resuming card/slice flow.

Procedure

Mode: create

1. Confirm a roadmap exists and this milestone advances a roadmap item. If no roadmap → /pragma:roadmap first.
2. Interview if context is incomplete:
   • What phase-level outcome are we targeting?
   • What must become trustworthy by the end of this phase?
   • What is currently uncertain?
   • What must not change?
3. Write all required sections. Mark optional sections as N/A if not relevant.
4. Assess the two-part "Ready for Pragma?" gate.
5. If capsule readiness fails → recommend /pragma:capsule.
6. If capsule readiness passes but execution readiness fails → recommend /pragma:spike, /pragma:shaping-*, or further narrowing.
7. If both pass and next behavior is clear → recommend /pragma:card.
8. If both pass but behavior is still unclear → recommend /pragma:spike.
9. If direction itself is unstable or scope is too broad → recommend /pragma:roadmap (and optionally /pragma:shaping-* before re-entering).

Mode: update

1. Identify what changed: slice completed, assumption invalidated, new evidence, status shift.
2. Classify authority deltas from new evidence:
   • Semantics changed → /pragma:capsule update
   • Strategy changed → /pragma:roadmap update
   • Phase control changed → continue milestone update
   • Confidence changed → /pragma:assumptions update
   • Enforcement readiness changed → /pragma:contract
3. Update affected phase-control sections (especially phase status, candidate sequence, entry assumptions links).
4. Re-assess both gate halves if either was previously failing.
5. Check review triggers.
6. If exit criteria are met → recommend milestone completion and roadmap update.

Mode: review

1. Check entry assumptions against docs/assumptions.md — any invalidated?
2. Check exit criteria progress.
3. Check candidate sequence — does ordering still make sense?
4. Check "Phase Stability Boundaries" — any stability violations?
5. Check open design questions — any now answerable and where should they land?
6. Classify authority deltas (semantics/strategy/phase-control/confidence/enforcement).
7. Recommend: authority update first when needed, then next card/spike, milestone revision, or milestone completion.

Output

1. The milestone document (created or updated)
2. "Ready for Pragma?" gate assessment (capsule + execution)
3. Top risks or blockers
4. Authority Delta block (all lanes explicit; none required when no change)
5. Recommended next action

Lifecycle

• State: planning
• Next: /pragma:capsule (if gate passes and capsule needed), /pragma:card (if capsule exists and next behavior is clear), /pragma:spike (if gate fails due to uncertainty), /pragma:roadmap update (if milestone completes), or first non-none authority delta command
• Loop: /pragma:consult