@pmelab/gtd 1.9.1 → 1.10.0

package/README.md

@@ -218,7 +218,10 @@ The last commit subject is bucketed two ways:
    Review; uncommitted → Await Review (commits REVIEW.md and auto-advances to
    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.
+   Squashing; unrelated code dirty → New Feature. 8a. **Green health check + ≥1
+   `gtd: health-fix` + `squash` enabled** → Squashing (same agent-authored
+   conventional-commits path as the feature-cycle squash — no hardcoded
+   placeholder).
 6. **Boundary HEAD + pending changes** (and no `.gtd`/REVIEW/FEEDBACK), or HEAD
    `gtd: new task` + clean tree (regenerate a lost seed) → New Feature.
 7. **TODO.md present** → Grilling / Grilled.
@@ -254,7 +257,7 @@ flowchart TD
     P4 -->|"uncommitted"| Await["Await Review — commit gtd: awaiting review"]:::edge
     Await -.->|"re-resolve"| Done
     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 enabled"| Squashing["Squashing — agent authors conventional-commits message, reset --soft base, squash commit"]:::agent
     Done -->|"squash disabled"| Idle
     Squashing --> Idle["Idle — nothing to do (STOP)"]:::gate
     P5 -->|yes| NewFeature["New Feature — gtd: new task, revert, seed TODO"]:::edge
@@ -756,6 +759,7 @@ Commands:
   (default)        Run the gtd driver loop — detect state, emit next prompt
   format <file>    Format a markdown file in place
   review <target>  Ad-hoc human review against a git ref or branch
+  status           Print current state, next state, and pending edge actions (no actions, no prompt)
 
 Options:
   --json           Output structured JSON instead of plain text
@@ -770,7 +774,7 @@ repository-state work — they run outside a repo and in any repo state.
 
 ## Subcommands
 
-gtd ships two subcommands: `format` and `review`.
+gtd ships three subcommands: `format`, `review`, and `status`.
 
 ## Review subcommand
 
@@ -809,6 +813,82 @@ All errors exit with **code 1** and write a message to **stderr**:
   (nothing to review):
   `gtd review: nothing to review (<target> diff is empty after filtering)`
 
+## Status subcommand
+
+```bash
+gtd status
+```
+
+Pure, read-only introspection. Prints the current machine state, the state the
+next real `gtd` run would stop at, and a short summary of the edge actions the
+next run would perform. Performs **nothing** (no commit, reset, or file write)
+and prints **no prompt** — guaranteed side-effect free.
+
+### Fields
+
+| Field             | Description                                                       |
+| ----------------- | ----------------------------------------------------------------- |
+| `state`           | Current machine state                                             |
+| `nextState`       | State the next `gtd` run would stop at, or `null` for edge-only   |
+| `willAutoAdvance` | `true` when the current state is edge-only (auto-advances on run) |
+| `edgeActions`     | List of edge actions the next run would perform before prompting  |
+
+### One-hop semantics
+
+`status` runs the same read-only gather+resolve the driver's first iteration
+does, then reports it without looping or performing.
+
+- A **prompt-bearing / human / terminal** current state reports itself as
+  `nextState`. The next run performs any pending edge action, then prompts
+  there.
+- An **edge-only** current state reports `nextState: null` and
+  `willAutoAdvance: true`, naming the immediate edge action. Because the landing
+  state after auto-advance depends on side effects (test pass/fail, commits)
+  that `status` refuses to run, it honestly reports the current state rather
+  than guessing a landing state. There is **no** multi-hop simulation.
+
+### Output
+
+Default (human-readable) — `building` example:
+
+```
+State:      building
+Next state: building (next run prompts here)
+Edge actions:
+  - commit pending changes as "gtd: building"
+```
+
+With `--json` — same example:
+
+```json
+{
+  "state": "building",
+  "nextState": "building",
+  "willAutoAdvance": false,
+  "edgeActions": ["commit pending changes as \"gtd: building\""]
+}
+```
+
+Edge-only example (`testing` state):
+
+```json
+{
+  "state": "testing",
+  "nextState": null,
+  "willAutoAdvance": true,
+  "edgeActions": ["run the test suite (attempt 1)"]
+}
+```
+
+The JSON envelope contains no `prompt` field — this distinguishes it from the
+default `gtd` run and `gtd review` JSON output.
+
+### Requirements
+
+- Must be run from the **repository root** (same cwd guard as other repo
+  commands).
+- Takes **no arguments** — extra args are rejected with an error.
+
 ## Format subcommand
 
 `gtd format` formats a markdown file in place: