@rasensio/aidlc-content 1.61.0 → 1.63.0

package/docs/lifecycle.md

@@ -147,7 +147,9 @@ instance changed the same requirement first, its revision no longer matches the
 completion is not recorded, and nothing is written. That is the whole conflict rule — a requirement is
 never silently overwritten. `aidlc spec fold <instance> --dry-run` runs the same check any time before.
 An instance with no delta completes exactly as before; nothing was back-filled, so the corpus starts
-empty and grows.
+empty and grows. A `## Spec delta` section that holds only prose — "None." and the reason — counts as
+no delta. One with nothing in it, or whose only block headings sit inside a code fence or at the wrong
+level, is still an error, because that is a delta someone meant to write.
 
 **Before code is written**, `aidlc cross-check <instance>` reads `requirements.md`, `design.md` and
 `tasks.md` side by side. `aidlc review` reads one artifact at a time, so a criterion design forgot, or a

package/docs/roadmap.md

@@ -143,21 +143,36 @@ Each item goes through these steps:
 
 1. **Pick.** `aidlc roadmap next` names the next ready backlog item.
 2. **Build.** `aidlc start … --worktree --roadmap-item <item>` creates the instance in its own
-   worktree, then the configured agent runs there with `AIDLC_UNATTENDED=1`. The agent follows the
-   unattended rule and stops at the release boundary, or parks the item on a hard stop. A start that
+   worktree, then the configured agent runs there with `AIDLC_UNATTENDED=1` and `AIDLC_PAUSE_AFTER`
+   set to the phases it must stop after. The agent follows the unattended rule and stops at a review
+   boundary or the release boundary, or parks the item on a hard stop. A start that
    fails parks the item with `parked — could not start: <error>` and autopilot goes straight on to
    the next ready item; the parked one does not count toward `--items`. Retrying the same item every
    pass is what held a whole `--all` run on one item for five hours.
-3. **PR and CI.** Autopilot pushes the branch and opens the pull request. Green checks queue it;
+3. **Your review, after each paused phase.** When a phase in `pause_after` is complete and
+   unapproved, the item waits as `awaiting-review` — not parked. Read the artifact in the item's
+   worktree, then `aidlc autopilot approve <instance>`; the next pass waits at the next paused
+   phase, opens the pull request, or relaunches the agent to carry on. Autopilot reads the phase
+   files, not the agent's word, so an agent that runs past a pause still cannot reach a pull request.
+   A waiting item holds no build slot, so the run keeps starting others, and it keeps the run alive
+   so there is something to carry it on after you approve.
+4. **PR and CI.** Autopilot pushes the branch and opens the pull request. Green checks queue it;
    a failure relaunches the agent once with the failing checks, and a second failure parks the item.
-4. **Up to date with main.** Before merging, autopilot merges `origin/main` into the branch in the
+5. **Your merge, where the stop is the pull request** (the default). Green CI leaves the item as
+   `awaiting-merge` and autopilot neither merges nor releases. When you merge, it closes the instance
+   out on main — pull, mark the deployment record complete, `aidlc transition`, commit, push — and
+   runs no release; if the instance is already closed there, it just stops tracking it. Close the
+   pull request without merging and it stops tracking it too. That pull request is yours while it
+   waits: autopilot does not bring it up to date with main or chase its CI.
+6. **Up to date with main**, for an item autopilot merges itself. Before merging, it merges
+   `origin/main` into the branch in the
    item's worktree — locally, so the repository's `merge=union` rules apply — pushes, and waits for
    CI on the new head. A conflict goes back to the item's agent to resolve, twice at most, then the
    item is parked. A pull request with no checks that GitHub reports as conflicting is handled the
    same way: GitHub runs no checks on a conflicting PR, so waiting for them would wait forever.
-5. **Merge and release**, one at a time, never while a release workflow is running: merge the exact
-   commit CI passed (`--match-head-commit`), pull `main`, run the release step, then
-   `aidlc transition` to close the instance. A failure halts the queue. Running
+7. **Merge and release**, one at a time, never while a release workflow is running: merge the exact
+   commit CI passed (`--match-head-commit`), pull `main`, run the release step when the item's stop
+   is `release`, then `aidlc transition` to close the instance. A failure halts the queue. Running
    `aidlc autopilot run` again retries a failure that came before the merge; from the pull onward
    nothing is retried — a half-finished release is for a person.
 
@@ -167,7 +182,7 @@ never edits a rank or a dependency: deciding what is agreed work stays a person'
 
 **Setup** comes first, once per machine. A plain `aidlc init` ends by asking "Set up autopilot now?"
 (default no); `aidlc init --autopilot` skips that question, and `aidlc autopilot setup` asks the same
-four questions on its own. Each is a list with one choice marked recommended:
+six questions on its own. Each is a list with one choice marked recommended:
 
 - **The agent, and what it may do.** Claude Code limited to editing files and running git, pnpm,
   node and read-only shell tools (recommended); Claude Code with full access; Codex in full-auto
@@ -176,38 +191,63 @@ four questions on its own. Each is a list with one choice marked recommended:
   `--non-interactive`.
 - **How many items build at once** — two (recommended) or one.
 - **A cost cap per item** — an item past it is stopped and parked.
+- **Which phases to pause after for your review** — after requirements and design (recommended),
+  after design only, or no pauses. These are the two phases whose output decides the shape of the
+  code.
+- **How far autopilot takes each item** — open the pull request and wait for you to merge it
+  (recommended); merge when CI passes with no release; or merge and run the release step below.
 - **The release step.** In a project with `scripts/autopilot-release.sh`, running it after each
   merge (recommended); otherwise merge only, and you release when you choose. This repository's
   script runs `release-bookkeeping --write`, commits the manifest and `.aidlc`, and runs
-  `scripts/release.sh` with the bump bookkeeping printed.
+  `scripts/release.sh` with the bump bookkeeping printed. It runs only for an item whose stop is
+  `release`.
 
-Flags skip the questions: `--agent`, `--parallel`, `--cost-cap <usd|none>`, `--release
-<repo-script|merge-only>`. `aidlc autopilot setup` writes all four answers to
+Flags skip the questions: `--agent`, `--parallel`, `--cost-cap <usd|none>`, `--pause-after
+<phases|none>`, `--stop-at <pr|merge|release>`, `--release <repo-script|merge-only>`. `aidlc
+autopilot setup` writes every answer to
 `<git-common-dir>/aidlc/autopilot/config.json`, per machine and never committed, beside autopilot's
 `state.json`, `run.json`, `logs/`, `STOP` file and, while paused, `paused.json`.
 
-**Team defaults.** The cost cap and the release step are the team's to decide, so `aidlc init` saves
-those two in the committed `.aidlc/config.yaml` and the agent and items-at-once on the machine:
+**One run at a time.** `aidlc autopilot run --stop-at <pr|merge|release>` and `--pause-after
+<phases|none>` change the stops for the items that run starts, without touching either saved file.
+Each item records the stops in force when it started and is held to them until it finishes, so a
+later run cannot make an item in flight wait on a phase that completed hours ago. Every run prints a
+`stops:` line saying what applies.
+
+**Team defaults.** The cost cap, the stops and the release step are the team's to decide, so
+`aidlc init` saves those in the committed `.aidlc/config.yaml` and the agent and items-at-once on the
+machine:
 
 ```yaml
 # .aidlc/config.yaml
 autopilot:
-  cost_cap_usd: 15        # or null for no cap
-  release: repo-script    # or merge-only — a preset name, never a command
+  cost_cap_usd: 15                     # or null for no cap
+  pause_after: [requirements, design]  # or [] for no pauses
+  stop_at: pr                          # or merge, or release
+  release: repo-script                 # or merge-only — a preset name, never a command
 ```
 
+**Upgrading changes nothing on its own.** A config with no `stop_at` and no `pause_after` behaves
+exactly as it did before stops existed: no pauses, merge and release. Every `aidlc autopilot run`
+prints that in so many words, and names `aidlc autopilot setup` as what changes it. The new defaults
+reach you when you next answer the questions, not behind your back.
+
 A teammate's autopilot follows them without being asked. The machine's own `config.json` wins
-wherever it sets the same key, and when init saves a team answer it removes this machine's copy so the
+wherever it sets the same key, and a run's flags win over both; when init saves a team answer it
+removes this machine's copy so the
 answer takes effect here too. The agent, its permissions and parallelism are read from the machine
 file only: the same keys in `.aidlc/config.yaml` are ignored, so cloning a repo can never grant an
 agent full access on your machine. A team value that is not valid — a cap that is not a positive number
-or `null`, a release step that is not one of the two names, `repo-script` with no script — is ignored.
+or `null`, a release step that is not one of the two names, `repo-script` with no script, a `stop_at`
+outside the three names, a `pause_after` that is not a list of phase names — is ignored.
 Re-running `aidlc init` pre-selects every answer in force, and an answer no choice matches is offered as
 "(current)" and left as it is. `--non-interactive --autopilot` asks nothing, keeps what is there and
 fills only what is missing with the recommended choice.
 
 **Watching and stopping.** `aidlc autopilot status` shows the active run and each item's step, pull
-request, CI failure count and last error. `aidlc autopilot stop` (or `/aidlc-autopilot-stop`) ends the
+request, CI failure count and last error, and for an item waiting on you: the phase, its worktree and
+the `aidlc autopilot approve` command, or the pull request number to merge.
+`aidlc autopilot stop` (or `/aidlc-autopilot-stop`) ends the
 run at its next step: nothing further is started, merged or released, and agents already running
 finish their item. `aidlc autopilot pause` freezes the run and its agents where they are —
 for closing a laptop, whose sleep would otherwise cut the agents' network and get their items parked —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasensio/aidlc-content",
-  "version": "1.61.0",
+  "version": "1.63.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/resources/rules/unattended.md

@@ -7,6 +7,7 @@ Unattended mode is on exactly when the environment variable `AIDLC_UNATTENDED` i
 - **Default and log** — take the named default, log it, carry on.
 - **Hard stop** — log it, park the item, release the claim, end the session.
 - **Release boundary** — the normal end of an unattended run. Not a hard stop, and the item is not parked.
+- **Review boundary** — a planned stop for a person's review, part way through. Not a hard stop, and the item is not parked.
 
 A situation no entry below covers is a hard stop. Guessing is what this mode exists to prevent.
 
@@ -34,6 +35,19 @@ To stop:
 
 When testing completes, write the deployment record's release plan and end the session. Do not push, open a pull request, merge or release: whatever runs the agent owns those, and two actors on one release lane is how two releases collided on 2026-10-01.
 
+## The review boundary
+
+`AIDLC_PAUSE_AFTER` (`printenv AIDLC_PAUSE_AFTER`) is a comma-separated list of phase names, set by whatever runs the agent. Empty or unset names none, and every phase boundary is the `phase-end-turn` default: carry on.
+
+When it names the phase that just completed, that boundary is a **review boundary**. A person reads the artifact and approves it; the run carries the work on afterwards, in a later session. So:
+
+1. Append the log entry.
+2. Commit on the instance branch. Never push, open a pull request, merge or release.
+3. Run `aidlc release <instance>` — a review can outlast the claim's 60-minute staleness, and the next session must not find a claim it has to override.
+4. End the session. Do **not** park the item: it is waiting, not failed.
+
+Nothing else changes: the phase is completed and transitioned as usual first, so the next session resumes from the next phase.
+
 ## Every known stop
 
 Each bullet begins with its one outcome; a condition after it is part of the rule.
@@ -48,7 +62,8 @@ Each bullet begins with its one outcome; a condition after it is part of the rul
 - `open-question` — **default and log**: the recommended option, marked `(unattended default)`; if it is a hard-stop class, hard stop — never another option.
 - `requirements-confirmation` — **default and log**: hard stop if the requirements exceed the roadmap item.
 - `design-confirmation` — **default and log**: the same scope test.
-- `phase-end-turn` — **default and log**: continue into the next phase.
+- `phase-end-turn` — **default and log**: continue into the next phase, unless `AIDLC_PAUSE_AFTER` names the phase just completed, which is a review boundary.
+- `review-boundary` — **review boundary**: `AIDLC_PAUSE_AFTER` names the phase just completed.
 - `fresh-session` — **default and log**: continue; the runner decides where sessions start.
 - `own-change-revert` — **default and log**: reverting this session's own change, after keeping a copy.
 - `generated-output-discard` — **hard stop**: discarding output this session did not write.

package/skills/84-autopilot.md

@@ -9,7 +9,7 @@ trigger: When the user asks to do, work, build or ship the next n backlog items,
 
 ## Purpose
 
-Turn "do the next 3 items" into one background run. The run builds each ready backlog item in its own worktree with an unattended agent, opens a pull request, waits for CI, merges, and runs the configured release step — one item at a time through the merge.
+Turn "do the next 3 items" into one background run. The run builds each ready backlog item in its own worktree with an unattended agent, opens a pull request, waits for CI, and goes as far as the user's stop settings allow — one item at a time through the merge. By default it pauses for a review after requirements and after design, and stops at the pull request for the user to merge.
 
 The CLI does the work. This skill starts it and says how to watch and stop it. Do not build the items yourself in this session.
 
@@ -30,20 +30,28 @@ The CLI does the work. This skill starts it and says how to watch and stop it. D
    - *a run is already active* → report its pid and offer `aidlc autopilot stop` first.
    - *the run is paused* → offer `aidlc autopilot resume`.
 
-5. **Report**, in five short lines: what it is doing (how many items), the log file it printed, `aidlc autopilot status` to watch, `aidlc autopilot pause` before the machine sleeps (`aidlc autopilot resume` after), and `/aidlc-autopilot-stop` (or `aidlc autopilot stop`) to stop.
+5. **Report**, in six short lines: what it is doing (how many items), the `stops:` line `run` printed verbatim, the log file, `aidlc autopilot status` to watch, `aidlc autopilot pause` before the machine sleeps (`aidlc autopilot resume` after), and `/aidlc-autopilot-stop` (or `aidlc autopilot stop`) to stop. When the stops line says none are set, say plainly that every item will be merged and released with no review, and name `aidlc autopilot setup` as what changes that.
 
-6. **Pause and resume.** When the user is stepping away or closing the laptop, run `aidlc autopilot pause`; when they are back, `aidlc autopilot resume`. Report what each printed. If pause says a pass is in progress — a merge or a release — run it again a minute later rather than stopping the run.
+6. **Where it stops for a person.** Two stops, both set in `aidlc autopilot setup` or `aidlc init` and on by default:
+   - **After a phase** — the agent stops when a phase in `pause_after` completes (requirements and design by default). The item waits as `awaiting-review`; it is *not* parked. The user reads the artifact in the item's worktree, then `aidlc autopilot approve <instance>` carries it on.
+   - **At the pull request** — autopilot opens it and waits for the user to merge. Merging is the approval: autopilot then closes the instance out on main and runs no release.
+
+   One run can change both without touching the saved setup: `aidlc autopilot run --items 3 --stop-at merge` or `--pause-after design` (`--pause-after none` for no pauses, `--stop-at release` for the old merge-and-release). The flags apply to the items that run starts; an item already in flight keeps the stops it started with. A config saved before stops existed keeps today's behaviour — no pauses, merge and release — until somebody sets them.
+
+   When the user asks what is waiting for them, run `aidlc autopilot status`: it names the phase, the worktree and the exact approve command for each waiting item.
+
+7. **Pause and resume.** When the user is stepping away or closing the laptop, run `aidlc autopilot pause`; when they are back, `aidlc autopilot resume`. Report what each printed. If pause says a pass is in progress — a merge or a release — run it again a minute later rather than stopping the run.
 
 ## What the run does on its own
 
 - Takes items in `aidlc roadmap next` order. Builds at most two at once, and never more than the count asked for.
-- Parks an item (moves it to `hold/` with a reason) when its agent stops short, when CI fails twice, or when it passes the cost cap.
+- Parks an item (moves it to `hold/` with a reason) when its agent stops short of a stop it was told to reach, when CI fails twice, or when it passes the cost cap. An item waiting for a person is never parked, and holds no build slot, so the run goes on starting others.
 - An agent that loses the network exits, and is parked. Sleep cuts the network, so a run on a laptop needs `aidlc autopilot pause` first: it freezes the run and its agents where they are, and `aidlc autopilot resume` carries on.
 - Before each merge, brings the item's branch up to date with main and waits for CI on the new head. A conflict with main goes back to the item's agent, twice at most, then the item is parked. A pull request someone merged by hand is dropped from tracking.
 - Halts the merge queue when a step fails. Running `aidlc autopilot run` again retries a failure that came before the merge; a failed release is for a person — `aidlc autopilot status` shows the error. `aidlc autopilot forget <instance>` stops tracking an item finished by hand.
-- Ends when the asked-for items are each released or parked, or, with `--all`, when nothing is ready and nothing is in flight.
+- Ends when the asked-for items are each released or parked, or, with `--all`, when nothing is ready and nothing is in flight. An item waiting for a person keeps its run alive, so the run is still there to carry the item on after an approval or a merge.
 
 ## Exit Criteria
 
 - `aidlc autopilot run` has started a run, or its refusal has been reported with the one command that fixes it
-- The user knows where the log is, how to watch, how to pause, and how to stop
+- The user knows where it will stop for them, where the log is, how to watch, how to pause, and how to stop