@pmelab/gtd 1.9.2 → 1.10.0

package/README.md

@@ -759,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
@@ -773,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
 
@@ -812,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:

package/dist/gtd.bundle.mjs

@@ -389281,6 +389281,37 @@ var EDGE_ONLY_STATES2 = /* @__PURE__ */ new Set([
   "health-check"
 ]);
 var isEdgeOnly = (state) => EDGE_ONLY_STATES2.has(state);
+var edgeActionHandlers = {
+  transportReset: () => "reset the working tree to the gtd: transport parent",
+  seedNewFeature: () => "seed a new feature (write the initial TODO.md)",
+  seedAcceptReview: () => "seed the accept-review step",
+  captureGrillingEdits: () => "capture pending grilling edits into TODO.md",
+  runTest: (a5) => `run the test suite (attempt ${a5.errorCount + 1}${a5.capReached ? ", cap reached" : ""})`,
+  commitPending: (a5) => {
+    let msg = `commit pending changes as "${a5.prefix}"`;
+    if (a5.removeTodo) msg += " (removing TODO.md)";
+    if (a5.removeFeedback) msg += " (removing FEEDBACK.md)";
+    if (a5.removeHealth) msg += " (removing HEALTH.md)";
+    return msg;
+  },
+  runHealthCheck: (a5) => `run the health check${a5.commitErrorsReset ? " (resetting the error budget)" : ""}`,
+  closePackage: () => "close the active package (commit gtd: package done)",
+  commitReview: () => "commit the review record (REVIEW.md)",
+  done: () => "finalize the review cycle (commit gtd: done)",
+  squashCommit: (a5) => `squash the cycle onto ${a5.squashBase}`,
+  removeHealthSentinel: () => "remove the health-squash sentinel before prompting for a squash message",
+  removeStraySquashMsg: () => "remove a stray SQUASH_MSG.md"
+};
+var describeEdgeAction = (a5) => edgeActionHandlers[a5.kind](a5);
+var describeStatus = (result) => {
+  const willAutoAdvance = isEdgeOnly(result.state);
+  return {
+    state: result.state,
+    nextState: willAutoAdvance ? null : result.state,
+    willAutoAdvance,
+    edgeActions: result.edgeAction ? [describeEdgeAction(result.edgeAction)] : []
+  };
+};
 var detect = () => Effect_exports.gen(function* () {
   const events = yield* gatherEvents();
   return yield* Effect_exports.try({
@@ -389298,6 +389329,7 @@ Commands:
   (default)        Run the gtd driver loop \u2014 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
@@ -389320,6 +389352,24 @@ var IDLE_RESULT = {
   }
 };
 var MAX_EDGE_HOPS = 100;
+var renderStatus = (s5) => {
+  const lines3 = [];
+  lines3.push(`State:      ${s5.state}`);
+  if (s5.willAutoAdvance) {
+    lines3.push(`Next state: (edge-only \u2014 next run performs the action(s) below and auto-advances)`);
+  } else {
+    lines3.push(`Next state: ${s5.nextState} (next run prompts here)`);
+  }
+  if (s5.edgeActions.length === 0) {
+    lines3.push(`Edge actions: none`);
+  } else {
+    lines3.push(`Edge actions:`);
+    for (const action of s5.edgeActions) {
+      lines3.push(`  - ${action}`);
+    }
+  }
+  return lines3.join("\n") + "\n";
+};
 function makeProgram(opts = {}) {
   const argv = opts.argv ?? process.argv;
   const write4 = opts.write ?? ((chunk4) => process.stdout.write(chunk4));
@@ -389404,6 +389454,22 @@ function makeProgram(opts = {}) {
       }
       return;
     }
+    if (sub === "status") {
+      const args2 = argv.slice(3).filter((a5) => a5.length > 0 && !a5.startsWith("--"));
+      if (args2.length > 0) {
+        return yield* Effect_exports.fail(
+          new Error(`gtd status: too many arguments \u2014 expected none, got: ${args2.join(", ")}`)
+        );
+      }
+      const result = yield* detect();
+      const summary5 = describeStatus(result);
+      if (json2) {
+        write4(JSON.stringify(summary5) + "\n");
+      } else {
+        write4(renderStatus(summary5));
+      }
+      return;
+    }
     if (sub !== void 0) {
       return yield* Effect_exports.fail(new Error(`unknown command '${sub}'`));
     }

package/package.json

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