@pmelab/gtd 37.0.0 → 38.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "37.0.0",
+  "version": "38.1.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/src/testkit/steps.ts

@@ -26,6 +26,8 @@ export class TestkitWorld extends QuickPickleWorld {
   /** Per step, what its scripted actor does, in the order the scenario declared it. */
   actions = new Map<string, Actor[]>()
   verdicts = new Map<string, string>()
+  /** Per judge step, a verdict for each text its questions may contain; the first match answers. */
+  conditionalVerdicts = new Map<string, [text: string, verdict: string][]>()
   private created: TestRepo | undefined = undefined
 
   // The repository is created on first use and keeps the config and
@@ -79,6 +81,19 @@ export class TestkitWorld extends QuickPickleWorld {
       }
       actors[step] = () => verdict
     }
+    for (const [step, choices] of this.conditionalVerdicts) {
+      if (this.actions.has(step) || this.verdicts.has(step)) {
+        throw new Error(`step "${step}" has a conditional verdict and another script`)
+      }
+      // Matched against the pending questions, which `gtd judge` prints and the beat does not.
+      actors[step] = async (_, repo) => {
+        const { stdout } = await repo.gtd("judge")
+        const hit = choices.find(([text]) => stdout.includes(text))
+        if (hit === undefined)
+          throw new Error(`judge step "${step}" matched no verdict:\n${stdout}`)
+        return hit[1]
+      }
+    }
     await this.repo().drive(actors)
   }
 }
@@ -137,6 +152,20 @@ Given(
   },
 )
 
+// Lets one step write differently per visit, told apart by what it is prompted with.
+Given(
+  "step {string}, when prompted with {string}, writes {string} with:",
+  (world: TestkitWorld, step: string, text: string, path: string, content: string) => {
+    world.act(step, (beat, repo) => {
+      if (beat.content.includes(text)) repo.write(path, withNewline(content))
+    })
+  },
+)
+
+Given("step {string} deletes {string}", (world: TestkitWorld, step: string, path: string) => {
+  world.act(step, (_, repo) => repo.remove(path))
+})
+
 // A standing assertion like any queued action: it applies on every later visit
 // to the step until `from now on` clears the list.
 Given(
@@ -169,6 +198,16 @@ Given("judge step {string} answers:", (world: TestkitWorld, step: string, verdic
   world.verdicts.set(step, String(verdict))
 })
 
+Given(
+  "judge step {string}, when its questions contain {string}, answers:",
+  (world: TestkitWorld, step: string, text: string, verdict: string) => {
+    world.conditionalVerdicts.set(step, [
+      ...(world.conditionalVerdicts.get(step) ?? []),
+      [text, String(verdict)],
+    ])
+  },
+)
+
 When("gtd starts workflow {string}", async (world: TestkitWorld, workflow: string) => {
   await world.repo().start(workflow)
 })

package/src/wire/ContextLimit.ts

@@ -156,7 +156,7 @@ export const contextHook = (input: {
   if (tokens >= limit.soft * window) {
     return {
       kind: "soft",
-      reason: `Context limit: ${used} used, past the ${percent(limit.soft)} soft limit. Stop working now. Do not start anything new; end your turn with a short handoff note as your answer: what you touched, and what was next.`,
+      reason: `Context limit: ${used} used, past the ${percent(limit.soft)} soft limit. Stop working now. Do not start anything new; end your turn with a short handoff note as your answer: what you touched, and what was next. Where your instructions name a file for that note, write it there too.`,
     }
   }
   return undefined

package/src/workflows/feature/continuation-cap.feature

@@ -0,0 +1,65 @@
+@inmem
+Feature: past its continuation cap a phase rests for a person
+
+  With `continuations` at 1, a naive pass stopped at its context limit gets
+  one continuation; when that one stops too, `seam.oversized` asks a person,
+  and landing there grants a fresh round.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_CONTINUATIONS" set to "1"
+    And an environment variable "GTD_QUALITYREVIEWS" set to ""
+    And an environment variable "GTD_REFACTORQUALITYREVIEWS" set to ""
+    And an environment variable "GTD_FLAG_RISK_TIER" set to "0"
+    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"
+    And a file "TODO.md" with:
+      """
+      # Add subtract and multiply
+      """
+    And step "unwind" changes nothing
+    And step "start-gate.check" changes nothing
+    And step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+      """
+      # Requirements
+
+      ## Acceptance Criteria
+
+      - AC-1: `subtract(5, 3)` returns 2.
+      - AC-2: `multiply(2, 3)` returns 6.
+      """
+    And step "design.gate.answer" changes nothing
+    And step "seam.check" changes nothing
+
+  Scenario: past the continuation cap the naive pass rests for a person, and landing there grants a new round
+    Given step "seam.naive" writes ".gtd/HANDOFF.md" with:
+      """
+      Roughed out subtract.
+      """
+    And step "seam.continue.naive" writes "tests/calc.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      """
+    And step "seam.continue.naive" writes ".gtd/HANDOFF.md" with:
+      """
+      Subtract is tested; multiply was next.
+      """
+    When the process is driven
+    Then the process rests at "seam.oversized"
+    And the resting step's content contains "1 continuation ran and the last still stopped at its context limit"
+    And the resting step's content contains "still open: AC-2"
+
+    When gtd lands
+    Then the process rests at "seam.continue.naive"
+    And the resting step's content contains "Still open: AC-2."
+    And the commit subjects end with:
+      """
+      gtd(human): design.gate.answer → seam.naive
+      gtd(agent): seam.naive → seam.continue.naive
+      gtd(agent): seam.continue.naive → seam.oversized
+      gtd(human): seam.oversized → seam.continue.naive
+      """
+

package/src/workflows/feature/continuation-rebuild.feature

@@ -0,0 +1,88 @@
+@inmem
+Feature: a rebuild stopped at its context limit is continued on the branch
+
+  The rebuild's snapshot is its own commit: the continuation finds the work
+  in the tree, and the health loop greens the whole build afterwards.
+  `seamAllow` is empty here, so the naive pass's change to an existing test
+  file is the judge's only stray and refactor-first rebuilds with no refactor.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_SEAMALLOW" set to ""
+    And an environment variable "GTD_QUALITYREVIEWS" set to ""
+    And an environment variable "GTD_REFACTORQUALITYREVIEWS" set to ""
+    And an environment variable "GTD_FLAG_RISK_TIER" set to "0"
+    And a file "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      """
+    And a file "tests/calc.test.ts" with:
+      """
+      it("adds", () => {})
+      """
+    And the working tree is committed as "feat: add calculator"
+    And a file "TODO.md" with:
+      """
+      # Add subtract and multiply
+      """
+    And step "unwind" changes nothing
+    And step "start-gate.check" changes nothing
+    And step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+      """
+      # Requirements
+
+      ## Acceptance Criteria
+
+      - AC-1: `subtract(5, 3)` returns 2.
+      - AC-2: `multiply(2, 3)` returns 6.
+      """
+    And step "design.gate.answer" changes nothing
+    And step "seam.check" changes nothing
+
+  Scenario: a rebuild stopped at its context limit lands its snapshot and is continued on the branch
+    Given step "seam.naive" writes "src/ops.ts" with:
+      """
+      export const subtract = (a: number, b: number) => a - b
+      export const multiply = (a: number, b: number) => a * b
+      """
+    And step "seam.naive" writes "tests/calc.test.ts" with:
+      """
+      it("adds", () => {})
+      it("[AC-1] subtracts", () => {})
+      it("[AC-2] multiplies", () => {})
+      """
+    And judge step "seam.judge" answers:
+      """
+      [{"id":"shape","answer":"refactor-first","p":0.9}]
+      """
+    And step "implement.building" writes "tests/calc.test.ts" with:
+      """
+      it("adds", () => {})
+      it("[AC-1] subtracts", () => {})
+      """
+    And step "implement.building" writes ".gtd/HANDOFF.md" with:
+      """
+      Rebuilt subtract behind the flag; multiply was next.
+      """
+    When the process is driven
+    Then the process rests at "implement.continue.building"
+    And the resting step's content contains "Still open: AC-2."
+    And the resting step's content contains "Its work is already in the tree."
+    And the resting step's content contains "Delete `.gtd/HANDOFF.md` once you are done"
+    And "tests/calc.test.ts" contains "[AC-1] subtracts"
+
+    Given step "implement.continue.building" writes "tests/calc.test.ts" with:
+      """
+      it("adds", () => {})
+      it("[AC-1] subtracts", () => {})
+      it("[AC-2] multiplies", () => {})
+      """
+    And step "implement.continue.building" deletes ".gtd/HANDOFF.md"
+    When the process is driven
+    Then the process rests at "implement.health.check"
+    And the commit subjects end with:
+      """
+      gtd(agent): implement.building → implement.continue.building
+      gtd(agent): implement.continue.building → implement.health.check
+      """
+

package/src/workflows/feature/continuation-slices.feature

@@ -0,0 +1,64 @@
+@inmem
+Feature: a continuation stays inside its coarse slice
+
+  A naive pass of one coarse slice that stops at its context limit is
+  continued with that slice's criteria still open, never another slice's.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_QUALITYREVIEWS" set to ""
+    And an environment variable "GTD_FLAGMODE" set to "false"
+    And an environment variable "GTD_SLICEMAXCRITERIA" set to "2"
+    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"
+    And a file "TODO.md" with:
+      """
+      # More arithmetic
+
+      subtract, multiply and divide.
+      """
+    And step "unwind" changes nothing
+    And step "start-gate.check" changes nothing
+    And step "design.gate.answer" changes nothing
+    And step "seam.check" changes nothing
+
+  Scenario: the first slice's continuation is told only that slice's open criterion
+    Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+      """
+      # Requirements
+
+      ## Acceptance Criteria
+
+      - AC-1: subtract(a, b) returns a - b.
+      - AC-2: multiply(a, b) returns a * b.
+      - AC-3: divide(a, b) returns a / b.
+      """
+    And step "design.slicing" writes ".gtd/SLICES.md" with:
+      """
+      # Slices
+
+      ## Subtract and divide
+
+      - AC-1
+      - AC-3
+
+      ## Multiply
+
+      - AC-2
+      """
+    And step "seam.naive" writes "src/sub.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      """
+    And step "seam.naive" writes ".gtd/HANDOFF.md" with:
+      """
+      Subtract is tested; divide was next.
+      """
+    When the process is driven
+    Then the process rests at "seam.continue.naive"
+    And the resting step's content contains "This slice builds AC-1, AC-3 only"
+    And the resting step's content contains "Still open: AC-3."
+    And the resting step's content does not contain "AC-2"

package/src/workflows/feature/continuation.feature

@@ -0,0 +1,205 @@
+@inmem
+Feature: a turn stopped at its context limit is snapshotted and continued
+
+  A naive pass, refactor or build turn told to stop at its context limit
+  writes its handoff note to `.gtd/HANDOFF.md`. That turn is the snapshot —
+  the naive pass's kept tip, or the refactor's or build's own commit — and a
+  continuation in a fresh conversation (`<phase>.continue.<step>`) picks up
+  from it with the note and what is still open. After `continuations` (3) of
+  them, or `continuationStall` (2) in a row that close nothing still open, the
+  phase rests at `<phase>.oversized`.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_QUALITYREVIEWS" set to ""
+    And an environment variable "GTD_REFACTORQUALITYREVIEWS" set to ""
+    And an environment variable "GTD_FLAG_RISK_TIER" set to "0"
+    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"
+    And a file "TODO.md" with:
+      """
+      # Add subtract and multiply
+      """
+    And step "unwind" changes nothing
+    And step "start-gate.check" changes nothing
+    And step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+      """
+      # Requirements
+
+      ## Acceptance Criteria
+
+      - AC-1: `subtract(5, 3)` returns 2.
+      - AC-2: `multiply(2, 3)` returns 6.
+      """
+    And step "design.gate.answer" changes nothing
+    And step "seam.check" changes nothing
+
+  Scenario: a naive pass stopped at its context limit is continued from its kept tip with the open IDs
+    Given step "seam.naive" writes "tests/calc.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      """
+    And step "seam.naive" writes ".gtd/HANDOFF.md" with:
+      """
+      Wrote subtract and its test; multiply was next.
+      """
+    When the process is driven
+    Then the process rests at "seam.continue.naive"
+    And the resting step's content contains "Your previous turn stopped at its context limit"
+    And the resting step's content contains "Still open: AC-2."
+    And the resting step's content contains "Wrote subtract and its test; multiply was next."
+    And the resting step's content contains "':(top)' ':(top,exclude).gtd/HANDOFF.md' | git apply"
+    And ".gtd/HANDOFF.md" does not exist
+    And the output of gtd "next --json" contains "\"resume\":false"
+    And the output of gtd "next --json" contains "\"memory\":\"seam.continue#"
+
+    Given step "seam.continue.naive" writes "tests/calc.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      it("[AC-2] multiplies", () => {})
+      """
+    When the process is driven
+    Then the process rests at "implement.applying"
+    And the commit subjects end with:
+      """
+      gtd(human): design.gate.answer → seam.naive
+      gtd(agent): seam.naive → seam.continue.naive
+      gtd(agent): seam.continue.naive → seam.check
+      gtd(check): seam.check → implement.applying
+      """
+
+  Scenario: two continuations in a row that close nothing rest for a person
+    Given step "seam.naive" writes "tests/calc.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      """
+    And step "seam.naive" writes ".gtd/HANDOFF.md" with:
+      """
+      Subtract is tested; multiply was next.
+      """
+    And step "seam.continue.naive" writes ".gtd/HANDOFF.md" with:
+      """
+      Still on multiply.
+      """
+    When the process is driven
+    Then the process rests at "seam.oversized"
+    And the resting step's content contains "the last 2 continuations closed nothing still open"
+    And the commit subjects end with:
+      """
+      gtd(human): design.gate.answer → seam.naive
+      gtd(agent): seam.naive → seam.continue.naive
+      gtd(agent): seam.continue.naive
+      gtd(agent): seam.continue.naive → seam.oversized
+      """
+
+  Scenario: a refactor stopped at its context limit is run green before its continuation
+    Given step "seam.naive" writes "tests/calc.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      it("[AC-2] multiplies", () => {})
+      """
+    And step "seam.naive" writes "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      export const subtract = (a: number, b: number) => a - b
+      export const multiply = (a: number, b: number) => a * b
+      """
+    And judge step "seam.judge" answers:
+      """
+      [{"id":"shape","answer":"refactor-first","p":0.9}]
+      """
+    And step "seam.note" writes ".gtd/REFACTOR-NOTE.md" with:
+      """
+      Seam: a shared `op` in src/calc.ts.
+      """
+    And step "refactor.deriving" runs its script
+    And step "refactor.building" writes ".gtd/HANDOFF.md" with:
+      """
+      Started on op; nothing changed yet.
+      """
+    And step "refactor.health.check" changes nothing
+    When the process is driven
+    Then the process rests at "refactor.continue.building"
+    And the resting step's content contains "Still open: src/calc.ts."
+    And the resting step's content contains "Started on op; nothing changed yet."
+    And the commit subjects end with:
+      """
+      gtd(agent): refactor.building → refactor.health.check
+      gtd(check): refactor.health.check → refactor.continue.building
+      """
+
+  Scenario: a refactor continuation that leaves the note in place stopped again
+    Given step "seam.naive" writes "tests/calc.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      it("[AC-2] multiplies", () => {})
+      """
+    And step "seam.naive" writes "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      export const subtract = (a: number, b: number) => a - b
+      """
+    And judge step "seam.judge" answers:
+      """
+      [{"id":"shape","answer":"refactor-first","p":0.9}]
+      """
+    And step "seam.note" writes ".gtd/REFACTOR-NOTE.md" with:
+      """
+      Seam: a shared `op` in src/calc.ts.
+      """
+    And step "refactor.deriving" runs its script
+    And step "refactor.building" writes "src/calc.ts" with:
+      """
+      export const op = (a: number, b: number, sign: number) => a + sign * b
+      export const add = (a: number, b: number) => a + b
+      """
+    And step "refactor.building" writes ".gtd/HANDOFF.md" with:
+      """
+      op is in; routing add through it was next.
+      """
+    And step "refactor.health.check" changes nothing
+    And step "refactor.continue.building" writes "src/calc.ts" with:
+      """
+      export const op = (a: number, b: number, sign: number) => a + sign * b
+      export const add = (a: number, b: number) => op(a, b, 1)
+      """
+    When the process is driven
+    Then the process rests at "refactor.continue.building"
+    And the commit subjects end with:
+      """
+      gtd(agent): refactor.building → refactor.health.check
+      gtd(check): refactor.health.check → refactor.continue.building
+      gtd(agent): refactor.continue.building → refactor.health.check
+      gtd(check): refactor.health.check → refactor.continue.building
+      gtd(agent): refactor.continue.building
+      """
+
+  Scenario: once a naive pass has continued, its retry runs in a fresh conversation, not as a continuation
+    Given step "seam.naive" writes "tests/calc.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      """
+    And step "seam.naive" writes ".gtd/HANDOFF.md" with:
+      """
+      Multiply was next.
+      """
+    And step "seam.continue.naive" writes "tests/calc.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      it("[AC-2] multiplies", () => {})
+      """
+    And step "seam.continue.naive" writes "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a - b
+      """
+    And judge step "seam.judge" answers:
+      """
+      [{"id":"shape","answer":"reject","p":0.9}]
+      """
+    When the process is driven
+    Then the process rests at "seam.fresh.naive"
+    And the resting step's content contains "rejected"
+    And the output of gtd "next --json" contains "\"resume\":false"

package/src/workflows/feature/coverage.ts

@@ -11,7 +11,13 @@ import {
 import { healthy } from "../shared/health.js"
 import { coder, FEEDBACK, REQUIREMENTS } from "../shared/steps.js"
 import * as t from "../shared/text.js"
-import { criteriaOf, requireCriteriaFrozen } from "./criteria.js"
+import {
+  criteriaOf,
+  criterionIds,
+  requireCriteriaFrozen,
+  sliceIds,
+  type CriteriaSlice,
+} from "./criteria.js"
 import { isTestFile } from "./refactor.js"
 import { isCode } from "./review.js"
 
@@ -51,13 +57,15 @@ const testsSince = (base: string): string =>
 
 /**
  * The criterion IDs of `.gtd/REQUIREMENTS.md` — read afresh, never carried
- * over — no passing test since `base` covers, by the judge.
+ * over, only `slice`'s when given — no passing test since `base` covers, by the judge.
  */
 const uncoveredSince = async (
   base: string,
+  slice: CriteriaSlice | undefined,
 ): Promise<{ readonly covered: string[]; readonly uncovered: string[] }> => {
   const requirements = read(REQUIREMENTS) ?? ""
-  const criteria = (criteriaOf(requirements) ?? []).filter((c) => c.id !== "")
+  const own = criterionIds(requirements, slice)
+  const criteria = (criteriaOf(requirements) ?? []).filter((c) => own.includes(c.id))
   if (criteria.length === 0) return { covered: [], uncovered: [] }
   const { answers } = await judge("coverage", {
     questions: criteria.map(t.coverageQuestion),
@@ -81,14 +89,14 @@ const record = (covered: readonly string[], uncovered: readonly string[] = []):
  * sending uncovered IDs back to a covering turn; marks the IDs covered on the
  * landing that ends it. A human may overrule once the retries are spent.
  */
-export const requireCoverage = async (base = start()): Promise<void> => {
+export const requireCoverage = async (base = start(), slice?: CriteriaSlice): Promise<void> => {
   let retries = 0
   for (;;) {
-    const { covered, uncovered } = await uncoveredSince(base)
+    const { covered, uncovered } = await uncoveredSince(base, slice)
     if (uncovered.length === 0) return record(covered)
     if (retries < COVERING_RETRIES) {
       retries++
-      await t.agentWithSkills("covering", t.coveringPrompt(uncovered), {
+      await t.agentWithSkills("covering", t.coveringPrompt(uncovered, sliceIds(slice)), {
         label: "Covering the acceptance criteria",
         model: coder(),
         system: t.builderSystem(),

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

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest"
 import type { Change } from "../../flows/index.js"
-import { criteriaOf, statedCriteria } from "./criteria.js"
+import { criteriaOf, criterionIds, statedCriteria } from "./criteria.js"
 
 const added = (path: string, after: string): Change => ({
   path,
@@ -104,3 +104,19 @@ describe("statedCriteria", () => {
     ).toBeUndefined()
   })
 })
+
+describe("criterionIds", () => {
+  const requirements = "## Acceptance Criteria\n\n- AC-1: a\n- AC-2: b\n- AC-4: added\n- unnamed\n"
+
+  it("lists every ID'd criterion of an unsliced change", () => {
+    expect(criterionIds(requirements)).toEqual(["AC-1", "AC-2", "AC-4"])
+  })
+
+  it("keeps `only` to the IDs the file still lists", () => {
+    expect(criterionIds(requirements, { only: ["AC-1", "AC-3"] })).toEqual(["AC-1"])
+  })
+
+  it("gives `except` every other ID, one added since included", () => {
+    expect(criterionIds(requirements, { except: ["AC-1", "AC-3"] })).toEqual(["AC-2", "AC-4"])
+  })
+})

package/src/workflows/feature/criteria.ts

@@ -8,7 +8,7 @@ import {
   scope,
   type Change,
 } from "../../flows/index.js"
-import { markFenced } from "../shared/fences.js"
+import { HEADING, ITEM, markFenced } from "../shared/fences.js"
 import { REQUIREMENTS } from "../shared/steps.js"
 import * as t from "../shared/text.js"
 
@@ -29,8 +29,6 @@ export interface StatedCriteria {
 /** Below this the judge's `yes` is not trusted: a wrong skip builds against criteria nobody can check. */
 const CLEAR_MIN_P = 0.8
 
-const HEADING = /^ {0,3}(#{1,6})\s+(.*?)\s*#*\s*$/
-const ITEM = /^ ?(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s+)?(.*)$/
 const ID = /^(AC-\d+):\s*(.*)$/
 
 /** The list items under the first heading `title` matches (at `level` when given), up to the next heading; wrapped lines joined, fenced lines ignored. */
@@ -71,6 +69,31 @@ export const criteriaOf = (text: string): readonly Criterion[] | undefined =>
     return id === null ? { id: "", text: item } : { id: id[1]!, text: id[2]! }
   })
 
+/**
+ * Which criteria one slice builds, resolved against the file whenever read:
+ * `only` drops an ID a steer deleted, `except` (the last slice) takes one a
+ * steer added.
+ */
+export interface CriteriaSlice {
+  readonly only?: readonly string[]
+  readonly except?: readonly string[]
+}
+
+/** The ID'd criteria of `text`, only `slice`'s when given. */
+export const criterionIds = (text: string, slice?: CriteriaSlice): string[] =>
+  (criteriaOf(text) ?? [])
+    .map((c) => c.id)
+    .filter(
+      (id) =>
+        id !== "" &&
+        (slice?.only === undefined || slice.only.includes(id)) &&
+        !(slice?.except ?? []).includes(id),
+    )
+
+/** `slice`'s IDs in `.gtd/REQUIREMENTS.md` as it is now; `undefined` for an unsliced change. */
+export const sliceIds = (slice: CriteriaSlice | undefined): string[] | undefined =>
+  slice === undefined ? undefined : criterionIds(read(REQUIREMENTS) ?? "", slice)
+
 /** Items numbered `AC-1`…, unless every one already carries its own distinct ID. */
 const numbered = (items: readonly string[]): Criterion[] => {
   const ids = items.map((item) => ID.exec(item))
@@ -166,3 +189,14 @@ export const skipDesign = (stated: StatedCriteria | undefined): Promise<boolean>
         })
         return true
       })
+
+/** After a gate that invites narrowing the requirements: an edit must leave valid criteria. */
+export const requireCriteriaIfEdited = (): void => {
+  const change = changes().get(REQUIREMENTS)
+  if (change === undefined) return
+  if (change.status === "deleted")
+    refuse(
+      `gtd land: criteria-missing: ${REQUIREMENTS} must stay — narrow its criteria, never delete it`,
+    )
+  requireCriteria(REQUIREMENTS)
+}