@pmelab/gtd 18.0.0 → 19.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "18.0.0",
+  "version": "19.0.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {
@@ -47,6 +47,7 @@
     "watch": "tsdown --watch",
     "bench:replay": "node scripts/bench-replay.mjs",
     "test": "turbo run format:check typecheck lint lint:sh lint:boundaries test:unit test:e2e:inmem test:e2e:live test:web analyze",
+    "test:fast": "turbo run format:check typecheck lint lint:sh lint:boundaries test:unit test:web analyze",
     "test:unit": "vitest run --project unit",
     "test:watch": "vitest",
     "test:changed": "vitest run --project unit --project e2e-inmem --changed HEAD",

package/schema.json

@@ -105,6 +105,28 @@
         }
       }
     },
+    "access": {
+      "type": "object",
+      "description": "Flat scope full-name -> { read?, write? } map of glob arrays. Each entry REPLACES the named scope's declared access wholesale (never merges into it) and reaches every nested scope that sets none of its own; a missing side is unrestricted, [] allows nothing, and {} lifts every restriction. read and write are independent: write grants no read. A key that is not a scope running a turn is a load error listing the known scopes — the schema itself cannot validate a key, only a value's shape.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "read": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "write": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
     "$schema": {
       "type": "string",
       "description": "Editor-only pointer at this schema. Stripped by gtd before validation."

package/skills/authoring/SKILL.md

@@ -63,9 +63,9 @@ current directory is the whole workflow. If one already exists, read it and edit
 it in place.
 
 Prefer the bundled workflow's own parts over re-implementing them — `healthy`,
-`escalation`, `gate`, `design`, `architecturePass`, `packages`, `specReview`,
-`qualityLap`, `review`, `buildTail`, and single steps like `triage` or `fix`.
-Their full step names are versioned API.
+`escalation`, `gate`, `design`, `architecture`, `packages`, `qualityLap`,
+`review`, `buildTail`, and single steps like `triage` or `fix`. Their full step
+names are versioned API.
 
 Make one small change, **verify it loads** (see "Verify"), then make the next. A
 workflow that fails to load breaks every gtd command in the repository.
@@ -212,7 +212,7 @@ sign-off between the two:
 const planAndBuild = async (): Promise<void> => {
   for (;;) {
     await design()
-    await architecturePass()
+    await architecture()
     await human("approve-plan", {
       message:
         "The packages under .gtd/packages/ are ready. Edit them to adjust the plan, or change nothing — then run `gtd land` to start building.",
@@ -229,9 +229,8 @@ const planAndBuild = async (): Promise<void> => {
 `acceptClean: true` is what makes an untouched landing approve; without it the
 gate would wait for an edit. `approve-plan` sits in the `root` scope and is a
 new, unique name. Verify: `gtd next` loads without errors, and in a scratch
-repository a landing at `architecture.decompose` (or `architecture-promote`) now
-leads to `approve-plan`, and an untouched landing there to
-`packages.item.building`.
+repository a landing at `architecture.decompose` now leads to `approve-plan`,
+and an untouched landing there to `packages.item.building`.
 
 ## No migration
 

package/src/flows/helpers.ts

@@ -36,6 +36,8 @@ export interface CheckOptions {
   readonly sweep?: readonly string[] | undefined
   /** Paths removed once it passes. */
   readonly sweepOnGreen?: readonly string[] | undefined
+  /** Shell lines run before the command, outside its output capture; an `exit 0` skips it and leaves `report` untouched. */
+  readonly preamble?: readonly string[] | undefined
 }
 
 /**
@@ -48,10 +50,10 @@ export const check = async (
   command: string,
   options: CheckOptions,
 ): Promise<boolean> => {
-  const { report, label, sweep, sweepOnGreen } = options
+  const { report, label, sweep, sweepOnGreen, preamble } = options
   await run(
     name,
-    checkScript(command, { report, stamp: head().slice(0, 7), sweep, sweepOnGreen }),
+    checkScript(command, { report, stamp: head().slice(0, 7), sweep, sweepOnGreen, preamble }),
     { label },
   )
   return !wrote(report)

package/src/flows/runtime.ts

@@ -83,6 +83,18 @@ export interface Changes extends ReadonlyArray<Change> {
   readonly get: (path: string) => Change | undefined
 }
 
+/** Glob arrays in the `glob()`/`changes()` dialect. A missing side is unrestricted, `[]` allows nothing; `write` grants no read. */
+export interface ScopeAccess {
+  readonly read?: readonly string[] | undefined
+  readonly write?: readonly string[] | undefined
+}
+
+/** A resolved access: `null` is an unrestricted side. */
+export interface AccessDef {
+  readonly read: readonly string[] | null
+  readonly write: readonly string[] | null
+}
+
 export interface ScopeOptions {
   /** Prefixes every step name inside, and so names their memory scope. */
   readonly name?: string | undefined
@@ -92,6 +104,8 @@ export interface ScopeOptions {
   readonly system?: string | undefined
   /** The skill names every agent step inside declares — `gtd next --json`'s `skills`. A nested scope inherits it unless it sets its own. */
   readonly skills?: readonly string[] | undefined
+  /** The file access every agent step inside runs with — `gtd next --json`'s `access`. A nested scope inherits it; its own replaces it wholesale. */
+  readonly access?: ScopeAccess | undefined
 }
 
 export type StepRequest =
@@ -141,6 +155,8 @@ export interface FlowContext {
   readonly start: () => string
   /** The skill list the memory scope `localName` lands in resolves to — the same resolver as the wire's `skills`. */
   readonly skillsFor: (localName: string) => readonly string[]
+  /** The folded access the memory scope `localName` lands in resolves to; `file` is the step's own steering file. */
+  readonly accessFor: (localName: string, file?: string) => AccessDef
 }
 
 const CONTEXT_KEY = Symbol.for("@pmelab/gtd/flow-context")
@@ -249,6 +265,10 @@ export const start = (): string => ctx().start()
 /** The skill list `localName` (scoped from here, same as `agent()`) resolves to — for a prompt preamble. */
 export const skillsFor = (localName: string): readonly string[] => ctx().skillsFor(localName)
 
+/** The folded access `localName` (scoped from here, same as `agent()`) resolves to — for a prompt preamble. */
+export const accessFor = (localName: string, file?: string): AccessDef =>
+  ctx().accessFor(localName, file)
+
 const settingsProxy = (
   read: () => Readonly<Record<string, string>>,
 ): Readonly<Record<string, string>> =>

package/src/flows/scripts.test.ts

@@ -1,5 +1,9 @@
+import { spawnSync } from "node:child_process"
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
 import { describe, expect, it } from "vitest"
-import { restoreScript } from "./scripts.js"
+import { checkScript, restoreScript } from "./scripts.js"
 
 describe("restoreScript", () => {
   const paths = { restore: ["a.ts"], remove: [] }
@@ -14,3 +18,26 @@ describe("restoreScript", () => {
     expect(script).not.toContain("abc~1")
   })
 })
+
+describe("checkScript preamble", () => {
+  const options = { report: ".gtd/FEEDBACK.md", stamp: "abc" }
+  const runIn = (script: string, dir: string): void => {
+    writeFileSync(join(dir, "s.sh"), script)
+    spawnSync("sh", ["s.sh"], { cwd: dir })
+  }
+
+  it("renders before the command subshell", () => {
+    const script = checkScript("npm test", { ...options, preamble: ["echo pre"] })
+    expect(script.indexOf("echo pre")).toBeGreaterThan(-1)
+    expect(script.indexOf("echo pre")).toBeLessThan(script.indexOf("npm test"))
+  })
+
+  it("an exit 0 in the preamble skips the command and leaves report alone", () => {
+    const dir = mkdtempSync(join(tmpdir(), "gtd-pre-"))
+    mkdirSync(join(dir, ".gtd"))
+    writeFileSync(join(dir, ".gtd/FEEDBACK.md"), "old")
+    runIn(checkScript("touch ran", { ...options, preamble: ["exit 0"] }), dir)
+    expect(existsSync(join(dir, "ran"))).toBe(false)
+    expect(readFileSync(join(dir, ".gtd/FEEDBACK.md"), "utf8")).toBe("old")
+  })
+})

package/src/flows/scripts.ts

@@ -14,6 +14,8 @@ export interface CheckScriptOptions {
   readonly sweep?: readonly string[] | undefined
   /** Paths removed once it passes. */
   readonly sweepOnGreen?: readonly string[] | undefined
+  /** Shell lines run before the command, outside its output capture; an `exit 0` skips it and leaves `report` untouched. */
+  readonly preamble?: readonly string[] | undefined
 }
 
 const removal = (paths: readonly string[]): string[] =>
@@ -29,6 +31,7 @@ export const checkScript = (command: string, options: CheckScriptOptions): strin
   return [
     "#!/usr/bin/env sh",
     "set +e",
+    ...(options.preamble ?? []),
     ...removal(options.sweep ?? []),
     `mkdir -p "$(dirname ${report})"`,
     // A subshell, so an `exit` inside the command ends only the command.

package/src/workflows/access.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest"
+import { access } from "./access.js"
+import { unified } from "./index.js"
+
+const { defaults } = unified
+
+const bundled = access(defaults)
+
+describe("the bundled workflow's access export", () => {
+  it("restricts writes on planning, review and lens scopes only", () => {
+    expect(bundled).toEqual({
+      design: { write: [] },
+      architecture: { write: [".gtd/REQUIREMENTS.md"] },
+      "architecture.decompose": { write: [".gtd/packages/**", ".gtd/ARCHITECTURE.md"] },
+      "build.review": { write: [".gtd/REVIEW.md"] },
+      "build.review.fix.nits": {},
+      "build.review.fix.risks": {},
+      "build.quality.correctness": { write: [] },
+      "build.quality.owasp-security": { write: [] },
+      "build.quality.ponytail-review": { write: [] },
+      "build.quality.test-audit": { write: [] },
+      "build.quality.conventions": { write: [] },
+      "build.quality.spec-challenge": { write: [] },
+    })
+  })
+
+  it("keys one lens scope per qualityReviews entry", () => {
+    const custom = access({ ...defaults, qualityReviews: " my-lens ,, correctness" })
+    expect(
+      Object.keys(custom)
+        .filter((k) => k.startsWith("build.quality."))
+        .sort(),
+    ).toEqual(["build.quality.correctness", "build.quality.my-lens"])
+  })
+
+  it("keys only scopes that run a turn (every key is a skills key)", () => {
+    const known = Object.keys(unified.skills(defaults))
+    for (const key of Object.keys(bundled)) expect(known).toContain(key)
+  })
+})

package/src/workflows/access.ts

@@ -0,0 +1,22 @@
+import type { ScopeAccess } from "../flows/index.js"
+import { lensesOf } from "./review.js"
+
+// The bundled workflow's default file access, keyed by scope full name — the
+// name a `.gtdrc` `access:` entry addresses. Only planning and review scopes
+// are restricted, and only on writes; no scope restricts reads. A step's own
+// steering file is folded in per step, so it is not listed here. Build and fix
+// scopes carry no entry: no project layout is assumed.
+export const access = (
+  vars: Readonly<Record<string, string>>,
+): Readonly<Record<string, ScopeAccess>> => ({
+  design: { write: [] },
+  architecture: { write: [".gtd/REQUIREMENTS.md"] },
+  "architecture.decompose": { write: [".gtd/packages/**", ".gtd/ARCHITECTURE.md"] },
+  "build.review": { write: [".gtd/REVIEW.md"] },
+  // `{}` reopens what `build.review` restricted: the fixes edit code.
+  "build.review.fix.nits": {},
+  "build.review.fix.risks": {},
+  ...Object.fromEntries(
+    lensesOf(vars.qualityReviews ?? "").map((lens) => [`build.quality.${lens}`, { write: [] }]),
+  ),
+})

package/src/workflows/health.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest"
 import { toRequest } from "../judges/index.js"
-import { retryQuestion } from "./health.js"
+import { fastSuiteGuard, retryQuestion } from "./health.js"
+import { renderText } from "./text.fixture.js"
 
 describe("retryQuestion", () => {
   it.each([true, false])("is sendable to jev (comparable=%s)", (comparable) => {
@@ -11,3 +12,22 @@ describe("retryQuestion", () => {
     ).toBeGreaterThanOrEqual(2)
   })
 })
+
+describe("fastSuiteGuard", () => {
+  it("unset: names the setting and exits 0", () => {
+    const lines = renderText(fastSuiteGuard).join("\n")
+    expect(lines).toContain("fastTestCommand")
+    expect(lines).toContain("GTD_FASTTESTCOMMAND")
+    expect(lines).toContain("exit 0")
+  })
+
+  it("blank after trim counts as unset", () => {
+    expect(renderText(fastSuiteGuard, { env: { fastTestCommand: "  \t " } })).toContain("exit 0")
+  })
+
+  it("set: only removes SETUP", () => {
+    const lines = renderText(fastSuiteGuard, { env: { fastTestCommand: "true" } })
+    expect(lines.join("\n")).not.toContain("exit 0")
+    expect(lines.join("\n")).toContain("rm -f")
+  })
+})

package/src/workflows/health.ts

@@ -1,3 +1,4 @@
+import { dirname } from "node:path"
 import {
   answered,
   check,
@@ -5,6 +6,7 @@ import {
   human,
   judge,
   numeric,
+  quote,
   read,
   scope,
   vars,
@@ -13,12 +15,37 @@ import {
 import { describeEscalation, escalate, escalationExhausted, ESCALATION, FEEDBACK } from "./steps.js"
 import * as t from "./text.js"
 
+/** Written while `fastTestCommand` is unset; its presence rests the process at the check. */
+export const SETUP = ".gtd/SETUP.md"
+
+const SETUP_TEXT =
+  "The bundled workflow needs the `fastTestCommand` setting: the fast suite (everything but e2e).\nSet it under `env:` in `.gtdrc` or as GTD_FASTTESTCOMMAND."
+
+/** Shell lines for a check's preamble: unset (blank after trim) setting writes `SETUP` and skips the suite. */
+export const fastSuiteGuard = (): string[] =>
+  (env.fastTestCommand ?? "").trim() === ""
+    ? [
+        `mkdir -p ${quote(dirname(SETUP))}`,
+        `printf '%s\\n' ${quote(SETUP_TEXT)} > ${quote(SETUP)}`,
+        `printf '%s\\n' ${quote(SETUP_TEXT)} >&2`,
+        "exit 0",
+      ]
+    : [`rm -f ${quote(SETUP)}`]
+
 /** Fix turns a run of red checks gets before it escalates. */
 export const FIX_CAP = 3
 
 /** Run the suite as step `name`; resolves `true` when it passed. A failure is in `.gtd/FEEDBACK.md`. */
-export const baseline = (name: string, label = "Checking the baseline"): Promise<boolean> =>
-  check(name, env.testCommand ?? "", { report: FEEDBACK, label })
+export const baseline = async (name: string, label = "Checking the baseline"): Promise<boolean> => {
+  for (;;) {
+    const green = await check(name, env.testCommand ?? "", {
+      report: FEEDBACK,
+      label,
+      preamble: fastSuiteGuard(),
+    })
+    if (read(SETUP) === undefined) return green
+  }
+}
 
 /** How many escalation rounds a run of red checks has spent — reset once the suite goes green. */
 export interface EscalationCount {
@@ -81,6 +108,21 @@ export interface HealthOptions {
   readonly fixesSoFar?: number
   /** Escalation rounds shared with other callers in the same run of red checks. */
   readonly escalations?: EscalationCount
+  /** `fast` runs `fastTestCommand` (default `full`: `testCommand`). */
+  readonly suite?: "full" | "fast"
+  /** Paths removed on a green run. */
+  readonly sweepOnGreen?: readonly string[]
+}
+
+const runSuite = (options: HealthOptions): Promise<boolean> => {
+  const fast = options.suite === "fast"
+  return check("health.check", (fast ? env.fastTestCommand : env.testCommand) ?? "", {
+    report: FEEDBACK,
+    label: "Running checks",
+    // Swept only on green: an unresolved analysis survives every retry.
+    sweepOnGreen: [ESCALATION, ...(options.sweepOnGreen ?? [])],
+    ...(fast ? { preamble: fastSuiteGuard() } : {}),
+  })
 }
 
 /**
@@ -96,12 +138,9 @@ export const healthy = async (
   let fixes = options.fixesSoFar ?? 0
   let previous: string | undefined
   for (;;) {
-    const green = await check("health.check", env.testCommand ?? "", {
-      report: FEEDBACK,
-      label: "Running checks",
-      // Swept only on green: an unresolved analysis survives every retry.
-      sweepOnGreen: [ESCALATION],
-    })
+    const green = await runSuite(options)
+    // Unconfigured: straight back to the check, no fix turn or count.
+    if (options.suite === "fast" && read(SETUP) !== undefined) continue
     if (green) {
       escalations.rounds = 0
       return

package/src/workflows/packages.test.ts

@@ -0,0 +1,91 @@
+import { afterEach, describe, expect, it } from "vitest"
+import { installContext, type Change, type StepRequest } from "../flows/index.js"
+import { declaredTests, packages, SCENARIO_PACKAGE } from "./packages.js"
+import { fixtureContext } from "./text.fixture.js"
+
+afterEach(() => installContext(undefined))
+
+describe("declaredTests", () => {
+  it("parses unit and e2e lines of the Tests section", () => {
+    const text = [
+      "# Package",
+      "",
+      "## Tests",
+      "",
+      "- unit: `lib/a.test.ts`",
+      "- e2e: `spec/a.feature`",
+    ].join("\n")
+    expect(declaredTests(text)).toEqual([
+      { level: "unit", path: "lib/a.test.ts" },
+      { level: "e2e", path: "spec/a.feature" },
+    ])
+  })
+
+  it("ignores prose, malformed lines and other sections", () => {
+    const text = [
+      "## Tasks",
+      "- unit: `lib/not-here.test.ts`",
+      "## Tests",
+      "Some prose.",
+      "- unit: lib/unquoted.test.ts",
+      "- integration: `lib/x.test.ts`",
+      "- unit: `lib/ok.test.ts` extra",
+      "## Notes",
+      "- e2e: `spec/other.feature`",
+    ].join("\n")
+    expect(declaredTests(text)).toEqual([{ level: "unit", path: "lib/ok.test.ts" }])
+  })
+
+  it("returns nothing without a Tests section", () => {
+    expect(declaredTests("# Chore\n\n## Tasks\n- do it\n")).toEqual([])
+  })
+})
+
+describe("packages scenarios", () => {
+  it("holds only package 0's own paths, not what later packages add", async () => {
+    const queue = [SCENARIO_PACKAGE, ".gtd/packages/01-impl.md"]
+    const touches: { at: number; change: Change }[] = []
+    let steps = 0
+    const touch = (path: string, status: Change["status"]): void => {
+      touches.push({ at: steps, change: { path, status, before: undefined, after: "x" } })
+    }
+    const effects: Record<string, () => void> = {
+      building: () => {
+        if (queue[0] === SCENARIO_PACKAGE) {
+          touch("tests/e2e/a.feature", "added")
+          touch(".gtd/packages/00-e2e-scenarios.md", "modified")
+        } else {
+          touch("src/impl.ts", "added")
+          touch("tests/e2e/b.feature", "added")
+          touch("tests/e2e/a.feature", "modified")
+        }
+      },
+      closing: () => void queue.shift(),
+    }
+    installContext(
+      fixtureContext(
+        {},
+        {
+          step: (request: StepRequest) => {
+            steps++
+            if (request.kind !== "restart") effects[request.name]?.()
+            return Promise.resolve()
+          },
+          pushScope: () => undefined,
+          popScope: () => undefined,
+          refuse: (message: string): never => {
+            throw new Error(message)
+          },
+          glob: () => [...queue],
+          changesSince: (hash: string): readonly Change[] =>
+            touches.filter((t) => t.at >= Number(hash.slice(1))).map((t) => t.change),
+          head: () => `c${steps}`,
+        },
+      ),
+    )
+    const plan = await packages()
+    expect(plan.ranges.map((r) => r.pkg)).toEqual([SCENARIO_PACKAGE, ".gtd/packages/01-impl.md"])
+    expect(plan.scenarios.added).toEqual(["tests/e2e/a.feature"])
+    expect(plan.scenarios.changed).toEqual([])
+  })
+})