@pmelab/gtd 17.0.0 → 17.3.0

package/src/workflows/text.test.ts

@@ -1,9 +1,11 @@
 import { describe, expect, it } from "vitest"
 import {
+  buildReviewReviewingPrompt,
   agentWithSkills,
   architectureAuthorPrompt,
   architectureGateAnswerMessage,
   buildFixQualityPrompt,
+  buildQualityReviewingPrompt,
   buildReviewAwaitReviewMessage,
   buildReviewCollectingPrompt,
   designGateAnswerMessage,
@@ -101,6 +103,25 @@ describe("the shared open-question instruction", () => {
   })
 })
 
+describe("answered-entry footnote exception", () => {
+  const exception = "carrying a human footnote on its"
+  it("is in the design return lap and loop-back, keeping the deleted-question rule", () => {
+    const prompt = renderText(() => designTriagePrompt("base"))
+    expect(prompt).toContain("Never re-raise a deleted question")
+    expect(prompt).toContain(`entry stays settled, except one ${exception}`)
+    expect(prompt).toContain(`stays settled, except\n  one ${exception}`)
+    expect(prompt).not.toContain("never re-open a settled")
+    expect(prompt).not.toContain("never re-open one")
+  })
+
+  it("is in the architecture return lap and keeps the first-lap settled line", () => {
+    const prompt = renderText(() => architectureAuthorPrompt())
+    expect(prompt).toContain(`entry stays settled, except one ${exception}`)
+    expect(prompt).not.toContain("never re-open a settled")
+    expect(prompt).toMatch(/treat every decision[\s\S]*as settled — never re-open it/)
+  })
+})
+
 describe("architectureAuthorPrompt", () => {
   it("qualifies the PERMISSIVE default with a settled-requirements exception", () => {
     const prompt = renderText(() => architectureAuthorPrompt())
@@ -116,6 +137,37 @@ describe("buildFixQualityPrompt", () => {
   })
 })
 
+describe("buildFixQualityPrompt scope", () => {
+  it("fixes every finding, blocking or not", () => {
+    const prompt = renderText(() => buildFixQualityPrompt())
+    expect(prompt).toContain("fix every finding in every chunk, blocking or not")
+    expect(prompt).not.toContain("found something blocking")
+  })
+})
+
+describe("buildQualityReviewingPrompt", () => {
+  const prompt = renderText(() => buildQualityReviewingPrompt("x"))
+  it("traces, reads touched paths on a large change, and judges tests by reasoning", () => {
+    expect(prompt).toContain("Trace, do not skim")
+    expect(prompt).toContain("order of external calls against")
+    expect(prompt).toContain("read the touched code")
+    expect(prompt).toContain("would fail with the guarded")
+    expect(prompt).toContain("never by running a")
+    expect(prompt).toContain("pins a bug is a finding")
+  })
+  it("writes every finding and approves only when nothing was found", () => {
+    expect(prompt).toContain("APPEND every finding you have, blocking or not")
+    expect(prompt).toContain("only when this lens found nothing at all")
+    expect(prompt).not.toContain("Write nothing when nothing is blocking")
+  })
+  it("adds a brief block only when given one", () => {
+    expect(prompt).not.toContain("This lens's brief")
+    expect(renderText(() => buildQualityReviewingPrompt("x", "BRIEF-TEXT"))).toContain(
+      "This lens's brief:\nBRIEF-TEXT",
+    )
+  })
+})
+
 describe("summaryPrompt", () => {
   it("puts the total and every model's cost on a line of its own", () => {
     const prompt = summaryPrompt({
@@ -198,3 +250,13 @@ describe("code threads in prompts", () => {
     }
   })
 })
+
+describe("buildReviewReviewingPrompt risk marking", () => {
+  it("states the Risk: marker rule and the re-review rule", () => {
+    const prompt = renderText(() => buildReviewReviewingPrompt("base"))
+    expect(prompt).toContain("Open a hunk's note with `Risk:` only for a concrete defect")
+    expect(prompt).toContain("never a style remark")
+    expect(prompt).toContain("describe what the fix changed under the")
+    expect(prompt).toContain("re-mark only a risk the fix did not resolve")
+  })
+})

package/src/workflows/text.ts

@@ -191,8 +191,10 @@ ${questionBarReturn}
   \`git show ${base}\`. (On the first lap that hash
   is the process's own diff base, \`${start()}\` — this
   branch doesn't apply)
-- Every decision under \`## Answered Questions\` stays settled —
-  never re-open one. A genuinely open PRODUCT point may still
+- Every decision under \`## Answered Questions\` stays settled, except
+  one carrying a human footnote on its \`### \` heading — the human's
+  review-round edit is where such notes arrive; fold the note in and
+  rewrite the answer or move it back to \`## Open Questions\`. A genuinely open PRODUCT point may still
   raise a fresh \`## Open Questions\` entry: the product gate sits
   on this path exactly as on the first lap
 - Before grouping anything, run \`${env.testCommand}\`
@@ -505,28 +507,70 @@ ${agentConduct}`
 
 export const buildFixQualityPrompt = (): string =>
   `${stateFileRules}
-- Read \`.gtd/QUALITY.md\` — one \`## \` chunk per quality dimension
-  that found something blocking. Merge duplicate findings across
-  dimensions FIRST, then fix every chunk
+- Read \`.gtd/QUALITY.md\` — one \`## \` chunk per finding a quality
+  dimension wrote. Merge duplicate findings across dimensions
+  FIRST, then fix every finding in every chunk, blocking or not
 - When findings conflict, missing test signal beats line count —
   a test is never deleted to satisfy a simplification finding
 - Delete \`.gtd/QUALITY.md\` once every finding is resolved
 - Leave everything else uncommitted and finish your turn
 `
 
-export const buildQualityReviewingPrompt = (lens: string): string =>
+/** Brief for a lens the workflow defines itself; a lens with none is just a skill of that name. */
+export const correctnessBrief = `- Trace partial-failure and retry paths: what a step that fails
+  after saving an id leaves behind, and whether the retry resumes
+  it or starts over
+- Check validation done before an external side effect — its
+  format, not just its presence
+- Check invariants that parallel write paths share: every path
+  that writes the same data must enforce what the main path
+  enforces
+- New mock behaviour without a contract test against the live
+  behaviour (mock/live drift) is a finding`
+
+export const conventionsBrief = `- Read every \`AGENTS.md\` and \`CLAUDE.md\` in the repository root
+  and in each touched file's directory ancestry, end to end, plus
+  every file they pull in by \`@path\`
+- Every violation of them in the change is a finding — quote the
+  rule it breaks`
+
+export const specChallengeBrief = `- Find this process's planning documents in history:
+  \`git log <start>..HEAD\` (\`<start>\` is the commit above) over the steering directory
+  (\`.gtd/\`), then \`git show\` the last version of the
+  requirements, architecture and package files
+- Flag a spec decision that conflicts with a system invariant — an
+  existing test, a documented constraint, or a data invariant
+  other code relies on — naming the decision and the invariant
+- With no planning documents in history, write nothing`
+
+export const buildQualityReviewingPrompt = (lens: string, brief?: string): string =>
   `${stateFileRules}
 - The only state file this turn writes is \`.gtd/QUALITY.md\` — no
   other files for notes or output
 - Review the whole assembled change, from \`${start()}\`
   to the working tree, through this ONE quality lens only —
-  \`${lens}\`, already loaded as this turn's own skill
-- Where you find something blocking, APPEND a \`## \` chunk to
-  \`.gtd/QUALITY.md\` describing it — never overwrite what an
-  earlier dimension already wrote there
-- Write nothing when nothing is blocking under this lens — a
+  \`${lens}\`
+- Trace, do not skim: follow the order of external calls against
+  the resume/retry logic. On a large change, read the touched code
+  paths, not just the diff hunks
+- A test counts as coverage only if it would fail with the guarded
+  behaviour removed — decide that by reasoning, never by running a
+  mutation-testing tool. A test that pins a bug is a finding, not
+  praise
+- APPEND every finding you have, blocking or not, as a \`## \`
+  chunk to \`.gtd/QUALITY.md\` — never overwrite what an earlier
+  dimension already wrote there
+- Write nothing only when this lens found nothing at all — then a
   clean turn IS this dimension's approval
-- Touch no other state file, and leave everything uncommitted
+${
+  brief
+    ? `
+This lens's brief:
+${brief}
+
+`
+    : ""
+}- Touch no other state file, and leave everything uncommitted
 `
 
 export const reviewerSystem = (): string =>
@@ -642,6 +686,17 @@ The nit notes are:
 
 ${notesCapture(notes)}`
 
+export const buildReviewFixRisksPrompt = (notes: readonly NoteInput[]): string =>
+  `${stateFileRules}
+- Fix every risk below in this one turn, all together
+- Where a risk is behavioural, add a test that fails without the fix
+- Leave \`.gtd/REVIEW.md\` untouched — the re-review rewrites it
+- Leave everything uncommitted and finish your turn
+
+The risk notes are:
+
+${notesCapture(notes)}`
+
 export const reviewEditNotesCapture = (
   commit: string,
   edits: readonly NoteInput[],
@@ -767,6 +822,14 @@ review the changes:
       - [ ] ./path/to/file.ts#42-70 — what this hunk does
         and here is more detail, continued below it
 
+  Open a hunk's note with \`Risk:\` only for a concrete defect
+  the change introduces, never a style remark — each such note is
+  fixed automatically before the human sees the review. On the
+  re-review after a fix, describe what the fix changed under the
+  hunk it touched, and re-mark only a risk the fix did not resolve:
+
+      - [ ] ./path/to/file.ts#42-70 — Risk: what is wrong
+
   A note sitting entirely on the line(s) beneath the pointer is
   also valid. Either way, the note must never start with a bare \`./path\` token
   — that parses as a second pointer, not a note

package/src/workflows/vars.ts

@@ -16,7 +16,8 @@ export const defaults: Readonly<Record<string, string>> = {
   // `./review.ts`) rather than naming one step's skill list, so it is a
   // setting — pairing with `build.quality.reviewing`'s entry in
   // `./skills.ts`, which replaces the lens on every one of those turns.
-  qualityReviews: "owasp-security, ponytail-review, test-audit",
+  qualityReviews:
+    "correctness, owasp-security, ponytail-review, test-audit, conventions, spec-challenge",
 }
 
 /** Environment settings. */