@markjaquith/agency 2.61.2 → 2.61.3

package/README.md

@@ -527,6 +527,12 @@ and reference authority, local checkout and resolved-commit state, recorded PR
 state, and validation warnings. Only `done` satisfies a dependency; `dropped` is
 terminal but remains a blocker.
 
+`authority.writable` identifies the writable repository checkout, while
+`authority.documents.writable` lists the absolute paths of Agency documents the
+target may maintain. A single-phase task lists its `TASK.md`; a phase lists its
+owning `TASK.md` and active `PHASE.md`; orchestration targets list none. Use
+Agency commands rather than direct edits for structural frontmatter mutations.
+
 Complete output is the default for entity targets. Pass `--compact` explicitly
 to omit document prose and low-level Git details while retaining identity,
 hashes, authority, paths, graph state, materialization state, and validation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.61.2",
+  "version": "2.61.3",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",

package/src/commands/context.test.ts

@@ -208,6 +208,10 @@ Phase prose.
 		expect(result.documents.task.body).toContain("Task prose.")
 		expect(result.documents.phase.body).toContain("Phase prose.")
 		expect(result.documents.phase.sha256).toMatch(/^[a-f0-9]{64}$/)
+		expect(result.authority.documents.writable).toEqual([
+			join(root, "tasks/agent-contract/TASK.md"),
+			join(root, "tasks/agent-contract/phases/context-command/PHASE.md"),
+		])
 		expect(result.workspace.writable.branchCommit).toMatch(/^[a-f0-9]{40}$/)
 		expect(result.workspace.writable.baseCommit).toMatch(/^[a-f0-9]{40}$/)
 		expect(result.workspace.references[0].resolvedCommit).toMatch(
@@ -232,6 +236,10 @@ Phase prose.
 			registered: true,
 		})
 		expect(result.authority.writable.checkoutPath).toContain("code/agency")
+		expect(result.authority.documents.writable).toEqual([
+			join(root, "tasks/agent-contract/TASK.md"),
+			join(root, "tasks/agent-contract/phases/context-command/PHASE.md"),
+		])
 	})
 
 	test("reports dependency and validation blockers deterministically", async () => {
@@ -275,6 +283,12 @@ status: dropped
 			taskId: "agent-contract",
 		})
 		expect(task.graph.parent).toEqual({ kind: "epic", id: "contract" })
+		expect(task.authority.documents.writable).toEqual([])
+
+		const executionTask = await readContext(root, "foundations")
+		expect(executionTask.authority.documents.writable).toEqual([
+			join(root, "tasks/foundations/TASK.md"),
+		])
 
 		const workbase = await readContext(root, ".")
 		expect(workbase).toMatchObject({

package/src/services/ContextService.ts

@@ -784,6 +784,15 @@ export class ContextService extends Effect.Service<ContextService>()(
 							: null
 					const reviewData =
 						task?.data && "review" in task.data ? task.data.review : null
+					const writableDocuments = reviewData
+						? task
+							? [task.path]
+							: []
+						: executionData && task
+							? phase
+								? [task.path, phase.path]
+								: [task.path]
+							: []
 					const references: readonly RepositoryReference[] = reviewData
 						? [{ repo: reviewData.repo, ref: reviewData.commit }]
 						: executionData
@@ -1078,7 +1087,7 @@ export class ContextService extends Effect.Service<ContextService>()(
 								checkoutPath: reference.checkoutPath,
 							})),
 							documents: {
-								writable: reviewData && task ? [task.path] : [],
+								writable: writableDocuments,
 							},
 						},
 						workspace: options.compact

package/src/services/IntegrationService.test.ts

@@ -418,6 +418,7 @@ describe("IntegrationService", () => {
 		expect(body).toContain("agency next --json")
 		expect(body).toContain("agency <command> --help")
 		expect(body).toContain("authority.writable.checkoutPath")
+		expect(body).toContain("authority.documents.writable")
 		expect(body).toContain("Only `done` satisfies a dependency")
 		expect(body).toContain("Require explicit user intent")
 		expect(body).toContain(

package/src/workbase/AGENTS.md

@@ -48,10 +48,11 @@ agency validate --json
 - A single-phase task or phase is an execution unit with one writable `repo` and
   optional read-only `repos`. Only `done` satisfies a dependency; `dropped` is
   terminal but leaves dependents blocked.
-- For an execution unit, write code only at
+- For an execution unit, write repository content only at
   `authority.writable.checkoutPath`. Every `authority.references` checkout is
   read-only, even if filesystem permissions allow writes.
-- Keep task-wide decisions in `TASK.md` and phase-specific delivery context in
+- Maintain only the Agency documents listed in `authority.documents.writable`:
+  keep task-wide decisions in `TASK.md` and phase-specific delivery context in
   `PHASE.md`. Use Agency commands for structural frontmatter mutations.
 
 ## Consent Boundaries