@pmelab/gtd 15.9.0 → 16.0.0

package/src/workflows/text.fixture.ts

@@ -4,6 +4,7 @@ import {
   type FlowContext,
   type StepRequest,
 } from "../flows/index.js"
+import { skills as bundledSkills } from "./skills.js"
 import { defaults } from "./vars.js"
 
 export interface TextContext {
@@ -12,12 +13,46 @@ export interface TextContext {
   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 = {},
@@ -40,6 +75,7 @@ export const fixtureContext = (
   vars: { ...defaults, ...context.vars },
   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"])
   })
 })
 

package/src/workflows/text.ts

@@ -2,6 +2,7 @@ import {
   agent,
   codeThreads,
   head,
+  skillsFor,
   start,
   vars,
   type AgentOptions,
@@ -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.`
@@ -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

@@ -32,6 +32,7 @@ import * as t from "./text.js"
 
 export { threads, type ThreadInfo } from "../flows/index.js"
 export { defaults } 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

@@ -10,14 +10,12 @@ export const defaults: Readonly<Record<string, string>> = {
   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",
+  // The per-step skill lists formerly declared here as `*Skills` vars now
+  // live in `./skills.ts`, addressed per step by `.gtdrc` `skills:`.
+  // `qualityReviews` is the one exception: it fans out into one turn per
+  // entry (`qualityLenses`, in `./review.ts`) rather than naming one step's
+  // skill list, so it stays a var — 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",
 }