@pmelab/gtd 1.5.4 → 1.6.0

package/README.md

@@ -442,19 +442,31 @@ loop before the next one starts.
    (`gtd: done`) → **Squashing** → **Idle**. The Squashing agent authors a
    conventional-commits message from the full process diff and squashes all
    intermediate `gtd: *` commits into one with `git reset --soft <base>` +
-   `git commit`, then **gtd STOPs**. Post-squash review does not fire
+   <<<<<<< HEAD `git commit`, then **gtd STOPs**. The base is the parent of the
+   current cycle's start marker **nearest to HEAD** (the last `gtd: new task`;
+   for legacy cycles the last contiguous `gtd: grilling` run), and on a feature
+   branch it never reaches below the merge-base with the default branch — stray
+   markers left behind by older squashes can never drag the squash into
+   previously shipped features. Post-squash review does not fire automatically —
+   it fires only on the next manual `gtd` run (when the squash commit is the
+   boundary HEAD and a reviewable diff exists). Squashing fires when the tree
+   has no unrelated code dirty — a lone untracked `SQUASH_MSG.md` is tolerated
+   and deleted before the squash commit. If unrelated code is dirty at
+   `gtd: done`, gtd routes to **New Feature** instead. Set `squash: false` in
+   ======= `git commit`, then **gtd STOPs**. Post-squash review does not fire
    automatically — it fires only on the next manual `gtd` run (when the squash
    commit is the boundary HEAD and a reviewable diff exists). Squashing fires
    when the tree has no unrelated code dirty — a lone untracked `SQUASH_MSG.md`
    is tolerated and deleted before the squash commit. If unrelated code is dirty
    at `gtd: done`, gtd routes to **New Feature** instead. Set `squash: false` in
-   `.gtdrc` to skip squashing and go straight to Idle. Checking off REVIEW.md
-   checkboxes (`- [ ]` → `- [x]`) also counts as approval and routes to **Done**
-   — they are navigation aids, not feedback. Only **non-checkbox** edits (code
-   changes, inline comments, textual annotations in REVIEW.md) trigger **Accept
-   Review**, which seeds a fresh `TODO.md` from your feedback, discards your
-   code edits, removes `REVIEW.md`, and re-enters Grilling — the loop starts
-   over.
+   > > > > > > > origin/46-config-schema `.gtdrc` to skip squashing and go
+   > > > > > > > straight to Idle. Checking off REVIEW.md checkboxes (`- [ ]` →
+   > > > > > > > `- [x]`) also counts as approval and routes to **Done** — they
+   > > > > > > > are navigation aids, not feedback. Only **non-checkbox** edits
+   > > > > > > > (code changes, inline comments, textual annotations in
+   > > > > > > > REVIEW.md) trigger **Accept Review**, which seeds a fresh
+   > > > > > > > `TODO.md` from your feedback, discards your code edits, removes
+   > > > > > > > `REVIEW.md`, and re-enters Grilling — the loop starts over.
 
 ## Configuration
 
@@ -496,6 +508,11 @@ built-in defaults apply. Supported filenames (searched in this order):
   - `states.*` — per-state overrides keyed by the six agent states: `decompose`
     (shared by the Grilled and Planning states), `grilling`, `building`,
     `fixing`, `agentic-review`, `clean`. Unknown `states` keys are **rejected**.
+- **`$schema`** (string, optional) — a recognized key that is **stripped before
+  validation**, so it never counts as an unknown key. Point it at the published
+  schema to get schema-backed autocompletion and inline docs in your editor. A
+  `schema.json` is generated from the config schema at build time and ships with
+  the package (and is published/committed on release).
 
 ### Validation and errors
 
@@ -526,6 +543,28 @@ This makes the worktree-parent case easy: drop a single `.gtdrc` in a shared
 parent directory and it cascades to **all** checkouts/worktrees beneath it,
 while any individual checkout can still override settings with its own `.gtdrc`.
 
+### Auto-init
+
+On every run, if the cwd→root walk finds **no** config anywhere, gtd creates and
+commits a starter config at the **git root**: a `.gtdrc.json` containing only a
+`$schema` link:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/pmelab/gtd/main/schema.json"
+}
+```
+
+It is committed as `chore: add .gtdrc.json`. This wires up editor autocompletion
+out of the box; add any settings below the `$schema` line to override the
+defaults.
+
+Auto-init is skipped when HEAD is a `gtd: transport` commit: transport is a
+consume-only handoff HEAD (mixed-reset in the Transport pre-pass), so committing
+a config stub on top of it would displace the transport commit — and, when it is
+the repository root, silently mask the "cannot reset transport commit" error.
+The stub is created on a later run, once the transport HEAD has been consumed.
+
 ### Example
 
 ```yaml
@@ -710,6 +749,26 @@ This mirrors the `format:check` step enforced in CI (`prettier --check .`),
 keeping committed code consistently formatted without requiring a separate
 manual format pass.
 
+### Prompt templates
+
+Each prompt-bearing state has a self-contained Eta template in
+`src/prompts/*.md` that owns its full prompt — header, context, body, and tail.
+Shared fragments live as partials in `src/prompts/partials/`: `header`, the
+context renderers (`context`, `package`, `diff`, `feedback`), and three tail
+variants (`auto-advance`, `neutral`, `stop`). Templates compose them via Eta's
+`<%~ include("@name", { … }) %>` syntax; dynamic values such as the resolved
+model string are injected as Eta variables (`<%= model %>`).
+
+At module load, `src/Prompt.ts` registers every template on a single `new Eta()`
+instance via `loadTemplate`. `readFile` and `resolvePath` are nulled afterward
+so rendering resolves exclusively from the in-memory cache — the compiled ESM
+bundle carries no runtime `fs` dependency.
+
+`buildPrompt(result, resolveModel?, output?)` selects the state's template,
+builds a view-model (model string, tail partial name, context), renders it,
+collapses runs of three or more blank lines to two, and ensures exactly one
+trailing newline.
+
 `npm run dev` runs `src/main.ts` directly via Node's native TypeScript
 type-stripping (requires Node 22.6+). It registers `dev/hooks.mjs`, which fills
 the two gaps the tsup build otherwise covers: resolving `./Foo.js` specifiers to