@pmelab/gtd 24.0.0 → 24.2.0

package/src/steering/fixtures/qa/requirements.read.json

@@ -0,0 +1,475 @@
+{
+  "nodes": [
+    {
+      "title": "Review note severity tiers (issue #270, T3b)",
+      "anchor": {
+        "kind": "paragraph",
+        "line": 0
+      }
+    },
+    {
+      "title": "Sketch: `.gtd/TODO.md` said \"work on issue 270\". Issue #270: at the `review.triage` judge rest (T3, shipped), ask four narrow questions per human note — `security` (yes/no), `reversibility` (one-way/two-way), `blastRadius` (local/module/contract), `newConcept` (yes/no) — in the same commit, as more `Gtd-Judge:` trailers. Flow code, never the model, turns the answers into a tier: security yes or one-way → `critical`; contract or new concept → `should`; else `could`.",
+      "anchor": {
+        "kind": "paragraph",
+        "line": 2
+      }
+    },
+    {
+      "title": "Concerns",
+      "anchor": {
+        "kind": "paragraph",
+        "line": 80
+      }
+    },
+    {
+      "title": "1. Severity questions at the triage rest — PRODUCT",
+      "anchor": {
+        "kind": "paragraph",
+        "line": 82
+      }
+    },
+    {
+      "title": "The `review.triage` rest asks the four severity questions per tiered note (which notes: open question above) alongside the T3 verdict, in one commit. Question wording follows the issue: one-way covers migrations, published API shapes, file formats, anything another system depends on by tomorrow; new concept is judged against the code, never a glossary file, and reusing or extending an existing concept is not new.",
+      "anchor": {
+        "kind": "paragraph",
+        "line": 84
+      }
+    },
+    {
+      "title": "2. Tier derivation and guard rails — PRODUCT",
+      "anchor": {
+        "kind": "paragraph",
+        "line": 91
+      }
+    },
+    {
+      "title": "Flow code derives the tier: security yes OR one-way → `critical`; contract OR new concept → `should`; else `could`. Deferring is the risky direction: an unanswered question, truncated evidence, or `p` below `reviewSeverityMinP` makes the note `critical`, never `could`. A human note starting with `!` is `critical` and gets no severity questions.",
+      "anchor": {
+        "kind": "paragraph",
+        "line": 93
+      }
+    },
+    {
+      "title": "3. Routing by tier — PRODUCT",
+      "anchor": {
+        "kind": "paragraph",
+        "line": 99
+      }
+    },
+    {
+      "title": "`critical` + `should` → `.gtd/REQUIREMENTS.md` this round, via the existing collecting turn. `could` → `.gtd/TODO.md` as a deferred package (lifecycle: open question above). Inside REQUIREMENTS.md: one-way doors first, then new concepts, then the rest in note order.",
+      "anchor": {
+        "kind": "paragraph",
+        "line": 101
+      }
+    },
+    {
+      "title": "4. Sign-off block on criticals — PRODUCT",
+      "anchor": {
+        "kind": "paragraph",
+        "line": 106
+      }
+    },
+    {
+      "title": "A round with an open critical cannot sign off (what counts as resolved: open question above).",
+      "anchor": {
+        "kind": "paragraph",
+        "line": 108
+      }
+    },
+    {
+      "title": "5. `!` marker in the review format — TECHNICAL",
+      "anchor": {
+        "kind": "paragraph",
+        "line": 111
+      }
+    },
+    {
+      "title": "`src/steering/review.ts` recognises the leading `!` on a human note and strips it from the text the folding turn sees.",
+      "anchor": {
+        "kind": "paragraph",
+        "line": 113
+      }
+    },
+    {
+      "title": "6. New process setting `reviewSeverityMinP` — TECHNICAL",
+      "anchor": {
+        "kind": "paragraph",
+        "line": 116
+      }
+    },
+    {
+      "title": "Default and fold-time recording per the answered questions below; outcomes stay re-foldable from the recorded trailers (T7, #272), never re-asked.",
+      "anchor": {
+        "kind": "paragraph",
+        "line": 118
+      }
+    },
+    {
+      "title": "7. Acceptance — PRODUCT",
+      "anchor": {
+        "kind": "paragraph",
+        "line": 121
+      }
+    },
+    {
+      "title": "A review with one one-way-door note, one new-concept note and six style notes produces REQUIREMENTS.md with two entries (one-way door first) and TODO.md with six, and sign-off stays blocked until the one-way door is resolved. Cucumber scenarios cover it; README and `docs/` reflect the `!` marker, the new setting and the deferral.",
+      "anchor": {
+        "kind": "paragraph",
+        "line": 123
+      }
+    },
+    {
+      "title": "Which notes get a severity tier?",
+      "detail": "T3 already routes each note by verdict: `edit` → planning lap, `question` → answered in place, `nit` → one batched fix, `praise` → dropped. The tier can reroute only edits, or also pull questions and nits into a lap.",
+      "status": "open",
+      "answered": false,
+      "anchor": {
+        "kind": "question",
+        "index": 0
+      },
+      "body": [
+        {
+          "title": "T3 already routes each note by verdict: `edit` → planning lap, `question` → answered in place, `nit` → one batched fix, `praise` → dropped. The tier can reroute only edits, or also pull questions and nits into a lap.",
+          "anchor": {
+            "kind": "paragraph",
+            "line": 14
+          }
+        }
+      ],
+      "children": [
+        {
+          "title": "Only `edit` notes are tiered",
+          "checked": false,
+          "anchor": {
+            "kind": "option",
+            "questionIndex": 0,
+            "index": 0
+          },
+          "body": [
+            {
+              "title": "critical/should edits → REQUIREMENTS.md now; could edits → TODO.md Questions, nits, praise route exactly as today; no severity asked for them A nit that renames a published API (one-way) is still fixed without a plan Done-when holds only if the six style notes are judged `edit`, not `nit`",
+              "anchor": {
+                "kind": "paragraph",
+                "line": 19
+              }
+            }
+          ]
+        },
+        {
+          "title": "Every note but praise is tiered; the tier only escalates",
+          "checked": false,
+          "anchor": {
+            "kind": "option",
+            "questionIndex": 0,
+            "index": 1
+          },
+          "body": [
+            {
+              "title": "A critical/should question or nit goes to REQUIREMENTS.md instead of its T3 route A could question is still answered, a could nit still fixed now; only could edits are deferred More judge questions per rest; a misjudged \"touches auth\" pulls a harmless nit into a full lap",
+              "anchor": {
+                "kind": "paragraph",
+                "line": 24
+              }
+            }
+          ]
+        },
+        {
+          "title": "Every note but praise is tiered; could also defers nits",
+          "checked": false,
+          "anchor": {
+            "kind": "option",
+            "questionIndex": 0,
+            "index": 2
+          },
+          "body": [
+            {
+              "title": "Same escalation as above, plus could nits go to TODO.md instead of being fixed The T3 nit route then only fires for nothing — effectively retired Matches the done-when literally whether style notes are judged edit or nit",
+              "anchor": {
+                "kind": "paragraph",
+                "line": 31
+              }
+            }
+          ]
+        },
+        {
+          "title": "",
+          "checked": false,
+          "anchor": {
+            "kind": "option",
+            "questionIndex": 0,
+            "index": 3
+          }
+        }
+      ]
+    },
+    {
+      "title": "What does \"a lap cannot sign off with an open critical\" enforce?",
+      "detail": "A critical note always goes to REQUIREMENTS.md, so the round it appears in already cannot sign off. The fork is whether the NEXT round checks that the critical was actually dealt with.",
+      "status": "open",
+      "answered": false,
+      "anchor": {
+        "kind": "question",
+        "index": 1
+      },
+      "body": [
+        {
+          "title": "A critical note always goes to REQUIREMENTS.md, so the round it appears in already cannot sign off. The fork is whether the NEXT round checks that the critical was actually dealt with.",
+          "anchor": {
+            "kind": "paragraph",
+            "line": 39
+          }
+        }
+      ],
+      "children": [
+        {
+          "title": "Nothing extra: routing a critical into a lap is the block",
+          "checked": false,
+          "anchor": {
+            "kind": "option",
+            "questionIndex": 1,
+            "index": 0
+          },
+          "body": [
+            {
+              "title": "No new step, no new guard The next round signs off whenever the human signs off, even if the fix missed the point",
+              "anchor": {
+                "kind": "paragraph",
+                "line": 44
+              }
+            }
+          ]
+        },
+        {
+          "title": "Carry each critical into the next REVIEW.md as an item the human must tick",
+          "checked": false,
+          "anchor": {
+            "kind": "option",
+            "questionIndex": 1,
+            "index": 1
+          },
+          "body": [
+            {
+              "title": "The review gate refuses sign-off while any carried critical is unticked New visible ritual in REVIEW.md; the human, not a model, decides \"resolved\"",
+              "anchor": {
+                "kind": "paragraph",
+                "line": 48
+              }
+            }
+          ]
+        },
+        {
+          "title": "A judge asks \"is this critical resolved?\" per carried critical at sign-off",
+          "checked": false,
+          "anchor": {
+            "kind": "option",
+            "questionIndex": 1,
+            "index": 2
+          },
+          "body": [
+            {
+              "title": "One more judge rest per signing round Below-floor or unanswered keeps sign-off blocked, which can loop until the human edits again",
+              "anchor": {
+                "kind": "paragraph",
+                "line": 51
+              }
+            }
+          ]
+        },
+        {
+          "title": "",
+          "checked": false,
+          "anchor": {
+            "kind": "option",
+            "questionIndex": 1,
+            "index": 3
+          }
+        }
+      ]
+    },
+    {
+      "title": "What happens to deferred `could` notes in `.gtd/TODO.md`?",
+      "detail": "TODO.md is the human's sketch file at `idle`. A deferred note written there mid process gets committed onto the branch, and the next process's `unwind` only reverts what the human adds at `idle` — not what is already committed — so deferred notes do not reach the next triage on their own.",
+      "status": "open",
+      "answered": false,
+      "anchor": {
+        "kind": "question",
+        "index": 2
+      },
+      "body": [
+        {
+          "title": "TODO.md is the human's sketch file at `idle`. A deferred note written there mid process gets committed onto the branch, and the next process's `unwind` only reverts what the human adds at `idle` — not what is already committed — so deferred notes do not reach the next triage on their own.",
+          "anchor": {
+            "kind": "paragraph",
+            "line": 58
+          }
+        }
+      ],
+      "children": [
+        {
+          "title": "Append them to TODO.md and leave them committed; the human pulls them into a later process by hand",
+          "checked": false,
+          "anchor": {
+            "kind": "option",
+            "questionIndex": 2,
+            "index": 0
+          },
+          "body": [
+            {
+              "title": "Smallest build `.gtd/TODO.md` ships in the branch/PR unless the human deletes it Deferred items are only a reminder until a human re-types or re-touches them",
+              "anchor": {
+                "kind": "paragraph",
+                "line": 65
+              }
+            }
+          ]
+        },
+        {
+          "title": "Append them to TODO.md, and the next ordinary start treats a committed TODO.md as part of its sketch",
+          "checked": false,
+          "anchor": {
+            "kind": "option",
+            "questionIndex": 2,
+            "index": 1
+          },
+          "body": [
+            {
+              "title": "Deferred items become concerns of the next process automatically Changes what `unwind`/triage read for every ordinary start `.gtd/TODO.md` still sits in the branch until that next process",
+              "anchor": {
+                "kind": "paragraph",
+                "line": 70
+              }
+            }
+          ]
+        },
+        {
+          "title": "Do not commit them: hand them back at sign-off (message or summary), tree stays clean",
+          "checked": false,
+          "anchor": {
+            "kind": "option",
+            "questionIndex": 2,
+            "index": 2
+          },
+          "body": [
+            {
+              "title": "No `.gtd/` file leaks into the PR Deviates from the issue's \"TODO.md as a deferred package\"; nothing persists unless the human copies it",
+              "anchor": {
+                "kind": "paragraph",
+                "line": 75
+              }
+            }
+          ]
+        },
+        {
+          "title": "",
+          "checked": false,
+          "anchor": {
+            "kind": "option",
+            "questionIndex": 2,
+            "index": 3
+          }
+        }
+      ]
+    },
+    {
+      "title": "Where does the `!` go, and on which notes?",
+      "detail": "As the first character of the human's own note text, on any note kind — pointer note, footnote, chunk prose — stripped before folding; prefixing the pointer path itself would break the pointer parse, and one rule for all kinds is easier to remember.",
+      "status": "answered",
+      "answered": false,
+      "anchor": {
+        "kind": "question",
+        "index": 3
+      },
+      "body": [
+        {
+          "title": "As the first character of the human's own note text, on any note kind — pointer note, footnote, chunk prose — stripped before folding; prefixing the pointer path itself would break the pointer parse, and one rule for all kinds is easier to remember.",
+          "anchor": {
+            "kind": "paragraph",
+            "line": 133
+          }
+        }
+      ],
+      "children": []
+    },
+    {
+      "title": "Does a REQUIREMENTS.md entry show its tier?",
+      "detail": "Yes: each folded note names its tier and the answer that earned it (\"critical: one-way door\", \"critical: forced by `!`\", \"critical: judge unsure\"); the issue rejects a single score for being unauditable, so the reason must be visible.",
+      "status": "answered",
+      "answered": false,
+      "anchor": {
+        "kind": "question",
+        "index": 4
+      },
+      "body": [
+        {
+          "title": "Yes: each folded note names its tier and the answer that earned it (\"critical: one-way door\", \"critical: forced by `!`\", \"critical: judge unsure\"); the issue rejects a single score for being unauditable, so the reason must be visible.",
+          "anchor": {
+            "kind": "paragraph",
+            "line": 140
+          }
+        }
+      ],
+      "children": []
+    },
+    {
+      "title": "What order do concerns take inside REQUIREMENTS.md?",
+      "detail": "One-way doors, then new concepts, then every other critical/should note in document order — the issue fixes the first two; document order is the existing tie-break.",
+      "status": "answered",
+      "answered": false,
+      "anchor": {
+        "kind": "question",
+        "index": 5
+      },
+      "body": [
+        {
+          "title": "One-way doors, then new concepts, then every other critical/should note in document order — the issue fixes the first two; document order is the existing tie-break.",
+          "anchor": {
+            "kind": "paragraph",
+            "line": 146
+          }
+        }
+      ],
+      "children": []
+    },
+    {
+      "title": "What is `reviewSeverityMinP`'s default, and what does a blank value do?",
+      "detail": "`0.7`, one floor for all four questions, matching `reviewNoteActionable` and `judgeIdenticalMinP`; a blank value makes every tiered note `critical`, the same fail-safe a blank `reviewNoteActionable` gives (every note an `edit`).",
+      "status": "answered",
+      "answered": false,
+      "anchor": {
+        "kind": "question",
+        "index": 6
+      },
+      "body": [
+        {
+          "title": "`0.7`, one floor for all four questions, matching `reviewNoteActionable` and `judgeIdenticalMinP`; a blank value makes every tiered note `critical`, the same fail-safe a blank `reviewNoteActionable` gives (every note an `edit`).",
+          "anchor": {
+            "kind": "paragraph",
+            "line": 152
+          }
+        }
+      ],
+      "children": []
+    },
+    {
+      "title": "What happens without a configured judge?",
+      "detail": "Same as T3: the rest surfaces to the driver, which answers the extra questions like the verdict; no separate fallback.",
+      "status": "answered",
+      "answered": false,
+      "anchor": {
+        "kind": "question",
+        "index": 7
+      },
+      "body": [
+        {
+          "title": "Same as T3: the rest surfaces to the driver, which answers the extra questions like the verdict; no separate fallback.",
+          "anchor": {
+            "kind": "paragraph",
+            "line": 158
+          }
+        }
+      ],
+      "children": []
+    }
+  ]
+}

package/src/steering/fixtures/review/review.md

@@ -0,0 +1,76 @@
+# Review: 0ef1c31
+
+<!-- base: 8d5defb41ddbf4ec3927018eecf09a893653a028 -->
+
+**This round closes the reverse gap from the last review: a commit footer under
+a title with no `!` now fails. It also anchors the title's `!` match and states
+the both-or-neither rule in both agent prompts.** No new risk found.
+`tests/tooling/commits.test.ts` passes locally: **31/31**.
+
+## PR check: both-or-neither for title and footer
+
+**The title check now runs both ways.** A `!` title with no footer fails, as
+before. **A footer with no `!` title now fails too.** The `!` match is a regex
+anchored at the type prefix, so **a `!:` later in the title no longer counts as
+breaking**.
+
+- [ ] ./.github/workflows/commits.yml#36-46 — one
+      `git log --no-merges --format=%B` over the range sets `carries`. The old
+      per-commit loop is gone. `bang` is the bash version of
+      `commitlint.config.mjs`'s `bangHeader` (`\w` spelled `[A-Za-z0-9_]`). The
+      step uses GitHub's default shell, `bash -e` without pipefail, so `grep -q`
+      closing the pipe early cannot flip `carries` off. **If anyone adds
+      `shell: bash` (which turns on pipefail), a SIGPIPE from `git log` can
+      silently drop a found footer.**
+- [ ] ./tests/tooling/commits.test.ts#52-59 — `check` now wraps `checkTitle`
+      with the fixed title `"feat: a title"`. `checkTitle` no longer adds a
+      `feat: fine` commit when given no messages, so callers pass their own.
+- [ ] ./tests/tooling/commits.test.ts#62-66 — the passing case includes a footer
+      commit, so its title gains `!`. Without it the new reverse rule fails the
+      case.
+- [ ] ./tests/tooling/commits.test.ts#118-132 — existing cases are adapted: the
+      title case now supplies its own commit, and the footer commit moves first
+      in the list. Neither changes what the case asserts.
+- [ ] ./tests/tooling/commits.test.ts#140-150 — two new cases: a footer under a
+      plain title fails with "title has no", and `` `!:` `` in the middle of a
+      title passes.
+
+## Convention doc
+
+**`docs/commits.md` states the reverse rule and that the 72-char limit applies
+before GitHub's ` (#N)` suffix.**
+
+- [ ] ./docs/commits.md#10-20 — prose only. The pinned string
+      `at most 72 characters` is unchanged, so the doc-pin test still matches.
+
+## Agent prompts state the rule
+
+**Both closing-message prompts now require `!` and
+`BREAKING CHANGE: <how to migrate>` together, and list the type set.** A new
+test pins this.
+
+- [ ] ./src/workflows/text.ts#867-878 — this replaces the old "`!` alone is not
+      enough" note with "both or neither". It adds a subject-format bullet with
+      the 9 types and the 72-char limit.
+- [ ] ./claude/hooks/ship.ts#64-67 — squash prompt: a `!` subject needs the
+      footer.
+- [ ] ./claude/hooks/ship.ts#301-304 — PR prompt: a `!` title needs the footer
+      line in the description. Line 304 now goes past the prompt's line width
+      (cosmetic only).
+- [ ] ./tests/tooling/commits.test.ts#161-170 — pins both prompt files to the
+      config's `type-enum` and the literal footer placeholder. **The type check
+      is weak: `toContain("ci")` / `"fix"` / `"test"` matches anywhere in large
+      files, so dropping a type from the prompt prose would not fail it.** Only
+      the footer string check has real power.
+
+## Release bump cases and cache inputs
+
+**More semantic-release cases, including a real GitHub squash body. The tooling
+task cache now also keys on `package-lock.json`.**
+
+- [ ] ./tests/tooling/commits.test.ts#238-240 — `fix` → patch, `docs` → no
+      release, and a `(#12)` squash with a `* feat!:` body footer → 2.0.0. This
+      proves the footer cuts a major from inside the squash body.
+- [ ] ./turbo.json#86-88 — adds `package-lock.json` to the inputs, so a
+      commitlint or semantic-release version bump no longer reuses a stale
+      cached pass.