@pmelab/gtd 17.2.0 → 18.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "17.2.0",
+  "version": "18.0.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

@@ -97,7 +97,7 @@
     },
     "skills": {
       "type": "object",
-      "description": "Flat step full-name -> skill-name array map. Each entry REPLACES the named step's bundled skill list wholesale (never merges into it); [] means no skills at all for that step, and no preamble. A key naming a step the workflow in play does not declare is a load error listing the known names — the schema itself cannot validate a key, only a value's shape.",
+      "description": "Flat scope full-name -> skill-name array map. Each entry REPLACES the named scope's skill list wholesale (never merges into it) and reaches every nested scope that sets no list of its own; [] means no skills at all for that scope, and no preamble. A key that is not a scope running a turn is a load error listing the known scopes — the schema itself cannot validate a key, only a value's shape.",
       "additionalProperties": {
         "type": "array",
         "items": {

package/skills/authoring/SKILL.md

@@ -115,10 +115,12 @@ needs across steps — a counter, the previous report, a review round's base —
 lives in local variables; replay rebuilds them.
 
 Composition: `scope(name, fn)` prefixes step names (`build.fix`) and sets their
-**memory scope** (one scope = one agent conversation = one model/system — mixing
-them inside a scope fails the process); `scope({ name?, model, system }, fn)`
-also sets defaults for agent steps inside. `refuse(message)` refuses the pending
-landing — call it right after the step whose turn you reject.
+**memory scope** (one scope = one agent conversation = one model/system/skills —
+mixing them inside a scope fails the process);
+`scope({ name?, model, system, skills }, fn)` also sets defaults for agent steps
+inside. Skills are declared per scope, never on `agent()`, and a driver
+restricts each turn to its scope's list where it can. `refuse(message)` refuses
+the pending landing — call it right after the step whose turn you reject.
 `@pmelab/gtd/flows` exports `requireProgress(file)`, `requireAnswers(file)` and
 `requireRevert(edited, base)`, three such checks ready-made.
 

package/src/flows/runtime.ts

@@ -24,8 +24,6 @@ export interface AgentOptions extends SteeringOptions {
    * is an attempt: recorded, but the process stays at the step (a stall).
    */
   readonly allowEmpty?: boolean | undefined
-  /** The skill names this turn declares — what `gtd next --json`'s `skills` key carries. */
-  readonly skills?: readonly string[] | undefined
 }
 
 export interface HumanOptions extends SteeringOptions {
@@ -92,6 +90,8 @@ export interface ScopeOptions {
   readonly model?: string | undefined
   /** The system prompt every agent step inside runs with, unless it sets its own. */
   readonly system?: string | undefined
+  /** The skill names every agent step inside declares — `gtd next --json`'s `skills`. A nested scope inherits it unless it sets its own. */
+  readonly skills?: readonly string[] | undefined
 }
 
 export type StepRequest =
@@ -139,15 +139,8 @@ export interface FlowContext {
   readonly env: Readonly<Record<string, string>>
   readonly head: () => string
   readonly start: () => string
-  /**
-   * The skill list `localName` (scoped from here, same as `agent()`) resolves
-   * to — for a prompt preamble. `ownSkills`, when given, is the same
-   * precedence tier as a call's own `skills` option: it stands in for the
-   * bundled default when there isn't one, but a `.gtdrc` entry still beats
-   * it. Shares its resolution with `agent()`'s own wire resolver (both read
-   * `Workflow.ts`'s `configuredSkills`/`skills`), so the two can never drift.
-   */
-  readonly skillsFor: (localName: string, ownSkills?: readonly string[]) => readonly string[]
+  /** The skill list the memory scope `localName` lands in resolves to — the same resolver as the wire's `skills`. */
+  readonly skillsFor: (localName: string) => readonly string[]
 }
 
 const CONTEXT_KEY = Symbol.for("@pmelab/gtd/flow-context")
@@ -253,9 +246,8 @@ export const head = (): string => ctx().head()
 /** The process's diff base: the commit before it began, or the base `gtd --entry` fixed. */
 export const start = (): string => ctx().start()
 
-/** The skill list `localName` (scoped from here, same as `agent()`) resolves to — for a prompt preamble. See `FlowContext.skillsFor` for `ownSkills`. */
-export const skillsFor = (localName: string, ownSkills?: readonly string[]): readonly string[] =>
-  ctx().skillsFor(localName, ownSkills)
+/** The skill list `localName` (scoped from here, same as `agent()`) resolves to — for a prompt preamble. */
+export const skillsFor = (localName: string): readonly string[] => ctx().skillsFor(localName)
 
 const settingsProxy = (
   read: () => Readonly<Record<string, string>>,

package/src/workflows/prose.ts

@@ -180,13 +180,20 @@ export const questionBarReturn = `- This lap continues the same goal as the firs
   checkboxes
 - \`## Answered Questions\` is always the last \`##\` section — a moved
   question lands there, never wherever \`## Open Questions\` used to sit
-- Never re-raise a deleted question, and never re-open a settled
-  \`## Answered Questions\` entry
+- Never re-raise a deleted question. A settled \`## Answered Questions\`
+  entry stays settled, except one carrying a human footnote on its
+  \`### \` heading: that is the only entry that may change. Fold the note
+  in, then either rewrite the recorded answer in place (still under
+  \`## Answered Questions\`) or, when the note leaves the point genuinely
+  open, move it back to \`## Open Questions\` as a fresh fork with
+  options and the \`_your answer_\` slot. A note that only asks a
+  question follows the footnote rule: one \`- A:\` reply, answer unchanged
 - An answer may earn a follow-up: if it opens a genuinely new fork above
   the bar — one the answer itself created — raise it as a fresh \`##
   Open Questions\` entry on this same lap. Never restate a question
   already asked, and never treat this as licence to re-open a question
-  already settled under \`## Answered Questions\`
+  already settled under \`## Answered Questions\` that carries no
+  footnote on its heading
 - Recognise a silent lap from \`## Open Questions\` still present with
   nothing ticked and nothing else changed — the human's way of saying
   the gap is already closed. That lap ends the questions, whatever the

package/src/workflows/review.test.ts

@@ -64,7 +64,7 @@ const drive = async (d: Drive): Promise<Run> => {
     },
     "review.closing": () => void files.delete(REVIEW),
     "review.collecting": () => void files.set(REQUIREMENTS, "## Concern"),
-    "review.fix-nits": () => {
+    "review.fix.nits.fixing": () => {
       nitsFixed = true
     },
   }
@@ -118,22 +118,22 @@ describe("the risk-fix pass", () => {
     const run = await drive({ notes: [], reviewDocs: [risky, clean] })
     expect(run.log.slice(0, 5)).toEqual([
       "review.reviewing",
-      "review.fix-risks",
+      "review.fix.risks.fixing",
       "health.check",
       "review.reviewing",
       "review.await-review",
     ])
-    expect(run.prompts.get("review.fix-risks")).toContain("risk-1")
-    expect(run.prompts.get("review.fix-risks")).toContain("Risk: drops the carry")
-    expect(run.prompts.get("review.fix-risks")).toContain("Leave `.gtd/REVIEW.md` untouched")
+    expect(run.prompts.get("review.fix.risks.fixing")).toContain("risk-1")
+    expect(run.prompts.get("review.fix.risks.fixing")).toContain("Risk: drops the carry")
+    expect(run.prompts.get("review.fix.risks.fixing")).toContain("Leave `.gtd/REVIEW.md` untouched")
   })
 
   it("a risk the re-review still marks goes to the gate with no second fix", async () => {
     const run = await drive({ notes: [], reviewDocs: [risky, risky] })
-    expect(run.log.filter((n) => n === "review.fix-risks")).toHaveLength(1)
+    expect(run.log.filter((n) => n === "review.fix.risks.fixing")).toHaveLength(1)
     expect(run.log.slice(0, 5)).toEqual([
       "review.reviewing",
-      "review.fix-risks",
+      "review.fix.risks.fixing",
       "health.check",
       "review.reviewing",
       "review.await-review",
@@ -142,7 +142,7 @@ describe("the risk-fix pass", () => {
 
   it("no marker means no fix-risks step", async () => {
     const run = await drive({ notes: [], reviewDocs: [clean] })
-    expect(run.log).not.toContain("review.fix-risks")
+    expect(run.log).not.toContain("review.fix.risks.fixing")
     expect(run.log[0]).toBe("review.reviewing")
     expect(run.log[1]).toBe("review.await-review")
   })
@@ -157,11 +157,11 @@ describe("the risk-fix pass", () => {
       "review.reviewing",
       "review.await-review",
       "review.triage",
-      "review.fix-nits",
+      "review.fix.nits.fixing",
       "health.check",
       "review.closing",
       "review.reviewing",
-      "review.fix-risks",
+      "review.fix.risks.fixing",
       "health.check",
       "review.reviewing",
       "review.await-review",
@@ -250,12 +250,12 @@ describe("review verdict routing", () => {
       "review.await-review",
       "review.triage",
       "review.answer-review-questions",
-      "review.fix-nits",
+      "review.fix.nits.fixing",
       "health.check",
       "review.closing",
       "review.reviewing",
     ])
-    expect(run.prompts.get("review.fix-nits")).not.toContain("why?")
+    expect(run.prompts.get("review.fix.nits.fixing")).not.toContain("why?")
     expect(run.prompts.get("review.reviewing")).toContain("Carry-over: commit `c4`")
     expect(run.result).toBe("stopped")
   })
@@ -278,7 +278,7 @@ describe("review verdict routing", () => {
       "review.await-review",
       "review.triage",
       "review.answer-review-questions",
-      "review.fix-nits",
+      "review.fix.nits.fixing",
       "health.check",
       "review.closing",
       "review.collecting",

package/src/workflows/review.ts

@@ -36,9 +36,9 @@ import {
 } from "./steps.js"
 import * as t from "./text.js"
 
-/** The lenses the quality lap reviews with, one turn each: the `qualityReviews` var, split on `,` and trimmed. Unlike a `skills:` entry, this fans out into one whole turn per entry rather than naming one step's skill list — see `build.quality.reviewing` in `./skills.ts` for the (separate) skills a lens turn itself loads. */
-export const qualityLenses = (): readonly string[] =>
-  (vars.qualityReviews ?? "")
+/** Split a `qualityReviews` value into its lenses: on `,`, trimmed, blanks dropped. */
+export const lensesOf = (value: string): readonly string[] =>
+  value
     .split(",")
     .map((lens) => lens.trim())
     .filter((lens) => lens.length > 0)
@@ -49,7 +49,7 @@ export const qualityLenses = (): readonly string[] =>
  * has any.
  */
 export const qualityLap = async (): Promise<"clean" | "findings"> => {
-  for (const lens of qualityLenses()) await reviewQuality(lens)
+  for (const lens of lensesOf(vars.qualityReviews ?? "")) await reviewQuality(lens)
   return (read(QUALITY) ?? "").length > 0 ? "findings" : "clean"
 }
 

package/src/workflows/skills.test.ts

@@ -1,94 +1,80 @@
 import { describe, expect, it } from "vitest"
 import { skills } from "./skills.js"
+import { unified } from "./index.js"
 
-// Pins every bundled step's own declared list, keyed by its full name. This
-// file alone only catches a LOCAL-name rename (the list literally changes);
-// it cannot catch a SCOPE rename (e.g. `scope("architecture")` renamed to
-// `scope("design.architecture")`), because it never runs the real flow — it
-// compares the map against itself. Every one of the sixteen keys has its
-// own e2e grounding closing that gap instead — each runs the actual scoped
-// name through replay, so a scope rename desyncs a preamble assertion there,
-// not just silently drops a step's skills (see AGENTS.md's "workflow is
-// code" rule: a step's full name is public API):
-//   - design.triage, architecture.author, architecture.decompose,
-//     packages.item.building — default-workflow.feature's main scenario
-//   - packages.item.spec.review, packages.item.fix-spec — the same
-//     scenario, continued
-//   - packages.item.fix-suite, packages.item.health.describe — the
-//     "escalation loop ... under packages.item" scenario
-//   - build.fix — state-skills.feature
-//   - build.health.describe — the "repeated check failures escalate"
-//     scenario
-//   - build.quality.reviewing — per-step-skills.feature
-//   - build.fix-quality — quality-review-lap.feature
-//   - build.review.reviewing, build.review.collecting —
-//     default-workflow.feature's review-loop scenarios
-//   - build.review.answer-review-questions, build.review.fix-nits — NOT yet
-//     e2e-grounded; only steps.test.ts's preamble checks, which use local names
-describe("the bundled workflow's skills map", () => {
-  it("declares exactly the seventeen bundled agent steps, by full name", () => {
-    expect(Object.keys(skills).sort()).toEqual(
+const { defaults } = unified
+
+const bundled = skills(defaults)
+
+// Pins the lists by scope full name. It never runs the real flow, so a
+// scope rename is caught by the e2e features that rest on these names
+// (default-workflow, state-skills, scope-skills, quality-review-lap), not here.
+describe("the bundled workflow's skills export", () => {
+  it("declares exactly the bundled scopes under the default qualityReviews", () => {
+    expect(Object.keys(bundled).sort()).toEqual(
       [
-        "design.triage",
-        "architecture.author",
+        "design",
+        "architecture",
         "architecture.decompose",
-        "packages.item.building",
-        "packages.item.fix-suite",
-        "packages.item.fix-spec",
-        "packages.item.spec.review",
-        "packages.item.health.describe",
-        "build.fix",
-        "build.health.describe",
-        "build.quality.reviewing",
-        "build.fix-quality",
-        "build.review.reviewing",
-        "build.review.answer-review-questions",
-        "build.review.fix-nits",
-        "build.review.fix-risks",
-        "build.review.collecting",
+        "packages.item",
+        "packages.item.fix.suite",
+        "packages.item.fix.spec",
+        "packages.item.spec",
+        "packages.item.health",
+        "build",
+        "build.health",
+        "build.fix.quality",
+        "build.review",
+        "build.review.fix.nits",
+        "build.review.fix.risks",
+        "build.quality.correctness",
+        "build.quality.owasp-security",
+        "build.quality.ponytail-review",
+        "build.quality.test-audit",
+        "build.quality.conventions",
+        "build.quality.spec-challenge",
       ].sort(),
     )
   })
 
-  it("packages.item.health.describe and build.health.describe are both present, with the same list — the shared escalation loop resolves under both scopes", () => {
-    expect(skills["packages.item.health.describe"]).toEqual(skills["build.health.describe"])
-    expect(skills["packages.item.health.describe"]).toEqual(["debugging-and-error-recovery"])
+  it("keys no group scope", () => {
+    for (const group of ["packages.item.fix", "build.fix", "build.review.fix", "build.quality"]) {
+      expect(bundled).not.toHaveProperty(group)
+    }
+  })
+
+  it("pins each scope's list", () => {
+    expect(bundled).toMatchObject({
+      design: ["spec-driven-development", "planning-and-task-breakdown"],
+      architecture: ["api-and-interface-design", "documentation-and-adrs", "ponytail"],
+      "architecture.decompose": ["incremental-implementation", "planning-and-task-breakdown"],
+      "packages.item": ["test-driven-development", "incremental-implementation"],
+      "packages.item.fix.suite": ["debugging-and-error-recovery"],
+      "packages.item.fix.spec": ["incremental-implementation", "code-simplification"],
+      "packages.item.spec": ["code-review-and-quality", "spec-driven-development"],
+      "packages.item.health": ["debugging-and-error-recovery"],
+      build: ["debugging-and-error-recovery"],
+      "build.health": ["debugging-and-error-recovery"],
+      "build.fix.quality": ["incremental-implementation", "code-simplification"],
+      "build.review": ["code-review-and-quality"],
+      "build.review.fix.nits": ["incremental-implementation", "code-simplification"],
+      "build.review.fix.risks": ["debugging-and-error-recovery", "incremental-implementation"],
+    })
+  })
+
+  it("loads one lens skill per quality lens: correctness its review skill, conventions and spec-challenge none, any other itself", () => {
+    expect(bundled["build.quality.correctness"]).toEqual(["code-review-and-quality"])
+    expect(bundled["build.quality.conventions"]).toEqual([])
+    expect(bundled["build.quality.spec-challenge"]).toEqual([])
+    expect(bundled["build.quality.owasp-security"]).toEqual(["owasp-security"])
   })
 
-  it("pins each step's own declared list", () => {
-    expect(skills["design.triage"]).toEqual([
-      "spec-driven-development",
-      "planning-and-task-breakdown",
-    ])
-    expect(skills["architecture.author"]).toEqual([
-      "api-and-interface-design",
-      "documentation-and-adrs",
-      "ponytail",
-    ])
-    expect(skills["architecture.decompose"]).toEqual([
-      "incremental-implementation",
-      "planning-and-task-breakdown",
-    ])
-    expect(skills["packages.item.building"]).toEqual([
-      "test-driven-development",
-      "incremental-implementation",
-    ])
-    expect(skills["packages.item.fix-suite"]).toEqual(["debugging-and-error-recovery"])
-    expect(skills["build.fix"]).toEqual(["debugging-and-error-recovery"])
-    expect(skills["packages.item.fix-spec"]).toEqual([
-      "incremental-implementation",
-      "code-simplification",
-    ])
-    expect(skills["build.fix-quality"]).toEqual([
-      "incremental-implementation",
-      "code-simplification",
-    ])
-    expect(skills["packages.item.spec.review"]).toEqual([
-      "code-review-and-quality",
-      "spec-driven-development",
-    ])
-    expect(skills["build.review.reviewing"]).toEqual(["code-review-and-quality"])
-    expect(skills["build.review.collecting"]).toEqual(["code-review-and-quality"])
-    expect(skills["build.quality.reviewing"]).toEqual([])
+  it("keys one lens scope per qualityReviews entry", () => {
+    const custom = skills({ ...defaults, qualityReviews: " my-lens ,, correctness" })
+    expect(
+      Object.keys(custom)
+        .filter((k) => k.startsWith("build.quality."))
+        .sort(),
+    ).toEqual(["build.quality.correctness", "build.quality.my-lens"])
   })
 })

package/src/workflows/skills.ts

@@ -1,38 +1,34 @@
-// The bundled workflow's default skills, one list per agent step, keyed by
-// the step's FULL name (its scope prefixes included) — the same name a
-// `.gtdrc` `skills:` entry addresses. A step's name is not derivable from
-// flow code alone (loops, branches, shared calls), so this map is the only
-// place every addressable name is declared up front; `steps.test.ts` pins
-// each step's declared list against a renamed map key.
-//
-// `packages.item.health.describe` and `build.health.describe` are not a
-// duplicate: the escalation loop (`healthy()`, in `./health.ts`) is shared
-// code reached from both `scope("packages") -> scope("item")` and
-// `scope("build")`, so the one `health.describe` step name resolves to two
-// different full names depending on which caller is looping.
-export const skills: Readonly<Record<string, readonly string[]>> = {
-  "design.triage": ["spec-driven-development", "planning-and-task-breakdown"],
-  "architecture.author": ["api-and-interface-design", "documentation-and-adrs", "ponytail"],
+import { builtInLenses } from "./steps.js"
+import { lensesOf } from "./review.js"
+
+// The bundled workflow's default skills, one list per SCOPE, keyed by the
+// scope's full name — the same name a `.gtdrc` `skills:` entry addresses. A
+// nested scope with no entry inherits its parent's; group scopes
+// (`packages.item.fix`, `build.fix`, `build.review.fix`, `build.quality`) run
+// no turn and carry no key. `build.quality.<lens>` is one key per
+// `qualityReviews` entry, so the export is a function of the vars.
+export const skills = (
+  vars: Readonly<Record<string, string>>,
+): Readonly<Record<string, readonly string[]>> => ({
+  design: ["spec-driven-development", "planning-and-task-breakdown"],
+  architecture: ["api-and-interface-design", "documentation-and-adrs", "ponytail"],
   "architecture.decompose": ["incremental-implementation", "planning-and-task-breakdown"],
-  "packages.item.building": ["test-driven-development", "incremental-implementation"],
-  "packages.item.fix-suite": ["debugging-and-error-recovery"],
-  "packages.item.fix-spec": ["incremental-implementation", "code-simplification"],
-  "packages.item.spec.review": ["code-review-and-quality", "spec-driven-development"],
-  "packages.item.health.describe": ["debugging-and-error-recovery"],
-  "build.fix": ["debugging-and-error-recovery"],
-  "build.health.describe": ["debugging-and-error-recovery"],
-  // No bundled default: unlike every other entry, the lens named in the
-  // prompt BODY already varies per turn (see `reviewQuality` in
-  // `./steps.ts`), which is what the preamble falls back to naming instead —
-  // a fixed bundled list here would repeat one entry on every turn. A
-  // `.gtdrc` `skills:` entry still overrides that per-turn fallback, on the
-  // wire and in the preamble alike (`resolveSkills` in `../replay/Replay.ts`
-  // is what both share).
-  "build.quality.reviewing": [],
-  "build.fix-quality": ["incremental-implementation", "code-simplification"],
-  "build.review.reviewing": ["code-review-and-quality"],
-  "build.review.answer-review-questions": ["code-review-and-quality"],
-  "build.review.fix-nits": ["incremental-implementation", "code-simplification"],
-  "build.review.fix-risks": ["debugging-and-error-recovery", "incremental-implementation"],
-  "build.review.collecting": ["code-review-and-quality"],
-}
+  "packages.item": ["test-driven-development", "incremental-implementation"],
+  "packages.item.fix.suite": ["debugging-and-error-recovery"],
+  "packages.item.fix.spec": ["incremental-implementation", "code-simplification"],
+  "packages.item.spec": ["code-review-and-quality", "spec-driven-development"],
+  // `health` is shared code reached from both `packages.item` and `build`.
+  "packages.item.health": ["debugging-and-error-recovery"],
+  build: ["debugging-and-error-recovery"],
+  "build.health": ["debugging-and-error-recovery"],
+  "build.fix.quality": ["incremental-implementation", "code-simplification"],
+  "build.review": ["code-review-and-quality"],
+  "build.review.fix.nits": ["incremental-implementation", "code-simplification"],
+  "build.review.fix.risks": ["debugging-and-error-recovery", "incremental-implementation"],
+  ...Object.fromEntries(
+    lensesOf(vars.qualityReviews ?? "").map((lens) => [
+      `build.quality.${lens}`,
+      builtInLenses[lens]?.skills ?? [lens],
+    ]),
+  ),
+})