@pmelab/gtd 1.7.0 → 1.9.0

package/README.md

@@ -17,7 +17,7 @@ merge-base with the default branch (whole-history fallback when there is no
 default branch, when HEAD equals the merge-base, or when there is no merge-base
 — i.e. budgets engage on the default branch too) plus the working tree, turns
 them into a `COMMIT[]` + single terminal `RESOLVE` event stream, and folds them
-through the machine. The fold lands on exactly **one** of 18 states, which
+through the machine. The fold lands on exactly **one** of 19 states, which
 selects the prompt. A single run resolves to a single state.
 
 `resolve()` returns that state plus an optional **`EdgeAction`** (a commit,
@@ -50,7 +50,14 @@ No config file, no setup subcommand.
 
 Run `gtd` from your repository's working directory — it prints the next prompt
 to stdout. It takes **no ref argument** — the review base is always
-auto-computed.
+auto-computed. The one exception is `gtd review <target>`: an explicit,
+on-demand human review against a chosen base (see
+[Review subcommand](#review-subcommand) below).
+
+On an idle tree outside a process (no steering files, nothing reviewable), `gtd`
+now runs a **health check** instead of stopping immediately — `gtd review` is
+the only way to start an ad-hoc review when the automatic review base yields no
+diff.
 
 ## JSON output mode
 
@@ -138,6 +145,11 @@ across runs:
 - **ERRORS.md** — the escalation gate: persistent test-failure output that stops
   the loop for a human (written instead of FEEDBACK.md once the fix-attempt cap
   is hit; never auto-consumed).
+- **HEALTH.md** — idle health-check failure output: written when `testCommand`
+  fails on a bare idle tree (no `.gtd`, no REVIEW.md, no FEEDBACK.md). Carries
+  the failure while the dedicated health-fix loop repairs it. Analogous to
+  FEEDBACK.md but lives on the default-branch idle path rather than inside a
+  build process. Never written while any other steering file is present.
 - **.gtd/** — ordered work packages (one numbered directory each) of
   parallelizable subtasks.
 
@@ -158,9 +170,11 @@ Every run derives the state in **three layers**:
 1. **Transport pre-pass** — if HEAD is `gtd: transport`, short-circuit to the
    Transport state (mixed-reset) before anything else is considered.
 2. **Steering-file precedence** — the presence of `ERRORS.md` / `FEEDBACK.md` /
-   `.gtd/` / `REVIEW.md` drives the decision, authoritative regardless of HEAD.
+   `HEALTH.md` / `.gtd/` / `REVIEW.md` drives the decision, authoritative
+   regardless of HEAD.
 3. **HEAD bucket** — with no steering files in play, the last-commit bucket plus
-   working-tree cleanliness selects New Feature / Grilling / Clean / Idle.
+   working-tree cleanliness selects New Feature / Grilling / Clean / Health
+   check / Idle.
 
 Within layers 2 and 3 the HEAD subject further disambiguates states the
 filesystem alone cannot separate (e.g. inside the `.gtd/` lifecycle, HEAD
@@ -173,8 +187,9 @@ The complete set:
 
 `gtd: new task` · `gtd: grilling` · `gtd: grilled` · `gtd: planning` ·
 `gtd: building` · `gtd: errors` · `gtd: feedback` · `gtd: fixing` ·
-`gtd: package done` · `gtd: awaiting review` · `gtd: done` — plus the hand-made
-`gtd: transport` (see below).
+`gtd: package done` · `gtd: awaiting review` · `gtd: done` · `gtd: health-check`
+· `gtd: health-fix` · `gtd: reviewing` — plus the hand-made `gtd: transport`
+(see below).
 
 The last commit subject is bucketed two ways:
 
@@ -189,24 +204,28 @@ The last commit subject is bucketed two ways:
 1. **ERRORS.md present** → Escalate (human gate; STOP).
 2. **FEEDBACK.md present** → non-empty → Fixing; **empty** (clean agentic review
    = approval) → Close package.
-3. **.gtd present** → build lifecycle, routed by tree + HEAD:
+3. **HEALTH.md present** → Health Fixing (idle health-fix loop; no `.gtd`,
+   REVIEW.md, or FEEDBACK.md).
+4. **.gtd present** → build lifecycle, routed by tree + HEAD:
    - `.gtd` modified (package files added/edited) → Planning
    - code changes present → Testing
    - clean tree + HEAD `gtd: fixing` (no-op fixer) → Testing (re-test)
    - else clean, by HEAD: `gtd: planning` / `gtd: package done` → Building;
      `gtd: building` → Agentic Review (or Close package, if force-approved)
-4. **REVIEW.md present** → review lifecycle, routed by committed-ness + tree:
+5. **REVIEW.md present** → review lifecycle, routed by committed-ness + tree:
    committed + clean → Done; committed + checkbox-only edits (only `[ ]`↔`[x]`
    flips in REVIEW.md) → Done; committed + non-checkbox pending edits → Accept
    Review; uncommitted → Await Review (commits REVIEW.md and auto-advances to
-   Done). 4a. **HEAD `gtd: done` + `squash` enabled + squash base present + no
+   Done). 5a. **HEAD `gtd: done` + `squash` enabled + squash base present + no
    unrelated code dirty** (a lone untracked `SQUASH_MSG.md` is allowed) →
    Squashing; unrelated code dirty → New Feature.
-5. **Boundary HEAD + pending changes** (and no `.gtd`/REVIEW/FEEDBACK), or HEAD
+6. **Boundary HEAD + pending changes** (and no `.gtd`/REVIEW/FEEDBACK), or HEAD
    `gtd: new task` + clean tree (regenerate a lost seed) → New Feature.
-6. **TODO.md present** → Grilling / Grilled.
-7. **Boundary or `gtd: package done` HEAD + clean tree** → Clean (review the
-   work) or Idle (nothing to review).
+7. **TODO.md present** → Grilling / Grilled.
+8. **Boundary or `gtd: package done` HEAD + clean tree** → Clean (review the
+   work), **Health check** (run `testCommand` when there is nothing to review —
+   on any branch outside a process), or Idle (health check green, nothing to
+   do).
 
 Anything matching no rule is corruption — `gtd` **hard-errors** rather than
 guess.
@@ -221,7 +240,10 @@ flowchart TD
     P1 -->|no| P2{"FEEDBACK.md?"}
     P2 -->|"empty = approval"| Close["Close package — rm pkg dir, gtd: package done"]:::edge
     P2 -->|"non-empty"| Fixing["Fixing — rm FEEDBACK, fixer agent"]:::agent
-    P2 -->|absent| P3{".gtd/?"}
+    P2 -->|absent| P2b{"HEALTH.md?"}
+    P2b -->|"present"| HealthFix["Health Fixing — rm HEALTH.md, gtd: health-fix, fixer agent"]:::agent
+    HealthFix -.->|"re-resolve"| HealthCheck
+    P2b -->|absent| P3{".gtd/?"}
     P3 -->|"modified"| Planning["Planning — gtd: planning"]:::agent
     P3 -->|"code dirty / resume / no-op fixer"| Testing["Testing — gtd: building, run tests"]:::edge
     P3 -->|"clean, HEAD planning/package done"| Building["Building — pick & build one package"]:::agent
@@ -234,17 +256,21 @@ flowchart TD
     P4 -->|absent| P5{"boundary HEAD + dirty,<br/>or gtd: new task + clean?"}
     Done -->|"squash enabled"| Squashing["Squashing — reset --soft base, squash commit"]:::agent
     Done -->|"squash disabled"| Idle
-    Squashing --> Idle["Idle — nothing to do (STOP; review on next manual gtd run)"]:::gate
+    Squashing --> Idle["Idle — nothing to do (STOP)"]:::gate
     P5 -->|yes| NewFeature["New Feature — gtd: new task, revert, seed TODO"]:::edge
     P5 -->|no| P6{"TODO.md?"}
     P6 -->|"open markers"| GrillStop["Grilling — gtd: grilling, STOP for answers"]:::gate
     P6 -->|"dirty, no markers"| GrillIter["Grilling — gtd: grilling, agent iterates"]:::agent
-    P6 -->|"clean, no markers"| GrilledReview["Grilled review — gtd: grilled, human review"]:::gate
-    GrilledReview -->|"re-run gtd clean"| Grilled["Grilled — gtd: grilled, decompose"]:::agent
-    GrilledReview -->|"edits present"| GrillIter
+    P6 -->|"clean, no markers"| Grilled["Grilled — gtd: grilled, decompose"]:::agent
     P6 -->|absent| P7{"clean + boundary/package-done HEAD,<br/>reviewable diff?"}
     P7 -->|yes| CleanState["Clean — write REVIEW.md"]:::agent
-    P7 -->|no| Idle
+    P7 -->|"no (idle, outside a process)"| HealthCheck["Health check — run testCommand"]:::edge
+    HealthCheck -->|"green, no health-fix"| Idle
+    HealthCheck -->|"green + ≥1 health-fix, squash enabled"| Squashing
+    HealthCheck -->|"red, below cap"| HealthMd["write HEALTH.md, gtd: health-check"]:::edge
+    HealthMd -.->|"re-resolve"| HealthFix
+    HealthCheck -->|"red, at cap"| ErrorsMd["write ERRORS.md, gtd: health-check"]:::edge
+    ErrorsMd -.->|"re-resolve"| Escalate
     classDef edge fill:#1a4a6b,color:#fff
     classDef agent fill:#2d6a4f,color:#fff
     classDef gate fill:#7a3b1d,color:#fff
@@ -265,6 +291,10 @@ guessing:
 - FEEDBACK.md without .gtd
 - ERRORS.md + FEEDBACK.md
 - ERRORS.md without .gtd
+- HEALTH.md + .gtd (health check only runs from a bare idle tree)
+- HEALTH.md + REVIEW.md (same)
+- HEALTH.md + FEEDBACK.md (same)
+- HEALTH.md + ERRORS.md (escalation wins; HEALTH.md must not coexist)
 
 Legal coexistence: `.gtd` + TODO.md (plan kept alongside packages during
 **Planning** only — TODO.md is deleted at the first Building turn);
@@ -292,7 +322,7 @@ back into the working tree uncommitted, and re-derives state from scratch. If
 the transport commit is the repository's root commit (no parent), `gtd` fails
 immediately with a clear error instead of looping.
 
-## The 18 states
+## The 19 states
 
 Each state has a **condition** (when it wins), a deterministic **action**, the
 **commit(s)** it produces, and where it **advances**. States marked
@@ -300,35 +330,36 @@ Each state has a **condition** (when it wins), a deterministic **action**, the
 human; **edge-only** states render no prompt at all — the driver performs their
 action and re-resolves silently.
 
-| State              | Kind                             | Wins when                                                                                                                                                                   | Action & commit                                                                                                                                                                                                                                                                                                        | Advances to                                                  |
-| ------------------ | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
-| **Transport**      | edge-only, auto                  | HEAD `gtd: transport` (hand-made handoff commit)                                                                                                                            | mixed-reset HEAD (`git reset HEAD~1`), keep work in tree; **no commit**                                                                                                                                                                                                                                                | re-derive from the restored tree                             |
-| **Escalate**       | STOP                             | ERRORS.md present                                                                                                                                                           | none                                                                                                                                                                                                                                                                                                                   | held until the human deletes ERRORS.md                       |
-| **Fixing**         | agent, auto                      | non-empty FEEDBACK.md present                                                                                                                                               | inline FEEDBACK into the prompt, remove FEEDBACK.md; commit its removal `gtd: fixing` (FEEDBACK was committed by Testing) or `gtd: feedback` (uncommitted, written by Agentic Review)                                                                                                                                  | fixer edits → Testing                                        |
-| **Close package**  | edge-only, auto                  | empty FEEDBACK.md present (clean review); also reached from Agentic Review force-approve                                                                                    | rm FEEDBACK.md, rm the first (finished) package dir (+ the now-empty `.gtd/`); commit `gtd: package done`                                                                                                                                                                                                              | more packages → Building; `.gtd` gone → Clean                |
-| **Planning**       | agent, auto                      | `.gtd` present **and modified**; HEAD `gtd: grilled` or `gtd: planning`                                                                                                     | commit the `.gtd/` changes `gtd: planning`                                                                                                                                                                                                                                                                             | continue decomposing, else → Building                        |
-| **Testing**        | edge-only, auto                  | `.gtd` present, no FEEDBACK/ERRORS, and a reason to test: code changes, a pending ERRORS.md deletion (human resume), or a clean tree under HEAD `gtd: fixing` (no-op fixer) | commit pending tree `gtd: building`, run `testCommand`; green → proceed; red → write FEEDBACK (below cap) or ERRORS (at cap), commit `gtd: errors`; if captured output is empty/whitespace, a sentinel string is written so the file is never empty (empty FEEDBACK remains reserved for agentic-review approval)      | green → Agentic Review; FEEDBACK → Fixing; ERRORS → Escalate |
-| **Building**       | agent, auto                      | `.gtd` present and clean, clean tree; HEAD `gtd: planning` or `gtd: package done`                                                                                           | if HEAD `gtd: planning` and TODO.md present, delete TODO.md and commit (prefix unchanged, fires once); select the first package, inline its tasks; agent leaves work **uncommitted**                                                                                                                                   | Testing                                                      |
-| **Agentic Review** | agent, auto                      | `.gtd` present and clean, clean tree; HEAD `gtd: building`                                                                                                                  | reviewer writes FEEDBACK.md (empty = approval), uncommitted — **unless** force-approved (kill-switch off or review-fix threshold hit), which routes straight to Close package                                                                                                                                          | empty FEEDBACK → Close package; non-empty → Fixing           |
-| **Done**           | edge-only, auto                  | REVIEW.md committed + clean tree, **or** committed + checkbox-only edits (only `- [ ]`→`- [x]` flips in REVIEW.md = approval)                                               | rm REVIEW.md, commit `gtd: done`                                                                                                                                                                                                                                                                                       | Squashing (if enabled) or Idle                               |
-| **Squashing**      | agent, auto                      | no steering files, HEAD `gtd: done`, `squash` enabled, squash base present, no unrelated code dirty (a lone untracked `SQUASH_MSG.md` is allowed)                           | agent authors a conventional-commits message from the full `<base>..HEAD` diff, then runs `git reset --soft <base>` + `git commit` — collapses all intermediate `gtd: *` commits (including any interleaved non-gtd commits) into one; **gtd then STOPs** — post-squash review fires only on the next manual `gtd` run | Idle (STOP)                                                  |
-| **Accept Review**  | edge-only, auto                  | REVIEW.md committed + pending **non-checkbox** edits (human annotated REVIEW.md with comments / edited code)                                                                | seed TODO.md from the changeset, `git checkout` to discard the code edits, rm REVIEW.md; **all uncommitted**                                                                                                                                                                                                           | Grilling                                                     |
-| **Await Review**   | edge-only, auto                  | REVIEW.md present and **uncommitted** (freshly written by Clean)                                                                                                            | commit REVIEW.md `gtd: awaiting review`                                                                                                                                                                                                                                                                                | Done (auto, same run)                                        |
-| **New Feature**    | edge-only, auto                  | boundary HEAD + pending changes (code and/or a new uncommitted TODO.md), **or** HEAD `gtd: new task` + clean tree (lost-seed regen)                                         | commit the raw input verbatim `gtd: new task` (unless already there), `git revert --no-commit` it back to a clean baseline, seed TODO.md from that diff — revert + seed left **uncommitted**                                                                                                                           | Grilling                                                     |
-| **Grilling**       | agent (iterate) / STOP (answers) | TODO.md present, not New Feature                                                                                                                                            | commit pending edits `gtd: grilling`. Open-question markers present → STOP for the human to answer inline; no markers but dirty → grilling agent iterates                                                                                                                                                              | converge (no markers, clean tree) → Grilled review           |
-| **Grilled review** | STOP                             | TODO.md present, no markers, clean tree, HEAD `gtd: grilled` (converged — not yet decomposed)                                                                               | none                                                                                                                                                                                                                                                                                                                   | edits → Grilling; clean re-run → Grilled                     |
-| **Grilled**        | agent, auto                      | TODO.md present, no markers, clean tree, HEAD `gtd: grilled` (returning from Grilled review with no new edits)                                                              | commit pending `gtd: grilled`                                                                                                                                                                                                                                                                                          | decompose into `.gtd/` → Planning                            |
-| **Clean**          | agent                            | no steering files, clean tree, boundary or `gtd: package done` HEAD, and the review base yields a **non-empty** diff                                                        | compute the review base (four rules — see below); agent writes REVIEW.md **uncommitted** with `# Review: <short-hash>` heading, `<!-- base: <full-hash> -->` marker, and per-hunk `- [ ]` checkboxes (ticking them signals approval → Done)                                                                            | Await Review                                                 |
-| **Idle**           | STOP                             | no steering files, clean tree, and nothing to review (HEAD `gtd: done` with `squash` disabled or after Squashing, or no reviewable diff)                                    | none                                                                                                                                                                                                                                                                                                                   | —                                                            |
+| State              | Kind                             | Wins when                                                                                                                                                                                         | Action & commit                                                                                                                                                                                                                                                                                                        | Advances to                                                                     |
+| ------------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| **Transport**      | edge-only, auto                  | HEAD `gtd: transport` (hand-made handoff commit)                                                                                                                                                  | mixed-reset HEAD (`git reset HEAD~1`), keep work in tree; **no commit**                                                                                                                                                                                                                                                | re-derive from the restored tree                                                |
+| **Escalate**       | STOP                             | ERRORS.md present                                                                                                                                                                                 | none                                                                                                                                                                                                                                                                                                                   | held until the human deletes ERRORS.md                                          |
+| **Fixing**         | agent, auto                      | non-empty FEEDBACK.md present                                                                                                                                                                     | inline FEEDBACK into the prompt, remove FEEDBACK.md; commit its removal `gtd: fixing` (FEEDBACK was committed by Testing) or `gtd: feedback` (uncommitted, written by Agentic Review)                                                                                                                                  | fixer edits → Testing                                                           |
+| **Health Fixing**  | agent, auto                      | HEALTH.md present (no `.gtd`, REVIEW.md, or FEEDBACK.md)                                                                                                                                          | read HEALTH.md into the prompt, commit its removal `gtd: health-fix`                                                                                                                                                                                                                                                   | fixer edits → Health check                                                      |
+| **Close package**  | edge-only, auto                  | empty FEEDBACK.md present (clean review); also reached from Agentic Review force-approve                                                                                                          | rm FEEDBACK.md, rm the first (finished) package dir (+ the now-empty `.gtd/`); commit `gtd: package done`                                                                                                                                                                                                              | more packages → Building; `.gtd` gone → Clean                                   |
+| **Planning**       | agent, auto                      | `.gtd` present **and modified**; HEAD `gtd: grilled` or `gtd: planning`                                                                                                                           | commit the `.gtd/` changes `gtd: planning`                                                                                                                                                                                                                                                                             | continue decomposing, else → Building                                           |
+| **Testing**        | edge-only, auto                  | `.gtd` present, no FEEDBACK/ERRORS, and a reason to test: code changes, a pending ERRORS.md deletion (human resume), or a clean tree under HEAD `gtd: fixing` (no-op fixer)                       | commit pending tree `gtd: building`, run `testCommand`; green → proceed; red → write FEEDBACK (below cap) or ERRORS (at cap), commit `gtd: errors`; if captured output is empty/whitespace, a sentinel string is written so the file is never empty (empty FEEDBACK remains reserved for agentic-review approval)      | green → Agentic Review; FEEDBACK → Fixing; ERRORS → Escalate                    |
+| **Building**       | agent, auto                      | `.gtd` present and clean, clean tree; HEAD `gtd: planning` or `gtd: package done`                                                                                                                 | if HEAD `gtd: planning` and TODO.md present, delete TODO.md and commit (prefix unchanged, fires once); select the first package, inline its tasks; agent leaves work **uncommitted**                                                                                                                                   | Testing                                                                         |
+| **Agentic Review** | agent, auto                      | `.gtd` present and clean, clean tree; HEAD `gtd: building`                                                                                                                                        | reviewer writes FEEDBACK.md (empty = approval), uncommitted — **unless** force-approved (kill-switch off or review-fix threshold hit), which routes straight to Close package                                                                                                                                          | empty FEEDBACK → Close package; non-empty → Fixing                              |
+| **Done**           | edge-only, auto                  | REVIEW.md committed + clean tree, **or** committed + checkbox-only edits (only `- [ ]`→`- [x]` flips in REVIEW.md = approval)                                                                     | rm REVIEW.md, commit `gtd: done`                                                                                                                                                                                                                                                                                       | Squashing (if enabled) or Idle                                                  |
+| **Squashing**      | agent, auto                      | no steering files, HEAD `gtd: done` or green Health check with ≥1 `gtd: health-fix`, `squash` enabled, squash base present, no unrelated code dirty (a lone untracked `SQUASH_MSG.md` is allowed) | agent authors a conventional-commits message from the full `<base>..HEAD` diff, then runs `git reset --soft <base>` + `git commit` — collapses all intermediate `gtd: *` commits (including any interleaved non-gtd commits) into one; **gtd then STOPs** — post-squash review fires only on the next manual `gtd` run | Idle (STOP)                                                                     |
+| **Accept Review**  | edge-only, auto                  | REVIEW.md committed + pending **non-checkbox** edits (human annotated REVIEW.md with comments / edited code)                                                                                      | seed TODO.md from the changeset, `git checkout` to discard the code edits, rm REVIEW.md; **all uncommitted**                                                                                                                                                                                                           | Grilling                                                                        |
+| **Await Review**   | edge-only, auto                  | REVIEW.md present and **uncommitted** (freshly written by Clean)                                                                                                                                  | commit REVIEW.md `gtd: awaiting review`                                                                                                                                                                                                                                                                                | Done (auto, same run)                                                           |
+| **New Feature**    | edge-only, auto                  | boundary HEAD + pending changes (code and/or a new uncommitted TODO.md), **or** HEAD `gtd: new task` + clean tree (lost-seed regen)                                                               | commit the raw input verbatim `gtd: new task` (unless already there), `git revert --no-commit` it back to a clean baseline, seed TODO.md from that diff — revert + seed left **uncommitted**                                                                                                                           | Grilling                                                                        |
+| **Grilling**       | agent (iterate) / STOP (answers) | TODO.md present, not New Feature                                                                                                                                                                  | commit pending edits `gtd: grilling`. Open-question markers present → STOP for the human to answer inline; no markers but dirty → grilling agent iterates                                                                                                                                                              | converge (no markers, clean tree) → Grilled                                     |
+| **Grilled**        | agent, auto                      | TODO.md present, no markers, clean tree                                                                                                                                                           | commit pending `gtd: grilled`                                                                                                                                                                                                                                                                                          | decompose into `.gtd/` → Planning                                               |
+| **Clean**          | agent                            | no steering files, clean tree, boundary or `gtd: package done` HEAD, and the review base yields a **non-empty** diff                                                                              | compute the review base (three rules — see below); agent writes REVIEW.md **uncommitted** with `# Review: <short-hash>` heading, `<!-- base: <full-hash> -->` marker, and per-hunk `- [ ]` checkboxes (ticking them signals approval → Done)                                                                           | Await Review                                                                    |
+| **Health check**   | edge-only, auto                  | no steering files, clean tree, outside a process with no reviewable diff (any branch) — the `!reviewable` case from rule 8                                                                        | run `testCommand`: green + no prior `gtd: health-fix` → Idle (no commit); red below `fixAttemptCap` → write HEALTH.md, commit `gtd: health-check` → Health Fixing; red at cap → write ERRORS.md, commit `gtd: health-check` → Escalate; green + ≥1 `gtd: health-fix` → Squashing (if `squash`) or Idle                 | green → Idle or Squashing; red below cap → Health Fixing; red at cap → Escalate |
+| **Idle**           | STOP                             | no steering files, clean tree, health check passed with no prior `gtd: health-fix` commits, and nothing to review                                                                                 | none (no commit — the health check edge terminates the driver loop directly)                                                                                                                                                                                                                                           | —                                                                               |
 
 Every prompt also embeds the current `git diff HEAD` (untracked files included)
 inline, plus the last commit subject and working-tree status, so the agent has
 full context.
 
-### Review base — four rules
+### Review base — three rules
 
 The review base (the commit whose diff to HEAD forms the REVIEW.md) is chosen by
-four rules evaluated in priority order:
+three rules evaluated in priority order:
 
 1. **Within a process, first review** — a `gtd: grilling` commit exists after
    the last `gtd: done` (or task start), but no `gtd: awaiting review` yet →
@@ -337,18 +368,16 @@ four rules evaluated in priority order:
 2. **Within a process, incremental** — `gtd: awaiting review` also present in
    the current cycle (takes precedence over rule 1) → base = last
    `gtd: awaiting review`; `refDiff` spans only the post-review changes.
-3. **Outside a process, feature branch** — no `gtd: grilling` after the last
-   `gtd: done`, and HEAD is not on the default branch → base = merge-base with
-   the default branch; `refDiff` spans the whole branch.
-4. **Outside a process, default branch** — no process active and HEAD is on the
-   default branch → skip review; `reviewBase`/`refDiff` unset → Idle.
+3. **Outside a process (any branch)** — no `gtd: grilling` after the last
+   `gtd: done` → skip review; `reviewBase`/`refDiff` unset → Idle (the health
+   check runs instead).
 
 In all cases, if the diff from the chosen base to HEAD is empty,
 `reviewBase`/`refDiff` are left unset and the machine settles in Idle.
 
 ## The fix loops & counter folds
 
-Two derived counters drive the budgeted loops. Both are **folded in the
+Three derived counters drive the budgeted loops. All are **folded in the
 machine** from flags on the `COMMIT[]` stream — never recomputed at the edge:
 
 - **`testFixCount`** — `gtd: errors` commits (test-fix attempts) since the
@@ -358,6 +387,9 @@ machine** from flags on the `COMMIT[]` stream — never recomputed at the edge:
   round, and every human resume starts a **fresh budget**.
 - **`reviewFixCount`** — `gtd: feedback` commits (review-fix rounds) since the
   most recent package start.
+- **`healthFixCount`** — `gtd: health-check` commits since the most recent
+  commit that removed HEALTH.md (or the start of branch history if none). Reuses
+  `fixAttemptCap` — no separate config key.
 
 ### Test-fix loop (`fixAttemptCap`, default 3)
 
@@ -381,6 +413,31 @@ ERRORS.md — which **resets the fix-attempt budget** (the next run re-tests and
 grants a fresh `cap` attempts before escalating again). While ERRORS.md exists,
 every run resolves straight back to Escalate.
 
+### Health-fix loop (`fixAttemptCap`, `squash` — no new config)
+
+Outside a process (any branch), when there is no reviewable diff and no steering
+files, `gtd` runs `testCommand` instead of stopping. This reuses `fixAttemptCap`
+(default 3) and `squash` — no new config keys are introduced.
+
+```
+Idle path → Health check(red) → Health Fixing → Health check(red) → … → Health check(green)
+                  │                                                             │
+                  └── below cap: HEALTH.md, gtd: health-check ─────────────────┘
+                  └── at/over the cap: ERRORS.md, gtd: health-check → Escalate
+                                                              green + ≥1 health-fix → Squashing (if squash enabled) → Idle
+```
+
+- **green, no prior `gtd: health-fix`** → Idle immediately (no commit).
+- **red, below `fixAttemptCap`** → write test output to HEALTH.md, commit
+  `gtd: health-check` → **Health Fixing** agent fixes, commits removal as
+  `gtd: health-fix`, loops back to Health check.
+- **red, at or over `fixAttemptCap`** → write test output to ERRORS.md, commit
+  `gtd: health-check` → **Escalate** (human gate). Delete ERRORS.md to reset the
+  budget and resume.
+- **green, ≥1 `gtd: health-fix` present** → health-fix cycle converged: if
+  `squash` is enabled → **Squashing** (squash base = parent of the first
+  `gtd: health-check` of the current run); otherwise → Idle (no commit).
+
 ### Review-fix loop & agentic review (`reviewThreshold`, default 3)
 
 After a green test run, **Agentic Review** reviews the package's accumulated
@@ -425,11 +482,9 @@ loop before the next one starts.
    your answer, and run `gtd` again. The agent integrates answers, moves them to
    `## Resolved`, and raises fresh questions — repeat until none remain (it
    writes `no open questions — run gtd to plan` with no markers).
-4. **Converge.** A clean tree with no markers resolves to **Grilled review**
-   (`gtd: grilled`) — a human STOP. Review the plan; edit and re-run `gtd` to
-   re-enter Grilling, or re-run `gtd` with no changes to advance. A clean re-run
-   triggers **Grilled** (auto-advance), which then **Planning** decomposes
-   `TODO.md` into ordered `.gtd/` work packages (`gtd: planning`).
+4. **Converge.** A clean tree with no markers resolves to **Grilled**
+   (`gtd: grilled`), then **Planning** decomposes `TODO.md` into ordered `.gtd/`
+   work packages (`gtd: planning`).
 5. **Build.** Run `gtd` — **Building** first deletes `TODO.md` (when HEAD is
    `gtd: planning` and it is still present, committed under the same
    `gtd: planning` prefix — fires once). It then names the single next package
@@ -482,11 +537,13 @@ built-in defaults apply. Supported filenames (searched in this order):
 ### Schema
 
 - **`testCommand`** (string, default `npm run test`) — the command the edge runs
-  in the Testing state to verify a built package.
+  in the Testing state to verify a built package, and in the Health check state
+  on the default-branch idle path.
 - **`fixAttemptCap`** (non-negative integer, default `3`) — the test-fix budget:
   how many `gtd: errors` attempts are allowed per sub-loop before the failure is
   escalated to ERRORS.md (Escalate). `0` disables the cap (escalates immediately
-  on the first red run).
+  on the first red run). Also reused as the health-fix budget (no separate
+  config key).
 - **`reviewThreshold`** (integer ≥ 1, default `3`) — the review-fix budget: how
   many `gtd: feedback` rounds are allowed per package before Agentic Review
   force-approves.
@@ -682,10 +739,50 @@ When there are genuinely no open questions left, the agent writes the sentinel
 line `no open questions — run gtd to plan` and leaves **no** markers — a clean
 tree with no markers is what advances the plan to **Grilled** and decomposition.
 
-## Formatting
+## Subcommands
+
+gtd ships two subcommands: `format` and `review`.
+
+## Review subcommand
+
+```bash
+gtd review <target>
+```
+
+Starts an explicit, on-demand human review of the diff between HEAD and
+`merge-base(<target>, HEAD)`. Use this when the automatic review base yields no
+diff (idle tree outside a process) or when you want to review against a specific
+base regardless of workflow state.
 
-gtd ships a `format` subcommand — the **only** subcommand — that formats a
-markdown file in place:
+### Flow
+
+1. `gtd review <target>` computes the diff HEAD adds over
+   `merge-base(<target>, HEAD)`.
+2. The edge writes an empty anchor commit `gtd: reviewing` (no content — just
+   the marker).
+3. The **Clean** state writes `REVIEW.md` with the computed diff and emits the
+   normal review prompt. `--json` is accepted and enables auto-advance mode
+   (same behavior as the default command).
+4. The normal loop then drives: **Await Review** → **Done** → **Squashing**,
+   collapsing back to the `gtd: reviewing` anchor commit.
+
+### Error handling
+
+All errors exit with **code 1** and write a message to **stderr**:
+
+- **Missing target** — `gtd review` with no argument:
+  `gtd review: missing target argument`
+- **Extra arguments** — `gtd review main extra`:
+  `gtd review: too many arguments — expected one target, got: …`
+- **Unresolvable ref** — the target cannot be resolved by git:
+  `gtd review: cannot resolve ref '<target>': <error message>`
+- **Empty diff** — the merge-base diff between `<target>` and HEAD is empty
+  (nothing to review):
+  `gtd review: nothing to review (<target> diff is empty after filtering)`
+
+## Format subcommand
+
+`gtd format` formats a markdown file in place:
 
 ```bash
 gtd format <file>
@@ -812,6 +909,37 @@ Run `npm run test:mutation` after making changes to the mutated files to check
 whether surviving mutants increased. The HTML report lands in
 `reports/mutation/mutation.html` (git-ignored).
 
+### Mutation testing
+
+Run mutation testing on-demand with `npm run test:mutation` (StrykerJS, ~2 min).
+The single `stryker.config.json` mutates six core files:
+
+```
+src/Machine.ts  src/Prompt.ts  src/Config.ts
+src/Format.ts   src/State.ts   src/Events.ts
+```
+
+`src/Git.ts` is excluded: the Cucumber harness stubs git at the Effect boundary,
+so Git.ts mutants have zero in-memory coverage. Measuring its post-refactor
+Live-tier kill rate is a follow-up before re-including it.
+
+**`process.chdir()` gotcha (resolved).** `@stryker-mutator/vitest-runner`
+hardcodes `pool: 'threads'` internally, and `process.chdir()` is unsupported in
+worker threads. Before the cwd refactor (package 01), four test files
+(`Events.test.ts`, `Git.test.ts`, `Config.test.ts`, `TestRunner.test.ts`) had to
+be excluded from all Stryker runs. The refactor eliminated those calls, letting
+all four files rejoin the run.
+
+Two additional notes: `vitest.related` is disabled for feature-file runs because
+feature files don't import source files directly (Stryker's coverage-based
+filtering would assign zero tests to every mutant). Compile-error mutants are
+counted as kills by the TypeScript checker — they represent real signal, not a
+configuration problem.
+
+Run `npm run test:mutation` after making changes to the mutated files to check
+whether surviving mutants increased. The HTML report lands in
+`reports/mutation/mutation.html` (git-ignored).
+
 ## Releasing
 
 Releases are automatic. Push releasable Conventional Commits (`fix:`, `feat:`,

package/dist/gtd.bundle.mjs

@@ -368477,8 +368477,8 @@ var fixing_default = '<%~ include("@header") %>\n\n<%~ include("@context", { con
 // src/prompts/agentic-review.md
 var agentic_review_default = '<%~ include("@header") %>\n\n<%~ include("@context", { context: it.context, fenceFor: it.fenceFor }) %>\nSpawn a **reviewing subagent** using model `<%= it.model %>`. The package\'s task spec\nfiles and its cumulative diff are found below. The subagent must:\n\n1. **Read the task spec files** \u2014 they define the acceptance criteria. Every\n   requirement must be checked.\n2. **Read the package diff** \u2014 examine every hunk to determine whether the\n   implementation satisfies the spec.\n3. **Always write `FEEDBACK.md`** in the repo root:\n   - **Fully satisfies the spec** \u2192 write an **empty** `FEEDBACK.md` (zero bytes\n     or whitespace only). This empty file is the **approval** signal.\n   - **Does not fully satisfy** \u2192 write concrete, actionable findings anchored\n     to specific file and symbol names, grouped under short headings, so the fix\n     agent can act without re-reading the diff.\n4. **Do not edit source files and do not commit** \u2014 the reviewer only writes\n   `FEEDBACK.md`, left uncommitted.\n<% if (it.context.packages[0]) { %>\n<%~ include("@package", { pkg: it.context.packages[0], fenceFor: it.fenceFor }) %>\n<% } %><% if (it.context.refDiff && it.context.refDiff.trim()) { %>\n<%~ include("@diff", { heading: "Package diff", diff: it.context.refDiff, fenceFor: it.fenceFor }) %>\n<% } %>\n\n<%~ include(it.tail) %>\n';
 
-// src/prompts/clean.md
-var clean_default = '<%~ include("@header") %>\n\n<%~ include("@context", { context: it.context, fenceFor: it.fenceFor }) %>\nSpawn a **planning-model subagent** using model `<%= it.model %>` to author a\n`REVIEW.md` file that will help a human to review the changes. It must:\n\n1. **Read the diff inlined below** \u2014 extract the changed hunks with their file\n   paths.\n2. **Group hunks semantically** \u2014 cluster hunks that serve the same logical\n   concern (the same feature, refactor, or fix), even across files. Aim for the\n   fewest chunks that keep the review navigable.\n3. **Write `REVIEW.md`** in the repo root in this format:\n\n   ```markdown\n   # Review: <short-hash>\n\n   <!-- base: <full-hash> -->\n\n   ## <Chunk Title>\n\n   <What this chunk changes and why>\n\n   - [ ] ./path/to/file.ts#42\n   - [ ] ./path/to/file.ts#99\n\n   ## <Another Chunk Title>\n\n   <Explanation>\n\n   - [ ] ./path/to/another.ts#1\n   ```\n\n   - `<short-hash>` is the first 7 characters of the review base SHA;\n     `<full-hash>` is the full SHA. Both are read from the `Review base:` line /\n     diff label in the prompt context.\n   - Chunk titles are short imperative phrases (\u2264 6 words).\n   - Explanations describe _what_ changed and _why_, not just where.\n   - File pointers are relative, prefixed with `./`; the line numbers (`#42`)\n     are creation-time hints that will drift \u2014 not authoritative.\n   - Checkboxes (`- [ ]`) signal approval \u2014 ticking them (with no other edits)\n     counts as approving the review (`gtd: done`). Only non-checkbox edits to\n     `REVIEW.md` (or any code edits) are treated as a change-request.\n   - The user checks off or edits items in place as they work through the\n     review; there is no separate Resolved section.\n\n4. Leave `REVIEW.md` **uncommitted**, the outer loop will process it.\n<% if (it.context.refDiff && it.context.refDiff.trim()) { %>\n<%= it.context.reviewBase !== undefined ? "\\nReview base: " + it.context.reviewBase + "\\n" : "" %>\n<%~ include("@diff", { heading: "Changes to review (`git diff " + (it.context.reviewBase !== undefined ? it.context.reviewBase : "<base>") + " HEAD`)", diff: it.context.refDiff, fenceFor: it.fenceFor }) %>\n<% } %>\n\n<%~ include(it.tail) %>\n';
+// src/prompts/review.md
+var review_default = '<%~ include("@header") %>\n\n<%~ include("@context", { context: it.context, fenceFor: it.fenceFor }) %>\nSpawn a **planning-model subagent** using model `<%= it.model %>` to author a\n`REVIEW.md` file that will help a human to review the changes. It must:\n\n1. **Read the diff inlined below** \u2014 extract the changed hunks with their file\n   paths.\n2. **Group hunks semantically** \u2014 cluster hunks that serve the same logical\n   concern (the same feature, refactor, or fix), even across files. Aim for the\n   fewest chunks that keep the review navigable.\n3. **Write `REVIEW.md`** in the repo root in this format:\n\n   ```markdown\n   # Review: <short-hash>\n\n   <!-- base: <full-hash> -->\n\n   ## <Chunk Title>\n\n   <What this chunk changes and why>\n\n   - [ ] ./path/to/file.ts#42\n   - [ ] ./path/to/file.ts#99\n\n   ## <Another Chunk Title>\n\n   <Explanation>\n\n   - [ ] ./path/to/another.ts#1\n   ```\n\n   - `<short-hash>` is the first 7 characters of the review base SHA;\n     `<full-hash>` is the full SHA. Both are read from the `Review base:` line /\n     diff label in the prompt context.\n   - Chunk titles are short imperative phrases (\u2264 6 words).\n   - Explanations describe _what_ changed and _why_, not just where.\n   - File pointers are relative, prefixed with `./`; the line numbers (`#42`)\n     are creation-time hints that will drift \u2014 not authoritative.\n   - Checkboxes (`- [ ]`) signal approval \u2014 ticking them (with no other edits)\n     counts as approving the review (`gtd: done`). Only non-checkbox edits to\n     `REVIEW.md` (or any code edits) are treated as a change-request.\n   - The user checks off or edits items in place as they work through the\n     review; there is no separate Resolved section.\n\n4. Leave `REVIEW.md` **uncommitted**, the outer loop will process it.\n<% if (it.context.refDiff && it.context.refDiff.trim()) { %>\n<%= it.context.reviewBase !== undefined ? "\\nReview base: " + it.context.reviewBase + "\\n" : "" %>\n<%~ include("@diff", { heading: "Changes to review (`git diff " + (it.context.reviewBase !== undefined ? it.context.reviewBase : "<base>") + " HEAD`)", diff: it.context.refDiff, fenceFor: it.fenceFor }) %>\n<% } %>\n\n<%~ include(it.tail) %>\n';
 
 // src/prompts/squashing.md
 var squashing_default = '<%~ include("@header") %>\n\n<%~ include("@context", { context: it.context, fenceFor: it.fenceFor }) %>\nThe process is **approved and done**. Your job is to author a clean\nconventional-commits squash message and hand it off to the harness.\n\n### Step 1 \u2014 Extract decisions from grilling rounds\n\nScan the git history of recent `gtd: ...` commits. Look for changes to `TODO.md`\n\u2014 specifically the `## Captured input (grilling)` sections and any edits to plan\ntext. Extract **key decisions, trade-offs, and design choices** made during\ngrilling rounds. These will appear in the commit body so the history is\nself-documenting.\n\n### Step 2 \u2014 Draft the commit message\n\nDraft ONE conventional-commits message:\n\n```\ntype(scope): subject\n\nbody (explain the why \u2014 motivation, trade-offs, key decisions from grilling)\n```\n\n- **type**: `feat` / `fix` / `refactor` / `chore` / `docs` / `test`\n- **subject**: imperative mood, \u2264 72 characters, lowercase after the colon\n- **body**: include the important decisions / trade-offs from grilling sessions.\n  Omit if there were no meaningful decisions to capture.\n\n### Step 3 \u2014 Write SQUASH_MSG.md and hand off\n\nWrite the commit message (plain text, no markdown wrapper) to `SQUASH_MSG.md` in\nthe repo root, then leave it uncommitted \u2014 the harness handles the squash commit\non the next cycle once it sees `SQUASH_MSG.md`.\n\n**Do not run `git reset --soft` or `git commit` yourself** \u2014 the harness handles\nthe squash commit.\n<% if (it.context.squashDiff && it.context.squashDiff.trim()) { %>\n<%= it.context.squashBase !== undefined ? "\\nSquash base: " + it.context.squashBase + "\\n" : "" %>\n<%~ include("@diff", { heading: "Full-process diff (`git diff " + (it.context.squashBase !== undefined ? it.context.squashBase : "<squashBase>") + " HEAD`)", diff: it.context.squashDiff, fenceFor: it.fenceFor }) %>\n<% } %>\n\n<%~ include(it.tail) %>\n';
@@ -368486,9 +368486,6 @@ var squashing_default = '<%~ include("@header") %>\n\n<%~ include("@context", {
 // src/prompts/escalate.md
 var escalate_default = '<%~ include("@header") %>\n\n<%~ include("@context", { context: it.context, fenceFor: it.fenceFor }) %>\nThe agent was not able to fix all errors on its own. The last error report is\nstored in `ERRORS.md` for a human to investigate.\n\nNext steps for the human developer:\n\n1. Investigate and fix errors reported in `ERRORS.md`\n2. Delete `ERRORS.md`\n3. Continue the process when you are ready\n\n<%~ include(it.tail) %>\n';
 
-// src/prompts/grilled-review.md
-var grilled_review_default = '<%~ include("@header") %>\n\n<%~ include("@context", { context: it.context, fenceFor: it.fenceFor }) %> The\nplan in `TODO.md` has converged \u2014 no open questions remain \u2014 and has been\ncommitted as `gtd: grilled`.\n\n### Human review gate\n\nThis is a human review point. Tell the user to open `TODO.md` and review the\nfinalized plan:\n\n- To **proceed**, continue with a clean working tree \u2014 the plan will be\n  decomposed into `.gtd/` work packages.\n- To **revise**, edit `TODO.md` (or sketch code) and continue \u2014 the changes\n  re-enter the grilling loop for another convergence round.\n\n<%~ include(it.tail) %>\n';
-
 // src/prompts/idle.md
 var idle_default = '<%~ include("@header") %>\n\n<%~ include("@context", { context: it.context, fenceFor: it.fenceFor }) %>\nReport that the repository is idle \u2014 nothing to do.\n\n<%~ include(it.tail) %>\n';
 
@@ -368500,7 +368497,8 @@ var EDGE_ONLY_STATES = /* @__PURE__ */ new Set([
   "accept-review",
   "close-package",
   "done",
-  "await-review"
+  "await-review",
+  "health-check"
 ]);
 var MODEL_STATE = {
   grilling: "grilling",
@@ -368508,6 +368506,7 @@ var MODEL_STATE = {
   planning: "decompose",
   building: "building",
   fixing: "fixing",
+  "health-fixing": "fixing",
   "agentic-review": "agentic-review",
   clean: "clean",
   squashing: "clean"
@@ -368533,24 +368532,23 @@ eta.loadTemplate("@decompose", decompose_default);
 eta.loadTemplate("@building", building_default);
 eta.loadTemplate("@fixing", fixing_default);
 eta.loadTemplate("@agentic-review", agentic_review_default);
-eta.loadTemplate("@clean", clean_default);
+eta.loadTemplate("@review", review_default);
 eta.loadTemplate("@squashing", squashing_default);
 eta.loadTemplate("@escalate", escalate_default);
-eta.loadTemplate("@grilled-review", grilled_review_default);
 eta.loadTemplate("@idle", idle_default);
 eta.readFile = null;
 eta.resolvePath = null;
 var STATE_TEMPLATE = {
   grilled: "@decompose",
-  "grilled-review": "@grilled-review",
   planning: "@decompose",
   building: "@building",
   fixing: "@fixing",
   "agentic-review": "@agentic-review",
-  clean: "@clean",
+  clean: "@review",
   squashing: "@squashing",
   escalate: "@escalate",
-  idle: "@idle"
+  idle: "@idle",
+  "health-fixing": "@fixing"
 };
 var buildPrompt = (result, resolveModel = builtinResolveModel, output = "plain") => {
   const { state, context: context10 } = result;
@@ -385732,7 +385730,7 @@ function clean(original, cloned) {
   }
   return cloned;
 }
-var clean_default2 = clean;
+var clean_default = clean;
 function printFrontMatter({ node }) {
   return node.raw;
 }
@@ -385837,7 +385835,7 @@ function normalizePrinter(printer2) {
   if (originalCleanFunction && frontMatterSupport.massageAstNode) {
     massageAstNode = new Proxy(originalCleanFunction, {
       apply(target, thisArgument, argumentsList) {
-        clean_default2(...argumentsList);
+        clean_default(...argumentsList);
         return Reflect.apply(target, thisArgument, argumentsList);
       }
     });
@@ -388266,8 +388264,11 @@ var GTD_DIR = ".gtd";
 var REVIEW_FILE = "REVIEW.md";
 var FEEDBACK_FILE = "FEEDBACK.md";
 var ERRORS_FILE = "ERRORS.md";
+var HEALTH_FILE = "HEALTH.md";
 var EMPTY_FAILURE_SENTINEL = "Test command failed with no output (exit code non-zero).";
 var UNANSWERED_MARKER = "<!-- user answers here -->";
+var HEALTH_CHECK_SUBJECT = "gtd: health-check";
+var HEALTH_FIX_SUBJECT = "gtd: health-fix";
 var NEW_TASK_SUBJECT = "gtd: new task";
 var GRILLING_SUBJECT = "gtd: grilling";
 var PLANNING_SUBJECT = "gtd: planning";
@@ -388278,12 +388279,14 @@ var PACKAGE_DONE_SUBJECT = "gtd: package done";
 var AWAITING_REVIEW_SUBJECT = "gtd: awaiting review";
 var DONE_SUBJECT = "gtd: done";
 var REVIEW_FEEDBACK_SUBJECT = "gtd: review feedback";
+var REVIEWING_SUBJECT = "gtd: reviewing";
 var SQUASH_MSG_FILE = "SQUASH_MSG.md";
 var STEERING_FILES = [
   TODO_FILE,
   REVIEW_FILE,
   FEEDBACK_FILE,
   ERRORS_FILE,
+  HEALTH_FILE,
   SQUASH_MSG_FILE
 ];
 var WORKFLOW_FILE_EXCLUDES = [...STEERING_FILES, GTD_DIR];
@@ -388473,7 +388476,9 @@ var gatherEvents = () => (
           isFeedback: subject === FEEDBACK_SUBJECT,
           isPackageStart: subject === PLANNING_SUBJECT || subject === PACKAGE_DONE_SUBJECT,
           isWorkflowCommit: subject.startsWith("gtd: "),
-          removedErrors
+          removedErrors,
+          isHealthCheck: subject === HEALTH_CHECK_SUBJECT,
+          isHealthFix: subject === HEALTH_FIX_SUBJECT
         };
       }
     );
@@ -388547,10 +388552,6 @@ var gatherEvents = () => (
           candidate = firstGrilling.hash ?? EMPTY_TREE;
         }
       } else {
-        const mergeBaseCandidate = Option_exports.isSome(base) && base.value !== headHash ? base.value : void 0;
-        if (mergeBaseCandidate !== void 0) {
-          candidate = mergeBaseCandidate;
-        }
       }
       if (candidate !== void 0 && hasCommitsAfterLastDone) {
         const candidateDiff = yield* git.diffRef(candidate, WORKFLOW_FILE_EXCLUDES).pipe(Effect_exports.catchAll(() => Effect_exports.succeed("")));
@@ -388577,7 +388578,7 @@ var gatherEvents = () => (
         const squashCycle = squashHistory.slice(prevDoneIdx + 1, lastDoneIdxForSquash + 1);
         let startIdx = -1;
         for (let i = squashCycle.length - 1; i >= 0; i--) {
-          if (subjectOf(squashCycle[i]) === NEW_TASK_SUBJECT) {
+          if (subjectOf(squashCycle[i]) === NEW_TASK_SUBJECT || subjectOf(squashCycle[i]) === REVIEWING_SUBJECT) {
             startIdx = i;
             break;
           }
@@ -388606,6 +388607,31 @@ var gatherEvents = () => (
     }
     const squashMsgPresent = yield* fs9.exists(resolve5(SQUASH_MSG_FILE));
     const squashMsgContent = squashMsgPresent ? yield* fs9.readFileString(resolve5(SQUASH_MSG_FILE)) : "";
+    const healthPresent = yield* fs9.exists(resolve5(HEALTH_FILE));
+    const healthContent = healthPresent ? yield* fs9.readFileString(resolve5(HEALTH_FILE)) : "";
+    const healthCommitted = healthPresent && !isUncommitted(HEALTH_FILE);
+    let healthFixBase;
+    if (config2.squash) {
+      const subjectOf = (c7) => (c7.message.split("\n")[0] ?? "").trim();
+      let firstHealthCheckHash;
+      let healthCheckCount = 0;
+      for (const commit3 of history) {
+        const s5 = subjectOf(commit3);
+        const isPackageStart = s5 === PLANNING_SUBJECT || s5 === PACKAGE_DONE_SUBJECT;
+        if (isPackageStart || commit3.removedErrors) {
+          firstHealthCheckHash = void 0;
+          healthCheckCount = 0;
+        }
+        if (s5 === HEALTH_CHECK_SUBJECT) {
+          healthCheckCount++;
+          if (healthCheckCount === 1) firstHealthCheckHash = commit3.hash;
+        }
+      }
+      if (healthCheckCount > 0 && firstHealthCheckHash !== void 0) {
+        const base2 = yield* git.resolveRef(`${firstHealthCheckHash}~1`).pipe(Effect_exports.catchAll(() => Effect_exports.succeed(EMPTY_TREE)));
+        healthFixBase = base2;
+      }
+    }
     const payload = {
       todoExists,
       todoCommitted,
@@ -388637,7 +388663,11 @@ var gatherEvents = () => (
       ...squashBase !== void 0 ? { squashBase } : {},
       ...squashDiff !== void 0 ? { squashDiff } : {},
       squashMsgPresent,
-      squashMsgContent
+      squashMsgContent,
+      healthPresent,
+      healthContent,
+      healthCommitted,
+      ...healthFixBase !== void 0 ? { healthFixBase } : {}
     };
     const resolveEvent = { type: "RESOLVE", payload };
     return [...commitEvents, resolveEvent];
@@ -388655,6 +388685,15 @@ var captureAndRevert = (git, subject, onRegen) => Effect_exports.gen(function* (
   yield* git.revertNoCommit("HEAD");
   return captured;
 });
+var reviewAgainst = (target) => Effect_exports.gen(function* () {
+  const git = yield* GitService;
+  const targetHash = yield* git.resolveRef(target);
+  const mergeBase = yield* git.mergeBase(target, "HEAD");
+  const mergeBaseHash = Option_exports.isNone(mergeBase) || mergeBase.value === targetHash ? targetHash : mergeBase.value;
+  const refDiff = yield* git.diffRef(mergeBaseHash, WORKFLOW_FILE_EXCLUDES);
+  if (refDiff.trim().length === 0) return void 0;
+  return { reviewBase: mergeBaseHash, refDiff };
+});
 var perform = (action) => (
   // fallow-ignore-next-line complexity
   Effect_exports.gen(function* () {
@@ -388667,7 +388706,7 @@ var perform = (action) => (
       // work in the tree, then re-derive. (No producer command — consume only.)
       case "transportReset": {
         yield* git.mixedResetHead();
-        return;
+        return { stop: false };
       }
       // New Feature: capture the raw input as `gtd: new task` (unless HEAD is
       // already there — the lost-seed regenerate case), revert it back to a
@@ -388675,7 +388714,7 @@ var perform = (action) => (
       case "seedNewFeature": {
         const captured = yield* captureAndRevert(git, NEW_TASK_SUBJECT, Effect_exports.void);
         yield* fs9.writeFileString(resolve5(TODO_FILE), seedTodo(captured));
-        return;
+        return { stop: false };
       }
       // Accept Review: capture the human's pending changeset durably as
       // `gtd: review feedback` (annotations, code edits, and new files alike),
@@ -388687,7 +388726,7 @@ var perform = (action) => (
         const captured = yield* captureAndRevert(git, REVIEW_FEEDBACK_SUBJECT, git.resetHard());
         yield* fs9.remove(resolve5(REVIEW_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.void));
         yield* fs9.writeFileString(resolve5(TODO_FILE), seedTodo(captured));
-        return;
+        return { stop: false };
       }
       // Grilling capture: the plan is already committed and the user sketched
       // code during the round. Fold the code diff (untracked included, steering
@@ -388710,7 +388749,7 @@ var perform = (action) => (
         }
         yield* fs9.writeFileString(resolve5(TODO_FILE), appendCapturedInput(todoNow, captured));
         yield* git.commitAllWithPrefix(GRILLING_SUBJECT);
-        return;
+        return { stop: false };
       }
       // Testing: commit the pending tree `gtd: building` (nothing pending in the
       // no-op-fixer case), run tests; on red write FEEDBACK (below cap) or ERRORS
@@ -388727,13 +388766,46 @@ var perform = (action) => (
           if (!committedBuilding) {
             yield* git.commitAllWithPrefix(BUILDING_SUBJECT);
           }
-          return;
+          return { stop: false };
         }
         const target = action.capReached ? ERRORS_FILE : FEEDBACK_FILE;
         const body = /\S/.test(result.output) ? result.output : EMPTY_FAILURE_SENTINEL;
         yield* fs9.writeFileString(resolve5(target), body);
         yield* git.commitAllWithPrefix(ERRORS_SUBJECT);
-        return;
+        return { stop: false };
+      }
+      // Health check: run tests on an idle/clean tree.
+      // Green, no prior fixes → stop immediately (no commit).
+      // Green, fixes exist → stop immediately (squash handled via healthFixBase
+      //   when gatherEvents sets it; the machine resolves squashing state).
+      // Red below cap → write HEALTH.md (uncommitted); resolveHealth will
+      //   commit it as `gtd: health-check` via `commitPending removeHealth`.
+      // Red at cap → write ERRORS.md and commit `gtd: health-check` immediately
+      //   so the Escalate state fires on the next resolve.
+      case "runHealthCheck": {
+        if (action.commitErrorsReset === true) {
+          yield* git.commitAllWithPrefix(HEALTH_FIX_SUBJECT);
+        }
+        const runner = yield* TestRunner;
+        const result = yield* runner.run();
+        if (result.exitCode === 0) {
+          if (action.healthFixBase !== void 0 && action.commitErrorsReset !== true) {
+            yield* fs9.writeFileString(
+              resolve5(SQUASH_MSG_FILE),
+              "chore: health-check cycle squash\n"
+            );
+            return { stop: false };
+          }
+          return { stop: true };
+        }
+        const body = /\S/.test(result.output) ? result.output : EMPTY_FAILURE_SENTINEL;
+        if (action.capReached) {
+          yield* fs9.writeFileString(resolve5(ERRORS_FILE), body);
+          yield* git.commitAllWithPrefix(HEALTH_CHECK_SUBJECT);
+        } else {
+          yield* fs9.writeFileString(resolve5(HEALTH_FILE), body);
+        }
+        return { stop: false };
       }
       // Grilling / Grilled / Planning / Fixing: commit the pending tree under a
       // fixed phase prefix. Fixing sets `removeFeedback` so FEEDBACK.md's removal
@@ -388747,11 +388819,14 @@ var perform = (action) => (
         if (action.removeTodo === true) {
           yield* fs9.remove(resolve5(TODO_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.void));
         }
+        if (action.removeHealth === true) {
+          yield* fs9.remove(resolve5(HEALTH_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.void));
+        }
         if (action.removeTodo !== true) {
           yield* formatFile(resolve5(TODO_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.void));
         }
         yield* git.commitAllWithPrefix(action.prefix);
-        return;
+        return { stop: false };
       }
       // Close package: remove the (maybe-empty / maybe-absent) FEEDBACK.md, rm
       // the first (finished) package dir (+ the now-empty `.gtd/`), commit
@@ -388764,19 +388839,19 @@ var perform = (action) => (
           yield* git.removePackageDir(`${GTD_DIR}/${first2.name}`);
         }
         yield* git.commitAllWithPrefix(PACKAGE_DONE_SUBJECT);
-        return;
+        return { stop: false };
       }
       // Await Review: commit REVIEW.md as `gtd: awaiting review`.
       case "commitReview": {
         yield* formatFile(resolve5(REVIEW_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.void));
         yield* git.commitAllWithPrefix(AWAITING_REVIEW_SUBJECT);
-        return;
+        return { stop: false };
       }
       // Done: rm REVIEW.md, commit `gtd: done`.
       case "done": {
         yield* fs9.remove(resolve5(REVIEW_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.void));
         yield* git.commitAllWithPrefix(DONE_SUBJECT);
-        return;
+        return { stop: false };
       }
       // Squash: rm SQUASH_MSG.md, soft-reset to squashBase, commit everything
       // under the provided commit message.
@@ -388784,7 +388859,7 @@ var perform = (action) => (
         yield* fs9.remove(resolve5(SQUASH_MSG_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.void));
         yield* git.softResetTo(action.squashBase);
         yield* git.commitAllWithPrefix(action.commitMessage);
-        return;
+        return { stop: false };
       }
     }
   }).pipe(Effect_exports.mapError((e7) => e7 instanceof Error ? e7 : new Error(String(e7))))
@@ -388802,14 +388877,17 @@ var GtdStateError = class extends Error {
 var foldCounters = (events) => {
   let testFixCount = 0;
   let reviewFixCount = 0;
+  let healthFixCount = 0;
   for (const event of events) {
     if (event.type !== "COMMIT") continue;
     if (event.isPackageStart || event.isFeedback || event.removedErrors) testFixCount = 0;
     if (event.isErrors) testFixCount += 1;
     if (event.isPackageStart) reviewFixCount = 0;
     if (event.isFeedback) reviewFixCount += 1;
+    if (event.isPackageStart || event.removedErrors) healthFixCount = 0;
+    if (event.isHealthCheck) healthFixCount += 1;
   }
-  return { testFixCount, reviewFixCount };
+  return { testFixCount, reviewFixCount, healthFixCount };
 };
 var isBoundary = (subject) => !subject.startsWith("gtd: ") || subject === "gtd: done";
 var DEFAULT_PAYLOAD = {
@@ -388839,7 +388917,10 @@ var DEFAULT_PAYLOAD = {
   reviewThreshold: 3,
   squashEnabled: false,
   squashMsgPresent: false,
-  squashMsgContent: ""
+  squashMsgContent: "",
+  healthPresent: false,
+  healthContent: "",
+  healthCommitted: false
 };
 var buildContext = (p4, counters, grillingCase) => ({
   testFixCount: counters.testFixCount,
@@ -388852,7 +388933,7 @@ var buildContext = (p4, counters, grillingCase) => ({
   ...p4.squashDiff !== void 0 ? { squashDiff: p4.squashDiff } : {},
   lastCommitSubject: p4.lastCommitSubject,
   workingTreeClean: p4.workingTreeClean,
-  feedbackContent: p4.feedbackContent,
+  feedbackContent: p4.feedbackContent !== "" ? p4.feedbackContent : p4.healthContent,
   ...grillingCase !== void 0 ? { grillingCase } : {}
 });
 var assertLegal = (p4) => {
@@ -388866,7 +388947,32 @@ var assertLegal = (p4) => {
   if (p4.feedbackPresent && p4.reviewPresent) fail20("illegal combination: FEEDBACK.md + REVIEW.md");
   if (p4.feedbackPresent && !p4.gtdDirExists) fail20("illegal combination: FEEDBACK.md without .gtd");
   if (p4.errorsPresent && p4.feedbackPresent) fail20("illegal combination: ERRORS.md + FEEDBACK.md");
-  if (p4.errorsPresent && !p4.gtdDirExists) fail20("illegal combination: ERRORS.md without .gtd");
+  const isHealthCapEscalation = p4.lastCommitSubject === "gtd: health-check" || p4.lastCommitSubject === "gtd: health-fix";
+  if (p4.errorsPresent && !p4.gtdDirExists && !isHealthCapEscalation)
+    fail20("illegal combination: ERRORS.md without .gtd");
+  if (p4.healthPresent && p4.gtdDirExists) fail20("illegal combination: HEALTH.md + .gtd");
+  if (p4.healthPresent && p4.reviewPresent) fail20("illegal combination: HEALTH.md + REVIEW.md");
+  if (p4.healthPresent && p4.feedbackPresent) fail20("illegal combination: HEALTH.md + FEEDBACK.md");
+  if (p4.healthPresent && p4.errorsPresent) fail20("illegal combination: HEALTH.md + ERRORS.md");
+};
+var resolveHealth = (p4, counters) => {
+  const hasPendingWork = !p4.healthCommitted || !p4.workingTreeClean;
+  const prefix = p4.healthCommitted ? "gtd: health-fix" : "gtd: health-check";
+  return {
+    state: "health-fixing",
+    autoAdvance: true,
+    ...hasPendingWork ? {
+      edgeAction: {
+        kind: "commitPending",
+        prefix,
+        // Always remove HEALTH.md: on gtd: health-check this clears it so
+        // the next run re-enters resolveCleanOrIdle; on gtd: health-fix it
+        // clears the marker left by a prior health-check run.
+        removeHealth: true
+      }
+    } : {},
+    context: buildContext(p4, counters)
+  };
 };
 var resolveFeedback = (p4, counters) => {
   if (p4.feedbackEmpty) {
@@ -388992,22 +389098,21 @@ var resolveGrilling = (p4, counters, head7) => {
       context: buildContext(p4, counters, "iterate")
     };
   }
-  if (head7 === "gtd: grilled") {
-    return {
-      state: "grilled",
-      autoAdvance: true,
-      context: buildContext(p4, counters)
-    };
-  }
   return {
-    state: "grilled-review",
-    autoAdvance: false,
+    state: "grilled",
+    autoAdvance: true,
     edgeAction: { kind: "commitPending", prefix: "gtd: grilled" },
     context: buildContext(p4, counters)
   };
 };
 var resolveCleanOrIdle = (p4, counters, head7) => {
-  if (!p4.workingTreeClean || !isBoundary(head7) && head7 !== "gtd: package done") return null;
+  const isHealthHead = head7 === "gtd: health-check" || head7 === "gtd: health-fix";
+  if (!p4.workingTreeClean && !p4.pendingErrorsDeletion) return null;
+  if (!p4.workingTreeClean && p4.pendingErrorsDeletion && p4.gtdDirExists) return null;
+  if (!p4.workingTreeClean && p4.pendingErrorsDeletion && !isBoundary(head7) && head7 !== "gtd: package done" && !isHealthHead)
+    return null;
+  if (p4.workingTreeClean && !isBoundary(head7) && head7 !== "gtd: package done" && !isHealthHead)
+    return null;
   if (head7 === "gtd: done" && p4.squashEnabled && p4.squashBase !== void 0) {
     if (p4.squashMsgPresent) {
       return {
@@ -389024,9 +389129,20 @@ var resolveCleanOrIdle = (p4, counters, head7) => {
     return { state: "squashing", autoAdvance: true, context: buildContext(p4, counters) };
   }
   const reviewable = p4.hasCommitsAfterLastDone && p4.reviewBase !== void 0 && (p4.refDiff ?? "").trim().length > 0;
+  if (reviewable) {
+    return { state: "clean", autoAdvance: false, context: buildContext(p4, counters) };
+  }
+  const squashHealth = p4.squashEnabled && counters.healthFixCount > 0 && p4.healthFixBase !== void 0;
   return {
-    state: reviewable ? "clean" : "idle",
-    autoAdvance: false,
+    state: "health-check",
+    autoAdvance: true,
+    edgeAction: {
+      kind: "runHealthCheck",
+      errorCount: counters.healthFixCount,
+      capReached: counters.healthFixCount >= p4.fixAttemptCap,
+      ...squashHealth ? { healthFixBase: p4.healthFixBase } : {},
+      ...p4.pendingErrorsDeletion ? { commitErrorsReset: true } : {}
+    },
     context: buildContext(p4, counters)
   };
 };
@@ -389053,6 +389169,7 @@ var resolve4 = (events) => {
   }
   if (p4.errorsPresent)
     return { state: "escalate", autoAdvance: false, context: buildContext(p4, counters) };
+  if (p4.healthPresent) return resolveHealth(p4, counters);
   if (p4.feedbackPresent) return resolveFeedback(p4, counters);
   if (p4.gtdDirExists) return resolveGtdLifecycle(p4, counters, head7, corrupt);
   if (p4.reviewPresent) return resolveReviewLifecycle(p4, counters, head7);
@@ -389068,6 +389185,18 @@ var resolve4 = (events) => {
       context: buildContext(p4, counters)
     };
   }
+  if (p4.squashEnabled && p4.healthFixBase !== void 0 && p4.squashMsgPresent && !p4.codeDirty) {
+    return {
+      state: "squashing",
+      autoAdvance: false,
+      edgeAction: {
+        kind: "squashCommit",
+        squashBase: p4.healthFixBase,
+        commitMessage: p4.squashMsgContent
+      },
+      context: buildContext(p4, counters)
+    };
+  }
   if (isBoundary(head7) && !p4.workingTreeClean && !p4.todoCommitted || head7 === "gtd: new task" && p4.workingTreeClean) {
     return {
       state: "new-feature",
@@ -389079,6 +389208,20 @@ var resolve4 = (events) => {
   if (p4.todoExists) return resolveGrilling(p4, counters, head7);
   return resolveCleanOrIdle(p4, counters, head7) ?? corrupt();
 };
+var cleanResult = (args2) => ({
+  state: "clean",
+  autoAdvance: args2.autoAdvance,
+  context: {
+    ...buildContext(
+      {
+        ...DEFAULT_PAYLOAD,
+        reviewBase: args2.reviewBase,
+        refDiff: args2.refDiff
+      },
+      { testFixCount: 0, reviewFixCount: 0, healthFixCount: 0 }
+    )
+  }
+});
 
 // src/State.ts
 var EDGE_ONLY_STATES2 = /* @__PURE__ */ new Set([
@@ -389088,7 +389231,8 @@ var EDGE_ONLY_STATES2 = /* @__PURE__ */ new Set([
   "await-review",
   "accept-review",
   "close-package",
-  "done"
+  "done",
+  "health-check"
 ]);
 var isEdgeOnly = (state) => EDGE_ONLY_STATES2.has(state);
 var detect = () => Effect_exports.gen(function* () {
@@ -389100,6 +389244,19 @@ var detect = () => Effect_exports.gen(function* () {
 });
 
 // src/program.ts
+var IDLE_RESULT = {
+  state: "idle",
+  autoAdvance: false,
+  context: {
+    testFixCount: 0,
+    reviewFixCount: 0,
+    packages: DEFAULT_PAYLOAD.packages,
+    diff: DEFAULT_PAYLOAD.diff,
+    lastCommitSubject: DEFAULT_PAYLOAD.lastCommitSubject,
+    workingTreeClean: DEFAULT_PAYLOAD.workingTreeClean,
+    feedbackContent: DEFAULT_PAYLOAD.feedbackContent
+  }
+};
 var MAX_EDGE_HOPS = 100;
 function makeProgram(opts = {}) {
   const argv = opts.argv ?? process.argv;
@@ -389124,10 +389281,6 @@ function makeProgram(opts = {}) {
       yield* formatFile(args2[0]);
       return;
     }
-    if (sub !== void 0) {
-      return yield* Effect_exports.fail(new Error(`unknown command '${sub}'`));
-    }
-    const config2 = yield* ConfigService;
     const git = yield* GitService;
     const fs9 = yield* FileSystem_exports.FileSystem;
     const topLevel = yield* git.topLevel();
@@ -389140,6 +389293,50 @@ function makeProgram(opts = {}) {
         )
       );
     }
+    const config2 = yield* ConfigService;
+    if (sub === "review") {
+      const args2 = argv.slice(3).filter((a5) => a5.length > 0 && !a5.startsWith("--"));
+      if (args2.length === 0) {
+        return yield* Effect_exports.fail(new Error("gtd review: missing target argument"));
+      }
+      if (args2.length > 1) {
+        return yield* Effect_exports.fail(
+          new Error(
+            `gtd review: too many arguments \u2014 expected one target, got: ${args2.join(", ")}`
+          )
+        );
+      }
+      const target = args2[0];
+      const reviewResult = yield* reviewAgainst(target).pipe(
+        Effect_exports.catchAll(
+          (error) => Effect_exports.fail(new Error(`gtd review: cannot resolve ref '${target}': ${error.message}`))
+        )
+      );
+      if (reviewResult === void 0) {
+        return yield* Effect_exports.fail(
+          new Error(`gtd review: nothing to review (${target} diff is empty after filtering)`)
+        );
+      }
+      const { reviewBase, refDiff } = reviewResult;
+      yield* git.commitAllWithPrefix(REVIEWING_SUBJECT);
+      const result = cleanResult({ reviewBase, refDiff, autoAdvance: json2 });
+      const builtPrompt = buildPrompt(result, config2.resolveModel, json2 ? "json" : "plain");
+      if (json2) {
+        write4(
+          JSON.stringify({
+            state: result.state,
+            autoAdvance: result.autoAdvance,
+            prompt: builtPrompt
+          }) + "\n"
+        );
+      } else {
+        write4(builtPrompt);
+      }
+      return;
+    }
+    if (sub !== void 0) {
+      return yield* Effect_exports.fail(new Error(`unknown command '${sub}'`));
+    }
     let hops = 0;
     while (true) {
       hops += 1;
@@ -389150,7 +389347,22 @@ function makeProgram(opts = {}) {
       }
       const result = yield* detect();
       if (result.edgeAction !== void 0) {
-        yield* perform(result.edgeAction);
+        const { stop: stop2 } = yield* perform(result.edgeAction);
+        if (stop2) {
+          const builtPrompt2 = buildPrompt(IDLE_RESULT, config2.resolveModel, json2 ? "json" : "plain");
+          if (json2) {
+            write4(
+              JSON.stringify({
+                state: "idle",
+                autoAdvance: false,
+                prompt: builtPrompt2
+              }) + "\n"
+            );
+          } else {
+            write4(builtPrompt2);
+          }
+          return;
+        }
       }
       if (isEdgeOnly(result.state)) {
         continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {