@pmelab/gtd 37.0.0 → 38.0.0

package/src/workflows/feature/slicing.ts

@@ -0,0 +1,105 @@
+import { read, refuse, scope, vars } from "../../flows/index.js"
+import { HEADING, ITEM, markFenced } from "../shared/fences.js"
+import { planner, REQUIREMENTS, SLICES } from "../shared/steps.js"
+import * as t from "../shared/text.js"
+import { defaults } from "../shared/vars.js"
+import { criterionIds, type CriteriaSlice } from "./criteria.js"
+
+/** One slice of the change: the criterion IDs it builds, in the order `.gtd/SLICES.md` lists them. */
+export interface Slice {
+  readonly title: string
+  readonly ids: readonly string[]
+}
+
+const ID = /^(AC-\d+)(?![\w-])/
+
+/** The `sliceMaxCriteria` setting. Anything but a positive integer fails rather than guess a cap. */
+export const sliceCap = (): number => {
+  const value = vars.sliceMaxCriteria ?? defaults.sliceMaxCriteria!
+  if (!/^[1-9]\d*$/.test(value))
+    refuse(`gtd: sliceMaxCriteria must be a positive integer, got ${JSON.stringify(value)}`)
+  return Number(value)
+}
+
+/** Each `## ` heading of `text` with the list items under it; an item not led by an ID keeps an empty one. */
+export const slicesOf = (text: string): readonly Slice[] => {
+  const slices: { title: string; ids: string[] }[] = []
+  // Only items right under a `##` heading: another heading ends the slice.
+  let open = false
+  for (const { line, fenced } of markFenced(text)) {
+    if (fenced) continue
+    const heading = HEADING.exec(line)
+    if (heading !== null) {
+      open = heading[1] === "##"
+      if (open) slices.push({ title: heading[2]!, ids: [] })
+      continue
+    }
+    const item = ITEM.exec(line)
+    if (item !== null && open) slices.at(-1)!.ids.push(ID.exec(item[1]!)?.[1] ?? "")
+  }
+  return slices
+}
+
+const twice = (list: readonly string[]): string[] => [
+  ...new Set(list.filter((id, i) => list.indexOf(id) !== i)),
+]
+
+/** Why `slices` fail to put each of `ids` in exactly one slice of at most `cap`, or `undefined`. */
+const sliceFault = (
+  slices: readonly Slice[],
+  ids: readonly string[],
+  cap: number,
+): string | undefined => {
+  const listed = slices.flatMap((s) => s.ids)
+  if (slices.length === 0) return `no "## " slice`
+  const empty = slices.filter((s) => s.ids.length === 0).map((s) => s.title)
+  if (empty.length > 0) return `a slice with no criterion: ${empty.join(", ")}`
+  if (listed.includes("")) return "a list item not led by a criterion ID"
+  const over = slices.filter((s) => s.ids.length > cap).map((s) => s.title)
+  if (over.length > 0) return `more than ${cap} criteria in: ${over.join(", ")}`
+  const repeated = twice(listed)
+  if (repeated.length > 0) return `an ID in more than one slice: ${repeated.join(", ")}`
+  const unknown = listed.filter((id) => !ids.includes(id))
+  if (unknown.length > 0) return `an ID ${REQUIREMENTS} does not list: ${unknown.join(", ")}`
+  const missing = ids.filter((id) => !listed.includes(id))
+  if (missing.length > 0) return `no slice for: ${missing.join(", ")}`
+  return undefined
+}
+
+/** Refuse a turn whose `.gtd/SLICES.md` does not put each of `ids` in exactly one slice of at most `cap`. */
+export const requireSlices = (ids: readonly string[], cap: number): readonly Slice[] => {
+  const slices = slicesOf(read(SLICES) ?? "")
+  const why = sliceFault(slices, ids, cap)
+  if (why !== undefined)
+    refuse(
+      `gtd land: slices: ${SLICES} has ${why} — list each slice as a "## <title>" heading over "- AC-<n>" items, every criterion of ${REQUIREMENTS} in exactly one slice, at most ${cap} per slice`,
+    )
+  return slices
+}
+
+/**
+ * The slices to build, in order. Criteria within `sliceMaxCriteria` are one
+ * slice and no turn; above it `design.slicing` groups them.
+ */
+export const slicing = async (): Promise<readonly Slice[]> => {
+  const all = criterionIds(read(REQUIREMENTS) ?? "")
+  const cap = sliceCap()
+  if (all.length <= cap) return [{ title: "", ids: all }]
+  return scope("design", async () => {
+    await t.agentWithSkills("slicing", t.slicingPrompt(cap), {
+      label: "Slicing the change",
+      file: SLICES,
+      model: planner(),
+      system: t.designSystem(),
+    })
+    return requireSlices(all, cap)
+  })
+}
+
+/** Slice `i`'s criteria; `undefined` when `slices` is the one slice of an unsliced change. */
+export const sliceCriteria = (slices: readonly Slice[], i: number): CriteriaSlice | undefined =>
+  slices.length === 1
+    ? undefined
+    : i < slices.length - 1
+      ? { only: slices[i]!.ids }
+      : { except: slices.slice(0, -1).flatMap((s) => s.ids) }

package/src/workflows/index.ts

@@ -25,6 +25,7 @@ export * from "./feature/criteria.js"
 export * from "./feature/planning.js"
 export * from "./feature/refactor.js"
 export * from "./feature/seam.js"
+export * from "./feature/slicing.js"
 export {
   buildTail,
   type BuildTailOptions,

package/src/workflows/shared/fences.ts

@@ -17,3 +17,8 @@ export const markFenced = (text: string): readonly { line: string; fenced: boole
     return { line, fenced }
   })
 }
+
+/** A markdown heading: its `#` run, then its text. */
+export const HEADING = /^ {0,3}(#{1,6})\s+(.*?)\s*#*\s*$/
+/** A list item, its checkbox dropped: its text. */
+export const ITEM = /^ ?(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s+)?(.*)$/

package/src/workflows/shared/options.ts

@@ -21,6 +21,7 @@ export const ShippedOptions = Schema.Struct({
   reviewSeverityMinP: setting,
   refactorFlagPattern: setting,
   seamAllow: setting,
+  sliceMaxCriteria: setting,
   qualityReviews: setting,
   refactorQualityReviews: setting,
   testCommand: setting,

package/src/workflows/shared/steps.ts

@@ -14,6 +14,7 @@ export const REVIEW = ".gtd/REVIEW.md"
 export const REFACTOR = ".gtd/REFACTOR.md"
 export const REFACTOR_NOTE = ".gtd/REFACTOR-NOTE.md"
 export const QUALITY = ".gtd/QUALITY.md"
+export const SLICES = ".gtd/SLICES.md"
 
 export const planner = (): string => env.plannerModel ?? ""
 export const coder = (): string => env.coderModel ?? ""

package/src/workflows/shared/text.ts

@@ -290,6 +290,30 @@ printf '%s\\n' ${lines.map(quote).join(" ")} > ${quote(".gtd/REQUIREMENTS.md")}
 `
 }
 
+export const slicingPrompt = (cap: number): string =>
+  `${stateFileRules}
+- Read \`.gtd/REQUIREMENTS.md\`: its \`## Acceptance Criteria\` are settled
+  and more than ${cap}, too many to build in one slice
+- Group them into slices in \`.gtd/SLICES.md\`, one \`## <title>\` heading per
+  slice over a \`- AC-<n>\` list item per criterion it builds. Put criteria of
+  the same flow or subsystem together; every criterion in exactly one slice,
+  at most ${cap} per slice
+- Keep it coarse: as few slices as the cap allows, never one per criterion
+- Order the slices so each builds on the ones before: they run in that order,
+  each from where the previous one landed
+- Change nothing but \`.gtd/SLICES.md\` — leave the criteria as they are
+- Leave everything uncommitted and finish your turn — do not commit
+`
+
+/** The line telling a slice's turn which criteria are its own; empty for a single slice. */
+const sliceLine = (ids: readonly string[] | undefined): string =>
+  ids === undefined
+    ? ""
+    : `- This slice builds ${ids.join(", ")} only: every rule here about the criteria
+  means these. The others are for other slices, before or after it — leave
+  them unbuilt and untested
+`
+
 export const designSystem = (): string =>
   `${designPersona}
 
@@ -1203,10 +1227,10 @@ ${listed(retry.strays)}
 Start over and choose a different approach; do not rebuild the same diff.
 `
 
-export const naivePassPrompt = (retry?: NaiveRetry): string =>
+export const naivePassPrompt = (retry?: NaiveRetry, slice?: readonly string[]): string =>
   `${stateFileRules}
 - Read \`.gtd/REQUIREMENTS.md\`: the settled requirements for this change
-${criteriaBinding(false)}
+${sliceLine(slice)}${criteriaBinding(false)}
 - Implement them the quickest way that works — the naive version. Do not
   restructure, abstract or refactor around the change; it may land exactly as
   you leave it, and a reviewer makes it fit
@@ -1289,6 +1313,25 @@ const afterRefactorLine = (rebuild: Rebuild): string =>
   rule below; if nothing is, ${carries(rebuild) ? "carry over the acceptance tests below and change nothing else" : "change nothing and finish your turn"}
 `
 
+const flagLine = (
+  flagMode: boolean,
+  tier: "low" | "high" | undefined,
+  amend: boolean | undefined,
+  sliced: boolean,
+): string =>
+  !flagMode
+    ? "- Add no release flag — this project ships without release flags"
+    : tier === "low"
+      ? "- Add no release flag — this change is low risk tier"
+      : amend === true
+        ? "- Keep the release flag the earlier lap added, if it added one; otherwise put\n  the behaviour behind a new release flag"
+        : sliced
+          ? `- Put the new behaviour behind the release flag an earlier slice of this
+  change added; only when none did, behind a new one, following the
+  repository's flag conventions`
+          : `- Put the new behaviour behind a new release flag, following the
+  repository's flag conventions`
+
 export const implementBuildingPrompt = (
   reference: string | undefined,
   tier?: "low" | "high",
@@ -1296,10 +1339,11 @@ export const implementBuildingPrompt = (
   afterRefactor?: boolean,
   flagMode = true,
   rebuild: Rebuild = {},
+  slice?: readonly string[],
 ): string =>
   `${stateFileRules}
 - Read \`.gtd/REQUIREMENTS.md\`: the settled requirements for this change
-${criteriaBinding(true)}
+${sliceLine(slice)}${criteriaBinding(true)}
 ${afterRefactor === true ? afterRefactorLine(rebuild) : ""}${
     amend === true
       ? `- The change already exists in the tree from an earlier lap; amend it to meet
@@ -1318,16 +1362,7 @@ ${afterRefactor === true ? afterRefactorLine(rebuild) : ""}${
   Read it for ideas; never apply, cherry-pick or check it out — write
   the change fresh${carries(rebuild) ? ", its acceptance tests excepted (below)" : ""}
 `
-  }${rebuildLines(rebuild)}${
-    !flagMode
-      ? "- Add no release flag — this project ships without release flags"
-      : tier === "low"
-        ? "- Add no release flag — this change is low risk tier"
-        : amend === true
-          ? "- Keep the release flag the earlier lap added, if it added one; otherwise put\n  the behaviour behind a new release flag"
-          : `- Put the new behaviour behind a new release flag, following the
-  repository's flag conventions`
-  }
+  }${rebuildLines(rebuild)}${flagLine(flagMode, tier, amend, slice !== undefined)}
 - Write the tests first, then the code that makes them pass. Name each
   criterion's ID in the test that covers it (\`[AC-3] …\`): once the suite is
   green a judge checks every ID has a passing test, and sends uncovered ones back
@@ -1437,10 +1472,10 @@ export const coverageMessage = (): string =>
 counts every criterion as uncovered.
 `
 
-export const coveringPrompt = (uncovered: readonly string[]): string =>
+export const coveringPrompt = (uncovered: readonly string[], slice?: readonly string[]): string =>
   `${stateFileRules}
 - Read \`.gtd/REQUIREMENTS.md\`: the settled requirements for this change
-${criteriaBinding(true)}
+${sliceLine(slice)}${criteriaBinding(true)}
 - A judge found no passing test in this change that covers ${uncovered.join(", ")}.
   Write a behaviour-level test for each, naming its ID in the test or scenario
   name (\`[${uncovered[0]}] …\`), and fix the code if the test shows it falls short

package/src/workflows/shared/vars.ts

@@ -26,6 +26,7 @@ export const defaults: Readonly<Record<string, string>> = {
   refactorFlagPattern: "\\bGTD_FLAG_\\w+",
   seamAllow: [...testFileGlobs, ".gtd/**"].join(", "),
   flagMode: "true",
+  sliceMaxCriteria: "8",
   // GTD_FLAG_RISK_TIER, recorded at process start; only "1" is on.
   flag_risk_tier: "0",
   // Decides the turn count: one `build.quality.<lens>` scope per entry, each

package/src/workflows/shared/workflows.steps.ts

@@ -52,3 +52,16 @@ Then("no commit body contains {string}", (world: TestkitWorld, text: string) =>
     .find((m) => m.includes(text))
   assert.ok(hit === undefined, `a commit body contains "${text}":\n${hit}`)
 })
+
+Then(
+  "slice {string} begins where slice {string} ends",
+  async (world: TestkitWorld, later: string, earlier: string) => {
+    const { stdout } = await world.repo().gtd("slices")
+    const range = (name: string): string[] => {
+      const line = stdout.split("\n").find((l) => l.startsWith(`${name} `))
+      assert.ok(line !== undefined, stdout)
+      return line.slice(name.length + 1).split("..")
+    }
+    assert.strictEqual(range(later)[0], range(earlier)[1], stdout)
+  },
+)