@markjaquith/agency 2.48.0 → 2.49.0

package/README.md

@@ -53,7 +53,6 @@ workbase/
   .opencode/
     opencode.jsonc         # managed @agency subagent, instructions, and reference
     tui.jsonc              # managed TUI plugin registration
-    command/agency.md      # managed /agency workflow command
     plugin/agency-repository-skills.ts # managed workbase access and checkout skills
     tui/agency-debug.ts    # managed /agency-debug TUI diagnostic
   agency.json              # tracked config and portable repository declarations
@@ -84,10 +83,11 @@ workbase/
 
 Agency keeps discovery and other observational commands read-only. Run
 `agency integration status` to inspect `.agency/AGENTS.md` and
-`.opencode/opencode.jsonc`, `.opencode/tui.jsonc`, and their managed command and
-plugin files, then `agency integration sync` to create missing files or refresh
+`.opencode/opencode.jsonc`, `.opencode/tui.jsonc`, and their managed plugin
+files, then `agency integration sync` to create missing files or refresh
 checksum-safe managed files. Customized files are reported but never
-overwritten. The root
+overwritten. Sync also removes checksum-valid retired managed artifacts while
+preserving customized files at their former paths. The root
 `AGENTS.md` is user-owned and is not inspected or modified by Agency.
 
 The managed `.agency/AGENTS.md` is the complete in-workbase operating contract
@@ -122,13 +122,6 @@ The plugin grants whole-workbase access dynamically, while the portable
 reference advertises that context to agents. Bash and Agency operations must
 still follow the write authority reported by `agency context`.
 
-OpenCode also discovers a managed `/agency` command. Use `/agency status` for a
-read-only current-work summary, `/agency start [target]` to begin or resume work
-in the active session, `/agency next` to inspect ready work, `/agency validate`
-to check the workbase, and `/agency finish [target]` for verified closeout. The
-command uses OpenCode positional arguments internally and defaults to the safe
-`status` workflow when no subcommand is supplied.
-
 Repository aliases and canonical fetch remotes are declared in tracked
 `agency.json`; local bare clones and symlinks remain ignored under
 `repos/{alias}`. A declaration contains no local path, symlink target, checkout,
@@ -617,7 +610,8 @@ Inspect tasks:
 ```text
 agency task list [filters] [--json]
 agency task show <id> [--json]
-agency task status <id> <open|working|dropped> [--json]
+agency task status <id> <open|working|done|dropped>
+  [--no-pull-request --summary <text> [--evidence-url <url>]] [--json]
 agency task update <id> [metadata options] [--json]
 agency task rename <id> <new-id> [--json]
 agency task move <id> (--epic <epic-id> | --no-epic) [--json]
@@ -656,7 +650,8 @@ agency phase create <task-id> <phase-id>
 
 agency phase list <task-id> [filters] [--json]
 agency phase show <task-id> <phase-id> [--json]
-agency phase status <task-id> <phase-id> <open|working|dropped> [--json]
+agency phase status <task-id> <phase-id> <open|working|done|dropped>
+  [--no-pull-request --summary <text> [--evidence-url <url>]] [--json]
 agency phase update <task-id> <phase-id> [metadata options] [--json]
 agency phase rename <task-id> <phase-id> <new-id> [--json]
 agency phase dependency <add|remove> <task-id> <phase-id> <dependency-id>
@@ -679,8 +674,12 @@ writing anything.
 Single-phase tasks and phases store status in YAML. New execution units start
 `open`, and `agency work` marks the selected execution unit `working` immediately
 before launch. Running `agency work` again can relaunch unclaimed `working` work.
-The `done` status is reserved for an authoritative merged pull request and is
-applied by `agency sync --apply`, not by task or phase status commands.
+By default, `done` requires an authoritative merged pull request and is applied
+by `agency sync --apply`. Work whose intended outcome genuinely requires no pull
+request may instead use an explicit `--no-pull-request --summary <text>` status
+transition. Agency records the summary, completion time, and optional evidence
+URL durably; reopening removes that evidence. This exceptional path refuses work
+that already has a recorded pull request.
 Use explicit claims only when an external orchestrator needs coordinated
 ownership. The interactive work selector displays status markers before
 execution units. Existing working and delegated work may be released to `open`
@@ -711,15 +710,19 @@ agency claim <task-id> [phase-id] --claimant <id> --runner <id>
 agency release <task-id> [phase-id] --session-id <id>
   --revision <sha256> [--json]
 agency finish <task-id> [phase-id] --session-id <id>
-  --revision <sha256> --outcome <done|dropped> [--json]
+  --revision <sha256> --outcome <done|dropped>
+  [--no-pull-request --summary <text> [--evidence-url <url>]] [--json]
 ```
 
 An active claim sets status to `working`. Release returns it to `open`. Finish
 records the claim outcome and ownership history; a `done` claim outcome leaves
 the execution unit `working` until its pull request is merged, while `dropped`
-remains terminal. Conflicts return the current revision and complete ownership
-record in the machine error envelope rather than overwriting it. Expired claims
-may be replaced with a revision-guarded claim.
+remains terminal. For a genuine non-PR outcome, `--no-pull-request` atomically
+records completion evidence, finishes the claim, and sets the execution unit to
+`done`; `--summary` is required and `--evidence-url` is optional. Conflicts return
+the current revision and complete ownership record in the machine error envelope
+rather than overwriting it. Expired claims may be replaced with a
+revision-guarded claim.
 
 `agency work` does not claim execution units. It refuses active explicit claims,
 marks open execution work `working`, and launches the runner. External

package/cli.ts

@@ -205,6 +205,9 @@ const commands: Record<string, Command> = {
 					sessionId: options["session-id"],
 					revision: options.revision,
 					outcome: options.outcome,
+					noPullRequest: options["no-pull-request"],
+					summary: options.summary,
+					evidenceUrl: options["evidence-url"],
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
@@ -298,6 +301,9 @@ const commands: Record<string, Command> = {
 					clearReferences: options["clear-references"],
 					prUrl: options["pr-url"],
 					clearPr: options["clear-pr"],
+					noPullRequest: options["no-pull-request"],
+					summary: options.summary,
+					evidenceUrl: options["evidence-url"],
 					ifRevision: options["if-revision"],
 					dependsOn: options["depends-on"],
 					firstPhase: options["first-phase"],
@@ -449,6 +455,9 @@ const commands: Record<string, Command> = {
 					clearReferences: options["clear-references"],
 					prUrl: options["pr-url"],
 					clearPr: options["clear-pr"],
+					noPullRequest: options["no-pull-request"],
+					summary: options.summary,
+					evidenceUrl: options["evidence-url"],
 					ifRevision: options["if-revision"],
 					noEpic: options["no-epic"],
 					multiPhase: options["multi-phase"],

package/package.json

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

package/src/cli-parser.test.ts

@@ -362,6 +362,64 @@ describe("strict CLI parsing", () => {
 				"working",
 			]),
 		).toThrow("must be 'done' or 'dropped'")
+		expect(
+			parseCli([
+				"finish",
+				"task",
+				"--session-id",
+				"job-1",
+				"--revision",
+				revision,
+				"--outcome",
+				"done",
+				"--no-pull-request",
+				"--summary",
+				"Investigation completed",
+				"--evidence-url",
+				"https://example.com/result",
+			]),
+		).toMatchObject({
+			values: {
+				"no-pull-request": true,
+				summary: "Investigation completed",
+				"evidence-url": "https://example.com/result",
+			},
+		})
+		expect(() =>
+			parseCli([
+				"finish",
+				"task",
+				"--session-id",
+				"job-1",
+				"--revision",
+				revision,
+				"--outcome",
+				"done",
+				"--no-pull-request",
+			]),
+		).toThrow("--summary' is required")
+		expect(() =>
+			parseCli([
+				"task",
+				"status",
+				"example",
+				"working",
+				"--no-pull-request",
+				"--summary",
+				"Not done",
+			]),
+		).toThrow("valid only with a done status")
+		expect(() =>
+			parseCli([
+				"phase",
+				"status",
+				"task",
+				"phase",
+				"done",
+				"--summary",
+				"Missing explicit flag",
+			]),
+		).toThrow("require '--no-pull-request'")
 	})
 
 	test("accepts valid mutation revisions and rejects malformed hashes", () => {

package/src/cli-parser.ts

@@ -120,6 +120,12 @@ const ownedClaimOptions = {
 	revision: { type: "string" },
 } satisfies OptionConfig
 
+const nonPrCompletionOptions = {
+	"no-pull-request": { type: "boolean" },
+	summary: { type: "string" },
+	"evidence-url": { type: "string" },
+} satisfies OptionConfig
+
 const commands = {
 	init: {
 		usage: "agency init [path] [--json]",
@@ -360,6 +366,7 @@ const commands = {
 			...newWorkOptions,
 			...viewOptions,
 			...mutationOptions,
+			...nonPrCompletionOptions,
 			"pr-url": { type: "string" },
 			task: { type: "string" },
 		},
@@ -417,10 +424,10 @@ const commands = {
 				options: ["json", "task"],
 			},
 			status: {
-				usage: "agency task status <id> <status> [--json]",
+				usage: "agency task status <id> <status> [options] [--json]",
 				minArgs: 2,
 				maxArgs: 2,
-				options: ["json", "task"],
+				options: ["json", "task", "no-pull-request", "summary", "evidence-url"],
 			},
 			update: {
 				usage: "agency task update <id> [options] [--json]",
@@ -479,6 +486,7 @@ const commands = {
 			...newWorkOptions,
 			...viewOptions,
 			...mutationOptions,
+			...nonPrCompletionOptions,
 			"pr-url": { type: "string" },
 			task: { type: "string" },
 			phase: { type: "string" },
@@ -542,10 +550,18 @@ const commands = {
 				options: ["json", "task", "phase"],
 			},
 			status: {
-				usage: "agency phase status <task-id> <phase-id> <status> [--json]",
+				usage:
+					"agency phase status <task-id> <phase-id> <status> [options] [--json]",
 				minArgs: 3,
 				maxArgs: 3,
-				options: ["json", "task", "phase"],
+				options: [
+					"json",
+					"task",
+					"phase",
+					"no-pull-request",
+					"summary",
+					"evidence-url",
+				],
 			},
 			update: {
 				usage: "agency phase update <task-id> <phase-id> [options] [--json]",
@@ -631,16 +647,27 @@ const commands = {
 		usage: "agency finish <task-id> [phase-id] [options]",
 		options: {
 			...ownedClaimOptions,
+			...nonPrCompletionOptions,
 			outcome: { type: "string" },
 			task: { type: "string" },
 			phase: { type: "string" },
 		},
 		command: {
 			usage:
-				"agency finish <task-id> [phase-id] --session-id <id> --revision <sha256> --outcome <done|dropped> [--json]",
+				"agency finish <task-id> [phase-id] --session-id <id> --revision <sha256> --outcome <done|dropped> [options] [--json]",
 			minArgs: 1,
 			maxArgs: 2,
-			options: ["session-id", "revision", "outcome", "json", "task", "phase"],
+			options: [
+				"session-id",
+				"revision",
+				"outcome",
+				"no-pull-request",
+				"summary",
+				"evidence-url",
+				"json",
+				"task",
+				"phase",
+			],
 			required: ["session-id", "revision", "outcome"],
 		},
 	},
@@ -1409,6 +1436,40 @@ export function parseCli(args: readonly string[]): ParsedCli {
 			spec.usage,
 		)
 	}
+	const nonPrCompletion = parsed.values["no-pull-request"] === true
+	const completionSummary = parsed.values.summary
+	const completionEvidenceUrl = parsed.values["evidence-url"]
+	if (
+		(completionSummary !== undefined || completionEvidenceUrl !== undefined) &&
+		!nonPrCompletion
+	) {
+		throw usageError(
+			"Options '--summary' and '--evidence-url' require '--no-pull-request'.",
+			spec.usage,
+		)
+	}
+	if (nonPrCompletion) {
+		if (
+			typeof completionSummary !== "string" ||
+			completionSummary.trim().length === 0
+		) {
+			throw usageError(
+				"Option '--summary' is required with '--no-pull-request'.",
+				spec.usage,
+			)
+		}
+		const completesDone =
+			(commandName === "finish" && parsed.values.outcome === "done") ||
+			(["task", "phase"].includes(commandName) &&
+				subcommand === "status" &&
+				commandPositionals.at(-1) === "done")
+		if (!completesDone) {
+			throw usageError(
+				"Option '--no-pull-request' is valid only with a done status or outcome.",
+				spec.usage,
+			)
+		}
+	}
 	if (commandName === "work") {
 		const preparing = commandPositionals[0] === "prepare"
 		if (

package/src/cli.test.ts

@@ -248,6 +248,77 @@ describe("CLI", () => {
 			parseJson(await runCli(["task", "show", "claimed", "--json"], root)).data
 				.status,
 		).toBe("working")
+
+		parseJson(
+			await runCli(
+				["task", "create", "non-pr", "--repo", "agency", "--json"],
+				root,
+			),
+		)
+		const nonPrContext = parseJson(
+			await runCli(["context", "tasks/non-pr", "--json"], root),
+		)
+		const nonPrClaim = parseJson(
+			await runCli(
+				[
+					"claim",
+					"non-pr",
+					"--claimant",
+					"orchestrator",
+					"--runner",
+					"agent",
+					"--session-id",
+					"job-2",
+					"--revision",
+					nonPrContext.documents.task.sha256,
+					"--json",
+				],
+				root,
+			),
+		)
+		parseJson(
+			await runCli(
+				[
+					"finish",
+					"non-pr",
+					"--session-id",
+					"job-2",
+					"--revision",
+					nonPrClaim.revision,
+					"--outcome",
+					"done",
+					"--no-pull-request",
+					"--summary",
+					"Investigation completed without changes.",
+					"--evidence-url",
+					"https://example.com/result",
+					"--json",
+				],
+				root,
+			),
+		)
+		expect(
+			parseJson(await runCli(["task", "show", "non-pr", "--json"], root)).data,
+		).toMatchObject({
+			status: "done",
+			completion: {
+				mode: "non-pr",
+				summary: "Investigation completed without changes.",
+				evidenceUrl: "https://example.com/result",
+			},
+		})
+		const prUpdate = await runCli(
+			[
+				"task",
+				"update",
+				"non-pr",
+				"--pr-url",
+				"https://github.com/example/agency/pull/1",
+			],
+			root,
+		)
+		expect(prUpdate.exitCode).toBe(1)
+		expect(prUpdate.stderr).toContain("Reopen non-PR completed work")
 	})
 
 	test("routes graph mutations through structured output", async () => {
@@ -526,7 +597,6 @@ describe("CLI", () => {
 		expect(before.files).toMatchObject([
 			{ name: "agents", state: "managed" },
 			{ name: "opencode", state: "managed" },
-			{ name: "opencode-command", state: "managed" },
 			{ name: "opencode-plugin", state: "managed" },
 			{ name: "opencode-tui", state: "managed" },
 			{ name: "opencode-tui-plugin", state: "managed" },
@@ -538,7 +608,6 @@ describe("CLI", () => {
 		expect(synced.files).toMatchObject([
 			{ name: "agents", state: "managed", changed: false },
 			{ name: "opencode", state: "managed", changed: false },
-			{ name: "opencode-command", state: "managed", changed: false },
 			{ name: "opencode-plugin", state: "managed", changed: false },
 			{ name: "opencode-tui", state: "managed", changed: false },
 			{ name: "opencode-tui-plugin", state: "managed", changed: false },
@@ -1022,7 +1091,7 @@ status: open
 				},
 				{
 					args: ["--task", "pipeline", "--phase", "build"],
-					cwd: join(workbaseRoot, "tasks/pipeline"),
+					cwd: join(workbaseRoot, "tasks/pipeline/phases/build"),
 					checkoutPath: join(
 						workbaseRoot,
 						"tasks/pipeline/phases/build/code/agency",
@@ -1060,6 +1129,16 @@ status: open
 					launch.checkoutPath,
 				)
 				expect(contract.environment.OPENCODE_CONFIG_CONTENT).toBeUndefined()
+				if (launch === launches[1]) {
+					const context = parseJson(
+						await runCli(["context", ".", "--json"], contract.cwd),
+					)
+					expect(context.target).toMatchObject({
+						kind: "phase",
+						taskId: "pipeline",
+						phaseId: "build",
+					})
+				}
 				const environment = {
 					...process.env,
 					...contract.environment,

package/src/commands/claim.ts

@@ -13,6 +13,9 @@ interface ClaimCommandOptions extends BaseCommandOptions {
 	readonly revision?: string
 	readonly expiresAt?: string
 	readonly outcome?: string
+	readonly noPullRequest?: boolean
+	readonly summary?: string
+	readonly evidenceUrl?: string
 	readonly json?: boolean
 }
 
@@ -32,6 +35,16 @@ export const claimCommand = (options: ClaimCommandOptions) =>
 				new Error("Claimant and runner identities are required"),
 			)
 		}
+		if (options.noPullRequest && !options.summary?.trim()) {
+			return yield* Effect.fail(
+				new Error("Non-PR completion requires a non-empty summary"),
+			)
+		}
+		if (options.noPullRequest && options.outcome !== "done") {
+			return yield* Effect.fail(
+				new Error("Non-PR completion is valid only with a done outcome"),
+			)
+		}
 		if (
 			options.operation === "finish" &&
 			options.outcome !== "done" &&
@@ -65,6 +78,16 @@ export const claimCommand = (options: ClaimCommandOptions) =>
 							{
 								...common,
 								outcome: options.outcome as "done" | "dropped",
+								...(options.noPullRequest
+									? {
+											nonPrCompletion: {
+												summary: options.summary!,
+												...(options.evidenceUrl
+													? { evidenceUrl: options.evidenceUrl }
+													: {}),
+											},
+										}
+									: {}),
 							},
 							cwd,
 						)
@@ -91,8 +114,9 @@ Release an execution unit owned by the session.
 `
 
 export const finishHelp = `
-Usage: agency finish <task-id> [phase-id] --session-id <id> --revision <sha256> --outcome <done|dropped>
+Usage: agency finish <task-id> [phase-id] --session-id <id> --revision <sha256> --outcome <done|dropped> [--no-pull-request --summary <text> [--evidence-url <url>]]
 
 Finish a claim owned by the session. A done claim outcome leaves unmerged work
-working; agency sync --apply marks the execution unit done after merge.
+working; agency sync --apply marks the execution unit done after merge. Use
+--no-pull-request with a summary for an explicit non-PR completion.
 `

package/src/commands/init.test.ts

@@ -68,11 +68,9 @@ describe("init command", () => {
 			workbase: expect.objectContaining({ path: ".." }),
 		})
 		expect(config.permission).toBeUndefined()
-		const command = await Bun.file(
-			join(root, ".opencode/command/agency.md"),
-		).text()
-		expect(command).toContain("Workflow: `$1`")
-		expect(command).toContain("Optional target: `$2`")
+		expect(
+			await Bun.file(join(root, ".opencode/command/agency.md")).exists(),
+		).toBe(false)
 		const plugin = await Bun.file(
 			join(root, ".opencode/plugin/agency-repository-skills.ts"),
 		).text()

package/src/commands/integration.test.ts

@@ -36,11 +36,6 @@ describe("integration command", () => {
 					diagnostic: expect.stringContaining("cannot load"),
 					remediation: expect.stringContaining("integration sync"),
 				},
-				{
-					name: "opencode-command",
-					state: "missing",
-					remediation: expect.stringContaining("integration sync"),
-				},
 				{
 					name: "opencode-plugin",
 					state: "missing",
@@ -91,11 +86,6 @@ OpenCode config: missing
   Agency OpenCode launches cannot load current Agency instructions or whole-workbase access.
   Action: Run 'agency integration sync' to install Agency instructions and whole-workbase OpenCode access.
 
-OpenCode /agency command: missing
-  Path: .opencode/command/agency.md
-  The managed OpenCode /agency command needs synchronization.
-  Action: Run 'agency integration sync' to install the managed /agency command.
-
 OpenCode workbase plugin: missing
   Path: .opencode/plugin/agency-repository-skills.ts
   The managed OpenCode workbase plugin needs synchronization.
@@ -120,7 +110,6 @@ OpenCode /agency-debug: missing
 		expect(JSON.parse(logs[0]!).files).toMatchObject([
 			{ name: "agents", state: "managed", changed: true },
 			{ name: "opencode", state: "managed", changed: true },
-			{ name: "opencode-command", state: "managed", changed: true },
 			{ name: "opencode-plugin", state: "managed", changed: true },
 			{ name: "opencode-tui", state: "managed", changed: true },
 			{ name: "opencode-tui-plugin", state: "managed", changed: true },
@@ -132,7 +121,7 @@ OpenCode /agency-debug: missing
 		).toBe(true)
 		expect(
 			await Bun.file(join(root, ".opencode/command/agency.md")).exists(),
-		).toBe(true)
+		).toBe(false)
 		expect(
 			await Bun.file(
 				join(root, ".opencode/plugin/agency-repository-skills.ts"),
@@ -161,10 +150,6 @@ OpenCode config: synced
   Path: .opencode/opencode.jsonc
   Agency's managed OpenCode launch config is ready to load Agency instructions and provide whole-workbase read access.
 
-OpenCode /agency command: synced
-  Path: .opencode/command/agency.md
-  Agency's managed OpenCode /agency command is current.
-
 OpenCode workbase plugin: synced
   Path: .opencode/plugin/agency-repository-skills.ts
   Agency's managed OpenCode plugin provides whole-workbase access and exposes writable-checkout skills.

package/src/commands/integration.ts

@@ -15,7 +15,6 @@ interface IntegrationResult {
 		readonly name:
 			| "agents"
 			| "opencode"
-			| "opencode-command"
 			| "opencode-plugin"
 			| "opencode-tui"
 			| "opencode-tui-plugin"
@@ -30,7 +29,6 @@ interface IntegrationResult {
 const integrationNames = {
 	agents: "Agent instructions",
 	opencode: "OpenCode config",
-	"opencode-command": "OpenCode /agency command",
 	"opencode-plugin": "OpenCode workbase plugin",
 	"opencode-tui": "OpenCode TUI config",
 	"opencode-tui-plugin": "OpenCode /agency-debug",

package/src/commands/phase.ts

@@ -31,6 +31,9 @@ interface PhaseOptions extends BaseCommandOptions {
 	readonly pr?: boolean
 	readonly work?: boolean
 	readonly auto?: boolean
+	readonly noPullRequest?: boolean
+	readonly summary?: string
+	readonly evidenceUrl?: string
 }
 
 export const phase = (options: PhaseOptions, work: StartWork = startWork) =>
@@ -166,7 +169,20 @@ export const phase = (options: PhaseOptions, work: StartWork = startWork) =>
 						),
 					)
 				}
-				const record = yield* phases.setStatus(taskId, phaseId, status, cwd)
+				const record = yield* phases.setStatus(
+					taskId,
+					phaseId,
+					status,
+					cwd,
+					options.noPullRequest
+						? {
+								summary: options.summary ?? "",
+								...(options.evidenceUrl
+									? { evidenceUrl: options.evidenceUrl }
+									: {}),
+							}
+						: undefined,
+				)
 				const { content: _, ...output } = record
 				log(
 					options.json
@@ -275,7 +291,7 @@ Subcommands:
   list <task>           List task phases
   show <task> <phase>   Show a phase
   status <task> <phase> <status>
-                        Set open, working, or dropped
+                        Set open, working, dropped, or explicit non-PR done
   update <task> <phase> Update phase metadata
   rename <task> <phase> <new-id>
                         Rename a phase and update dependencies
@@ -285,6 +301,11 @@ Subcommands:
 Mutation option:
   --if-revision <hash>  Require the target's current revision
 
+Non-PR completion options (status done only):
+  --no-pull-request     Complete without a pull request
+  --summary <text>      Required durable outcome summary
+  --evidence-url <url>  Optional supporting record
+
 Create options:
   --description <text>  Short description of the phase
   --repo <alias>        Writable repository