@pmelab/gtd 18.0.0 → 18.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "18.0.0",
+  "version": "18.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/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/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/workflows/access.test.ts

@@ -0,0 +1,41 @@
+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"] },
+      "packages.item.spec": { write: [".gtd/SPEC_FEEDBACK.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,23 @@
+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"] },
+  "packages.item.spec": { write: [".gtd/SPEC_FEEDBACK.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/prose.ts

@@ -12,6 +12,23 @@ export const skillsPreamble = `- Load whatever's listed here that your harness a
 - Never let a loaded skill turn this turn interactive — answer nothing,
   ask nothing; this runs unattended, with no one at a keyboard`
 
+/** One bullet per restricted side; empty when neither is. An empty glob list reads "nothing". */
+export const accessPreamble = (access: {
+  readonly read: readonly string[] | null
+  readonly write: readonly string[] | null
+}): string => {
+  const globs = (list: readonly string[]): string =>
+    list.length === 0 ? "nothing" : list.join(", ")
+  return [
+    ...(access.read === null ? [] : [`- This turn may read only: ${globs(access.read)}`]),
+    ...(access.write === null
+      ? []
+      : [
+          `- This turn may write only: ${globs(access.write)} — anything else is refused when the turn lands`,
+        ]),
+  ].join("\n")
+}
+
 export const styleBlock = `- A deliverable, not a chat reply — size follows the work; cut padding
 - Lead with the answer; never circle back to restate it
 - Flat, commanding sentences — commit to the claim, never hedge

package/src/workflows/text.fixture.ts

@@ -1,9 +1,13 @@
 import {
   installContext,
   type CodeThreadInfo,
+  type AccessDef,
   type FlowContext,
+  type ScopeAccess,
   type StepRequest,
 } from "../flows/index.js"
+import { foldAccess } from "../replay/index.js"
+import { access as bundledAccess } from "./access.js"
 import { skills as bundledSkills } from "./skills.js"
 import { defaults, envDefaults } from "./vars.js"
 
@@ -18,6 +22,8 @@ export interface TextContext {
   readonly scope?: string
   /** Stands in for `.gtdrc` `skills:`, keyed by scope full name. */
   readonly skills?: Readonly<Record<string, readonly string[]>>
+  /** Stands in for `.gtdrc` `access:`, keyed by scope full name. */
+  readonly access?: Readonly<Record<string, ScopeAccess>>
 }
 
 const unavailable = (): never => {
@@ -39,6 +45,25 @@ const skillsForOf =
     return []
   }
 
+/** The same walk for access, folded the way `Replay.ts` folds it. */
+const accessForOf =
+  (context: TextContext) =>
+  (localName: string, file?: string): AccessDef => {
+    const full = [context.scope, localName].filter((part) => part !== undefined && part !== "")
+    const parts = full.join(".").split(".").slice(0, -1)
+    const bundled = bundledAccess({ ...defaults, ...context.vars })
+    let hit: ScopeAccess | undefined
+    for (let n = parts.length; n >= 0 && hit === undefined; n--) {
+      const prefix = parts.slice(0, n).join(".")
+      hit = context.access?.[prefix] ?? bundled[prefix]
+    }
+    return foldAccess(
+      hit,
+      file,
+      (context.codeThreads ?? []).filter((t) => t.waitingOn === "agent").map((t) => t.path),
+    )
+  }
+
 /** The fixed replay context texts render against; steps, refusals and scopes are unavailable unless overridden. */
 export const fixtureContext = (
   context: TextContext = {},
@@ -63,6 +88,7 @@ export const fixtureContext = (
   head: () => context.head ?? "",
   start: () => context.start ?? "",
   skillsFor: skillsForOf(context),
+  accessFor: accessForOf(context),
   ...overrides,
 })
 

package/src/workflows/text.test.ts

@@ -56,6 +56,47 @@ describe("agentWithSkills", () => {
   })
 })
 
+describe("agentWithSkills access preamble", () => {
+  const capture = (
+    context: Parameters<typeof captureStep>[1],
+    options: Parameters<typeof agentWithSkills>[2] = {},
+  ) => captureStep(() => agentWithSkills("name", "do-the-work", options), context)
+
+  it("names each restricted side, after the skills preamble and before the prompt", async () => {
+    const request = await capture({
+      scope: "a",
+      skills: { a: ["testing"] },
+      access: { a: { read: ["docs/**"], write: ["out/**"] } },
+    })
+    if (request.kind !== "agent") throw new Error("unreachable")
+    const prompt = request.prompt
+    expect(prompt).toContain("- This turn may read only: docs/**")
+    expect(prompt).toContain(
+      "- This turn may write only: out/** — anything else is refused when the turn lands",
+    )
+    expect(prompt.indexOf("missing one: testing")).toBeLessThan(
+      prompt.indexOf("This turn may read only"),
+    )
+    expect(prompt.endsWith("\n\ndo-the-work")).toBe(true)
+  })
+
+  it("folds the steering file into the named globs", async () => {
+    const request = await capture(
+      { scope: "a", access: { a: { write: [] } } },
+      { file: ".gtd/NOTES.md" },
+    )
+    if (request.kind !== "agent") throw new Error("unreachable")
+    expect(request.prompt).toContain("may write only: .gtd/NOTES.md —")
+    expect(request.prompt).not.toContain("may read only")
+  })
+
+  it("leaves the prompt byte-identical when both sides are unrestricted", async () => {
+    const request = await capture({ scope: "a", skills: { a: [] }, access: { a: {} } })
+    if (request.kind !== "agent") throw new Error("unreachable")
+    expect(request.prompt).toBe("do-the-work")
+  })
+})
+
 describe("the shared open-question instruction", () => {
   it("leaves the option count to the agent, floored at two real options", () => {
     const prompt = renderText(() => designTriagePrompt("base"))

package/src/workflows/text.ts

@@ -3,12 +3,14 @@ import {
   codeThreads,
   env,
   head,
+  accessFor,
   skillsFor,
   start,
   type AgentOptions,
   type SummaryContext,
 } from "../flows/index.js"
 import {
+  accessPreamble,
   skillsPreamble,
   styleBlock,
   styleFormatContract,
@@ -37,12 +39,16 @@ export const withSkills = (skills: string | undefined, prompt: string): string =
   return `${skillsPreamble.replaceAll("{skills}", skills)}\n\n${prompt}`
 }
 
-/** An `agent()` step whose prompt opens with the preamble naming its scope's skills. */
+/** An `agent()` step whose prompt opens with the preamble naming its scope's skills, then its restricted file access. */
 export const agentWithSkills = (
   name: string,
   prompt: string,
   options: AgentOptions = {},
-): Promise<void> => agent(name, withSkills(skillsFor(name).join(", "), prompt), options)
+): Promise<void> => {
+  const access = accessPreamble(accessFor(name, options.file))
+  const body = access === "" ? prompt : `${access}\n\n${prompt}`
+  return agent(name, withSkills(skillsFor(name).join(", "), body), options)
+}
 
 export const unwindFailure = (commit: string): string =>
   `gtd could not unwind ${commit} out of your working tree.`

package/src/workflows/unified.ts

@@ -33,6 +33,7 @@ import * as t from "./text.js"
 export { threads, type ThreadInfo } from "../flows/index.js"
 export { defaults, envDefaults } from "./vars.js"
 export { skills } from "./skills.js"
+export { access } from "./access.js"
 export { agentWithSkills } from "./text.js"
 export * from "./steps.js"
 export * from "./health.js"