@pmelab/gtd 2.1.0 → 2.3.0

package/README.md

@@ -7,8 +7,9 @@
 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.
+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 +19,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 20 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
@@ -29,12 +30,12 @@ the machine performs itself between turns) looks like `gtd: tests green`.
 
 All workflow state lives under **`.gtd/`**: the plan (`.gtd/TODO.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
 
@@ -116,6 +117,12 @@ to cwd, so it refuses with a clear error if invoked from a subdirectory.
 `--jsn`) is rejected with a usage error rather than silently ignored, so a
 mistyped flag can never degrade a JSON caller to plain-text mode.
 
+One nuance to "(no mutation)": `next` and `status` never author commits or
+change workflow state, but while a human review is pending they do maintain the
+review checkout window (closing it to read state, re-arming it on the way out —
+see [Human review gate](#human-review-gate)), which transiently moves HEAD and
+the index. The working tree is never touched.
+
 ### `gtd step` / `gtd step-agent`
 
 Both drive the **same fixpoint loop** — gather → resolve → perform the returned
@@ -422,12 +429,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`,
+`resolve()` lands on exactly one of **20 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**.
+`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.
@@ -446,6 +455,8 @@ The closed set of gates:
 | `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)                           |
 
@@ -456,7 +467,8 @@ agent "wins": `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
@@ -520,23 +532,25 @@ the threshold simply closes the package as usual.) Setting
 
 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).
+`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/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
+(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, clean approval at review, accept-the-draft-as-is
+at the learning review gate).
 
 ### Human review gate
 
@@ -547,28 +561,79 @@ Once `.gtd/` is fully closed, the machine writes `.gtd/REVIEW.md` and rests at
   plus routing `gtd: done`.
 - Flipping only `- [ ]` → `- [x]` checkboxes in `.gtd/REVIEW.md` — checkbox-only
   edits are also treated as clean approval.
+- Deleting `.gtd/REVIEW.md` outright.
 
 Any **substantive** edit — to `.gtd/REVIEW.md` prose, or to the reviewed code
 itself — is feedback: `gtd(human): review` plus routing `gtd: review feedback`,
 `.gtd/REVIEW.md` removed, and `gtd next` re-emits a grilling prompt to the agent
 that inlines the human's finding.
 
+**The review diff lives in your editor.** While the gate is pending, gtd holds
+open a _review checkout window_: it saves the real head to
+`refs/gtd/review-head`, then rewinds HEAD and the index to the review base with
+`git reset --mixed`, leaving the working tree untouched. Every editor's standard
+git integration now shows the entire reviewable diff as ordinary uncommitted
+changes — SCM panel, gutter marks, per-file diffs. Review it there:
+
+- **Edit** anything (code or `.gtd/REVIEW.md` prose) → feedback.
+- **Discard a hunk** in the editor → that reversion IS the feedback: the agent
+  is re-grilled with it.
+- **Delete a surfaced file** → reject-this-file feedback.
+- Touch nothing (or tick checkboxes / delete `.gtd/REVIEW.md`) → approval.
+
+Any gtd invocation closes the window first (restoring HEAD/index exactly, so
+only your own edits remain dirty — they land as their own separate
+`gtd(human): review` commit, never mixed into the reviewed work), and
+`gtd next`/`gtd status` re-arm it on their way out. The mechanics are
+crash-safe; details and invariants in STATES.md ("The review checkout window").
+
+Caveats while a review is pending: don't push (the branch tip rests at the
+review base — the real head is safe under `refs/gtd/review-head`); commits you
+make manually survive as working-tree content and become review feedback, but
+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.
-`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.
+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-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, and the learning phase's own commits if learning
+ran: 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). 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
 
@@ -577,9 +642,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
 
@@ -591,24 +656,28 @@ 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`                  |
+| `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.
@@ -641,13 +710,19 @@ 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).
+    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`,
@@ -706,6 +781,7 @@ fixAttemptCap: 3
 reviewThreshold: 3
 agenticReview: true
 squash: true
+learning: true
 models:
   planning: claude-opus-4-8
   execution: claude-sonnet-4-8

package/dist/gtd.bundle.mjs

@@ -367051,6 +367051,7 @@ var builtinTierDefault = {
 var DEFAULT_TEST_COMMAND = "npm run test";
 var DEFAULT_AGENTIC_REVIEW = true;
 var DEFAULT_SQUASH = true;
+var DEFAULT_LEARNING = true;
 var DEFAULT_FIX_ATTEMPT_CAP = 3;
 var DEFAULT_REVIEW_THRESHOLD = 3;
 var ModelStatesSchema = Schema_exports.Struct({
@@ -367071,6 +367072,7 @@ var ConfigSchema = Schema_exports.Struct({
   models: Schema_exports.optional(ModelsSchema),
   agenticReview: Schema_exports.optional(Schema_exports.Boolean),
   squash: Schema_exports.optional(Schema_exports.Boolean),
+  learning: Schema_exports.optional(Schema_exports.Boolean),
   fixAttemptCap: Schema_exports.optional(Schema_exports.Int.pipe(Schema_exports.greaterThanOrEqualTo(0))),
   reviewThreshold: Schema_exports.optional(Schema_exports.Int.pipe(Schema_exports.greaterThanOrEqualTo(1)))
 });
@@ -367202,6 +367204,7 @@ var toOperations = (decoded) => {
     resolveModel,
     agenticReview: decoded.agenticReview ?? DEFAULT_AGENTIC_REVIEW,
     squash: decoded.squash ?? DEFAULT_SQUASH,
+    learning: decoded.learning ?? DEFAULT_LEARNING,
     fixAttemptCap: decoded.fixAttemptCap ?? DEFAULT_FIX_ATTEMPT_CAP,
     reviewThreshold: decoded.reviewThreshold ?? DEFAULT_REVIEW_THRESHOLD
   };
@@ -367862,6 +367865,10 @@ var makeGitImpl = (executor, root2) => {
         (hash3) => /^[0-9a-f]{40}$/.test(hash3) ? Effect_exports.succeed(hash3) : Effect_exports.fail(new Error(`Invalid ref: ${ref}`))
       )
     ),
+    readRefOption: (ref) => exec2("git", "rev-parse", "--verify", "--quiet", ref).pipe(
+      Effect_exports.map((s5) => Option_exports.some(s5.trim())),
+      Effect_exports.catchAll(() => Effect_exports.succeed(Option_exports.none()))
+    ),
     topLevel: () => exec2("git", "rev-parse", "--show-toplevel").pipe(Effect_exports.map((s5) => s5.trim())),
     resolveDefaultBranch: () => exec2("git", "rev-parse", "--abbrev-ref", "origin/HEAD").pipe(
       Effect_exports.map((s5) => s5.trim()),
@@ -367995,7 +368002,20 @@ var makeGitImpl = (executor, root2) => {
         )
       );
     }).pipe(Effect_exports.asVoid),
-    softResetTo: (ref) => exec2("git", "reset", "--soft", ref).pipe(Effect_exports.asVoid)
+    softResetTo: (ref) => exec2("git", "reset", "--soft", ref).pipe(Effect_exports.asVoid),
+    updateRef: (ref, hash3) => exec2("git", "update-ref", ref, hash3).pipe(Effect_exports.asVoid),
+    deleteRef: (ref) => exec2("git", "update-ref", "-d", ref).pipe(
+      Effect_exports.asVoid,
+      Effect_exports.catchAll(() => Effect_exports.void)
+    ),
+    mixedResetTo: (ref) => exec2("git", "reset", "--mixed", ref).pipe(Effect_exports.asVoid),
+    restoreStagedFrom: (source2, paths) => paths.length === 0 ? Effect_exports.void : exec2("git", "restore", "--staged", `--source=${source2}`, "--", ...paths).pipe(
+      Effect_exports.asVoid,
+      // `git restore` errors when a pathspec matches nothing at either
+      // side — for an optional dir like `.gtd/` that's a no-op, not a failure.
+      Effect_exports.catchAll(() => Effect_exports.void)
+    ),
+    addIntentToAdd: () => exec2("git", "add", "--intent-to-add", ".").pipe(Effect_exports.asVoid)
   };
 };
 var makeLiveEffect = Effect_exports.gen(function* () {
@@ -387748,7 +387768,11 @@ var ROUTING_SUBJECT = {
   done: "gtd: done",
   "squash-template": "gtd: squash template",
   "health-check": "gtd: health-check",
-  "health-fix": "gtd: health-fix"
+  "health-fix": "gtd: health-fix",
+  "learning-template": "gtd: learning template",
+  "learning-drafted": "gtd: learning drafted",
+  "learning-approved": "gtd: learning approved",
+  "learning-applied": "gtd: learning applied"
 };
 var reviewingSubject = (baseHash) => `gtd: reviewing ${baseHash}`;
 var TURN_RE = /^gtd\((human|agent)\): (.+)$/;
@@ -387761,7 +387785,9 @@ var TURN_GATES = /* @__PURE__ */ new Set([
   "review",
   "squashing",
   "health-fixing",
-  "escalate"
+  "escalate",
+  "learning",
+  "learning-apply"
 ]);
 var ROUTING_SUBJECT_TO_PHASE = new Map(
   Object.entries(ROUTING_SUBJECT).map(([phase, subject]) => [
@@ -387801,6 +387827,7 @@ var FEEDBACK_FILE = `${GTD_DIR}/FEEDBACK.md`;
 var ERRORS_FILE = `${GTD_DIR}/ERRORS.md`;
 var HEALTH_FILE = `${GTD_DIR}/HEALTH.md`;
 var SQUASH_MSG_FILE = `${GTD_DIR}/SQUASH_MSG.md`;
+var LEARNINGS_FILE = `${GTD_DIR}/LEARNINGS.md`;
 var LEGACY_FEEDBACK_FILE = "FEEDBACK.md";
 var emptyFailureSentinel = (command, exitCode3) => `Test command \`${command}\` failed with exit code ${exitCode3} and produced no output.`;
 var DONE_SUBJECT = "gtd: done";
@@ -387809,6 +387836,18 @@ var GATE_OWN_STEERING_FILE = {
   grilling: TODO_FILE,
   review: REVIEW_FILE
 };
+var SQUASH_OR_LEARNING_ROUTING_PHASES = /* @__PURE__ */ new Set([
+  "squash-template",
+  "learning-template",
+  "learning-drafted",
+  "learning-approved",
+  "learning-applied"
+]);
+var SQUASH_OR_LEARNING_TURN_GATES = /* @__PURE__ */ new Set([
+  "squashing",
+  "learning",
+  "learning-apply"
+]);
 var turnDiffExcludes = (gate) => {
   const ownFile = GATE_OWN_STEERING_FILE[gate];
   return ownFile ? [...WORKFLOW_FILE_EXCLUDES, `!${ownFile}`] : WORKFLOW_FILE_EXCLUDES;
@@ -388079,8 +388118,8 @@ var gatherEvents = (invoker) => (
     let squashBase;
     let squashDiff;
     const headParsedForSquash = parseSubject(lastCommitSubject);
-    const inSquashChain = lastCommitSubject === DONE_SUBJECT || headParsedForSquash.kind === "routing" && headParsedForSquash.phase === "squash-template" || headParsedForSquash.kind === "turn" && headParsedForSquash.actor === "agent" && headParsedForSquash.gate === "squashing";
-    if (hasCommits && inSquashChain && config2.squash) {
+    const inSquashOrLearningChain = lastCommitSubject === DONE_SUBJECT || headParsedForSquash.kind === "routing" && SQUASH_OR_LEARNING_ROUTING_PHASES.has(headParsedForSquash.phase) || headParsedForSquash.kind === "turn" && SQUASH_OR_LEARNING_TURN_GATES.has(headParsedForSquash.gate);
+    if (hasCommits && inSquashOrLearningChain && (config2.squash || config2.learning)) {
       const squashHistory = history;
       let lastDoneIdxForSquash = -1;
       let prevDoneIdx = -1;
@@ -388126,11 +388165,13 @@ var gatherEvents = (invoker) => (
     }
     const squashMsgPresent = yield* fs9.exists(resolve5(SQUASH_MSG_FILE));
     const squashMsgIsTemplate = squashMsgPresent && (yield* fs9.readFileString(resolve5(SQUASH_MSG_FILE))).trim() === SQUASH_TEMPLATE.trim();
+    const learningMsgPresent = yield* fs9.exists(resolve5(LEARNINGS_FILE));
+    const learningMsgIsTemplate = learningMsgPresent && (yield* fs9.readFileString(resolve5(LEARNINGS_FILE))).trim() === LEARNING_TEMPLATE.trim();
     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) {
+    if (config2.squash || config2.learning) {
       let firstHealthCheckHash;
       let healthCheckCount = 0;
       for (const commit3 of commitEvents) {
@@ -388204,7 +388245,10 @@ var gatherEvents = (invoker) => (
       healthPresent,
       healthContent,
       healthCommitted,
-      ...healthFixBase !== void 0 ? { healthFixBase } : {}
+      ...healthFixBase !== void 0 ? { healthFixBase } : {},
+      learningEnabled: config2.learning,
+      learningMsgPresent,
+      learningMsgIsTemplate
     };
     const resolveEvent = { type: "RESOLVE", payload };
     return [...commitEvents, resolveEvent];
@@ -388228,6 +388272,15 @@ var SQUASH_TEMPLATE = [
   "Longer description of the change, if needed.",
   ""
 ].join("\n");
+var LEARNING_TEMPLATE = [
+  "<!-- gtd: replace this file's content with the actual distilled learnings for this cycle. -->",
+  "<!-- Keep only durable, generalizable lessons \u2014 delete anything that's a one-off detail. -->",
+  "",
+  "## Learnings",
+  "",
+  "- ...",
+  ""
+].join("\n");
 var perform = (action) => (
   // fallow-ignore-next-line complexity
   Effect_exports.gen(function* () {
@@ -388262,6 +388315,9 @@ var perform = (action) => (
         if (action.removeHealth === true) {
           yield* fs9.remove(resolve5(HEALTH_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.void));
         }
+        if (action.removeLearning === true) {
+          yield* fs9.remove(resolve5(LEARNINGS_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.void));
+        }
         yield* git.commitAllWithPrefix(action.subject);
         return { stop: false };
       }
@@ -388309,6 +388365,14 @@ var perform = (action) => (
         yield* git.commitAllWithPrefix("gtd: squash template");
         return { stop: false };
       }
+      // Write the LEARNINGS.md template (a durable-lessons skeleton) and
+      // commit routing `gtd: learning template`.
+      case "writeLearningTemplate": {
+        yield* ensureGtdDir;
+        yield* fs9.writeFileString(resolve5(LEARNINGS_FILE), LEARNING_TEMPLATE);
+        yield* git.commitAllWithPrefix("gtd: learning template");
+        return { stop: false };
+      }
       // Squash: read SQUASH_MSG.md content (the real message authored by the
       // squashing turn), rm it, soft-reset to squashBase, commit-all under the
       // file's content as the message.
@@ -388320,10 +388384,11 @@ var perform = (action) => (
         return { stop: false };
       }
       // Health check: run tests on an idle/clean tree.
-      // Green, no squash-after chain queued → stop immediately, no commit/write.
-      // Green, `squashAfterGreen` → commit routing `gtd: tests green` (the
+      // Green, no learning/squash-after chain queued → stop immediately, no
+      //   commit/write.
+      // Green, `chainAfterGreen` → commit routing `gtd: tests green` (the
       //   observable green marker) and continue — the resolver chains
-      //   `writeSquashTemplate` at that HEAD next.
+      //   `writeLearningTemplate` or `writeSquashTemplate` at that HEAD next.
       // Red below cap → write HEALTH.md, commit routing `gtd: health-check` (the
       //   always-clean invariant: write-and-commit in the same chain).
       // Red at cap → write ERRORS.md, commit routing `gtd: health-check`.
@@ -388331,7 +388396,7 @@ var perform = (action) => (
         const runner = yield* TestRunner;
         const result = yield* runner.run();
         if (result.exitCode === 0) {
-          if (action.squashAfterGreen) {
+          if (action.chainAfterGreen) {
             yield* git.commitAllWithPrefix("gtd: tests green");
             return { stop: false };
           }
@@ -388428,7 +388493,10 @@ var DEFAULT_PAYLOAD = {
   squashMsgIsTemplate: false,
   healthPresent: false,
   healthContent: "",
-  healthCommitted: false
+  healthCommitted: false,
+  learningEnabled: false,
+  learningMsgPresent: false,
+  learningMsgIsTemplate: false
 };
 var buildContext = (p4, counters) => ({
   testFixCount: counters.testFixCount,
@@ -388459,6 +388527,32 @@ var healthFileConflictRules = [
     message: ".gtd/HEALTH.md + .gtd/ERRORS.md"
   }
 ];
+var learningFileConflictRules = [
+  {
+    isViolated: (p4) => p4.learningMsgPresent && p4.packagesPresent,
+    message: ".gtd/LEARNINGS.md + packages"
+  },
+  {
+    isViolated: (p4) => p4.learningMsgPresent && p4.reviewPresent,
+    message: ".gtd/LEARNINGS.md + .gtd/REVIEW.md"
+  },
+  {
+    isViolated: (p4) => p4.learningMsgPresent && p4.feedbackPresent,
+    message: ".gtd/LEARNINGS.md + .gtd/FEEDBACK.md"
+  },
+  {
+    isViolated: (p4) => p4.learningMsgPresent && p4.errorsPresent,
+    message: ".gtd/LEARNINGS.md + .gtd/ERRORS.md"
+  },
+  {
+    isViolated: (p4) => p4.learningMsgPresent && p4.healthPresent,
+    message: ".gtd/LEARNINGS.md + .gtd/HEALTH.md"
+  },
+  {
+    isViolated: (p4) => p4.learningMsgPresent && p4.squashMsgPresent,
+    message: ".gtd/LEARNINGS.md + .gtd/SQUASH_MSG.md"
+  }
+];
 var isReviewPackagesConflict = (p4) => p4.reviewPresent && p4.packagesPresent;
 var isReviewCommittedTodoConflict = (p4) => p4.reviewPresent && p4.todoCommitted;
 var isUncommittedReviewWithTodoConflict = (p4) => p4.reviewPresent && !(p4.reviewCommitted || p4.reviewDirty) && p4.todoExists;
@@ -388483,12 +388577,53 @@ var reviewAndFeedbackRules = [
   { isViolated: isErrorsWithoutPackages, message: ".gtd/ERRORS.md without packages" }
 ];
 var assertLegal = (p4) => {
-  for (const rule of [...healthFileConflictRules, ...reviewAndFeedbackRules]) {
+  for (const rule of [
+    ...healthFileConflictRules,
+    ...learningFileConflictRules,
+    ...reviewAndFeedbackRules
+  ]) {
     if (rule.isViolated(p4)) {
       throw new GtdStateError("illegal-combination", `illegal combination: ${rule.message}`);
     }
   }
 };
+var nextAfterReviewOrLearning = (flags, state, learningAlreadyRan) => {
+  if (!learningAlreadyRan && flags.learningEnabled && flags.hasSquashBase) {
+    return { kind: "mid-chain", state, actor: "agent", action: { kind: "writeLearningTemplate" } };
+  }
+  return flags.squashEnabled && flags.hasSquashBase ? { kind: "mid-chain", state, actor: "agent", action: { kind: "writeSquashTemplate" } } : { kind: "rest", state: "idle", actor: "human" };
+};
+var classifyLearningTurn = (actor, gate, flags) => {
+  if (actor === "agent" && gate === "learning") {
+    return flags.hasSquashBase && !flags.learningMsgIsTemplate ? {
+      kind: "mid-chain",
+      state: "learning",
+      actor: "agent",
+      action: { kind: "commitRouting", subject: "gtd: learning drafted" }
+    } : { kind: "rest", state: "learning", actor: "agent" };
+  }
+  if (actor === "human" && gate === "learning") {
+    return {
+      kind: "mid-chain",
+      state: "learning",
+      actor: "human",
+      action: { kind: "commitRouting", subject: "gtd: learning approved" }
+    };
+  }
+  if (actor === "agent" && gate === "learning-apply") {
+    return {
+      kind: "mid-chain",
+      state: "learning-apply",
+      actor: "agent",
+      action: {
+        kind: "commitRouting",
+        subject: "gtd: learning applied",
+        removeLearning: true
+      }
+    };
+  }
+  return null;
+};
 var classifyHead = (subject, flags) => {
   const parsed = parseSubject(subject);
   if (parsed.kind === "turn") {
@@ -388561,6 +388696,8 @@ var classifyHead = (subject, flags) => {
         // squashBase filled in by the caller
       } : { kind: "rest", state: "squashing", actor: "agent" };
     }
+    const learningTurn = classifyLearningTurn(actor, gate, flags);
+    if (learningTurn !== null) return learningTurn;
     if (actor === "agent" && gate === "health-fixing") {
       return {
         kind: "mid-chain",
@@ -388594,12 +388731,7 @@ var classifyHead = (subject, flags) => {
             action: { kind: "closePackage" }
           } : { kind: "rest", state: "agentic-review", actor: "agent" };
         }
-        return flags.squashEnabled && flags.squashAfterGreen ? {
-          kind: "mid-chain",
-          state: "testing",
-          actor: "agent",
-          action: { kind: "writeSquashTemplate" }
-        } : { kind: "rest", state: "idle", actor: "human" };
+        return nextAfterReviewOrLearning(flags, "testing", false);
       case "errors":
         return flags.errorsPresent ? { kind: "rest", state: "escalate", actor: "human" } : { kind: "rest", state: "fixing", actor: "agent" };
       case "package-done":
@@ -388609,16 +388741,19 @@ var classifyHead = (subject, flags) => {
       case "review-feedback":
         return { kind: "rest", state: "grilling", actor: "agent" };
       case "done":
-        return flags.squashEnabled && flags.hasSquashBase ? {
-          kind: "mid-chain",
-          state: "done",
-          actor: "agent",
-          action: { kind: "writeSquashTemplate" }
-        } : { kind: "rest", state: "idle", actor: "human" };
+        return nextAfterReviewOrLearning(flags, "done", false);
       case "squash-template":
         return { kind: "rest", state: "squashing", actor: "agent" };
       case "reviewing":
         return { kind: "rest", state: "review", actor: "agent" };
+      case "learning-template":
+        return { kind: "rest", state: "learning", actor: "agent" };
+      case "learning-drafted":
+        return { kind: "rest", state: "await-learning-review", actor: "human" };
+      case "learning-approved":
+        return { kind: "rest", state: "learning-apply", actor: "agent" };
+      case "learning-applied":
+        return nextAfterReviewOrLearning(flags, "learning-applied", true);
       case "health-check":
         return flags.errorsPresent ? { kind: "rest", state: "escalate", actor: "human" } : { kind: "rest", state: "health-fixing", actor: "agent" };
       case "health-fix":
@@ -388636,18 +388771,24 @@ var STATE_IS_OWN_GATE = /* @__PURE__ */ new Set([
   "review",
   "squashing",
   "health-fixing",
-  "escalate"
+  "escalate",
+  "learning",
+  "learning-apply"
 ]);
-var gateForState = (state) => STATE_IS_OWN_GATE.has(state) ? state : "review";
+var GATE_OVERRIDES = {
+  "await-learning-review": "learning"
+};
+var gateForState = (state) => STATE_IS_OWN_GATE.has(state) ? state : GATE_OVERRIDES[state] ?? "review";
 var INERT_EMPTY_AGENT_GATES = /* @__PURE__ */ new Set([
   "grilling",
   "grilled",
   "building",
   "fixing",
   "agentic-review",
-  "review"
+  "review",
+  "learning-apply"
 ]);
-var isInertEmptyAgentRest = (state, p4) => p4.workingTreeClean && (INERT_EMPTY_AGENT_GATES.has(state) || state === "squashing" && p4.squashMsgIsTemplate);
+var isInertEmptyAgentRest = (state, p4) => p4.workingTreeClean && (INERT_EMPTY_AGENT_GATES.has(state) || state === "squashing" && p4.squashMsgIsTemplate || state === "learning" && p4.learningMsgIsTemplate);
 var resolveBaseline = (p4, counters, head7, corrupt, lastTurn) => {
   const headIsFixerTurn = (() => {
     const parsed = parseSubject(head7);
@@ -388676,7 +388817,6 @@ var resolveBaseline = (p4, counters, head7, corrupt, lastTurn) => {
       action: { kind: "closePackage" }
     } : { kind: "rest", state: "fixing", actor: "agent" };
   }
-  const squashAfterGreen = p4.squashEnabled && counters.healthFixCount > 0 && p4.healthFixBase !== void 0;
   const reviewSubstantive = p4.headTurnReviewSubstantive !== void 0 ? p4.headTurnReviewSubstantive : p4.reviewDirty && !p4.reviewCheckboxOnly;
   const flags = {
     headTurnIsEmpty: p4.headTurnIsEmpty,
@@ -388684,7 +388824,8 @@ var resolveBaseline = (p4, counters, head7, corrupt, lastTurn) => {
     agenticReviewForceApproved: forceApprove,
     squashEnabled: p4.squashEnabled,
     hasSquashBase: p4.squashBase !== void 0,
-    squashAfterGreen,
+    learningEnabled: p4.learningEnabled,
+    learningMsgIsTemplate: p4.learningMsgIsTemplate,
     reviewSubstantive,
     // A pending (uncommitted) deletion of ERRORS.md still counts as "ERRORS.md
     // was committed at this HEAD" for classification purposes: `fs.exists`
@@ -388722,7 +388863,7 @@ var resolveBaseline = (p4, counters, head7, corrupt, lastTurn) => {
           kind: "runHealthCheck",
           errorCount: counters.healthFixCount,
           capReached: counters.healthFixCount >= p4.fixAttemptCap,
-          squashAfterGreen: classified.action.squashAfterGreen
+          chainAfterGreen: classified.action.chainAfterGreen
         }
       };
     }
@@ -388791,7 +388932,7 @@ var applyTurnTaking = (p4, counters, head7, baseline) => {
   }
   const healthCheckCapReached = head7 === "gtd: health-check" && counters.healthFixCount >= p4.fixAttemptCap;
   if (head7 === "gtd: health-fix" && baseline.state === "idle" || healthCheckCapReached && baseline.state === "health-fixing") {
-    const squashAfterGreenAtHealthFix = p4.squashEnabled && counters.healthFixCount > 0 && p4.healthFixBase !== void 0;
+    const chainAfterGreenAtHealthFix = (p4.squashEnabled || p4.learningEnabled) && counters.healthFixCount > 0 && p4.healthFixBase !== void 0;
     return {
       state: "idle",
       actor: "agent",
@@ -388800,7 +388941,7 @@ var applyTurnTaking = (p4, counters, head7, baseline) => {
         kind: "runHealthCheck",
         errorCount: counters.healthFixCount,
         capReached: counters.healthFixCount >= p4.fixAttemptCap,
-        squashAfterGreen: squashAfterGreenAtHealthFix
+        chainAfterGreen: chainAfterGreenAtHealthFix
       },
       context: context10
     };
@@ -388815,7 +388956,7 @@ var applyTurnTaking = (p4, counters, head7, baseline) => {
     };
   }
   if (baseline.state === "idle" && invoker === "human") {
-    const squashAfterGreen = p4.squashEnabled && counters.healthFixCount > 0 && p4.healthFixBase !== void 0;
+    const chainAfterGreen = (p4.squashEnabled || p4.learningEnabled) && counters.healthFixCount > 0 && p4.healthFixBase !== void 0;
     return {
       state: "idle",
       actor: "human",
@@ -388824,7 +388965,7 @@ var applyTurnTaking = (p4, counters, head7, baseline) => {
         kind: "runHealthCheck",
         errorCount: counters.healthFixCount,
         capReached: counters.healthFixCount >= p4.fixAttemptCap,
-        squashAfterGreen
+        chainAfterGreen
       },
       context: context10
     };
@@ -389399,6 +389540,15 @@ var await_review_default = '<%~ include("@header") %>\n\n`.gtd/REVIEW.md` holds
 // src/prompts/squashing.md
 var squashing_default = '<%~ include("@header") %>\n\nThe process is **approved and done**. `.gtd/SQUASH_MSG.md` has already been\ncommitted with a template \u2014 your job is to overwrite it with the real\nconventional-commits squash message and finish your turn.\n\n### Step 1 \u2014 Extract decisions from grilling rounds\n\nScan the git history of recent `gtd: ...` / `gtd(agent): ...` /\n`gtd(human): ...` commits. Look for changes to `.gtd/TODO.md` \u2014 specifically the\n`## Captured input` sections and any edits to plan text. Extract **key\ndecisions, trade-offs, and design choices** made during grilling rounds. These\nwill appear in the commit body so the history is self-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\n  sessions. Omit if there were no meaningful decisions to capture.\n\n### Step 3 \u2014 Overwrite .gtd/SQUASH_MSG.md\n\nReplace the **entire content** of `.gtd/SQUASH_MSG.md` (plain text, no markdown\nwrapper, no leftover template scaffolding) with the message from Step 2, then\nleave it uncommitted and finish your turn \u2014 `gtd step-agent` performs the\nsquash using this file\'s content.\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<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
 
+// src/prompts/learning.md
+var learning_default = '<%~ include("@header") %>\n\nThe process is **approved and done**, and headed for a squash. Before that\nhappens, `.gtd/LEARNINGS.md` has been committed with a template \u2014 your job is\nto overwrite it with the real, distilled learnings from this cycle so they\nsurvive the squash even though the granular history won\'t.\n\n### Step 1 \u2014 Walk the cycle\'s history\n\nScan the git history back to the cycle\'s start (the full-process diff is\ninlined below, and `git log` over the same range shows every `gtd: ...` /\n`gtd(agent): ...` / `gtd(human): ...` commit). Look specifically for:\n\n- **Test failures and fixes** \u2014 each `gtd: errors` round and the fix that\n  followed it. What broke, and what actually made it pass?\n- **Review feedback** \u2014 human `.gtd/REVIEW.md` notes and `gtd: review\n  feedback` detours. What did the human have to correct that the agent got\n  wrong on its own?\n- **Health-check rounds** \u2014 any `gtd: health-check` / `gtd: health-fix`\n  cycles. Environmental or systemic issues surfaced outside normal building?\n- **Grilling decisions** \u2014 `.gtd/TODO.md`\'s "## Captured input" sections and\n  plan edits. Trade-offs or conventions the human specified that a future\n  agent should already know.\n\n### Step 2 \u2014 Distill, don\'t transcribe\n\nFor each thing you found, ask: is this a **durable, generalizable lesson**\n(a convention, a gotcha, a pattern this project wants followed next time), or\na **one-off detail** specific to this change? Keep only the former. A future\nagent reading this should learn something that changes how it works on this\nproject, not a recap of what happened.\n\n### Step 3 \u2014 Overwrite .gtd/LEARNINGS.md\n\nReplace the **entire content** of `.gtd/LEARNINGS.md` with your distilled\nlearnings (plain markdown, no leftover template scaffolding). If nothing\ndurable surfaced this cycle, write a short explicit note saying so \u2014 don\'t\nleave the placeholder text in place. Leave the file uncommitted and finish\nyour turn; a human reviews it next before it\'s integrated into the project\'s\nown memory (CLAUDE.md/AGENTS.md/docs).\n<% if (it.context.squashDiff && it.context.squashDiff.trim()) { %>\n<%= it.context.squashBase !== undefined ? "\\nCycle 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<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
+
+// src/prompts/await-learning-review.md
+var await_learning_review_default = "<%~ include(\"@header\") %>\n\n`.gtd/LEARNINGS.md` holds the distilled learnings from this cycle, drafted by\nthe agent. This is a human gate; there is nothing for the agent to do.\n\nTell the user:\n\n- Read `.gtd/LEARNINGS.md`.\n- Delete anything not worth keeping, or edit/add anything the draft missed.\n- Run `gtd step` \u2014 with or without edits, either way proceeds: the agent\n  integrates whatever remains into the project's own memory\n  (CLAUDE.md/AGENTS.md/docs) next.\n\nThere is no reject path \u2014 this gate only refines what gets kept, it doesn't\nsend the cycle back for rework.\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n";
+
+// src/prompts/learning-apply.md
+var learning_apply_default = "<%~ include(\"@header\") %>\n\nThe human has approved (and possibly amended) `.gtd/LEARNINGS.md`. Your job is\nto integrate those learnings into the project's own memory, not to touch\n`.gtd/LEARNINGS.md` itself.\n\n1. **Read `.gtd/LEARNINGS.md`.**\n2. **Pick the right home for each point**, using your judgment and this\n   project's existing convention:\n   - An existing `CLAUDE.md` or `AGENTS.md` at the repo root (or a directory\n     closer to what the learning concerns) is usually the right place.\n   - If neither exists and the learnings warrant one, create `AGENTS.md` at\n     the repo root.\n   - A learning about a specific subsystem may fit better in that\n     subsystem's own docs than a root-level file \u2014 use your judgment.\n3. **Integrate, don't just append** \u2014 merge each point into the relevant\n   section of the target file(s); rephrase for clarity, dedupe against what's\n   already documented, and keep the existing document's structure and tone.\n4. **Never delete or edit `.gtd/LEARNINGS.md`** \u2014 the machine removes it once\n   your turn is captured.\n5. **Leave every change uncommitted and finish your turn.**\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n";
+
 // src/prompts/escalate.md
 var escalate_default = '<%~ include("@header") %>\n\nThe agent was not able to fix all errors on its own. The last error report is\nstored in `.gtd/ERRORS.md` for a human to investigate.\n\nNext steps for the human developer:\n\n1. Investigate and fix errors reported in `.gtd/ERRORS.md`\n2. Delete `.gtd/ERRORS.md`\n3. Run `gtd step` when you are ready to continue\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
 
@@ -389415,6 +389565,9 @@ var PROMPT_STATES = /* @__PURE__ */ new Set([
   "review",
   "await-review",
   "squashing",
+  "learning",
+  "await-learning-review",
+  "learning-apply",
   "escalate",
   "idle",
   "health-fixing"
@@ -389428,7 +389581,9 @@ var MODEL_STATE = {
   "health-fixing": "fixing",
   "agentic-review": "agentic-review",
   review: "clean",
-  squashing: "clean"
+  squashing: "clean",
+  learning: "clean",
+  "learning-apply": "clean"
 };
 var builtinResolveModel = (state) => builtinTierDefault[stateTier[state]];
 var fenceFor = (content) => {
@@ -389452,6 +389607,9 @@ eta.loadTemplate("@agentic-review", agentic_review_default);
 eta.loadTemplate("@review", review_default);
 eta.loadTemplate("@await-review", await_review_default);
 eta.loadTemplate("@squashing", squashing_default);
+eta.loadTemplate("@learning", learning_default);
+eta.loadTemplate("@await-learning-review", await_learning_review_default);
+eta.loadTemplate("@learning-apply", learning_apply_default);
 eta.loadTemplate("@escalate", escalate_default);
 eta.loadTemplate("@idle", idle_default);
 eta.readFile = null;
@@ -389464,6 +389622,9 @@ var STATE_TEMPLATE = {
   review: "@review",
   "await-review": "@await-review",
   squashing: "@squashing",
+  learning: "@learning",
+  "await-learning-review": "@await-learning-review",
+  "learning-apply": "@learning-apply",
   escalate: "@escalate",
   idle: "@idle",
   "health-fixing": "@health-fixing"
@@ -389493,6 +389654,78 @@ var buildPrompt = (result, resolveModel = builtinResolveModel, output = "plain")
   return raw.replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
 };
 
+// src/ReviewWindow.ts
+var REVIEW_HEAD_REF = "refs/gtd/review-head";
+var REVIEW_BASE_REF = "refs/gtd/review-base";
+var AWAITING_REVIEW_SUBJECT = ROUTING_SUBJECT["awaiting-review"];
+var subjectOf2 = (message) => message.split("\n")[0] ?? "";
+var reviewWindowBase = (history) => {
+  const beforeHead = history.slice(0, -1);
+  let lastDoneIdx = -1;
+  for (let i = 0; i < beforeHead.length; i++) {
+    if (subjectOf2(beforeHead[i].message) === ROUTING_SUBJECT.done) lastDoneIdx = i;
+  }
+  const currentCycle = beforeHead.slice(lastDoneIdx + 1);
+  let anchor;
+  let lastAwaitingReview;
+  let firstGrilling;
+  for (const c7 of currentCycle) {
+    const parsed = parseSubject(subjectOf2(c7.message));
+    if (parsed.kind === "routing" && parsed.phase === "reviewing" && parsed.param !== void 0) {
+      anchor = parsed.param;
+    }
+    if (parsed.kind === "routing" && parsed.phase === "awaiting-review") {
+      lastAwaitingReview = c7.hash;
+    }
+    if (parsed.kind === "turn" && parsed.gate === "grilling" && firstGrilling === void 0) {
+      firstGrilling = c7.hash;
+    }
+  }
+  return anchor ?? lastAwaitingReview ?? firstGrilling;
+};
+var closeReviewWindow = Effect_exports.gen(
+  function* () {
+    const git = yield* GitService;
+    const savedHead = yield* git.readRefOption(REVIEW_HEAD_REF);
+    if (Option_exports.isNone(savedHead)) return { closed: false };
+    const base = yield* git.readRefOption(REVIEW_BASE_REF);
+    if (Option_exports.isSome(base)) {
+      const onReviewedBranch = yield* git.isAncestor(base.value, "HEAD");
+      if (!onReviewedBranch) {
+        return yield* Effect_exports.fail(
+          new Error(
+            "a gtd review checkout window is open but HEAD has moved off the reviewed branch \u2014 return to it, or restore manually with `git reset --mixed refs/gtd/review-head && git update-ref -d refs/gtd/review-head && git update-ref -d refs/gtd/review-base`"
+          )
+        );
+      }
+    }
+    yield* git.mixedResetTo(REVIEW_HEAD_REF);
+    yield* git.deleteRef(REVIEW_HEAD_REF);
+    yield* git.deleteRef(REVIEW_BASE_REF);
+    return { closed: true };
+  }
+);
+var openReviewWindow = Effect_exports.gen(
+  function* () {
+    const git = yield* GitService;
+    const hasCommits = yield* git.hasCommits();
+    if (!hasCommits) return { opened: false };
+    const subject = yield* git.lastCommitSubject();
+    if (subject !== AWAITING_REVIEW_SUBJECT) return { opened: false };
+    const history = yield* git.commitHistory();
+    const base = reviewWindowBase(history);
+    if (base === void 0) return { opened: false };
+    const headHash = yield* git.resolveRef("HEAD");
+    if (base === headHash) return { opened: false };
+    yield* git.updateRef(REVIEW_BASE_REF, base);
+    yield* git.updateRef(REVIEW_HEAD_REF, headHash);
+    yield* git.mixedResetTo(base);
+    yield* git.restoreStagedFrom(REVIEW_HEAD_REF, [".gtd"]);
+    yield* git.addIntentToAdd();
+    return { opened: true };
+  }
+);
+
 // src/State.ts
 var edgeActionHandlers = {
   captureTurn: (a5) => `capture the ${a5.actor} turn as "gtd(${a5.actor}): ${a5.gate}"`,
@@ -389503,6 +389736,7 @@ var edgeActionHandlers = {
     if (a5.removeReview) removed.push(".gtd/REVIEW.md");
     if (a5.removeFeedback) removed.push(".gtd/FEEDBACK.md");
     if (a5.removeHealth) removed.push(".gtd/HEALTH.md");
+    if (a5.removeLearning) removed.push(".gtd/LEARNINGS.md");
     if (removed.length > 0) msg += ` (removing ${removed.join(", ")})`;
     return msg;
   },
@@ -389510,7 +389744,8 @@ var edgeActionHandlers = {
   closePackage: () => "close the active package",
   writeSquashTemplate: () => "write the squash message template",
   squashCommit: (a5) => `squash the cycle onto ${a5.squashBase}`,
-  runHealthCheck: (a5) => `run the health check (attempt ${a5.errorCount + 1}${a5.capReached ? ", cap reached" : ""}${a5.squashAfterGreen ? ", squash after green" : ""})`
+  writeLearningTemplate: () => "write the learnings template",
+  runHealthCheck: (a5) => `run the health check (attempt ${a5.errorCount + 1}${a5.capReached ? ", cap reached" : ""}${a5.chainAfterGreen ? ", chain after green" : ""})`
 };
 var describeEdgeAction = (a5) => edgeActionHandlers[a5.kind](a5);
 var describeStatus = (prediction) => ({
@@ -389807,9 +390042,13 @@ function makeProgram(opts = {}) {
     const git = yield* GitService;
     const fs9 = yield* FileSystem_exports.FileSystem;
     yield* assertRunningFromRepoRoot(git, fs9);
+    yield* closeReviewWindow;
     yield* (yield* ConfigInit).ensure;
     const config2 = yield* ConfigService;
-    yield* dispatchKnownSubcommand(sub, argv, git, config2, json2, write4);
+    yield* dispatchKnownSubcommand(sub, argv, git, config2, json2, write4).pipe(
+      Effect_exports.tap(() => openReviewWindow),
+      Effect_exports.tapError(() => openReviewWindow.pipe(Effect_exports.ignore))
+    );
   }).pipe(
     json2 ? Effect_exports.catchAll(
       (error) => Effect_exports.sync(

package/package.json

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

package/schema.json

@@ -57,6 +57,9 @@
     "squash": {
       "type": "boolean"
     },
+    "learning": {
+      "type": "boolean"
+    },
     "fixAttemptCap": {
       "$ref": "#/$defs/Int",
       "description": "a non-negative number",