@pmelab/gtd 18.0.0 → 19.0.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gtd",
-  "version": "18.0.0",
+  "version": "19.0.0",
   "description": "Drive the gtd loop inside Claude Code: agent turns run as subagents, gtd decides every beat",
   "author": {
     "name": "Philipp Melab"

package/README.md

@@ -34,6 +34,16 @@ own addressable `.gtdrc` `skills:` entry — see
 [Configuration](https://github.com/pmelab/gtd/blob/main/docs/configuration.md#the-skills-key)
 to repoint one to a set your own harness has instead.
 
+Each scope also declares which files its agent turns may read and write;
+`gtd land` refuses a turn that wrote outside its scope, and a driver can pass
+the read side to its agent. `read` is not a security boundary unless your driver
+enforces it at the OS level. See
+[Configuration](https://github.com/pmelab/gtd/blob/main/docs/configuration.md#file-access).
+
+> **`fastTestCommand` is required, with no fallback to `testCommand`.** Set it
+> (everything but e2e) under `env:` in `.gtdrc` or as `GTD_FASTTESTCOMMAND`; gtd
+> stops at the start gate, writing `.gtd/SETUP.md`, until it is.
+
 > **A repository's `gtd.config.ts` is code, and gtd runs it.** A custom workflow
 > is a TypeScript module, and every gtd command that looks at workflow state —
 > `gtd next` and `gtd lsp` included, not just `gtd land` — evaluates it. Treat
@@ -349,7 +359,7 @@ lists the open ones (editor-only — the phone UI does not show them).
 
 One built-in workflow drives all of that. From where you sit, it has four
 moments — everything between them runs without you, with the judged exceptions
-noted in steps 2, 3, and 4 below.
+noted in steps 3 and 4 below.
 
 1. **You sketch.** Change anything, or write the idea into `.gtd/TODO.md`. Rough
    is fine; it is treated as a sketch, not as work.
@@ -362,25 +372,22 @@ noted in steps 2, 3, and 4 below.
    the same gate again. Close a thread by replying with a conclusion or deleting
    it. While a thread's last entry is the agent's, moving on is refused. Leave
    the file untouched and start the loop to accept the plan as-is, unanswered
-   questions and all. One point along this phase is judged rather than always
-   asking you outright:
-   - Before the how-it-should-be-built pass starts: does this plan actually need
-     one? A confident no skips it — and the review it would have raised — going
-     straight from your answers to a single built package, with no technical
-     plan shown to you at all.
-
-   The reference driver answers this judgment itself (`gtd judge run`, auto
-   selection); if that fails it shows you the message and stops, same as any
-   other question. **The `llm` provider's `p` is self-reported by the model, not
-   a measured probability, so a confidently wrong haiku verdict can skip a
-   question you would have asked.**
+   questions and all. Every plan gets the technical pass: its document has four
+   sections, in order — `## Interfaces`, `## Call Stacks`, `## E2E Scenarios`,
+   `## Unit Tests` — behind a leading `## Open Questions` when there are any.
+   `## E2E Scenarios` is never empty: it holds the scenarios, or, when nothing
+   user-visible changes, the line `No e2e change.` with a one-line reason.
 
 3. **You wait.** The work is split into packages and built one at a time, each
-   one checked against your test suite and fixed until it passes, then reviewed
-   against its own spec before moving on. Three points along that loop are
-   judged rather than always asking you outright — each stops and hands you a
-   verdict to make (`gtd judge answer`, or land with a clean tree to accept the
-   conservative default, which never skips work;
+   one starting from the unit tests it declares (a build turn missing one is
+   refused), checked against the fast suite and fixed until it passes before
+   moving on. A package that rewords a frozen `.feature` step stops at a wording
+   gate: accept the change, or reject it and the original is restored. After the
+   last package a full run (e2e included) has its own fix loop before the
+   quality lap. Two points along the process are judged rather than always
+   asking you outright — each stops and hands you a verdict to make
+   (`gtd judge answer`, or land with a clean tree to accept the conservative
+   default, which never skips work;
    `gtd judge run --provider fixed --answers <path>` — or the
    `GTD_JUDGE_ANSWERS` env var, inline JSON — answers one from a file, piped
    between `gtd judge --json` and `gtd judge answer`;
@@ -397,17 +404,15 @@ noted in steps 2, 3, and 4 below.
    stdout when they cannot answer every question):
    - Every red round after the first: was the failure identical, new, or
      progress?
-   - Before spending a review turn on a package: does the code already satisfy
-     each of its requirements?
-   - After a review turn raises concerns: would each one actually violate the
-     spec if left unaddressed, or is it a nit?
+   - After you review: is each of your notes an edit, a question, a nit or
+     praise?
 
    The reference driver answers these itself (`gtd judge run`, auto selection:
    jev when `TYPESAFE_API_KEY` is set, else `llm` via `claude`, default model
    haiku, `--model <name>` overrides); if that fails it shows you the message
    and stops. **The `llm` provider's `p` is self-reported by the model, not a
-   measured probability, so a confidently wrong verdict can clear the 0.9/0.7
-   floors and skip a gate unattended.**
+   measured probability, so a confidently wrong verdict can clear the 0.7 floor
+   and skip a gate unattended.**
 
    Once the last package is built, the whole change goes through a qualitative
    review lap before you see anything: six lenses, one turn each, in order —
@@ -415,8 +420,7 @@ noted in steps 2, 3, and 4 below.
    `conventions`, `spec-challenge`. Each traces the change from its own angle
    and records every finding, blocking or not; one fix turn then fixes ALL of
    them once, with no re-review after the fix. A clean turn means approval only
-   when that lens found nothing at all. The per-package review above only judges
-   that package against its own spec; this lap is where code quality is looked
+   when that lens found nothing at all. This lap is where code quality is looked
    at, and every round pays for it. It never replaces step 4 — your review stays
    the final gate, and nothing here skips it. The `gtd --entry fix-precheck`
    side door (below) repairs a red baseline through this same lap.
@@ -432,10 +436,10 @@ noted in steps 2, 3, and 4 below.
 
 4. **You review.** You get a review document listing what changed and what to
    look at. Before you see it, an automatic risk-fix pass
-   (`build.review.fix-risks`) runs. Any risk the reviewer names (a note opening
-   with `Risk:`) is fixed first, the suite kept green, and the review rewritten
-   — once per review round, so a risk the rewrite still names reaches you
-   unfixed; risk: a fix lands with no check that the risk was real. Tick the
+   (`build.review.fix.risks.fixing`) runs. Any risk the reviewer names (a note
+   opening with `Risk:`) is fixed first, the suite kept green, and the review
+   rewritten — once per review round, so a risk the rewrite still names reaches
+   you unfixed; risk: a fix lands with no check that the risk was real. Tick the
    boxes to approve, or write what is wrong. Approving ends the process;
    feedback is judged note by note, each as `edit`, `question`, `nit` or
    `praise`. An `edit` sends the process back to step 2 for a fresh plan — it

package/claude/hooks/access.ts

@@ -0,0 +1,58 @@
+import { isAbsolute, relative, resolve } from "node:path"
+
+import { globMatches } from "../../src/replay/Glob.js"
+
+export type AccessDef = { read: string[] | null; write: string[] | null }
+
+const READ = new Set(["Read"])
+const WRITE: Record<string, string> = {
+  Edit: "file_path",
+  MultiEdit: "file_path",
+  Write: "file_path",
+  NotebookEdit: "notebook_path",
+}
+
+// Repo-relative form of a path; undefined when it lies outside the repo.
+const inRepo = (p: string, root: string): string | undefined => {
+  const rel = relative(root, isAbsolute(p) ? p : resolve(root, p))
+  return rel === ".." || rel.startsWith("../") || isAbsolute(rel) ? undefined : rel
+}
+
+const deny = (verb: string, path: string, globs: string[]) =>
+  `gtd access: ${verb} of ${path} is outside this step's ${verb} access (${globs.join(", ") || "none"})`
+
+// Bash is deliberately not inspected: access is best effort at the tool level,
+// and `gtd land` is the backstop for writes.
+export function accessDenial(
+  tool: string,
+  input: Record<string, unknown>,
+  access: AccessDef,
+  root: string,
+): string | undefined {
+  if (READ.has(tool)) return check("read", input.file_path, access.read, root)
+  const key = WRITE[tool]
+  if (key) return check("write", input[key], access.write, root)
+  if (tool === "Glob" || tool === "Grep") return searchDenial(input.path, access.read, root)
+  return undefined
+}
+
+function check(verb: string, raw: unknown, globs: string[] | null, root: string) {
+  if (globs === null || typeof raw !== "string") return undefined
+  const rel = inRepo(raw, root)
+  if (rel === undefined || globs.some((g) => globMatches(rel, g))) return undefined
+  return deny(verb, rel, globs)
+}
+
+// A search is allowed only from a root that sits inside the literal directory
+// prefix of some read glob, so it cannot enumerate files outside the access.
+function searchDenial(raw: unknown, globs: string[] | null, root: string) {
+  if (globs === null) return undefined
+  const rel = typeof raw === "string" && raw ? inRepo(raw, root) : ""
+  if (rel === undefined) return undefined
+  const inside = globs.some((g) => {
+    const prefix = g.split("*")[0]!
+    const dir = prefix.slice(0, prefix.lastIndexOf("/") + 1).replace(/\/$/, "")
+    return dir === "" || rel === dir || rel.startsWith(`${dir}/`)
+  })
+  return inside ? undefined : deny("read", rel || ".", globs)
+}

package/claude/hooks/drive.ts

@@ -1,4 +1,6 @@
+import { ACCESS_REFUSAL } from "../../src/wire/constants.js"
 import type { Stop } from "../types"
+import type { AccessDef } from "./access"
 
 // The subset of `gtd next --json` this driver reads. Absent optional fields
 // are simply missing; booleans may arrive as strings.
@@ -15,6 +17,7 @@ export type Beat = {
   system?: string
   skills?: string[]
   validate?: string
+  access?: AccessDef
   judge?: unknown
   changes?: { status: string; path: string }[]
   session?: { id?: string; resume?: boolean | string }
@@ -36,6 +39,7 @@ export type Turn = {
   system?: string
   skills: readonly string[]
   scope: string
+  access?: AccessDef
 }
 
 export type TurnEnd = { ok: true } | { ok: false; why: string }
@@ -83,7 +87,7 @@ export async function drive(io: Io, landTurn?: string): Promise<Stop> {
     const acted = await act(io, b, beat, judged, beat === 1 ? landTurn : undefined)
     if (acted.stop) return acted.stop
     judged = acted.verdict ? b.state : undefined
-    const landed = await land(io, b, acted.verdict)
+    const landed = await land(io, b, acted.verdict, true)
     if (landed) return landed
   }
 }
@@ -123,7 +127,7 @@ async function message(io: Io, b: Beat, beat: number, judged: string | undefined
 }
 
 async function agent(io: Io, b: Beat, landTurn: string | undefined): Promise<Acted> {
-  const memory = b.memory ?? b.session?.id ?? b.state ?? "root"
+  const memory = memoryOf(b)
   const t =
     landTurn === memory
       ? ({ ok: true } as const)
@@ -136,6 +140,7 @@ async function agent(io: Io, b: Beat, landTurn: string | undefined): Promise<Act
           system: b.system || undefined,
           skills: b.skills ?? [],
           scope: memory.split("#")[0]!,
+          access: b.access,
         })
   if (!t.ok) return failed(b, t.why)
   return b.validate ? validated(io, b, b.validate, memory) : {}
@@ -153,8 +158,25 @@ async function validated(io: Io, b: Beat, validate: string, memory: string): Pro
   }
 }
 
-async function land(io: Io, b: Beat, verdict: string | undefined): Promise<Stop | undefined> {
-  const l = await io.land(verdict)
+const memoryOf = (b: Beat) => b.memory ?? b.session?.id ?? b.state ?? "root"
+
+// A prompt beat whose turn wrote outside its access gets one recovery turn
+// with the refusal text; a second refusal is an error, not another loop.
+async function land(
+  io: Io,
+  b: Beat,
+  verdict: string | undefined,
+  mayRecover: boolean,
+): Promise<Stop | undefined> {
+  let l: Landing
+  try {
+    l = await io.land(verdict)
+  } catch (e) {
+    const text = e instanceof Error ? e.message : String(e)
+    if (b.kind !== "prompt" || !text.includes(ACCESS_REFUSAL)) throw e
+    if (!mayRecover) return { kind: "error", text, ...where(b) }
+    return recover(io, b, verdict, text)
+  }
   const code = await io.sh(l.script, b.log)
   if (code !== 0) return { kind: "error", text: `landing script exited ${code}`, ...where(b) }
   if (!isTrue(l.settled)) return undefined
@@ -162,6 +184,22 @@ async function land(io: Io, b: Beat, verdict: string | undefined): Promise<Stop
   return { kind: "done", text, ...where(b) }
 }
 
+async function recover(
+  io: Io,
+  b: Beat,
+  verdict: string | undefined,
+  text: string,
+): Promise<Stop | undefined> {
+  const memory = memoryOf(b)
+  const r = await io.resume(memory, text)
+  if (!r.ok) return { kind: "error", text: r.why, ...where(b) }
+  if (b.validate) {
+    const v = await validated(io, b, b.validate, memory)
+    if (v.stop) return v.stop
+  }
+  return land(io, b, verdict, false)
+}
+
 // What a reload that cut the loop off does next. Only a turn the agent
 // finished lands; any other end runs it again. A script cut off may have run
 // partly, and running it again is not safe to assume, so a person decides.

package/claude/hooks/register.tsx

@@ -2,6 +2,8 @@ import { atom, read, update } from "claude-code"
 import type { EngineInterface, Register } from "claude-code"
 
 import type { Run, Stop } from "../types"
+import { accessDenial } from "./access"
+import type { AccessDef } from "./access"
 import { afterReload, drive, isTrue } from "./drive"
 import type { Beat, Io, Landing, Turn, TurnEnd } from "./drive"
 import { enter } from "./entry"
@@ -66,6 +68,11 @@ let isShipping = false
 // subagents answering into a file: what each may touch (see tool.call)
 const delegates = new Map<string, { file: string; mayRun: RegExp | undefined }>()
 const ours = new Set<string>()
+// What each turn agent may read and write; reset on every spawn and resume,
+// since the steering file can differ per step.
+const accesses = new Map<string, AccessDef>()
+const setAccess = (id: string, a: AccessDef | undefined) =>
+  void (a ? accesses.set(id, a) : accesses.delete(id))
 const waiting = new Map<string, (end: TurnEnd) => void>()
 const ended = new Map<string, TurnEnd>()
 const personas = new Set<string>()
@@ -168,6 +175,7 @@ function io($: $): Io {
       const known = resumable(entry, name)
       if (t.resume && entry && !known) $.ui.log(restartLine(t.scope))
       if (t.resume && known) {
+        setAccess(known, t.access)
         const end = send($, known, t.prompt)
         await update($, run, (r) => ({ ...r, inflight: { agentId: known, memory: t.memory } }))
         const ended = await end
@@ -188,6 +196,7 @@ function io($: $): Io {
       const id = spawned.agentId
       if (!id) return { ok: false, why: spawned.deny ?? "subagent spawn refused" }
       ours.add(id)
+      setAccess(id, t.access)
       await update($, agents, (list) => [...list, id].slice(-200))
       await update($, scopes, (s) => ({ ...s, [t.memory]: { agentId: id, persona: name } }))
       await update($, run, (r) => ({ ...r, inflight: { agentId: id, memory: t.memory } }))
@@ -744,6 +753,9 @@ export const register: Register = (on) => {
   // would still be writing the tree gtd is committing.
   on("tool.call", ($, e, next) => {
     if (!e.agentId || !ours.has(e.agentId)) return next(e)
+    const access = accesses.get(e.agentId)
+    const denial = access && accessDenial(String(e.tool), e, access, root)
+    if (denial) return { deny: denial }
     const delegated = delegates.get(e.agentId)
     if (delegated) {
       if (e.tool === "Write" && e.file_path !== delegated.file) {