@pmelab/gtd 15.10.0 → 17.0.0

package/src/workflows/steps.ts

@@ -1,4 +1,4 @@
-import { human, vars } from "../flows/index.js"
+import { env, human } from "../flows/index.js"
 import * as t from "./text.js"
 
 // The bundled workflow's single steps. A step's name is relative to the
@@ -14,14 +14,14 @@ export const REVIEW = ".gtd/REVIEW.md"
 export const QUALITY = ".gtd/QUALITY.md"
 export const SPEC_FEEDBACK = ".gtd/SPEC_FEEDBACK.md"
 
-const planner = (): string => vars.plannerModel ?? ""
-const coder = (): string => vars.coderModel ?? ""
+const planner = (): string => env.plannerModel ?? ""
+const coder = (): string => env.coderModel ?? ""
 
 // ── Planning ────────────────────────────────────────────────────────────────
 
 /** Turn the sketch since `base` into `.gtd/REQUIREMENTS.md`. */
 export const triage = (base: string): Promise<void> =>
-  t.agentWithSkills("triage", vars.triageSkills, t.designTriagePrompt(base), {
+  t.agentWithSkills("triage", t.designTriagePrompt(base), {
     label: "Triaging the change",
     file: REQUIREMENTS,
     mode: "qa",
@@ -30,7 +30,7 @@ export const triage = (base: string): Promise<void> =>
   })
 
 export const author = (): Promise<void> =>
-  t.agentWithSkills("author", vars.architectureSkills, t.architectureAuthorPrompt(), {
+  t.agentWithSkills("author", t.architectureAuthorPrompt(), {
     label: "Refining the technical plan",
     file: ARCHITECTURE,
     mode: "qa",
@@ -39,7 +39,7 @@ export const author = (): Promise<void> =>
   })
 
 export const decompose = (): Promise<void> =>
-  t.agentWithSkills("decompose", vars.decomposeSkills, t.architectureDecomposePrompt(), {
+  t.agentWithSkills("decompose", t.architectureDecomposePrompt(), {
     label: "Decomposing into packages",
     model: planner(),
     system: t.architectSystem(),
@@ -66,14 +66,14 @@ export const answerTechnicalQuestions = (): Promise<void> =>
 // ── Packages ────────────────────────────────────────────────────────────────
 
 export const build = (pkg: string): Promise<void> =>
-  t.agentWithSkills("building", vars.buildSkills, t.packagesItemBuildingPrompt(pkg), {
+  t.agentWithSkills("building", t.packagesItemBuildingPrompt(pkg), {
     label: "Building",
     model: coder(),
     system: t.builderSystem(),
   })
 
 export const fixSuite = (): Promise<void> =>
-  t.agentWithSkills("fix-suite", vars.fixSkills, t.packagesItemFixSuitePrompt(), {
+  t.agentWithSkills("fix-suite", t.packagesItemFixSuitePrompt(), {
     label: "Fixing the check",
     file: FEEDBACK,
     model: coder(),
@@ -81,7 +81,7 @@ export const fixSuite = (): Promise<void> =>
   })
 
 export const fixSpec = (pkg: string): Promise<void> =>
-  t.agentWithSkills("fix-spec", vars.reviewFixSkills, t.packagesItemFixSpecPrompt(pkg), {
+  t.agentWithSkills("fix-spec", t.packagesItemFixSpecPrompt(pkg), {
     label: "Fixing review feedback",
     file: SPEC_FEEDBACK,
     model: coder(),
@@ -90,22 +90,17 @@ export const fixSpec = (pkg: string): Promise<void> =>
 
 /** Review `pkg` against its spec, focused on the `failing` sections the pre-judge could not clear. */
 export const reviewPackage = (pkg: string, failing: readonly string[] = []): Promise<void> =>
-  t.agentWithSkills(
-    "spec.review",
-    vars.specReviewSkills,
-    t.packagesItemSpecReviewPrompt(pkg, failing),
-    {
-      label: "Reviewing the package",
-      model: planner(),
-      system: t.specReviewerSystem(),
-      allowEmpty: true,
-    },
-  )
+  t.agentWithSkills("spec.review", t.packagesItemSpecReviewPrompt(pkg, failing), {
+    label: "Reviewing the package",
+    model: planner(),
+    system: t.specReviewerSystem(),
+    allowEmpty: true,
+  })
 
 // ── Keeping the suite green ─────────────────────────────────────────────────
 
 export const fix = (): Promise<void> =>
-  t.agentWithSkills("fix", vars.fixSkills, t.buildFixPrompt(), {
+  t.agentWithSkills("fix", t.buildFixPrompt(), {
     label: "Fixing the check",
     file: FEEDBACK,
     model: coder(),
@@ -113,7 +108,7 @@ export const fix = (): Promise<void> =>
   })
 
 export const describeEscalation = (): Promise<void> =>
-  t.agentWithSkills("health.describe", vars.escalateSkills, t.healthDescribePrompt(), {
+  t.agentWithSkills("health.describe", t.healthDescribePrompt(), {
     label: "Describing the escalation",
     file: FEEDBACK,
     model: coder(),
@@ -139,18 +134,24 @@ export const escalationExhausted = (): Promise<void> =>
 
 // ── Quality and review ──────────────────────────────────────────────────────
 
-/** One quality review, through the skill `lens`. */
+/**
+ * One quality review, through the skill `lens`. `lens` rides as this turn's
+ * own `skills` option — a `.gtdrc` `build.quality.reviewing` entry still
+ * overrides it (config beats a flow-supplied list same as any other step),
+ * but absent one the lens itself is what the turn loads by default.
+ */
 export const reviewQuality = (lens: string): Promise<void> =>
-  t.agentWithSkills("quality.reviewing", lens, t.buildQualityReviewingPrompt(lens), {
+  t.agentWithSkills("quality.reviewing", t.buildQualityReviewingPrompt(lens), {
     label: "Reviewing (one quality lens)",
     file: QUALITY,
     model: planner(),
     system: t.reviewerSystem(),
     allowEmpty: true,
+    skills: [lens],
   })
 
 export const fixQuality = (): Promise<void> =>
-  t.agentWithSkills("fix-quality", vars.reviewFixSkills, t.buildFixQualityPrompt(), {
+  t.agentWithSkills("fix-quality", t.buildFixQualityPrompt(), {
     label: "Fixing quality findings",
     file: QUALITY,
     model: coder(),
@@ -160,41 +161,31 @@ export const fixQuality = (): Promise<void> =>
 
 /** Write `.gtd/REVIEW.md` over everything since `base`, carrying the answers of commit `carry` when given. */
 export const reviewing = (base: string, carry?: string): Promise<void> =>
-  t.agentWithSkills(
-    "review.reviewing",
-    vars.reviewSkills,
-    t.buildReviewReviewingPrompt(base, carry),
-    {
-      label: "Reviewing",
-      file: REVIEW,
-      mode: "review",
-      model: planner(),
-      system: t.reviewerSystem(),
-      base,
-    },
-  )
+  t.agentWithSkills("review.reviewing", t.buildReviewReviewingPrompt(base, carry), {
+    label: "Reviewing",
+    file: REVIEW,
+    mode: "review",
+    model: planner(),
+    system: t.reviewerSystem(),
+    base,
+  })
 
 /** Answer every `question` note inline in `.gtd/REVIEW.md`. */
 export const answerReviewQuestions = (notes: readonly t.NoteInput[]): Promise<void> =>
-  t.agentWithSkills(
-    "review.answer-review-questions",
-    vars.reviewSkills,
-    t.buildReviewAnswerQuestionsPrompt(notes),
-    {
-      label: "Answering your questions",
-      file: REVIEW,
-      mode: "review",
-      model: planner(),
-      system: t.reviewerSystem(),
-    },
-  )
+  t.agentWithSkills("review.answer-review-questions", t.buildReviewAnswerQuestionsPrompt(notes), {
+    label: "Answering your questions",
+    file: REVIEW,
+    mode: "review",
+    model: planner(),
+    system: t.reviewerSystem(),
+  })
 
 /**
  * Fix every `nit` note in one turn. Its name puts it in the `build.review`
  * conversation, which has one identity — so it runs as the reviewer, not the coder.
  */
 export const fixNits = (notes: readonly t.NoteInput[]): Promise<void> =>
-  t.agentWithSkills("review.fix-nits", vars.reviewFixSkills, t.buildReviewFixNitsPrompt(notes), {
+  t.agentWithSkills("review.fix-nits", t.buildReviewFixNitsPrompt(notes), {
     label: "Fixing your nits",
     file: REVIEW,
     model: planner(),
@@ -219,16 +210,11 @@ export const reviewMissing = (round: string): Promise<void> =>
 
 /** Turn the review round `capture` describes into `.gtd/REQUIREMENTS.md`, or change nothing. */
 export const collecting = (capture: string): Promise<void> =>
-  t.agentWithSkills(
-    "review.collecting",
-    vars.reviewSkills,
-    t.buildReviewCollectingPrompt(capture),
-    {
-      label: "Collecting your feedback",
-      file: REQUIREMENTS,
-      mode: "qa",
-      model: planner(),
-      system: t.reviewerSystem(),
-      allowEmpty: true,
-    },
-  )
+  t.agentWithSkills("review.collecting", t.buildReviewCollectingPrompt(capture), {
+    label: "Collecting your feedback",
+    file: REQUIREMENTS,
+    mode: "qa",
+    model: planner(),
+    system: t.reviewerSystem(),
+    allowEmpty: true,
+  })

package/src/workflows/text.fixture.ts

@@ -4,20 +4,56 @@ import {
   type FlowContext,
   type StepRequest,
 } from "../flows/index.js"
-import { defaults } from "./vars.js"
+import { skills as bundledSkills } from "./skills.js"
+import { defaults, envDefaults } from "./vars.js"
 
 export interface TextContext {
   readonly vars?: Readonly<Record<string, string>>
+  readonly env?: Readonly<Record<string, string>>
   readonly head?: string
   readonly start?: string
   readonly codeThreads?: readonly CodeThreadInfo[]
   readonly read?: (path: string) => string | undefined
+  /**
+   * A PER-KEY `skillsFor` override, keyed by the LOCAL name a bundled step
+   * calls itself with (`captureStep`/`renderText` push no scopes, so a local
+   * name is also the only name here) — stands in for a `.gtdrc` entry, so
+   * only the key it names is overridden; every other step still falls back
+   * to the call's own `skills` option, then the bundled map (`./skills.ts`),
+   * so an existing step test keeps its skills without having to declare them
+   * itself.
+   */
+  readonly skills?: Readonly<Record<string, readonly string[]>>
 }
 
 const unavailable = (): never => {
   throw new Error("not available while rendering a text outside a replay")
 }
 
+/** The bundled map is keyed by FULL name, but a bundled step calls itself by its own LOCAL name and this fixture pushes no scope to prefix it with — so the default lookup matches on the local name alone, or as the last `.`-separated segment of a bundled key. `health.describe`'s two bundled entries (`packages.item.health.describe`, `build.health.describe`) share one list, so the ambiguity this leaves resolves to the same answer either way. */
+const bundledSkillsFor = (localName: string): readonly string[] => {
+  const exact = bundledSkills[localName]
+  if (exact !== undefined) return exact
+  const suffix = `.${localName}`
+  const hit = Object.entries(bundledSkills).find(([key]) => key.endsWith(suffix))
+  return hit?.[1] ?? []
+}
+
+/**
+ * Mirrors `Replay.ts`'s `resolveSkills` three-way precedence: `context.skills`
+ * (a per-key override, standing in for `.gtdrc`) beats `ownSkills` (a call's
+ * own `skills` option), which beats the bundled default — so a step test that
+ * passes its own `skills` option (like `reviewQuality`'s lens) sees it in the
+ * preamble too, the same as a real replay would.
+ */
+const skillsForOf =
+  (context: TextContext) =>
+  (localName: string, ownSkills?: readonly string[]): readonly string[] => {
+    const configured = context.skills?.[localName]
+    if (configured !== undefined) return configured
+    return ownSkills ?? bundledSkillsFor(localName)
+  }
+
 /** The fixed replay context texts render against; steps, refusals and scopes are unavailable unless overridden. */
 export const fixtureContext = (
   context: TextContext = {},
@@ -38,8 +74,10 @@ export const fixtureContext = (
   threads: () => [],
   codeThreads: () => context.codeThreads ?? [],
   vars: { ...defaults, ...context.vars },
+  env: { ...envDefaults, ...context.env },
   head: () => context.head ?? "",
   start: () => context.start ?? "",
+  skillsFor: skillsForOf(context),
   ...overrides,
 })
 

package/src/workflows/text.test.ts

@@ -8,7 +8,6 @@ import {
   buildReviewCollectingPrompt,
   designGateAnswerMessage,
   designTriagePrompt,
-  splitSkills,
   summaryPrompt,
   withSkills,
 } from "./text.js"
@@ -30,42 +29,36 @@ describe("withSkills", () => {
   })
 })
 
-describe("splitSkills", () => {
-  it("splits on comma, trims each name, drops empty entries", () => {
-    expect(splitSkills("a, b")).toEqual(["a", "b"])
-    expect(splitSkills(" a ,, b ")).toEqual(["a", "b"])
-  })
-
-  it("returns [] for undefined, empty, or blank input", () => {
-    expect(splitSkills(undefined)).toEqual([])
-    expect(splitSkills("")).toEqual([])
-    expect(splitSkills("   ")).toEqual([])
-  })
-})
-
 describe("agentWithSkills", () => {
-  const capture = (fn: () => Promise<void>) => captureStep(fn)
+  const capture = (fn: () => Promise<void>, skills?: Readonly<Record<string, readonly string[]>>) =>
+    captureStep(fn, skills !== undefined ? { skills } : {})
 
-  it("produces a byte-identical preamble to withSkills for a comma-free name list", async () => {
-    const skills = "code-review, testing"
-    const viaHelper = await capture(() => agentWithSkills("name", skills, "do-the-work"))
-    if (viaHelper.kind !== "agent") throw new Error("unreachable")
-    expect(viaHelper.prompt).toBe(withSkills(skills, "do-the-work"))
+  it("puts skillsFor(name)'s list, joined, in the preamble", async () => {
+    const request = await capture(() => agentWithSkills("name", "do-the-work"), {
+      name: ["code-review", "testing"],
+    })
+    if (request.kind !== "agent") throw new Error("unreachable")
+    expect(request.prompt).toBe(withSkills("code-review, testing", "do-the-work"))
   })
 
-  it("passes the skills list, split, as the option, alongside the preamble", async () => {
-    const request = await capture(() =>
-      agentWithSkills("name", "code-review, testing", "do-the-work"),
-    )
+  it("passes no skills option itself — the replay resolver fills the wire field", async () => {
+    const request = await capture(() => agentWithSkills("name", "do-the-work"))
     if (request.kind !== "agent") throw new Error("unreachable")
-    expect(request.options.skills).toEqual(["code-review", "testing"])
+    expect(request.options.skills).toBeUndefined()
   })
 
-  it("leaves the prompt bare and the option an empty array when skills is undefined", async () => {
-    const request = await capture(() => agentWithSkills("name", undefined, "do-the-work"))
+  it("leaves the prompt bare when the name resolves to no configured skills", async () => {
+    const request = await capture(() => agentWithSkills("name", "do-the-work"), { name: [] })
     if (request.kind !== "agent") throw new Error("unreachable")
     expect(request.prompt).toBe("do-the-work")
-    expect(request.options.skills).toEqual([])
+  })
+
+  it("still accepts an explicit options.skills of its own, untouched", async () => {
+    const request = await capture(() =>
+      agentWithSkills("name", "do-the-work", { skills: ["own-skill"] }),
+    )
+    if (request.kind !== "agent") throw new Error("unreachable")
+    expect(request.options.skills).toEqual(["own-skill"])
   })
 })
 
@@ -136,6 +129,7 @@ describe("summaryPrompt", () => {
         { model: "base", cost: 7 },
       ],
       vars: {},
+      env: {},
     })
     expect(prompt).toContain("Token cost: 12\n- smart: 5\n- base: 7\n\nPrint the closing message")
   })

package/src/workflows/text.ts

@@ -1,9 +1,10 @@
 import {
   agent,
   codeThreads,
+  env,
   head,
+  skillsFor,
   start,
-  vars,
   type AgentOptions,
   type SummaryContext,
 } from "../flows/index.js"
@@ -36,31 +37,23 @@ export const withSkills = (skills: string | undefined, prompt: string): string =
   return `${skillsPreamble.replaceAll("{skills}", skills)}\n\n${prompt}`
 }
 
-/** `skills:` split on `,`, each name trimmed, empty entries dropped — `[]` for `undefined`, `""`, or blank. */
-export const splitSkills = (raw: string | undefined): readonly string[] =>
-  (raw ?? "")
-    .split(",")
-    .map((name) => name.trim())
-    .filter((name) => name.length > 0)
-
 /**
- * An `agent()` step declaring `skills`: the raw, comma-separated var feeds
- * both the `skills` option (the wire's `skills` key, split) and, re-joined
- * with `", "`, `withSkills`'s preamble — one declaration, so the two can
- * never drift apart.
+ * An `agent()` step whose preamble names its resolved skills: `skillsFor`
+ * resolves `name` (scoped from here, same as `agent()`'s own resolver) for
+ * the preamble prose, passing `options.skills` through as `ownSkills` — the
+ * same precedence tier `agent()`'s own wire resolver gives a call's own
+ * `skills` option, so a step that declares one (`reviewQuality`'s per-turn
+ * lens) gets it in the preamble too, not just on the wire, whenever no
+ * bundled or configured entry outranks it. Both reads share one resolver
+ * (`Replay.ts`'s `resolveSkills`), so the preamble and the wire can't drift
+ * apart.
  */
 export const agentWithSkills = (
   name: string,
-  skills: string | undefined,
   prompt: string,
   options: AgentOptions = {},
-): Promise<void> => {
-  const list = splitSkills(skills)
-  return agent(name, withSkills(list.join(", "), prompt), {
-    ...options,
-    skills: list,
-  })
-}
+): Promise<void> =>
+  agent(name, withSkills(skillsFor(name, options.skills).join(", "), prompt), options)
 
 export const unwindFailure = (commit: string): string =>
   `gtd could not unwind ${commit} out of your working tree.`
@@ -202,7 +195,7 @@ ${questionBarReturn}
   never re-open one. 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 \`${vars.testCommand}\`
+- Before grouping anything, run \`${env.testCommand}\`
   yourself — a loop-back runs no green-baseline gate, so the
   tree may already be red (reverting the edit can undo a fix it
   made). If red, make that breakage the first concern, ahead of
@@ -814,10 +807,13 @@ every commit is machine-authored.
   high-level architectural changes — never which files changed; \`git
   diff --stat\` is for that, not this message
 - If the range removes or renames a documented config key, CLI flag, or
-  workflow state — a public surface, not an internal one — add a literal
-  \`BREAKING CHANGE:\` footer naming what disappears. A \`!\` on the type
-  prefix alone (\`feat!:\`/\`refactor!:\`) is NOT enough: this repo's own
-  commit-analyzer has missed that marker before, cutting no release
+  workflow state, OR makes a previously-accepted config value now fail to
+  load (a stricter validation, an escape a value must now spell differently)
+  — a public surface, not an internal one, either way — add a literal
+  \`BREAKING CHANGE:\` footer naming what breaks and, for the second case,
+  the exact escape or rewrite a committed \`.gtdrc\` needs. A \`!\` on the
+  type prefix alone (\`feat!:\`/\`refactor!:\`) is NOT enough: this repo's
+  own commit-analyzer has missed that marker before, cutting no release
   until a follow-up commit carried the literal footer instead
 
 The process's entry commit is \`${it.entryCommit}\`. ${human}Inspect the range: \`git log ${it.processBase}..${it.processTip}\`

package/src/workflows/unified.ts

@@ -31,7 +31,8 @@ import * as t from "./text.js"
 // re-exported below.
 
 export { threads, type ThreadInfo } from "../flows/index.js"
-export { defaults } from "./vars.js"
+export { defaults, envDefaults } from "./vars.js"
+export { skills } from "./skills.js"
 export { agentWithSkills } from "./text.js"
 export * from "./steps.js"
 export * from "./health.js"

package/src/workflows/vars.ts

@@ -1,23 +1,27 @@
-// The bundled workflow's variable defaults. `.gtdrc` `vars:`, `--var` and
-// `GTD_<NAME>` override any of them.
+// The bundled workflow's settings, in two kinds. A process setting changes
+// which step comes next, so it is pinned for the whole process at its start;
+// an environment setting only changes how a step runs on this machine, so it
+// is read live on every invocation. `.gtdrc` `vars:`/`env:`, `--var` (process
+// settings only) and `GTD_<NAME>` override either.
+
+/** Process settings. */
 export const defaults: Readonly<Record<string, string>> = {
-  testCommand: "npm test",
-  plannerModel: "smart",
-  coderModel: "base",
   reviewBase: "",
   judgeBudgetBytes: "32768",
   judgeIdenticalMinP: "0.7",
   specPreJudge: "0.9",
   reviewNoteActionable: "0.7",
   architectureSkipMinP: "0.85",
-  triageSkills: "spec-driven-development, planning-and-task-breakdown",
-  architectureSkills: "api-and-interface-design, documentation-and-adrs, ponytail",
-  decomposeSkills: "incremental-implementation, planning-and-task-breakdown",
-  buildSkills: "test-driven-development, incremental-implementation",
-  fixSkills: "debugging-and-error-recovery",
-  reviewFixSkills: "incremental-implementation, code-simplification",
-  reviewSkills: "code-review-and-quality",
-  specReviewSkills: "code-review-and-quality, spec-driven-development",
-  escalateSkills: "debugging-and-error-recovery",
+  // `qualityReviews` fans out into one turn per entry (`qualityLenses`, in
+  // `./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",
 }
+
+/** Environment settings. */
+export const envDefaults: Readonly<Record<string, string>> = {
+  testCommand: "npm test",
+  plannerModel: "smart",
+  coderModel: "base",
+}