@markjaquith/agency 2.54.4 → 2.56.0

package/README.md

@@ -235,6 +235,56 @@ Supplemental read-only repositories remain detached Git worktrees at their
 declared refs so they do not acquire writable branches. Jj workbases always use
 jj workspaces and ignore this Git-specific customization.
 
+### Post-checkout Commands
+
+Each repository declaration may provide a VCS-neutral `postCheckoutCommand` argv
+template for repository-specific setup. Agency invokes it directly, without a
+shell, with the new checkout as its working directory:
+
+```json
+{
+	"version": 2,
+	"repositories": {
+		"frontend": {
+			"remote": "git@example.com:team/frontend.git",
+			"postCheckoutCommand": ["bun", "install", "--frozen-lockfile"]
+		}
+	}
+}
+```
+
+The hook runs for each newly created managed checkout, including writable and
+reference checkouts, after Git worktree or jj workspace creation has completed
+and Agency has validated the checkout. It does not run for a reused checkout or
+for inspection-only commands. A custom `worktreeCreateCommand` completes and is
+validated before this hook runs.
+
+Available placeholders and matching environment variables are:
+
+| Placeholder        | Environment              | Value                                          |
+| ------------------ | ------------------------ | ---------------------------------------------- |
+| `{repoAlias}`      | `AGENCY_REPO_ALIAS`      | Repository alias                               |
+| `{repositoryPath}` | `AGENCY_REPOSITORY_PATH` | Absolute source repository path under `repos/` |
+| `{checkoutPath}`   | `AGENCY_CHECKOUT_PATH`   | Absolute managed checkout path                 |
+| `{checkoutKind}`   | `AGENCY_CHECKOUT_KIND`   | `writable` or `reference`                      |
+| `{requestedRef}`   | `AGENCY_REQUESTED_REF`   | Requested branch, reference, or review commit  |
+| `{base}`           | `AGENCY_BASE`            | Configured execution base                      |
+| `{vcs}`            | `AGENCY_VCS`             | `git` or `jj`                                  |
+| `{workbaseRoot}`   | `AGENCY_WORKBASE_ROOT`   | Absolute workbase root                         |
+| `{taskId}`         | `AGENCY_TASK_ID`         | Task ID                                        |
+| `{phaseId}`        | `AGENCY_PHASE_ID`        | Phase ID                                       |
+
+`{base}` and `{phaseId}` and their environment variables are empty strings when
+they do not apply. Dry runs report a planned `post-checkout` operation but never
+execute it. Verbose output identifies the repository and expanded command.
+
+Hook success is part of checkout creation. A non-zero exit or failure to start
+rolls back the checkout and any branch created by the same operation; if cleanup
+also fails, Agency reports the exact manual recovery action. A later command
+retries checkout creation and the hook rather than reusing an uninitialized
+checkout. Hook commands should be idempotent so a retry is safe after any
+external effects the failed invocation may have completed.
+
 ### Agent Runners
 
 OpenCode and Claude Code are built-in runner presets. Select either preset or a
@@ -812,12 +862,13 @@ restore preflight all destinations and graph references before changing files.
 Versioned lifecycle provenance preserves parent declarations and dependency edges
 for restoration. Archived IDs are reserved until restored.
 
-### Work and Pull Requests
+### Work, Publication, and Pull Requests
 
 ```text
 agency work [<directory> | --epic <epic-id>] [--runner <name>] [--auto] [--print-command]
 agency work prepare [target] [--dry-run] [--json]
 agency worktree <list|inspect|prepare|remove|rebuild|repair>
+agency push [--json]
 agency pr create <task-id> [phase-id] [--draft] [--force] [--json]
 agency pr [args...]
 ```
@@ -865,6 +916,22 @@ Agency resolves the ref to a commit and creates a detached worktree. Existing
 reference worktrees are reused only while their commit still matches the declared
 ref; use a commit SHA as `ref` when reproducibility matters.
 
+`agency push` publishes the execution unit identified by current Agency context
+without creating a pull request. It requires a valid, registered writable
+checkout in `working` state, fetches the configured delivery remote, verifies
+that the declared base is in the publication history, validates every outgoing
+commit's description, author, and conflict state, and refuses non-fast-forward
+updates.
+
+For Git, YAML `branch` must exactly match the checked-out local branch, the
+worktree must be clean, and `HEAD` is pushed with upstream tracking. For jj, YAML
+`branch` is the authoritative delivery bookmark and need not exist before
+publication. Agency publishes `@` unless it is the canonical empty, undescribed
+post-commit working copy, in which case it publishes `@-`; described empty
+changes remain intentional publication tips. Missing descriptions or authors
+stop with exact change IDs and remediation commands. Agency creates or safely
+advances only the declared bookmark and never invents a `push-*` bookmark.
+
 Task-aware `agency pr create <task-id> [phase-id]` uses Agency's delivery flow,
 including readiness checks and durable PR recording. Other `agency pr`
 invocations forward every argument to `gh pr`. From an execution task or phase

package/cli-main.ts

@@ -6,6 +6,7 @@ import { parseCli } from "./src/cli-parser"
 import { init, help as initHelp } from "./src/commands/init"
 import { task, help as taskHelp } from "./src/commands/task"
 import { pr, prCreate, help as prHelp } from "./src/commands/pr"
+import { push, help as pushHelp } from "./src/commands/push"
 import { work, workPrepare, help as workHelp } from "./src/commands/work"
 import { worktree, help as worktreeHelp } from "./src/commands/worktree"
 import { status, help as statusHelp } from "./src/commands/status"
@@ -34,6 +35,7 @@ import { TaskService } from "./src/services/TaskService"
 import { PhaseService } from "./src/services/PhaseService"
 import { WorktreeService } from "./src/services/WorktreeService"
 import { PullRequestService } from "./src/services/PullRequestService"
+import { PushService } from "./src/services/PushService"
 import { ArchiveService } from "./src/services/ArchiveService"
 import { IntegrationService } from "./src/services/IntegrationService"
 import { ContextService } from "./src/services/ContextService"
@@ -79,6 +81,7 @@ const CliLayer = Layer.mergeAll(
 	PhaseService.Default,
 	WorktreeService.Default,
 	PullRequestService.Default,
+	PushService.Default,
 	ArchiveService.Default,
 	IntegrationService.Default,
 	ContextService.Default,
@@ -305,6 +308,22 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
+	push: {
+		run: async (_args: string[], options: Record<string, any>) => {
+			if (options.help) {
+				console.log(pushHelp)
+				return
+			}
+			await runCommand(
+				push({
+					json: options.json,
+					silent: options.silent,
+					verbose: options.verbose,
+					cwd: options.cwd,
+				}),
+			)
+		},
+	},
 	phase: {
 		run: async (args: string[], options: Record<string, any>) => {
 			if (options.help) return console.log(phaseHelp)
@@ -742,6 +761,7 @@ Commands:
   vcs <subcommand>       Inspect or migrate the version-control backend
   next                   List or select ready execution units
   pr create / pr [...]  Create an Agency PR or run gh pr with repository focus
+  push                   Validate and publish the current execution unit
   review refresh         Explicitly refresh a pinned review task
   repo <subcommand>      Manage workbase repositories
   status                 Show status for the current workbase

package/package.json

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

package/src/cli-parser.test.ts

@@ -616,6 +616,15 @@ describe("strict CLI parsing", () => {
 		).toThrow("cannot be combined")
 	})
 
+	test("parses push without accepting an alternate target", () => {
+		expect(parseCli(["push", "--json"])).toMatchObject({
+			commandName: "push",
+			args: [],
+			values: { json: true },
+		})
+		expectUsageError(["push", "example"], "agency push")
+	})
+
 	test("accepts runner selection and command inspection for work", () => {
 		expect(
 			parseCli([

package/src/cli-parser.ts

@@ -913,6 +913,16 @@ const commands = {
 			},
 		},
 	},
+	push: {
+		usage: "agency push [--json]",
+		options: outputOptions,
+		command: {
+			usage: "agency push [--json]",
+			minArgs: 0,
+			maxArgs: 0,
+			options: ["json"],
+		},
+	},
 	next: {
 		usage: "agency next [--select] [--json]",
 		options: {

package/src/cli.test.ts

@@ -502,6 +502,7 @@ describe("CLI", () => {
 			["archive", "Usage: agency archive"],
 			["restore", "Usage: agency restore"],
 			["work", "Usage: agency work"],
+			["push", "Usage: agency push"],
 			["pr", "Work with GitHub pull requests."],
 			["status", "Usage: agency status"],
 			["validate", "Usage: agency validate"],

package/src/commands/push.ts

@@ -0,0 +1,25 @@
+import { Effect } from "effect"
+import { PushService } from "../services/PushService"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
+
+export const push = (options: BaseCommandOptions = {}) =>
+	Effect.gen(function* () {
+		const publications = yield* PushService
+		const { log } = createLoggers(options)
+		const result = yield* publications.publish(options.cwd ?? process.cwd())
+		log(
+			options.json
+				? JSON.stringify(result, null, 2)
+				: `Published ${result.vcs} ${result.branch} at ${result.tip} to ${result.remote}`,
+		)
+	})
+
+export const help = `
+Usage: agency push [--json]
+
+Validate and publish the current Agency execution unit without creating a pull
+request. The command uses the durable base and branch declarations, requires the
+managed writable checkout and working status, refreshes remote state, validates
+every outgoing commit, and rejects non-fast-forward publication.
+`

package/src/protocol.ts

@@ -99,6 +99,7 @@ const errorMetadata: Readonly<Record<string, ErrorMetadata>> = {
 	},
 	ArchiveError: { code: "ARCHIVE_ERROR", retryable: false },
 	WorktreeError: { code: "WORKTREE_ERROR", retryable: false },
+	PushError: { code: "PUSH_ERROR", retryable: false },
 	PullRequestError: { code: "PULL_REQUEST_ERROR", retryable: false },
 	ReviewError: { code: "REVIEW_ERROR", retryable: false },
 	ContextError: {

package/src/services/DoctorService.ts

@@ -173,6 +173,18 @@ export class DoctorService extends Effect.Service<DoctorService>()(
 									] as const,
 								]
 							: []),
+						...Object.entries(config.repositories ?? {}).flatMap(
+							([alias, repository]) =>
+								repository.postCheckoutCommand
+									? [
+											[
+												`integration.repository.${alias}.post-checkout`,
+												repository.postCheckoutCommand,
+												`Repository '${alias}' post-checkout hook`,
+											] as const,
+										]
+									: [],
+						),
 						...Object.entries(config.runners ?? {}).map(
 							([name, runner]) =>
 								[

package/src/services/IntegrationService.test.ts

@@ -422,6 +422,8 @@ describe("IntegrationService", () => {
 		expect(body).toContain("without creating a claim")
 		expect(body).toContain("formatting, type checks, build, dead-code checks")
 		expect(body).toContain("Review and commit the diff")
+		expect(body).toContain("Use `agency push`")
+		expect(body).toContain("never authors semantic commit descriptions")
 		expect(body).toContain("Run `agency validate`")
 		expect(body).toContain("only with explicit user intent")
 		expect(body).toContain("An execution unit remains `working`")