chore: release v0.1.0

.agents/skills/delivery-decompose/SKILL.md

@@ -5,9 +5,10 @@ description: >-
   Part of Delivery Kit, invoked by delivery-orchestrator. Break approved requirements
   and their design spine into task files that parallel lanes can execute independently,
   with dependencies, file conflicts and tiers made explicit, then validate the set
-  deterministically. Use when work has been approved and needs splitting into tasks, or
-  when an existing task set needs checking before lanes start. Does not implement tasks or
-  decide requirements.
+  deterministically; for a large project, one milestone at a time, with a review note
+  closing each. Use when work has been approved and needs splitting into tasks, when an
+  existing task set needs checking before lanes start, or when a merged milestone needs
+  its review. Does not implement tasks or decide requirements.
 license: Apache-2.0
 repository: https://github.com/ancelin-code/delivery-kit.git
 product-version: delivery-kit@v0
@@ -18,6 +19,7 @@ keywords:
   - epics
   - dependencies
   - parallel-work
+  - milestones
 spec-version: "1.0"
 compatibility:
 metadata:
@@ -50,28 +52,39 @@ it directly. Splitting a one-task change into an epic costs more than it saves.
    the codebase too to know what already exists, including the project's other
    repositories when they are cloned beside this one. Decomposing from the
    requirements alone invents work that is already done.
-2. **Group work into epics**, as the delivery conventions,
+   On a project with milestones, also read the review notes in
+   `delivery/milestones/`: the last one says what to carry into this cut.
+2. **Decide whether to cut in milestones**, as the delivery conventions,
+   `<delivery-orchestrator>/references/conventions.md`, define them, when the
+   plan has none yet. Cut in milestones when the scope is too large or too
+   uncertain to cut at once, or when the riskiest parts should run end to end
+   before the rest is built. Order them so each is a working slice and the
+   riskiest come first, and write the plan into the summary's Milestones
+   section: every milestone, its exit criterion and the requirements it
+   targets. Then cut **only the current milestone**; the validator rejects
+   tasks of a later one. Without milestones, cut the whole approved scope.
+3. **Group work into epics**, as the delivery conventions,
    `<delivery-orchestrator>/references/conventions.md`, define them. A group
    that is more than one person can hold in their head, or that delivers two
    separate outcomes, is two epics, not one large one.
-3. **Write one task file per unit of work**, from
+4. **Write one task file per unit of work**, from
    [the template](assets/task.template.md), into `delivery/tasks/<id>.md`.
-4. **Derive the dependency edges.** A task depends on another only when it
+5. **Derive the dependency edges.** A task depends on another only when it
    genuinely cannot start without the other's merged output. Dependencies
    invented "to be safe" serialize work that could have run in parallel.
-5. **Derive the file conflicts.** List the files each task will touch, then
+6. **Derive the file conflicts.** List the files each task will touch, then
    record `conflicts_with` for any pair whose file sets intersect. Two tasks
    editing the same file are not parallel, however independent they look. Set
    `parallel: false` on a task whose shared ground is too wide to list, such as
    a lockfile, a migration or a repository-wide rename: it then runs alone.
-6. **Write the decomposition summary** to `delivery/decomposition.md`, from
+7. **Write the decomposition summary** to `delivery/decomposition.md`, from
    [the template](assets/decomposition.template.md). It states what each epic
    delivers, where the set serializes and why, and the critical path. When it
    serializes almost everywhere, say **Run as:** serially and mark every task
    `parallel: false`; the validator holds the two in step. The task files carry
    the work; this carries the reasoning behind the cut, which no later session
    can recover from them.
-7. **Validate the set** before anyone starts:
+8. **Validate the set** before anyone starts:
 
    ```sh
    sh <skill-root>/scripts/validate-tasks.sh
@@ -82,7 +95,31 @@ it directly. Splitting a one-task change into an epic costs more than it saves.
    1 is a usage error. Fix every reported failure. A set that fails validation
    stalls lanes hours later, when it is expensive to correct. It cross-checks the summary against the task
    files in both directions, so re-cutting tasks without revisiting the summary
-   fails here rather than at the approval gate.
+   fails here rather than at the approval gate. With milestones, it also checks
+   that every requirement the current milestone targets is covered by one of
+   its tasks.
+
+Cutting the next milestone revises an approved summary: set its status back to
+draft, add the new epics, and fill in the milestone's `**Epics:**` line. The
+human approves the new cut as they approved the first.
+
+## Closing a milestone
+
+When `where.sh` reports a milestone merged, draft its review note with the
+human, at `delivery/milestones/<slug>.md`, from
+[the template](assets/milestone-review.template.md). Start from the derived
+coverage:
+
+```sh
+sh <delivery-status>/scripts/coverage.sh --milestone <slug>
+```
+
+The human checks the exit criterion against the running system; record what
+they observed, not what the tasks claimed. Then write down what was learned,
+the decision, and what the next cut must carry over: above all, what remains
+of each requirement left partly covered. The human approves the note, which
+closes the milestone. Revising the requirements or a decision record is
+`delivery-spec`'s job; name what to revise and stop.
 
 ## Writing a task
 
@@ -115,6 +152,12 @@ as the conventions' section on several repositories describes. One task changes
 one repository; a change that needs two is two tasks with a dependency, usually
 through a contract.
 
+Fill `## Covers` when the requirements carry ids: every requirement the task
+delivers, with `(part)` and a note when it delivers only some of it. The note
+says what this task does and what it leaves, so a reader can tell what is left
+of the requirement without opening the code. A task that delivers no
+requirement, such as tooling, has no section.
+
 Set `review` to the lenses the task's change will need beyond the general
 review, taken from `delivery/review-lenses.conf` when the project has one: a
 task handling credentials needs `security`, one changing a table schema needs
@@ -139,3 +182,7 @@ rediscovered at run time by the lanes.
 - each task states observable acceptance criteria and its files in scope
 - `delivery/decomposition.md` exists, names what every epic delivers, and lists the same
   tasks under the same epics as the task files do
+- with milestones, only the current milestone has tasks, and they cover every
+  requirement it targets
+- a closed milestone has an approved review note recording its exit evidence,
+  what was learned and the decision

.agents/skills/delivery-decompose/assets/decomposition.template.md

@@ -11,6 +11,21 @@ reader who saw none of the decomposition must be able to follow it back.
 - <link to the approved requirements, `delivery/prd.md`>
 - <links to the decision records and `delivery/contracts/` files the cut uses>
 
+## Milestones
+
+Optional: delete this section to cut the whole scope at once. Keep it when the
+project is delivered in end-to-end slices, with a review after each. List every
+milestone in delivery order. Only the current one has epics; a later one names
+its exit and targets, and is cut after the review of the one before.
+
+### <milestone-slug>
+
+<Why this slice comes here: the risk it retires, or what it unlocks.>
+
+**Exit:** <the observable outcome that shows the slice works end to end>
+**Requirements:** <requirement ids it targets, `(part)` after one it delivers only in part>
+**Epics:** <the epics cut for it, comma-separated; empty until it is cut>
+
 ## Epics
 
 One section per epic. State what the slice
@@ -28,7 +43,8 @@ the tasks belong to another epic.>
 
 ## Parallelism
 
-Where the set serializes, and what forces it. A set that serializes almost
+Where the set serializes, and what forces it. With milestones, this section and
+the critical path describe the current milestone's cut. A set that serializes almost
 everywhere is a finding: say serially, and mark every task `parallel: false`.
 
 **Run as:** lanes | serially

.agents/skills/delivery-decompose/assets/milestone-review.template.md

@@ -0,0 +1,37 @@
+# Milestone review: <milestone-slug>
+
+**Status:** draft | approved
+**Approved by:** <name, date>
+
+## Exit criterion
+
+<The exit line from `delivery/decomposition.md`, then whether it held and the
+evidence: what was run, against which deployment, and what was observed. A
+criterion nobody exercised did not hold.>
+
+## Coverage
+
+<The output of `coverage.sh --milestone <milestone-slug>`, and for each
+requirement it reports as partly covered or not started: why, and where the
+rest goes.>
+
+## What we learned
+
+<What building this slice taught that the requirements, the decision records
+or the plan did not know: a wrong assumption, a cost, a risk retired or found.
+Only what changes something later; leave out what went to plan.>
+
+## Decision
+
+**Decision:** continue | revise
+
+<Continue: the next milestone is cut as planned, and anything below adjusts
+it. Revise: name each artifact to change (`delivery/prd.md`, a decision
+record, the milestone plan) and what changes. Each is revised and approved
+through its own gate before the next milestone is cut.>
+
+## Carried over
+
+<What the next cut must take into account: requirements left in part, work
+deferred from this milestone, follow-ups found in review. Empty when nothing
+is.>

.agents/skills/delivery-decompose/assets/task.template.md

@@ -15,6 +15,14 @@ review: []
 <Two or three sentences: what exists now, and why this change is needed. Link
 the requirements document, `../prd.md`, rather than restating it.>
 
+## Covers
+
+<The requirement ids this task delivers, one per line, when the requirements
+carry ids. Delete the section otherwise.>
+
+- <id>
+- <id> (part): <what this task does of it, and what it leaves>
+
 ## Scope
 
 Files this task is expected to touch: