@pmelab/gtd 24.0.0 → 24.2.0

package/src/workflow/skills.test.ts

@@ -0,0 +1,109 @@
+import { Cause, Effect, Exit } from "effect"
+import { describe, expect, it } from "vitest"
+import { resolveScopeAccess, resolveScopeSkills } from "./skills.js"
+
+const FILE = "/repo/gtd.config.ts"
+
+const failure = async (skills: (vars: Record<string, string>) => unknown): Promise<string> => {
+  const exit = await Effect.runPromiseExit(
+    resolveScopeSkills({ skills: skills as never, configuredSkills: {}, skillsOrigin: FILE }, {}),
+  )
+  expect(Exit.isFailure(exit)).toBe(true)
+  return Exit.isFailure(exit) ? String(Cause.squash(exit.cause)) : ""
+}
+
+describe("resolveScopeSkills", () => {
+  it("wraps a throwing export with the config prefix and file", async () => {
+    const message = await failure(() => {
+      throw new Error("boom")
+    })
+    expect(message).toContain(`gtd config:\n  - ${FILE}: boom`)
+  })
+
+  it("rejects a non-object return", async () => {
+    expect(await failure(() => ["a"])).toContain(
+      `gtd config:\n  - ${FILE}: skills export must return an object of scope -> skill names`,
+    )
+  })
+
+  it("rejects a non-array value", async () => {
+    expect(await failure(() => ({ a: "x" }))).toContain(
+      `gtd config:\n  - ${FILE}: skills export: "a" must be an array of skill names`,
+    )
+  })
+
+  it("rejects a non-string entry", async () => {
+    expect(await failure(() => ({ a: ["x", 1] }))).toContain(
+      `gtd config:\n  - ${FILE}: skills export: "a" must be an array of skill names`,
+    )
+  })
+
+  it("reports an unknown config key at gtd.config.ts", async () => {
+    const exit = await Effect.runPromiseExit(
+      resolveScopeSkills(
+        { skills: () => ({ a: ["x"] }), configuredSkills: { nope: [] }, skillsOrigin: FILE },
+        {},
+      ),
+    )
+    expect(String(Exit.isFailure(exit) ? Cause.squash(exit.cause) : "")).toContain(
+      `${FILE}: config.skills.nope: "skills.nope" is not a scope that runs a turn — known scopes: a`,
+    )
+  })
+})
+
+describe("resolveScopeAccess", () => {
+  const run = (
+    def: {
+      access: (vars: Record<string, string>) => unknown
+      configuredAccess?: Record<string, object>
+    },
+    skills: Record<string, readonly string[]> = {},
+  ) =>
+    Effect.runPromiseExit(
+      resolveScopeAccess(
+        {
+          access: def.access as never,
+          configuredAccess: def.configuredAccess ?? {},
+          skillsOrigin: FILE,
+        },
+        skills,
+        {},
+      ),
+    )
+  const message = (exit: Awaited<ReturnType<typeof run>>): string =>
+    Exit.isFailure(exit) ? String(Cause.squash(exit.cause)) : ""
+
+  it("returns a well-shaped record", async () => {
+    const exit = await run({ access: () => ({ a: { write: ["x"] }, b: {} }) })
+    expect(Exit.isSuccess(exit) && exit.value).toEqual({ a: { write: ["x"] }, b: {} })
+  })
+
+  it("rejects a malformed export with the file", async () => {
+    expect(message(await run({ access: () => ["a"] }))).toContain(
+      `gtd config:\n  - ${FILE}: access export must return an object`,
+    )
+    expect(message(await run({ access: () => ({ a: { write: "x" } }) }))).toContain(
+      `${FILE}: access export: "a": access.write must be an array`,
+    )
+  })
+
+  it("knows the scopes of both the skills and access exports", async () => {
+    const exit = await run(
+      {
+        access: () => ({ fromAccess: {} }),
+        configuredAccess: { fromSkills: {}, fromAccess: {} },
+      },
+      { fromSkills: ["s"] },
+    )
+    expect(Exit.isSuccess(exit)).toBe(true)
+  })
+
+  it("reports an unknown key with the exact message and known scopes", async () => {
+    const text = message(
+      await run({ access: () => ({ b: {} }), configuredAccess: { nope: {} } }, { a: ["x"] }),
+    )
+    expect(text).toContain(
+      `${FILE}: config.access.nope: "access.nope" is not a scope that runs a turn — known scopes: a, b`,
+    )
+  })
+})

package/src/workflow/skills.ts

@@ -0,0 +1,90 @@
+import { Effect } from "effect"
+import { GtdError } from "../platform/index.js"
+import type { WorkflowDefinition } from "./Workflow.js"
+import { accessShapeFault } from "../replay/index.js"
+import type { ScopeAccess } from "../flows/index.js"
+import type { Diagnostic } from "./Diagnostic.js"
+import { failOnErrors } from "./load.js"
+
+const fail = (origin: string, message: string): GtdError =>
+  new GtdError(`gtd config:\n  - ${origin}: ${message}`)
+
+const checkShape = (value: unknown): Record<string, readonly string[]> => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("skills export must return an object of scope -> skill names")
+  }
+  for (const [scope, names] of Object.entries(value)) {
+    if (!Array.isArray(names) || names.some((n) => typeof n !== "string")) {
+      throw new Error(`skills export: "${scope}" must be an array of skill names`)
+    }
+  }
+  return value as Record<string, readonly string[]>
+}
+
+/** Every `config` key that names no known scope is a load error. */
+const checkKeys = (
+  configured: Readonly<Record<string, unknown>>,
+  origin: string,
+  known: readonly string[],
+  section: "skills" | "access",
+): Effect.Effect<void, GtdError> => {
+  const sorted = [...known].sort()
+  const diagnostics: Diagnostic[] = Object.keys(configured)
+    .filter((key) => !sorted.includes(key))
+    .sort()
+    .map((key) => ({
+      severity: "error" as const,
+      path: ["config", section, key],
+      message: `"${section}.${key}" is not a scope that runs a turn — known scopes: ${sorted.join(", ")}`,
+      origin,
+    }))
+  return failOnErrors(diagnostics)
+}
+
+/**
+ * Skill lists for the settings actually in use. `config.skills` keys are
+ * judged here, not at config load: only now are the pinned/entry vars known.
+ */
+export const resolveScopeSkills = (
+  def: Pick<WorkflowDefinition, "skills" | "configuredSkills" | "skillsOrigin">,
+  vars: Readonly<Record<string, string>>,
+): Effect.Effect<Record<string, readonly string[]>, GtdError> =>
+  Effect.gen(function* () {
+    const skills = yield* Effect.try({
+      try: () => checkShape(def.skills(vars)),
+      catch: (e) => fail(def.skillsOrigin, e instanceof Error ? e.message : String(e)),
+    })
+    const known = Object.keys(skills)
+    yield* checkKeys(def.configuredSkills, def.skillsOrigin, known, "skills")
+    return skills
+  })
+
+const checkAccessShape = (value: unknown): Record<string, ScopeAccess> => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("access export must return an object of scope -> { read?, write? }")
+  }
+  for (const [scope, access] of Object.entries(value)) {
+    const fault = accessShapeFault(access)
+    if (fault !== undefined) throw new Error(`access export: "${scope}": ${fault}`)
+  }
+  return value as Record<string, ScopeAccess>
+}
+
+/**
+ * Access for the settings actually in use. A `config.access` key may name
+ * any scope the workflow gives skills or access to.
+ */
+export const resolveScopeAccess = (
+  def: Pick<WorkflowDefinition, "access" | "configuredAccess" | "skillsOrigin">,
+  skills: Readonly<Record<string, readonly string[]>>,
+  vars: Readonly<Record<string, string>>,
+): Effect.Effect<Record<string, ScopeAccess>, GtdError> =>
+  Effect.gen(function* () {
+    const access = yield* Effect.try({
+      try: () => checkAccessShape(def.access(vars)),
+      catch: (e) => fail(def.skillsOrigin, e instanceof Error ? e.message : String(e)),
+    })
+    const known = [...new Set([...Object.keys(skills), ...Object.keys(access)])]
+    yield* checkKeys(def.configuredAccess, def.skillsOrigin, known, "access")
+    return access
+  })

package/src/workflow/vars.ts

@@ -0,0 +1,33 @@
+const PREFIX = "GTD_"
+
+/**
+ * One kind of setting, later wins: the workflow's own defaults, `--var`
+ * overrides (process settings only; environment settings pass `{}`), then
+ * `GTD_<NAME>` for any name an earlier layer declared (a shell variable never
+ * introduces a name).
+ */
+export const resolveVars = (
+  workflowVars: Readonly<Record<string, string>>,
+  entryVars: Readonly<Record<string, string>>,
+  env: Readonly<Record<string, string | undefined>>,
+): Record<string, string> => {
+  const merged = { ...workflowVars, ...entryVars }
+  for (const name of Object.keys(merged)) {
+    const value = env[PREFIX + name.toUpperCase()]
+    if (value !== undefined) merged[name] = value
+  }
+  return merged
+}
+
+/** The first process setting whose value spans lines — a `Gtd-Var:` trailer cannot carry it. */
+export const multilineSetting = (vars: Readonly<Record<string, string>>): string | undefined =>
+  Object.keys(vars)
+    .sort()
+    .find((name) => /[\r\n]/.test(vars[name]!))
+
+const SETTING_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+/** A name is written verbatim into a `Gtd-Var: <name>=<value>` trailer, so `=` or a newline would corrupt it. */
+export const isSettingName = (name: string): boolean => SETTING_NAME.test(name)
+
+export const SETTING_NAME_RULE = 'a setting name is a letter or "_", then letters, digits or "_"'

package/src/workflows/feature/feature.test.ts

@@ -1,38 +1,32 @@
-import { afterEach, describe, expect, it } from "vitest"
-import { installContext, type StepRequest } from "../../flows/index.js"
-import { fixtureContext } from "../shared/text.fixture.js"
-import { ordinaryStart } from "./feature.js"
-
-afterEach(() => installContext(undefined))
-
-const FILES: Readonly<Record<string, string>> = {
-  ".gtd/REVIEW.md": "# Review: abc1234\n",
-  ".gtd/REVIEW.orig.md": "# Review: abc1234\n",
-}
+import { describe, expect, it } from "vitest"
+import { testRepo } from "../../testkit/index.js"
+import { CONFIG_SCAFFOLD } from "../../install/index.js"
+import { reviewDoc } from "../shared/config.fixture.js"
 
 describe("an ordinary feature start", () => {
+  it("unwinds a captured TODO, checks the baseline and starts design from it", async () => {
+    const repo = testRepo({ workflow: CONFIG_SCAFFOLD, env: { GTD_QUALITYREVIEWS: "" } })
+    repo.write("TODO.md", "# Add numbers\n\nadd(a, b) returns the sum.\n")
+    const rest = await repo.drive({ unwind: () => undefined, "start-gate.check": () => undefined })
+    expect(rest).toMatchObject({
+      state: "design.triage",
+      actor: "agent",
+      file: ".gtd/REQUIREMENTS.md",
+    })
+    expect(repo.subjects().slice(1)).toEqual([
+      "gtd(human): idle → unwind",
+      "gtd(check): unwind → start-gate.check",
+      "gtd(check): start-gate.check → design.triage",
+    ])
+  })
+
   it("refuses a pending hand-off right after idle, before unwinding", async () => {
-    const steps: StepRequest[] = []
-    installContext(
-      fixtureContext(
-        {},
-        {
-          step: (request: StepRequest) => {
-            steps.push(request)
-            return Promise.resolve()
-          },
-          refuse: (message: string): never => {
-            throw new Error(message)
-          },
-          pushScope: () => undefined,
-          popScope: () => undefined,
-          read: (path) => FILES[path],
-          head: () => "c1",
-          start: () => "c0",
-        },
-      ),
-    )
-    await expect(ordinaryStart()).rejects.toThrow(".gtd/REVIEW.orig.md is a pending hand-off")
-    expect(steps.map((s) => ("name" in s ? s.name : s.kind))).toEqual(["idle"])
+    const repo = testRepo({
+      workflow: CONFIG_SCAFFOLD,
+      files: { ".gtd/REVIEW.md": reviewDoc("note"), ".gtd/REVIEW.orig.md": reviewDoc("orig") },
+    })
+    repo.write("TODO.md", "# Add numbers\n")
+    await expect(repo.land()).rejects.toThrow(".gtd/REVIEW.orig.md is a pending hand-off")
+    expect(repo.subjects()).toEqual(["chore: initial commit"])
   })
 })

package/src/workflows/feature/index.ts

@@ -0,0 +1,10 @@
+import { feature } from "./feature.js"
+
+export * from "./steps.js"
+export * from "./planning.js"
+export * from "./packages.js"
+export { buildTail, type ReviewOutcome } from "./review.js"
+export * from "./feature.js"
+export * from "../shared/reserved.js"
+
+export default feature

package/src/workflows/fix/fix.feature

@@ -0,0 +1,80 @@
+Feature: fix fixes the notes review hands it
+
+  `review` and `fix` meet only in `.gtd/REVIEW.md`: a review the human leaves
+  a note in ends with the reviewer's copy kept beside it, and `gtd door fix`
+  picks both up.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_QUALITYREVIEWS" set to ""
+    And a file "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      """
+    And the working tree is committed as "feat: add calculator"
+
+  Scenario: a note left in review is fixed, and both review files are removed
+    Given step "review-gate.check" changes nothing
+    And step "build.health.check" changes nothing
+    And step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## calc
+
+      - [ ] ./src/calc.ts#1-1
+        new add function
+      """
+    When gtd opens door "review" with "HEAD~1"
+    And the process is driven
+    Then the process rests at "build.review.await-review"
+
+    Given a file ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## calc
+
+      - [ ] ./src/calc.ts#1-1
+        new add function — rename it to sum
+      """
+    And step "build.review.handing-off" runs its script
+    When gtd lands
+    And the process is driven
+    Then the process rests at "idle"
+    And ".gtd/REVIEW.orig.md" contains "new add function"
+
+    Given step "notes.fixing" writes "src/calc.ts" with:
+      """
+      export const sum = (a: number, b: number) => a + b
+      """
+    And step "notes.closing" runs its script
+    When gtd opens door "fix"
+    Then the resting step's content contains "rename it to sum"
+    # The fix goes to its own review, which the same scripted reviewer writes
+    # afresh — the handed-off review itself is gone, as the reviewer's copy shows.
+    When the process is driven
+    Then the process rests at "build.review.await-review"
+    And the commit subjects end with:
+      """
+      gtd(human): notes.fixing
+      gtd(agent): notes.fixing → notes.closing
+      gtd(check): notes.closing → build.health.check
+      gtd(check): build.health.check → build.review.reviewing
+      gtd(agent): build.review.reviewing → build.review.await-review
+      """
+    And ".gtd/REVIEW.orig.md" does not exist
+    And ".gtd/REVIEW.md" contains "new add function"
+    And "src/calc.ts" contains "sum"
+
+  Scenario: a reviewer's copy with no review is refused
+    Given a file ".gtd/REVIEW.orig.md" with:
+      """
+      # Review: abc1234
+      """
+    And the working tree is committed as "chore: stray copy"
+    Then opening door "fix" is refused with "has no .gtd/REVIEW.md"

package/src/workflows/fix/fix.test.ts

@@ -1,94 +1,74 @@
-import { afterEach, describe, expect, it } from "vitest"
-import { installContext, type StepRequest } from "../../flows/index.js"
-import { fixtureContext } from "../shared/text.fixture.js"
-import { fixFlow } from "./fix.js"
-
-afterEach(() => installContext(undefined))
+import { describe, expect, it } from "vitest"
+import { runsItsScript, testRepo } from "../../testkit/index.js"
+import { CONFIG_SCAFFOLD } from "../../install/index.js"
+import { reviewDoc } from "../shared/config.fixture.js"
 
 const REVIEW = ".gtd/REVIEW.md"
 const ORIG = ".gtd/REVIEW.orig.md"
+const CALC = "export const add = (a: number, b: number) => a + b\n"
 
-const reviewDoc = (...notes: string[]): string =>
-  [
-    "# Review: abc1234",
-    "",
-    "<!-- base: 0000000 -->",
-    "",
-    "## calc",
-    ...notes.flatMap((note, i) => [`- [ ] ./src/calc.ts#${i + 1}`, note]),
-    "",
-  ].join("\n")
-
-class Stop extends Error {}
-
-/** Run `fix` over `files` until its third step; returns the steps it asked for. */
-const drive = async (files: Readonly<Record<string, string>>): Promise<StepRequest[]> => {
-  const steps: StepRequest[] = []
-  installContext(
-    fixtureContext(
-      {},
-      {
-        step: (request: StepRequest) => {
-          steps.push(request)
-          if (steps.length >= 3) throw new Stop()
-          return Promise.resolve()
-        },
-        refuse: (message: string): never => {
-          throw new Error(message)
-        },
-        pushScope: () => undefined,
-        popScope: () => undefined,
-        // Closing removes both review files, as the real tree would show.
-        read: (path) =>
-          steps.some((s) => "name" in s && s.name === "closing") ? undefined : files[path],
-        head: () => "c1",
-        start: () => "c0",
+describe("the fix workflow", () => {
+  it("with no handed-off review, repairs a red baseline and hands it to review", async () => {
+    const repo = testRepo({ workflow: CONFIG_SCAFFOLD, env: { GTD_QUALITYREVIEWS: "" } })
+    await repo.start("fix")
+    const rest = await repo.drive({
+      "fix-precheck": (_, r) => r.write(".gtd/FEEDBACK.md", "1 test failing\n"),
+      "build.fix": (beat, r) => {
+        expect(beat.content).toContain(".gtd/FEEDBACK.md")
+        r.remove(".gtd/FEEDBACK.md")
+        r.write("src/repair.ts", "export const repaired = true\n")
       },
-    ),
-  )
-  await fixFlow().catch((e: unknown) => {
-    if (!(e instanceof Stop)) throw e
+      "build.health.check": () => undefined,
+    })
+    expect(rest).toMatchObject({ state: "build.review.reviewing", actor: "agent" })
+    expect(repo.subjects().slice(1)).toEqual([
+      "gtd(human): fix-precheck",
+      "gtd(check): fix-precheck → build.fix",
+      "gtd(agent): build.fix → build.health.check",
+      "gtd(check): build.health.check → build.review.reviewing",
+    ])
   })
-  return steps
-}
 
-describe("the fix workflow", () => {
-  it("with no handed-off review, repairs a red baseline from fix-precheck", async () => {
-    const [first] = await drive({})
-    expect(first).toMatchObject({ kind: "run", name: "fix-precheck" })
+  it("with a green baseline, has nothing to fix", async () => {
+    const repo = testRepo({ workflow: CONFIG_SCAFFOLD, env: { GTD_QUALITYREVIEWS: "" } })
+    await repo.start("fix")
+    const rest = await repo.drive({ "fix-precheck": () => undefined })
+    expect(rest.state).toBe("idle")
+    expect(repo.subjects().at(-1)).toBe("gtd(check): fix-precheck → idle")
   })
 
-  it("fixes a handed-off review's notes and risks in one turn, then removes both review files", async () => {
-    const steps = await drive({
-      [REVIEW]: reviewDoc("add — rename it to sum", "Risk: drops the carry"),
-      [ORIG]: reviewDoc("add", "Risk: drops the carry"),
+  it("fixes a handed-off review's notes and risks in one turn, removes both review files, then checks health", async () => {
+    const repo = testRepo({
+      workflow: CONFIG_SCAFFOLD,
+      env: { GTD_QUALITYREVIEWS: "" },
+      files: {
+        "src/calc.ts": CALC,
+        [REVIEW]: reviewDoc("add — rename it to sum", "Risk: drops the carry"),
+        [ORIG]: reviewDoc("add", "Risk: drops the carry"),
+      },
     })
-    const [fixing, closing] = steps
-    if (fixing?.kind !== "agent" || closing?.kind !== "run") throw new Error("unexpected steps")
-    expect(fixing.name).toBe("fixing")
-    expect(fixing.prompt).toContain("rename it to sum")
-    expect(fixing.prompt).toContain("Risk: drops the carry")
-    expect(closing.name).toBe("closing")
-    expect(closing.body).toContain(REVIEW)
-    expect(closing.body).toContain(ORIG)
-  })
-
-  it("after the notes, checks health before the suite is trusted", async () => {
-    const steps = await drive({ [REVIEW]: reviewDoc("add"), [ORIG]: reviewDoc("add") })
-    expect(steps.map((s) => [s.kind, "name" in s ? s.name : undefined])).toEqual([
-      ["agent", "fixing"],
-      ["run", "closing"],
-      ["run", "health.check"],
+    await repo.door("fix")
+    const rest = await repo.drive({
+      "notes.fixing": (beat, r) => {
+        expect(beat.content).toContain("rename it to sum")
+        expect(beat.content).toContain("Risk: drops the carry")
+        r.write("src/calc.ts", CALC.replace("add", "sum"))
+      },
+      "notes.closing": runsItsScript,
+    })
+    expect(rest.state).toBe("build.health.check")
+    expect(repo.subjects().slice(1)).toEqual([
+      "gtd(human): notes.fixing",
+      "gtd(agent): notes.fixing → notes.closing",
+      "gtd(check): notes.closing → build.health.check",
     ])
-  })
-
-  it("refuses a reviewer's copy left with no review", async () => {
-    await expect(drive({ [ORIG]: reviewDoc("add") })).rejects.toThrow(/has no \.gtd\/REVIEW\.md/)
+    expect(repo.read("src/calc.ts")).toContain("sum")
+    expect(repo.read(REVIEW)).toBeUndefined()
+    expect(repo.read(ORIG)).toBeUndefined()
   })
 
   it("refuses a review with no reviewer's copy, so no note is deleted unread", async () => {
-    await expect(drive({ [REVIEW]: reviewDoc("Risk: drops the carry") })).rejects.toThrow(
-      /not handed off/,
-    )
+    const repo = testRepo({ workflow: CONFIG_SCAFFOLD, files: { [REVIEW]: reviewDoc("add") } })
+    await expect(repo.door("fix")).rejects.toThrow(/not handed off/)
   })
 })

package/src/workflows/fix/index.ts

@@ -0,0 +1,6 @@
+import { fix } from "./fix.js"
+
+export { fix, fixFlow, fixReviewNotes } from "./fix.js"
+export * from "../shared/reserved.js"
+
+export default fix

package/src/workflows/index.ts

@@ -1,15 +1,11 @@
 // The `@pmelab/gtd/workflows` entry, built on its own: core never imports it,
 // a repository's `gtd.config.ts` does.
-import type { Doors, Summary } from "../flows/index.js"
+import type { Doors } from "../flows/index.js"
 import { feature } from "./feature/feature.js"
-import * as t from "./shared/text.js"
-import { ARCHITECTURE, REQUIREMENTS, REVIEW } from "./shared/steps.js"
 
 export { threads, type ThreadInfo } from "../flows/index.js"
-export { defaults, envDefaults } from "./shared/vars.js"
+export * from "./shared/reserved.js"
 export { ShippedOptions } from "./shared/options.js"
-export { skills } from "./shared/skills.js"
-export { access } from "./shared/access.js"
 export { agentWithSkills } from "./shared/text.js"
 export * from "./shared/steps.js"
 export * from "./shared/health.js"
@@ -35,10 +31,6 @@ export { fix, fixFlow, fixReviewNotes } from "./fix/fix.js"
 
 export default feature
 
-export const summary: Summary = t.summaryPrompt
-
-export const steering = { [REQUIREMENTS]: "qa", [ARCHITECTURE]: "qa", [REVIEW]: "review" }
-
 /**
  * @deprecated Empty: each shipped workflow builds its own doors, so a config
  * gets `fix` and `review [base]` by exporting `fix` and `review`.

package/src/workflows/review/index.ts

@@ -0,0 +1,6 @@
+import { review } from "./review.js"
+
+export { review, reviewFlow } from "./review.js"
+export * from "../shared/reserved.js"
+
+export default review