@pmelab/gtd 2.2.0 → 2.4.0

package/README.md

@@ -5,10 +5,12 @@
 > in the first place. Now I have something that actually helps me.
 
 A git-aware CLI that drives a turn-taking loop between a human and an autonomous
-coding agent: capture an idea, grill it into a plan, decompose it into work
-packages, execute with parallel subagents, test, agentically review each
-package, and finally walk a human through a review — squashing the whole cycle
-into one conventional-commits commit at the end.
+coding agent: capture an idea, grill it into a product-level plan, grill that
+into a technical architecture, decompose it into work packages, execute with
+parallel subagents, test, agentically review each package, walk a human through
+a review, distill durable lessons from the cycle into the project's own docs,
+and finally squash the whole cycle into one conventional-commits commit at the
+end.
 
 Internally, gtd is a **pure fold** over git history. The decision core
 (`src/Machine.ts`) is a single IO-free function, `resolve(events)` — **no
@@ -18,7 +20,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)
 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 16 states, plus which actor (human or agent) is awaited there. A
+**one** of 21 states, plus which actor (human or agent) is awaited there. A
 single call resolves to a single state.
 
 Steering is entirely **machine-authored commit subjects** — there are no marker
@@ -27,14 +29,15 @@ files, sentinels, or auto-advance tails to parse. A turn commit looks like
 the machine performs itself between turns) looks like `gtd: tests green`.
 `src/Subjects.ts` is the closed grammar both the machine and the edge read.
 
-All workflow state lives under **`.gtd/`**: the plan (`.gtd/TODO.md`), work
+All workflow state lives under **`.gtd/`**: the product plan (`.gtd/TODO.md`),
+the technical architecture it converges into (`.gtd/ARCHITECTURE.md`), work
 packages (`.gtd/01-…/`), review records (`.gtd/REVIEW.md`, `.gtd/FEEDBACK.md`),
-and loop bookkeeping (`.gtd/ERRORS.md`, `.gtd/HEALTH.md`, `.gtd/SQUASH_MSG.md`).
-One rule follows for every agent in the loop: **never touch `.gtd/`** except the
-single file a prompt explicitly grants. A `TODO.md` or `REVIEW.md` at the
-repository root is the project's own file — gtd never reads, consumes, or
-deletes it. (Corollary: don't gitignore `.gtd/` — the workflow commits its state
-through it.)
+and loop bookkeeping (`.gtd/ERRORS.md`, `.gtd/HEALTH.md`, `.gtd/LEARNINGS.md`,
+`.gtd/SQUASH_MSG.md`). One rule follows for every agent in the loop: **never
+touch `.gtd/`** except the single file a prompt explicitly grants. A `TODO.md`
+or `REVIEW.md` at the repository root is the project's own file — gtd never
+reads, consumes, or deletes it. (Corollary: don't gitignore `.gtd/` — the
+workflow commits its state through it.)
 
 ## Quick start: the two-beat loop
 
@@ -55,9 +58,10 @@ An agent loop is a two-beat protocol repeated forever:
    act, then go back to step 1; at a pending checkpoint (`prompt` is null) go
    straight back to step 1.
 
-A human acts by editing files (answering questions in `.gtd/TODO.md`, annotating
-`.gtd/REVIEW.md`, fixing code) and then running `gtd step` to capture the edit
-as their turn and hand control back to the agent side of the loop.
+A human acts by editing files (answering questions in `.gtd/TODO.md` or
+`.gtd/ARCHITECTURE.md`, annotating `.gtd/REVIEW.md`, fixing code) and then
+running `gtd step` to capture the edit as their turn and hand control back to
+the agent side of the loop.
 
 ```bash
 gtd step-agent            # advance the machine's own bookkeeping
@@ -165,8 +169,8 @@ invocation authored (oldest→newest), then a final `state: <state>` line:
 
 ```
 committed: gtd(human): grilling
-committed: gtd: grilled
-state: grilled
+committed: gtd: architecting
+state: architecting
 ```
 
 `--json` emits `{state, actions, commits}` instead (see
@@ -295,9 +299,9 @@ single-line JSON output instead of plain text.
 
 ```json
 {
-  "state": "grilled",
+  "state": "architecting",
   "actions": ["capture the human turn as \"gtd(human): grilling\""],
-  "commits": ["gtd(human): grilling", "gtd: grilled"]
+  "commits": ["gtd(human): grilling", "gtd: architecting"]
 }
 ```
 
@@ -428,12 +432,14 @@ GTD_LOOP_AGENT_CMD='my-agent-cli --prompt "$GTD_LOOP_PROMPT"' gtd-loop
 
 ## States & subjects overview
 
-`resolve()` lands on exactly one of **16 states**: `grilling`, `grilled`,
-`planning`, `building`, `testing`, `fixing`, `escalate`, `agentic-review`,
-`close-package`, `review`, `await-review`, `done`, `squashing`, `idle`,
-`health-check`, `health-fixing`. Each state has a fixed awaited actor (see
-`awaitedActor` in `src/Machine.ts`): `idle`, `escalate`, and `await-review`
-await the **human**; every other state awaits the **agent**.
+`resolve()` lands on exactly one of **21 states**: `grilling`, `architecting`,
+`grilled`, `planning`, `building`, `testing`, `fixing`, `escalate`,
+`agentic-review`, `close-package`, `review`, `await-review`, `done`, `learning`,
+`await-learning-review`, `learning-apply`, `learning-applied`, `squashing`,
+`idle`, `health-check`, `health-fixing`. Each state has a fixed awaited actor
+(see `awaitedActor` in `src/Machine.ts`): `idle`, `escalate`, `await-review`,
+and `await-learning-review` await the **human**; every other state awaits the
+**agent**.
 
 For the full precedence ladder, illegal combinations, and the counter folds that
 drive the fix loops, see [STATES.md](STATES.md) — this section is a summary.
@@ -445,24 +451,28 @@ The closed set of gates:
 
 | Gate             | Authored by                                                        |
 | ---------------- | ------------------------------------------------------------------ |
-| `grilling`       | human (answers) / agent (plan iteration)                           |
+| `grilling`       | human (answers) / agent (product-plan iteration)                   |
+| `architecting`   | human (answers) / agent (architecture iteration)                   |
 | `grilled`        | agent (converged, ready to decompose)                              |
 | `building`       | agent (package work, or human feedback while agent is out of turn) |
 | `fixing`         | agent (test-fix or review-fix round)                               |
 | `agentic-review` | agent (writes .gtd/FEEDBACK.md verdict)                            |
 | `review`         | agent (writes .gtd/REVIEW.md) / human (approves or gives feedback) |
 | `squashing`      | agent (overwrites .gtd/SQUASH_MSG.md)                              |
+| `learning`       | agent (overwrites .gtd/LEARNINGS.md) / human (accepts or edits)    |
+| `learning-apply` | agent (integrates .gtd/LEARNINGS.md into CLAUDE.md/AGENTS.md/docs) |
 | `health-fixing`  | agent (idle health-check repair)                                   |
 | `escalate`       | human (deletes .gtd/ERRORS.md to resume)                           |
 
 ### Routing commits — `gtd: <phase>`
 
 Bookkeeping the machine authors itself between turns, never a turn a human or
-agent "wins": `gtd: grilled`, `gtd: planning`, `gtd: tests green`,
-`gtd: errors`, `gtd: package done`, `gtd: awaiting review`,
+agent "wins": `gtd: architecting`, `gtd: grilled`, `gtd: planning`,
+`gtd: tests green`, `gtd: errors`, `gtd: package done`, `gtd: awaiting review`,
 `gtd: review feedback`, `gtd: done`, `gtd: squash template`,
 `gtd: reviewing <hash>` (parameterized, from `gtd review`), `gtd: health-check`,
-`gtd: health-fix`.
+`gtd: health-fix`, `gtd: learning template`, `gtd: learning drafted`,
+`gtd: learning approved`, `gtd: learning applied`.
 
 Everything else — any non-`gtd` subject, and any `gtd: *` subject outside this
 closed set — is a **boundary commit**: inert as far as the machine's grammar is
@@ -471,25 +481,39 @@ this matters on upgrade.
 
 ## Workflow walkthroughs
 
-### Grilling
+### Grilling: two phases, product then architecture
 
 A dirty tree at a boundary HEAD (a fresh idea, sketched in a file or just left
 as pending code) is captured in **one** human turn: `gtd step` commits
 everything pending as `gtd(human): grilling` — nothing is reverted or seeded,
 the captured files stay in history. `gtd next` hands the agent that turn's diff;
-the agent develops `.gtd/TODO.md` into a concrete plan **in one turn**,
-proposing a **suggested default** for every open question, and leaves
-`.gtd/TODO.md` uncommitted for `gtd(agent): grilling`.
+the agent develops `.gtd/TODO.md` into a concrete **product-level** plan **in
+one turn** — user-facing decisions only, no architecture — proposing a
+**suggested default** for every open question, and leaves `.gtd/TODO.md`
+uncommitted for `gtd(agent): grilling`.
 
 There are no markers to answer — the human either:
 
 - **Accepts the suggested defaults**: runs a clean `gtd step` at the answer
-  gate. An empty `gtd(human): grilling` turn plus routing `gtd: grilled` lands
-  automatically, and `gtd next` emits the decompose prompt.
+  gate. An empty `gtd(human): grilling` turn plus routing `gtd: architecting`
+  lands automatically — `.gtd/ARCHITECTURE.md` is seeded from the converged
+  `.gtd/TODO.md` content and `.gtd/TODO.md` is deleted, in that one commit.
 - **Edits `.gtd/TODO.md`** with real answers, then runs `gtd step`, which
   captures the edit as a fresh `gtd(human): grilling` turn and hands it back to
   the agent for another round.
 
+Technical architecting works exactly the same way, one file later: the agent
+develops `.gtd/ARCHITECTURE.md` into a concrete **technical** plan — file/module
+structure, data model, tech-stack choices — and the human answers or accepts
+defaults at the `architecting` gate. Accepting converges to `gtd: grilled` and
+`gtd next` emits the decompose prompt (which now reads `.gtd/ARCHITECTURE.md`).
+
+**Escape hatch for already-technical input:** if the human's initial dirty tree
+already contains `.gtd/ARCHITECTURE.md` (their own technical sketch), `gtd step`
+captures the entry turn as `gtd(human): architecting` directly, skipping product
+grilling for that cycle entirely — no CLI flag needed, it's driven purely by
+which steering file is present.
+
 ### Build lifecycle: budgets
 
 Once decomposed, `.gtd/` holds ordered work packages. `gtd next` at
@@ -525,24 +549,26 @@ the threshold simply closes the package as usual.) Setting
 `agenticReview: false` force-approves every package immediately.
 
 A **do-nothing agent invocation** — `gtd step-agent` on a clean tree at ANY
-agent-awaited rest whose move is a file artifact (`grilling`, `grilled`,
-`building`, `fixing`, `agentic-review`, `review`, and `squashing` while
-`.gtd/SQUASH_MSG.md` still holds the unmodified template) — is inert: zero
-commits, no state consumed; `gtd next` re-emits the same prompt. This is
-load-bearing for the loop protocol, whose every iteration opens with
-`gtd step-agent` before the agent has acted: without the guard that opening beat
-would author junk empty turns — and worse, consume workflow state (an empty
-decompose turn would delete `.gtd/TODO.md` with no packages written; an empty
-squashing turn would squash the cycle under the placeholder template). The same
-guards hold at the classification layer for histories that already carry such
-turns: a `gtd(agent): grilled` HEAD only routes to `gtd: planning` when packages
-exist, a `gtd(agent): review` HEAD only routes to `gtd: awaiting review` when
-`.gtd/REVIEW.md` exists, and a squashing turn only squashes once the template
-has been overwritten. The one deliberate exception is `health-fixing`, whose
-empty turn is meaningful (the failure may have been environmental — the machine
-removes `.gtd/HEALTH.md` and re-tests). Human gates are unaffected: an empty
-**human** turn stays a signal (accept-defaults at grilling, clean approval at
-review).
+agent-awaited rest whose move is a file artifact (`grilling`, `architecting`,
+`grilled`, `building`, `fixing`, `agentic-review`, `review`, `squashing` while
+`.gtd/SQUASH_MSG.md` still holds the unmodified template, `learning` while
+`.gtd/LEARNINGS.md` still holds the unmodified template, and `learning-apply`
+unconditionally) — is inert: zero commits, no state consumed; `gtd next`
+re-emits the same prompt. This is load-bearing for the loop protocol, whose
+every iteration opens with `gtd step-agent` before the agent has acted: without
+the guard that opening beat would author junk empty turns — and worse, consume
+workflow state (an empty decompose turn would delete `.gtd/ARCHITECTURE.md` with
+no packages written; an empty squashing turn would squash the cycle under the
+placeholder template). The same guards hold at the classification layer for
+histories that already carry such turns: a `gtd(agent): grilled` HEAD only
+routes to `gtd: planning` when packages exist, a `gtd(agent): review` HEAD only
+routes to `gtd: awaiting review` when `.gtd/REVIEW.md` exists, and a squashing
+(or learning) turn only proceeds once its template has been overwritten. The one
+deliberate exception is `health-fixing`, whose empty turn is meaningful (the
+failure may have been environmental — the machine removes `.gtd/HEALTH.md` and
+re-tests). Human gates are unaffected: an empty **human** turn stays a signal
+(accept-defaults at grilling/architecting, clean approval at review,
+accept-the-draft-as-is at the learning review gate).
 
 ### Human review gate
 
@@ -586,22 +612,47 @@ their commit message is discarded; linked `git worktree` checkouts are
 unsupported. If you switch branches mid-review, gtd refuses to touch the foreign
 branch and prints the manual recovery command.
 
+### Learning
+
+With `learning: true` (the default), `gtd: done` (or the health-fix path's green
+re-test) is **not** a rest — the chain continues straight to
+`gtd: learning template`, writing and committing a `.gtd/LEARNINGS.md` template,
+running _before_ the squash decision so it still sees the pre-squash history.
+`gtd next` then emits the learning prompt: the agent walks the cycle's test
+failures, review feedback, and health-check rounds, keeps only
+durable/generalizable lessons, and overwrites `.gtd/LEARNINGS.md` with them.
+Once `gtd step-agent` captures that draft (`gtd(agent): learning`), it rests at
+**await-learning-review** for a human — who either accepts the draft as-is (an
+empty turn) or edits it; there is no reject path, so the very next `gtd step`
+always proceeds (`gtd(human): learning` → `gtd: learning approved`), resting at
+**learning-apply** for the agent. The agent integrates the approved learnings
+into the project's own docs (`CLAUDE.md`/`AGENTS.md`/wherever fits, its
+judgment); its turn (`gtd(agent): learning-apply`) removes `.gtd/LEARNINGS.md`
+and lands at `gtd: learning applied`, which then runs the same squash decision
+`gtd: done` runs today. With `learning: false`, `gtd: done` behaves exactly as
+it does without this section: no `.gtd/LEARNINGS.md` is ever written. Learning
+and squash are independent flags — either can be on without the other.
+
 ### Squash
 
-With `squash: true` (the default), `gtd: done` is **not** a rest — the same
-chain continues straight to `gtd: squash template`, writing and committing a
-`.gtd/SQUASH_MSG.md` template. `gtd next` then emits the squashing prompt: the
-agent overwrites `.gtd/SQUASH_MSG.md` with a real conventional-commits message
-(drawing on grilling-round decisions from history) and finishes its turn.
+With `squash: true` (the default), `gtd: done` (or, once learning has run,
+`gtd: learning applied`) is **not** a rest — the same chain continues straight
+to `gtd: squash template`, writing and committing a `.gtd/SQUASH_MSG.md`
+template. `gtd next` then emits the squashing prompt: the agent overwrites
+`.gtd/SQUASH_MSG.md` with a real conventional-commits message (drawing on
+grilling- and architecting-round decisions from history) and finishes its turn.
 `gtd step-agent` then performs the squash itself: `git reset --soft <base>` +
 `git commit`, collapsing every intermediate `gtd: *` commit of the cycle into
-one — including any review-feedback detours: the squash base is the cycle's
-ORIGINAL start (the first grilling run since the previous `gtd: done` boundary,
-or the `gtd: reviewing <hash>` anchor for an ad-hoc review cycle), not the most
-recent re-grilling round — the collapse folds the whole cycle into one, using
-the overwritten message's content verbatim (turn position, not message content,
-triggers the squash). With `squash: false`, `gtd: done` is the resting boundary
-and no template is ever written.
+one — including any review-feedback detours, and the learning phase's own
+commits if learning ran: the squash base is the cycle's ORIGINAL start (the
+first grilling or, via the escape hatch, architecting turn since the previous
+`gtd: done` boundary, or the `gtd: reviewing <hash>` anchor for an ad-hoc review
+cycle), not the most recent re-grilling round — the collapse folds the whole
+cycle into one, using the overwritten message's content verbatim (turn position,
+not message content, triggers the squash). Doc edits made during
+`learning-apply` survive in the squashed tree, not as their own commit. With
+`squash: false`, `gtd: done` (or `gtd: learning applied`) is the resting
+boundary and no template is ever written.
 
 ### Health check
 
@@ -610,9 +661,9 @@ runs `testCommand` as a health check rather than settling immediately. Green
 settles idle with zero commits. Red below `fixAttemptCap` writes
 `.gtd/HEALTH.md` and rests at **Health Fixing** for the agent; the fixer's own
 turn (`gtd(agent): health-fixing`) removes `.gtd/HEALTH.md` and re-tests in the
-same chain — a green re-test continues to squash (if enabled) or idle; red
-repeats the health-fix loop; red at the cap writes `.gtd/ERRORS.md` and
-escalates.
+same chain — a green re-test continues to learning (if enabled), then squash (if
+enabled), or idle; red repeats the health-fix loop; red at the cap writes
+`.gtd/ERRORS.md` and escalates.
 
 ### Escalate / budget reset
 
@@ -624,24 +675,29 @@ fix-attempt budget to zero.
 
 ## States & subjects: overview table
 
-| State            | Awaits         | Turn/routing subject at rest                                     |
-| ---------------- | -------------- | ---------------------------------------------------------------- |
-| `grilling`       | human or agent | `gtd(human): grilling` / `gtd(agent): grilling`                  |
-| `grilled`        | agent          | `gtd: grilled`                                                   |
-| `planning`       | agent          | `.gtd/` modified                                                 |
-| `building`       | agent          | `gtd: planning` / `gtd: package done`                            |
-| `testing`        | — (edge-only)  | mid-chain only                                                   |
-| `fixing`         | agent          | `gtd: errors`                                                    |
-| `escalate`       | human          | `.gtd/ERRORS.md` present                                         |
-| `agentic-review` | agent          | `gtd: tests green`                                               |
-| `close-package`  | — (edge-only)  | mid-chain only                                                   |
-| `review`         | agent          | `gtd: package done` (no more packages) / `gtd: reviewing <hash>` |
-| `await-review`   | human          | `gtd: awaiting review`                                           |
-| `done`           | — (edge-only)  | `gtd: done`                                                      |
-| `squashing`      | agent          | `gtd: squash template`                                           |
-| `idle`           | human          | no steering files, green health check                            |
-| `health-check`   | — (edge-only)  | mid-chain only                                                   |
-| `health-fixing`  | agent          | `.gtd/HEALTH.md` present                                         |
+| State                   | Awaits         | Turn/routing subject at rest                                     |
+| ----------------------- | -------------- | ---------------------------------------------------------------- |
+| `grilling`              | human or agent | `gtd(human): grilling` / `gtd(agent): grilling`                  |
+| `architecting`          | human or agent | `gtd: architecting` / `gtd(agent): architecting`                 |
+| `grilled`               | agent          | `gtd: grilled`                                                   |
+| `planning`              | agent          | `.gtd/` modified                                                 |
+| `building`              | agent          | `gtd: planning` / `gtd: package done`                            |
+| `testing`               | — (edge-only)  | mid-chain only                                                   |
+| `fixing`                | agent          | `gtd: errors`                                                    |
+| `escalate`              | human          | `.gtd/ERRORS.md` present                                         |
+| `agentic-review`        | agent          | `gtd: tests green`                                               |
+| `close-package`         | — (edge-only)  | mid-chain only                                                   |
+| `review`                | agent          | `gtd: package done` (no more packages) / `gtd: reviewing <hash>` |
+| `await-review`          | human          | `gtd: awaiting review`                                           |
+| `done`                  | — (edge-only)  | `gtd: done`                                                      |
+| `learning`              | agent          | `gtd: learning template`                                         |
+| `await-learning-review` | human          | `gtd: learning drafted`                                          |
+| `learning-apply`        | agent          | `gtd: learning approved`                                         |
+| `learning-applied`      | — (edge-only)  | `gtd: learning applied`                                          |
+| `squashing`             | agent          | `gtd: squash template`                                           |
+| `idle`                  | human          | no steering files, green health check                            |
+| `health-check`          | — (edge-only)  | mid-chain only                                                   |
+| `health-fixing`         | agent          | `.gtd/HEALTH.md` present                                         |
 
 See [STATES.md](STATES.md) for the full precedence ladder, the counter folds,
 and every illegal steering-file combination.
@@ -674,18 +730,25 @@ built-in defaults apply. Supported filenames (searched in this order):
 - **`agenticReview`** (boolean, default `true`) — kill-switch for the
   per-package Agentic Review gate. Set `false` to force-approve every package
   and proceed directly to human review.
-- **`squash`** (boolean, default `true`) — after `gtd: done`, collapse the
-  cycle's `gtd: *` commits into a single conventional-commits commit. Set
-  `false` to keep the granular history.
+- **`squash`** (boolean, default `true`) — after `gtd: done` (or, once learning
+  has run, `gtd: learning applied`), collapse the cycle's `gtd: *` commits into
+  a single conventional-commits commit. Set `false` to keep the granular
+  history.
+- **`learning`** (boolean, default `true`) — after `gtd: done` (or the
+  health-fix path's green re-test), distill durable lessons from the cycle into
+  `.gtd/LEARNINGS.md`, have a human review them, then integrate them into the
+  project's own docs before the squash decision runs. Set `false` to skip the
+  phase entirely — independent of `squash`.
 - **`models`** — model selection for the subagent-spawning states:
   - `planning` — high-reasoning tier (default `claude-opus-4-8`), used by
-    `decompose` (the `grilled`/`planning` states), `grilling`, `agentic-review`,
-    and `clean` (the `review`/`squashing` states).
+    `decompose` (the `grilled`/`planning` states), `grilling`, `architecting`,
+    `agentic-review`, and `clean` (the `review`/`squashing`/`learning`/
+    `learning-apply` states).
   - `execution` — everyday tier (default `claude-sonnet-4-8`), used by
     `building` and `fixing`.
   - `states.*` — per-state overrides keyed by `decompose`, `grilling`,
-    `building`, `fixing`, `agentic-review`, `clean`. Unknown `states` keys are
-    **rejected**.
+    `architecting`, `building`, `fixing`, `agentic-review`, `clean`. Unknown
+    `states` keys are **rejected**.
 - **`$schema`** (string, optional) — stripped before validation, so it never
   counts as an unknown key. Point it at the published schema for editor-backed
   autocompletion. A `schema.json` is generated from the config schema at build
@@ -739,6 +802,7 @@ fixAttemptCap: 3
 reviewThreshold: 3
 agenticReview: true
 squash: true
+learning: true
 models:
   planning: claude-opus-4-8
   execution: claude-sonnet-4-8
@@ -772,7 +836,7 @@ models:
 ### Decompose
 
 The Grilled/Planning states spawn a planning-model subagent that breaks
-`.gtd/TODO.md` into executable work packages under `.gtd/`:
+`.gtd/ARCHITECTURE.md` into executable work packages under `.gtd/`:
 
 ```
 .gtd/