@markjaquith/agency 2.48.1 → 2.49.0

package/src/services/WorkbaseService.ts

@@ -746,6 +746,24 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 						}
 					}
 
+					const validateCompletion = (
+						record: DocumentRecord<TaskData | PhaseData>,
+					) => {
+						if (!("repo" in record.data) || !record.data.completion) return
+						if (record.data.status !== "done") {
+							issue(record.path, "Non-PR completion requires status 'done'")
+						}
+						if (record.data.pr !== null) {
+							issue(
+								record.path,
+								"Non-PR completion cannot have a recorded pull request",
+							)
+						}
+						if (record.data.claim?.state === "active") {
+							issue(record.path, "Completed work cannot have an active claim")
+						}
+					}
+
 					for (const epic of epics.values()) {
 						validateRepositories(epic)
 						const ids = new Set(epic.data.tasks.map((task) => task.id))
@@ -776,6 +794,7 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 					for (const task of tasks.values()) {
 						validateRepositories(task)
 						validateBranchOwnership(task)
+						validateCompletion(task)
 						if (task.data.epic) {
 							const parent = epics.get(task.data.epic)
 							if (!parent) {
@@ -828,6 +847,7 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 					for (const phase of phases.values()) {
 						validateRepositories(phase)
 						validateBranchOwnership(phase)
+						validateCompletion(phase)
 					}
 
 					issues.sort((a, b) =>

package/src/workbase/AGENTS.md

@@ -43,7 +43,8 @@ reason to edit `agency.json` or `repos/` by hand.
 Require explicit user intent before initializing a workbase; changing repository
 aliases or applying repository setup or workbase sync changes; launching another
 agent from an active agent session; creating a pull request; archiving, restoring,
-dropping, or reopening work; or using `--force` to override readiness.
+dropping, reopening, or completing work without a pull request; or using `--force`
+to override readiness.
 
 ## Safety
 
@@ -80,7 +81,9 @@ release the claim with the current document revision.
 An execution unit remains `working` after implementation is committed and while
 its pull request is open. It becomes `done` only after its authoritative pull
 request is merged and Agency reconciles that state. Do not mark committed or
-review-ready work `done` manually.
+review-ready work `done` manually. A genuine investigation, operational action,
+or no-change result may complete without a pull request only with explicit user
+intent, `--no-pull-request`, and a durable outcome summary.
 
 At each closeout trigger (creating or updating a PR, marking it ready, completing
 a refinement loop, or pausing or handing off completed implementation work):
@@ -90,6 +93,8 @@ a refinement loop, or pausing or handing off completed implementation work):
   keep the execution unit `working` through review and merge.
 - After merge, run `agency sync --apply` to reconcile the execution unit to
   `done`.
+- For an approved non-PR outcome, finish an active claim or update unclaimed
+  status with `--no-pull-request --summary <text>` and optional supporting URL.
 - Refresh durable delivery context in `TASK.md` or `PHASE.md`, including recorded
   PR state, current head, diff summary, and verification results after later
   pushes when those details are maintained there.

package/src/workbase/completion.ts

@@ -0,0 +1,28 @@
+import type { CompletionRecord } from "./schemas"
+
+export interface NonPrCompletionInput {
+	readonly summary: string
+	readonly evidenceUrl?: string
+}
+
+export const buildNonPrCompletion = (
+	input: NonPrCompletionInput,
+	now: Date,
+): { readonly value: CompletionRecord } | { readonly error: string } => {
+	const summary = input.summary.trim()
+	if (!summary) return { error: "Non-PR completion summary must not be empty" }
+
+	const evidenceUrl = input.evidenceUrl?.trim()
+	if (evidenceUrl && !/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(evidenceUrl)) {
+		return { error: `Invalid completion evidence URL: ${evidenceUrl}` }
+	}
+
+	return {
+		value: {
+			mode: "non-pr",
+			completedAt: now.toISOString(),
+			summary,
+			...(evidenceUrl ? { evidenceUrl } : {}),
+		},
+	}
+}

package/src/workbase/schemas.ts

@@ -75,6 +75,13 @@ export const PullRequestRecord = Schema.Struct({
 	mergeable: Schema.optional(Schema.NullOr(Schema.Boolean)),
 })
 
+export const CompletionRecord = Schema.Struct({
+	mode: Schema.Literal("non-pr"),
+	completedAt: IsoTimestamp,
+	summary: NonEmptyString,
+	evidenceUrl: Schema.optional(Url),
+})
+
 const DeliveryProvider = Schema.Struct({
 	provider: EntityId,
 	remote: Schema.optional(NonEmptyString),
@@ -141,6 +148,7 @@ const ExecutionUnit = {
 	pr: Schema.NullOr(Schema.Union(GitHubPullRequestUrl, PullRequestRecord)),
 	status: Schema.optionalWith(WorkStatus, { default: () => "open" as const }),
 	claim: Schema.optional(ClaimRecord),
+	completion: Schema.optional(CompletionRecord),
 }
 
 export const EpicFrontmatter = Schema.Struct({
@@ -187,6 +195,7 @@ export type RepositoryDeclaration = Schema.Schema.Type<
 export type WorkStatus = Schema.Schema.Type<typeof WorkStatus>
 export type ClaimRecord = Schema.Schema.Type<typeof ClaimRecord>
 export type PullRequestRecord = Schema.Schema.Type<typeof PullRequestRecord>
+export type CompletionRecord = Schema.Schema.Type<typeof CompletionRecord>
 export type EpicFrontmatter = Schema.Schema.Type<typeof EpicFrontmatter>
 export type TaskFrontmatter = Schema.Schema.Type<typeof TaskFrontmatter>
 export type PhaseFrontmatter = Schema.Schema.Type<typeof PhaseFrontmatter>