@pmelab/gtd 12.5.0 → 14.0.0

package/README.md

@@ -29,6 +29,12 @@ bundled workflow names skills from it at several states instead of spelling out
 technique in the prompt itself; see
 [Setup](https://github.com/pmelab/gtd/blob/main/docs/setup.md) for the details.
 
+> **A repository's `gtd.config.ts` is code, and gtd runs it.** A custom workflow
+> is a TypeScript module, and every gtd command that looks at workflow state —
+> `gtd next` and `gtd lsp` included, not just `gtd land` — evaluates it. Treat
+> it like a Makefile or a `package.json` script: don't run gtd in a checkout you
+> don't trust.
+
 ## Quick start
 
 Pipe the output of `gtd install` into your coding agent and answer its
@@ -75,15 +81,17 @@ gtd next
 ```
 No active gtd process.
 
-To start one, make ANY change — a hand-edit to real code, a scratch note,
-anything at all. TODO.md is a good default place to start sketching.
+To start one, make ANY change — a hand-edit to real code, a scratch
+note, anything at all. .gtd/TODO.md is a good default
+place to start sketching.
 ```
 
-This means its your turn. Add a `TODO.md` file with a detailed, well articulated
-idea:
+This means its your turn. Add a `.gtd/TODO.md` file with a detailed, well
+articulated idea:
 
 ```bash
-echo "Make a billion dollar SaaS. Make no mistakes." > TODO.md
+mkdir -p .gtd
+echo "Make a billion dollar SaaS. Make no mistakes." > .gtd/TODO.md
 ```
 
 Ask again, and gtd leads with what to do, then reports what it sees:
@@ -92,14 +100,13 @@ Ask again, and gtd leads with what to do, then reports what it sees:
 The edit is already made — run `gtd land` to land it.
 State: idle
 Awaits: human
-Pending:
-  A TODO.md -> * **
-Next: Start → unwind
+Label: Idle
+File: .gtd/TODO.md
 ```
 
-Your change matched the pattern `* **`, which routes to the `unwind` state. For
-the moment its not important what that is. Important is the fact that changes to
-the source tree control what is going to happen next.
+At `idle`, any change at all starts a process, and the next step is `unwind`.
+For the moment its not important what that is. Important is the fact that what
+you leave in the tree controls what is going to happen next.
 
 ### Beat 2 — `gtd land` records it as a commit
 
@@ -123,7 +130,6 @@ gtd land --json=script | sh
 
 ```
 -> idle → unwind
-   TODO.md
 ```
 
 ```bash
@@ -148,12 +154,17 @@ Awaits: check
 Label: Unwinding your input
 
 #!/usr/bin/env sh
-...
-git revert --no-commit "$commit" 2> .gtd/.unwind-error
+set +e
+if ! git diff --quiet '<sketch commit>^' '<sketch commit>' --; then
+  mkdir -p "$(dirname '.gtd/FEEDBACK.md')"
+  git diff --binary '<sketch commit>^' '<sketch commit>' -- | git apply -R 2> …
+  …
 ```
 
-`Awaits: check` means this beat is not yours: it is a script. gtd never runs
-anything itself, so run it and land it exactly as before:
+`Awaits: check` means this beat is not yours: it is a script, here one that
+reverts your sketch out of the working tree. gtd never runs anything itself,
+never commits and never touches the index, so run it and land it exactly as
+before:
 
 ```bash
 sh -c "$(gtd next --json=content)"
@@ -171,13 +182,13 @@ baseline is green:
 ```
 State: start-gate.check
 Awaits: check
-Next: C → design.triage
+Label: Checking the baseline
 ```
 
-`C` is the clean-tree pattern: the suite passed, nothing changed, so move on to
-triage. A red suite instead writes `.gtd/FEEDBACK.md`, which matches a different
-pattern and routes to `start-gate.blocked` — same two commands, different
-outcome, decided entirely by what the beat left in the tree.
+A green suite leaves the tree clean, so the process moves on to triage. A red
+suite instead writes `.gtd/FEEDBACK.md`, and the process goes to
+`start-gate.blocked` — same two commands, different outcome, decided entirely by
+what the beat left in the tree.
 
 Land the green one, and the beat after it belongs to an agent.
 
@@ -306,9 +317,9 @@ noted in steps 2, 3, and 4 below.
 
 3. **You wait.** The work is split into packages and built one at a time, each
    one checked against your test suite and fixed until it passes, then reviewed
-   against its own spec before moving on. Four points along that loop are judged
-   rather than always asking you outright — each stops and hands you a verdict
-   to make (`gtd judge answer`, or land with a clean tree to accept the
+   against its own spec before moving on. Three points along that loop are
+   judged rather than always asking you outright — each stops and hands you a
+   verdict to make (`gtd judge answer`, or land with a clean tree to accept the
    conservative default, which never skips work):
    - Every red round after the first: was the failure identical, new, or
      progress?
@@ -316,22 +327,20 @@ noted in steps 2, 3, and 4 below.
      each of its requirements?
    - After a review turn raises concerns: would each one actually violate the
      spec if left unaddressed, or is it a nit?
-   - Before showing you the review document: is this round mechanical, touches
-     no public surface, and changes no behavior? Confident on all three skips
-     the agent's own review turn — step 4 still shows you a (machine-written)
-     summary of what changed.
 
    A driver built only to run this loop (not to answer judgments) still handles
    every one of these correctly: it shows you the message and stops, same as any
    other question.
 
-   The `gtd --entry fix-precheck` side door (below) repairs a red baseline
-   through this same loop's own green check, and that check also runs a
-   qualitative review lap first: one configured skill per turn, each looking at
-   the change from its own angle (a security checklist, a simplification pass)
-   and fixing what it finds once, with no re-review after the fix. It never
-   replaces step 4 — your review stays the final gate, and nothing here skips
-   it.
+   Once the last package is built, the whole change goes through a qualitative
+   review lap before you see anything: one configured skill per turn, each
+   looking at the change from its own angle (a security checklist, a
+   simplification pass) and fixing what it finds once, with no re-review after
+   the fix. The per-package review above only judges that package against its
+   own spec; this lap is where code quality is looked at, and every round pays
+   for it. It never replaces step 4 — your review stays the final gate, and
+   nothing here skips it. The `gtd --entry fix-precheck` side door (below)
+   repairs a red baseline through this same lap.
 
    A red suite that keeps failing past a few fix attempts escalates instead of
    retrying forever: an agent turn reads the failing output and writes
@@ -376,9 +385,11 @@ gtd --entry review-gate.check --var reviewBase=<commitish>
 starts a pure review of everything from `<commitish>` to HEAD — straight to step
 4, no planning and no building.
 
-The workflow itself is data, not code: a `.gtdrc` `workflow:` key replaces it
-wholesale. See
-[Configuration](https://github.com/pmelab/gtd/blob/main/docs/configuration.md).
+The workflow itself is a plain async TypeScript function: a `gtd.config.ts` at
+the repository root replaces it, and the pieces the bundled one is built from
+are exported for yours to reuse. See
+[Configuration](https://github.com/pmelab/gtd/blob/main/docs/configuration.md) —
+and remember gtd evaluates that file on every command.
 
 ## License