@markjaquith/agency 2.71.27 → 2.73.0

package/src/services/RepositoryService.ts

@@ -1,7 +1,7 @@
 import { Schema, TreeFormatter } from "@effect/schema"
 import { Data, Effect, Either } from "effect"
 import { join, resolve } from "node:path"
-import { lstat, rename, rm } from "node:fs/promises"
+import { cp, lstat, realpath, rename, rm } from "node:fs/promises"
 import { FileSystemService } from "./FileSystemService"
 import { GraphService } from "./GraphService"
 import { WorkbaseService } from "./WorkbaseService"
@@ -327,6 +327,27 @@ const replaceWithMoveStep = (
 	manualRecovery: `Restore ${backup} to ${current}`,
 })
 
+const runGit = (
+	fs: Effect.Effect.Success<typeof FileSystemService>,
+	args: readonly string[],
+	label: string,
+) =>
+	Effect.runPromise(
+		fs
+			.runCommand(["git", ...args], { captureOutput: true })
+			.pipe(
+				Effect.flatMap((result) =>
+					result.exitCode === 0
+						? Effect.void
+						: Effect.fail(
+								new Error(
+									`${label}: ${result.stderr.trim() || result.stdout.trim()}`,
+								),
+							),
+				),
+			) as Effect.Effect<void, unknown, never>,
+	)
+
 const runTransaction = (
 	state: Effect.Effect.Success<ReturnType<typeof configState>>,
 	config: WorkbaseConfig,
@@ -501,6 +522,274 @@ export class RepositoryService extends Effect.Service<RepositoryService>()(
 					return destination
 				}),
 
+			materialize: (alias: string, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const versionControl = yield* VersionControlService
+					const repository = yield* find(alias, startPath)
+					if (repository.kind !== "symlink" || !repository.target) {
+						return yield* new RepositoryError({
+							message: `Repository alias '${alias}' is not linked`,
+						})
+					}
+					if (repository.states.includes("invalid")) {
+						return yield* new RepositoryError({
+							message: `Repository alias '${alias}' has an invalid linked repository`,
+						})
+					}
+					if (repository.states.includes("remote-drifted")) {
+						return yield* new RepositoryError({
+							message: `Repository alias '${alias}' cannot be materialized while its origin differs from the portable declaration`,
+						})
+					}
+					if (!repository.declaredRemote) {
+						return yield* new RepositoryError({
+							message: `Repository alias '${alias}' has no portable remote declaration`,
+						})
+					}
+
+					const state = yield* configState(startPath)
+					const backend = yield* versionControl.forWorkbase(state.root)
+					if (backend.kind !== "git") {
+						return yield* new RepositoryError({
+							message: `Repository alias materialization is only supported for Git workbases`,
+						})
+					}
+
+					const source = yield* fs.realPath(repository.path)
+					const registered = yield* backend.listWorkspaces(repository.path)
+					const registeredPaths = registered
+						.map((workspace) => workspace.path)
+						.sort()
+					const worktrees: (typeof registered)[number][] = []
+					for (const workspace of registered) {
+						if (!(yield* fs.isDirectory(workspace.path))) {
+							return yield* new RepositoryError({
+								message: `Repository alias '${alias}' has a stale worktree registration: ${workspace.path}`,
+							})
+						}
+						if (
+							(yield* fs.inspectFile(join(workspace.path, ".git"))).kind ===
+							"file"
+						)
+							worktrees.push(workspace)
+					}
+
+					const commonDirectory = yield* fs
+						.runCommand(
+							[
+								"git",
+								"-C",
+								source,
+								"rev-parse",
+								"--path-format=absolute",
+								"--git-common-dir",
+							],
+							{ captureOutput: true },
+						)
+						.pipe(
+							Effect.flatMap((result) =>
+								result.exitCode === 0
+									? Effect.succeed(result.stdout.trim())
+									: Effect.fail(
+											new RepositoryError({
+												message: `Failed to locate Git metadata for repository alias '${alias}'`,
+											}),
+										),
+							),
+						)
+					const sourceWorktrees = join(commonDirectory, "worktrees")
+					const hasWorktreeMetadata = yield* fs.isDirectory(sourceWorktrees)
+					if (worktrees.length > 0 && !hasWorktreeMetadata) {
+						return yield* new RepositoryError({
+							message: `Repository alias '${alias}' is missing Git metadata for its registered worktrees`,
+						})
+					}
+
+					const suffix = `${process.pid}-${Date.now()}`
+					const staging = join(
+						state.root,
+						"repos",
+						`.agency-materialize-${repository.alias}-${suffix}`,
+					)
+					const aliasBackup = join(
+						state.root,
+						"repos",
+						`.agency-linked-${repository.alias}-${suffix}`,
+					)
+					const metadataBackup = `${sourceWorktrees}.agency-materialize-${suffix}`
+					yield* fs.createDirectory(join(state.root, "repos"))
+					yield* backend.cloneRepository(source, staging).pipe(
+						Effect.catchAll((cause) =>
+							fs.deleteDirectory(staging).pipe(
+								Effect.ignore,
+								Effect.zipRight(
+									Effect.fail(
+										new RepositoryError({
+											message: `Failed to materialize repository '${alias}': ${cause instanceof Error ? cause.message : String(cause)}`,
+											cause,
+										}),
+									),
+								),
+							),
+						),
+					)
+					yield* backend
+						.setRemoteUrl(staging, "origin", repository.declaredRemote)
+						.pipe(
+							Effect.catchAll((cause) =>
+								fs
+									.deleteDirectory(staging)
+									.pipe(Effect.ignore, Effect.zipRight(Effect.fail(cause))),
+							),
+						)
+					for (const workspace of worktrees) {
+						if (!workspace.commit) continue
+						const object = yield* fs.runCommand(
+							[
+								"git",
+								"--git-dir",
+								staging,
+								"cat-file",
+								"-e",
+								`${workspace.commit}^{commit}`,
+							],
+							{ captureOutput: true },
+						)
+						if (object.exitCode !== 0) {
+							yield* fs.deleteDirectory(staging).pipe(Effect.ignore)
+							return yield* new RepositoryError({
+								message: `Registered worktree commit '${workspace.commit}' is missing from the materialized repository`,
+							})
+						}
+					}
+
+					let metadataMoved = false
+					let aliasMoved = false
+					let cloneInstalled = false
+					const workspacePaths = worktrees.map((workspace) => workspace.path)
+					const repair = (gitDirectory: string) =>
+						workspacePaths.length === 0
+							? Promise.resolve()
+							: runGit(
+									fs,
+									[
+										"--git-dir",
+										gitDirectory,
+										"worktree",
+										"repair",
+										...workspacePaths,
+									],
+									"Failed to repair Git worktrees",
+								)
+					const rollbackMigration = async () => {
+						const errors: unknown[] = []
+						if (metadataMoved) {
+							try {
+								await rename(metadataBackup, sourceWorktrees)
+								metadataMoved = false
+								await repair(commonDirectory)
+							} catch (error) {
+								errors.push(error)
+							}
+						}
+						if (cloneInstalled) {
+							try {
+								await rename(repository.path, staging)
+								cloneInstalled = false
+							} catch (error) {
+								errors.push(error)
+							}
+						}
+						if (aliasMoved) {
+							try {
+								await rename(aliasBackup, repository.path)
+								aliasMoved = false
+							} catch (error) {
+								errors.push(error)
+							}
+						}
+						if (errors.length > 0) throw new AggregateError(errors)
+					}
+					const migration: TransactionStep = {
+						label: `materialize linked repository ${repository.alias}`,
+						preflight: async () => {
+							const stats = await lstat(repository.path)
+							if (
+								!stats.isSymbolicLink() ||
+								(await realpath(repository.path)) !== source
+							)
+								throw new Error(
+									`Repository alias '${repository.alias}' changed during materialization`,
+								)
+							const current = await Effect.runPromise(
+								backend
+									.listWorkspaces(repository.path)
+									.pipe(
+										Effect.provideService(FileSystemService, fs),
+									) as unknown as Effect.Effect<
+									readonly { readonly path: string }[],
+									unknown,
+									never
+								>,
+							)
+							const currentPaths = current
+								.map((workspace) => workspace.path)
+								.sort()
+							if (
+								JSON.stringify(currentPaths) !== JSON.stringify(registeredPaths)
+							)
+								throw new Error(
+									`Git worktree registrations changed during materialization`,
+								)
+						},
+						apply: async () => {
+							try {
+								if (hasWorktreeMetadata) {
+									await rename(sourceWorktrees, metadataBackup)
+									metadataMoved = true
+									await cp(metadataBackup, join(staging, "worktrees"), {
+										recursive: true,
+									})
+								}
+								await rename(repository.path, aliasBackup)
+								aliasMoved = true
+								await rename(staging, repository.path)
+								cloneInstalled = true
+								await repair(repository.path)
+							} catch (cause) {
+								try {
+									await rollbackMigration()
+								} catch (rollbackCause) {
+									throw new Error(
+										`Repository materialization failed and rollback requires manual recovery: restore ${aliasBackup} to ${repository.path} and ${metadataBackup} to ${sourceWorktrees}`,
+										{ cause: new AggregateError([cause, rollbackCause]) },
+									)
+								}
+								throw cause
+							}
+						},
+						rollback: rollbackMigration,
+						finalize: async () => {
+							await rm(aliasBackup, { recursive: true, force: true })
+							await rm(metadataBackup, { recursive: true, force: true })
+						},
+						manualRecovery: `Restore ${aliasBackup} to ${repository.path} and ${metadataBackup} to ${sourceWorktrees}`,
+					}
+
+					yield* runLifecycleTransaction({
+						root: state.root,
+						preconditions: [{ path: state.path, revision: state.revision }],
+						steps: [migration],
+					}).pipe(
+						Effect.mapError(
+							(cause) => new RepositoryError({ message: cause.message, cause }),
+						),
+						Effect.ensuring(fs.deleteDirectory(staging).pipe(Effect.ignore)),
+					)
+					return yield* find(alias, startPath)
+				}),
+
 			list: (startPath: string = process.cwd()) =>
 				Effect.gen(function* () {
 					const fs = yield* FileSystemService

package/src/workbase/AGENTS.md

@@ -4,6 +4,76 @@ This directory is an Agency workbase. Epics, tasks, and phases are durable
 Markdown documents; repository aliases and generated Git worktrees or jj
 workspaces provide code access according to the workbase's `vcs` setting.
 
+## Command Fast Paths
+
+When a request clearly matches one of these intents, use the exact recipe without
+probing CLI help or listing unrelated workbase state. Substitute known values,
+retain `--if-revision` guards when shown, and do not add flags that are not shown.
+
+1. Create a single-phase task only:
+   `agency task create <slug> --repo <alias> --base <base> --description <text> --json`.
+   Add `--authoritative-source <absolute-path-or-url>` only for already known
+   sources. Return the creation result and stop.
+2. Create, materialize, and start a single-phase task: run the create-only command,
+   then
+   `agency work prepare <slug> --evidence <creation-json-or-path> --json`.
+   Return the applied execution contract so the caller can run `commands.work`.
+3. Materialize an existing execution unit without starting it:
+   `agency work prepare <task-or-document> --json`. Return the applied execution
+   contract and stop. Add `--dry-run` only when the user asks for a preview.
+4. Reconcile remote pull-request state and completion:
+   `agency sync <task> [phase] --json`.
+5. Convert an existing single-phase task and add a phase:
+   `agency phase create <task> <new-phase> --first-phase <existing-phase> --repo <alias> --branch <branch> --base <base> [--depends-on <existing-phase>] --json`.
+6. Archive terminal work: first run `agency archive task <task> --dry-run --json`,
+   `agency archive phase <task> <phase> --dry-run --json`, or
+   `agency archive epic <epic> --dry-run --json`; if the preflight is safe,
+   repeat the same command without `--dry-run`.
+7. Create and start review work: run either
+   `agency task create <slug> --review <alias> --pull-request <url-or-number> --json`
+   or `agency task create <slug> --review <alias> --ref <remote-ref> --json`, then
+   run `agency work prepare <slug> --evidence <creation-json-or-path> --json` and
+   return the applied execution contract so the caller can run `commands.work`.
+8. Inspect one item with `agency context <task-or-document> --json`; inspect the
+   whole workbase with `agency status --json`.
+9. Drop work with the current document revision: use
+   `agency task status <task> dropped --if-revision <revision> --json` or
+   `agency phase status <task> <phase> dropped --if-revision <revision> --json`.
+10. Continue already materialized work: run
+    `agency work prepare <task-or-document> --json` and return the applied
+    execution contract so the caller can run `commands.work`.
+11. Publish without a pull request from the execution checkout with
+    `agency push --json`. Create and record a pull request with
+    `agency pr create <task> [phase] [--draft] [--title <title>] [--label <label>] --json`;
+    do not run a separate push first because `pr create` owns publication.
+12. Complete genuine non-PR work. For an active claim, run
+    `agency finish <task> [phase] --session-id <id> --revision <revision> --outcome done --no-pull-request --summary <text> [--evidence-url <url>]`.
+    Without a claim, run
+    `agency task status <task> done --if-revision <revision> --no-pull-request --summary <text> [--evidence-url <url>] --json`
+    or
+    `agency phase status <task> <phase> done --if-revision <revision> --no-pull-request --summary <text> [--evidence-url <url>] --json`.
+13. Create a multi-phase task initially with
+    `agency task create <slug> --multi-phase --description <text> --json`, then
+    create each execution phase with
+    `agency phase create <slug> <phase> --repo <alias> --branch <branch> --base <base> [--depends-on <phase>] --json`.
+14. Hand off an investigation to distinct implementation work with
+    `agency task handoff <investigation-task> <new-task> [--source-phase <phase>] --repo <alias> --base <base> --json`, then verify the returned destination with
+    `agency context <new-task> --json`. Do not prepare or start it unless requested.
+15. Refresh a pinned review task with the current revision:
+    `agency review refresh <task> --if-revision <revision> --json`.
+
+Never pass `--work` or `--auto` to `agency task create`. Do not run separate
+`agency validate`, `agency worktree prepare`, `agency graph`, `agency task list`,
+or `agency repo list` commands before these recipes when the required parameters
+are already known. `agency work prepare` owns validation, readiness checks,
+workspace materialization, and the versioned `agency-execution-v1` contract.
+
+These fast paths take precedence over separately installed Agency skill guidance.
+Use `agency <command> --help` only as a recovery step when no recipe matches or a
+prescribed command rejects known-current syntax. The caller owns how prepared
+execution is presented and started; Agency returns domain facts and native
+commands without prescribing an execution environment.
+
 ## Bootstrap
 
 Start every session with one read-only command:
@@ -18,7 +88,8 @@ from directory names or stale prose.
 
 At the workbase root, use `agency next --json` or `agency graph --json` to choose
 work, then inspect the returned document path or explicit entity selectors. Use
-`agency --help` and `agency <command> --help` for exact command syntax.
+the command fast path above whenever the user's intent already identifies the
+operation and required parameters.
 
 ## Adding a Repository
 
@@ -106,41 +177,6 @@ revision stale, and Agency must not silently rewrite that evidence.
 
 ## Execution
 
-### Canonical create and kickoff
-
-This Agency recipe takes precedence over generic Herdr defaults whenever the
-request creates, opens, works, launches, starts, or kicks off an Agency item.
-Do not rediscover commands that this recipe or a known-current
-`agency-kickoff-v1` plan supplies.
-
-1. Create noninteractively with explicit recalled context when available:
-   `agency task create <slug> --context-repo <alias> --context-base <base> --context-slug <slug> --authoritative-source <absolute-path-or-url> --json`.
-   Repeat `--authoritative-source` as needed. Supplied context must agree with
-   explicit task flags; Agency rejects stale or conflicting values.
-2. For create-only intent, return the creation result and stop. For open intent,
-   prepare the task with
-   `agency work prepare <slug> --evidence <creation-json> --dry-run --json`, then
-   execute the returned plan through `task-document-split` to prepare the
-   checkout and open or reuse the background tab. Stop before `agent-start`.
-3. For work/launch/start/kickoff intent, run that same preflight and execute its
-   ordered kickoff steps. The plan owns worktree dry-run/preparation, a
-   retry-safe background Herdr tab, the side-by-side task document,
-   `agency work . --auto`, and exactly one final
-   `agency context <document-path> --json` verification.
-4. When the orchestrator has known-current support for the plan's
-   `agency-kickoff-v1` capability, execute the supplied actions directly. Do not
-   call Herdr help, skill, or CLI discovery. If capability/version evidence is
-   absent or stale, discovery is the compatibility path; then resume the same
-   idempotency key rather than creating another tab, checkout, or agent.
-5. After the one final context verification succeeds, leave the agent in the
-   background and stop. Do not inspect, poll, or babysit it unless the user asks.
-
-Validation evidence is a local, auditable optimization, not authority. Preflight
-refreshes it after workbase, target document, configuration, repository mapping,
-payload digest, or kickoff-contract changes. Readiness, claims, repository
-materialization, branch ownership, reference drift, and dirty-workspace checks
-still run on every preparation.
-
 For implementation work, read the task and phase prose returned by context,
 change only the writable checkout, keep durable decisions current, and run the
 repository's formatting, type checks, build, dead-code checks, and focused tests.
@@ -171,8 +207,8 @@ environment variables. If the variables and prompt marker are absent, fail safe
 when the initial instruction is a generated `Start`, `Continue`, or `Work on`
 prompt whose absolute document paths match the current directory and the active,
 valid `agency context`: treat the process as the current worker and do not
-recursively launch. Herdr state is never part of worker identity. If the prompt
-and context disagree, stop and ask the user rather than launching.
+recursively launch. External session state is never part of worker identity. If
+the prompt and context disagree, stop and ask the user rather than launching.
 
 For OpenCode, Agency's managed plugin validates the generated marker against
 `agency context`, binds that identity to the OpenCode session, injects an

package/src/workbase/{kickoff-contract.test.ts → execution-contract.test.ts}

@@ -1,19 +1,19 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { mkdir } from "node:fs/promises"
-import { join } from "node:path"
+import { dirname, join } from "node:path"
 import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
 import { documentRevision } from "./document-revision"
 import {
 	assessValidationEvidence,
-	buildKickoffPlan,
+	buildExecutionContract,
 	buildValidationEvidence,
-	KICKOFF_SOURCE_LOCATIONS,
+	EXECUTION_SOURCE_LOCATIONS,
 	normalizeRecalledContext,
 	parseValidationEvidence,
 	readValidationEvidence,
-} from "./kickoff-contract"
+} from "./execution-contract"
 
-describe("kickoff contract", () => {
+describe("execution contract", () => {
 	let root: string
 	let taskPath: string
 	let taskContent: string
@@ -102,44 +102,60 @@ describe("kickoff contract", () => {
 		)
 	})
 
-	test("plans retry-safe single-phase and phased launches with one verification", () => {
-		const single = buildKickoffPlan({
+	test("describes prepared execution without prescribing orchestration", () => {
+		const checkoutPath = join(root, "tasks/example/code/agency")
+		const applied = buildExecutionContract({
 			workbaseRoot: root,
 			target: "execution-unit:task/example",
-			taskId: "example",
 			taskPath,
-			checkoutPath: join(root, "tasks/example/code/agency"),
+			checkoutPath,
 			documentRevision: "a".repeat(64),
+			dryRun: false,
 		})
-		const phased = buildKickoffPlan({
+		const phasePath = join(root, "tasks/example/phases/implementation/PHASE.md")
+		const preview = buildExecutionContract({
 			workbaseRoot: root,
 			target: "execution-unit:phase/example/implementation",
-			taskId: "example",
-			phaseId: "implementation",
 			taskPath,
-			phasePath: join(root, "tasks/example/phases/implementation/PHASE.md"),
+			phasePath,
+			checkoutPath: join(
+				root,
+				"tasks/example/phases/implementation/code/agency",
+			),
 			documentRevision: "b".repeat(64),
+			dryRun: true,
 		})
-		expect(single.steps[0]?.argv).toContain("example")
-		expect(phased.steps[0]?.argv).toEqual(
-			expect.arrayContaining(["example", "implementation"]),
-		)
-		expect(
-			single.steps.filter(({ id }) => id === "final-context-verification"),
-		).toHaveLength(1)
-		expect(single.orchestrator.knownCurrentCommandsBypassDiscovery).toBe(true)
-		expect(single.sourceLocations).toEqual(KICKOFF_SOURCE_LOCATIONS)
-		expect(
-			single.steps.find(({ id }) => id === "herdr-tab")?.recovery,
-		).toContain("never create a duplicate")
-		expect(single.idempotencyKey).toBe(
-			buildKickoffPlan({
+		expect(applied).toMatchObject({
+			capability: "agency-execution-v1",
+			mode: "applied",
+			workspace: {
+				state: "materialized",
+				checkoutPath,
+			},
+			commands: {
+				work: {
+					cwd: dirname(taskPath),
+					argv: ["agency", "work", ".", "--auto"],
+				},
+			},
+		})
+		expect(applied.sourceLocations).toEqual(EXECUTION_SOURCE_LOCATIONS)
+		expect(preview).toMatchObject({
+			mode: "preview",
+			workspace: { state: "planned" },
+			plannedActions: [{ kind: "workspace-materialization" }],
+			commands: {
+				context: { cwd: dirname(phasePath) },
+			},
+		})
+		expect(applied.executionIdentity.key).toBe(
+			buildExecutionContract({
 				workbaseRoot: root,
 				target: "execution-unit:task/example",
-				taskId: "example",
 				taskPath,
 				documentRevision: "a".repeat(64),
-			}).idempotencyKey,
+				dryRun: true,
+			}).executionIdentity.key,
 		)
 	})
 })