erikreinert · Sep 2, 2026 · Sep 2, 2026 · Sep 2, 2026 · Sep 2, 2026 · Sep 2, 2026
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
diff --git a/Makefile b/Makefile
@@ -1,12 +1,38 @@
-.PHONY: build test lint vet install clean demo
+# Developer targets and the gate targets `docket trust list` invokes.
+#
+# The gate targets exist so a trust entry can name `make <gate>` instead of an
+# absolute path into one worktree's checkout. Trust entries are bound to the
+# repository, not the worktree, and the engine spawns each gate with cwd set to
+# the step's worktree — an absolute path pins every worktree's gate to whichever
+# checkout happened to be current when the entry was approved, and goes dead the
+# day that worktree is removed. `make <gate>` resolves against the caller's cwd,
+# so it is correct from every worktree and survives their coming and going.
+#
+# Each gate target's NAME MATCHES ITS TRUST ENTRY NAME exactly, so a workflow's
+# `gates = ["build", "tests"]` reads the same as the Makefile and the same as
+# `docket trust list`. That is why the compile gate owns the name `build` and
+# the binary build is `make bin`.
+
+.PHONY: bin test lint vet install clean demo \
+        build tests qa-test self-hygiene doc-validate citation-check secret-scan \
+        vuln-scan sdet-abuse tdd-preflight reserved-name-check \
+        render-verify copy-verify ac-commands
 
 VERSION  ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
 COMMIT   ?= $(shell git rev-parse --short HEAD 2>/dev/null || echo "none")
 BUILD_DATE ?= $(shell date -u '+%Y-%m-%dT%H:%M:%SZ')
 
 LDFLAGS := -X github.com/ALT-F4-LLC/docket/internal/cli.version=$(VERSION) -X github.com/ALT-F4-LLC/docket/internal/cli.commit=$(COMMIT) -X github.com/ALT-F4-LLC/docket/internal/cli.buildDate=$(BUILD_DATE)
 
-build:
+QA := scripts/qa
+
+# ---------------------------------------------------------------------------
+# Developer targets
+# ---------------------------------------------------------------------------
+
+# bin — produce ./bin/docket. Formerly `build`; renamed so the compile gate can
+# own that name (see the header).
+bin:
 	CGO_ENABLED=0 go build -ldflags "$(LDFLAGS)" -o ./bin/docket ./cmd/docket
 
 test:
@@ -24,6 +50,55 @@ install:
 clean:
 	rm -rf ./bin/
 
-demo: build
+demo: bin
 	@command -v vhs >/dev/null 2>&1 || { echo "vhs is required: brew install vhs"; exit 1; }
 	vhs scripts/demo.tape
+
+# ---------------------------------------------------------------------------
+# Gate targets — one per `docket trust list` entry
+#
+# Each delegates to the script that already carries the gate's logic and its
+# failure explanation; this file adds a stable, worktree-independent name and
+# nothing else. A gate's behavior is changed in its script, not here.
+# ---------------------------------------------------------------------------
+
+build:
+	@bash $(QA)/build.sh
+
+tests:
+	@bash $(QA)/tests.sh
+
+qa-test: tests
+
+self-hygiene:
+	@bash $(QA)/self-hygiene.sh
+
+doc-validate:
+	@bash $(QA)/doc-validate.sh
+
+citation-check:
+	@bash $(QA)/citation-check.sh
+
+secret-scan:
+	@bash $(QA)/secret-scan.sh
+
+vuln-scan:
+	@bash $(QA)/vuln-scan.sh
+
+sdet-abuse:
+	@bash $(QA)/sdet-abuse.sh
+
+tdd-preflight:
+	@bash $(QA)/tdd-preflight.sh
+
+reserved-name-check:
+	@bash $(QA)/reserved-name-check.sh
+
+render-verify:
+	@bash $(QA)/render-verify.sh
+
+copy-verify:
+	@bash $(QA)/copy-verify.sh
+
+ac-commands:
+	@bash $(QA)/ac-commands.sh
diff --git a/README.md b/README.md
@@ -40,34 +40,15 @@ DOCKET_INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/A
 
 ### Agent Skill Setup
 
-If you're working with Docket through an AI coding agent, also install the companion skill so the agent has the full CLI workflow and command reference available without re-deriving usage from `--help` output. Copy this repo's [`skills/docket/SKILL.md`](skills/docket/SKILL.md) into your agent's skill directory:
-
-| Harness | Project-scoped | User-scoped |
-|---------|-----------------|-------------|
-| Claude Code | `.claude/skills/docket/SKILL.md` | `~/.claude/skills/docket/SKILL.md` |
-| Codex | `.agents/skills/docket/SKILL.md` | `~/.agents/skills/docket/SKILL.md` |
-| Opencode | `.opencode/skills/docket/SKILL.md` | `~/.config/opencode/skills/docket/SKILL.md` |
-
-```bash
-# Claude Code (project-scoped)
-mkdir -p .claude/skills/docket && cp skills/docket/SKILL.md .claude/skills/docket/SKILL.md
-
-# Codex (project-scoped)
-mkdir -p .agents/skills/docket && cp skills/docket/SKILL.md .agents/skills/docket/SKILL.md
-
-# Opencode (project-scoped)
-mkdir -p .opencode/skills/docket && cp skills/docket/SKILL.md .opencode/skills/docket/SKILL.md
-```
-
-See [Drop-in Skill](#drop-in-skill) for what the skill teaches.
+If you're working with Docket through an AI coding agent, also install the companion skill so the agent has the full CLI workflow and command reference available without re-deriving usage from `--help` output. The skill is maintained in [ALT-F4-LLC/dotfiles.vorpal](https://github.com/ALT-F4-LLC/dotfiles.vorpal) at `src/user/claude_code/skills/docket/`; copy that directory into your agent's skill directory (e.g. `.claude/skills/docket/` project-scoped, or `~/.claude/skills/docket/` user-scoped for Claude Code).
 
 ### From Source
 
 Requires Go 1.26.0+ (toolchain go1.26.5).
 
 ```bash
 # Build the binary to ./bin/docket
-make build
+make bin
 ./bin/docket --help
 
 # Install to $GOPATH/bin
@@ -142,7 +123,7 @@ Any agent that can run shell commands works with Docket. Point it at `docket nex
 
 ### Drop-in Skill
 
-[`skills/docket/SKILL.md`](skills/docket/SKILL.md) is a thorough reference teaching the full Docket CLI workflow and command/flag reference in one file, so your agent doesn't need to re-derive usage from `--help` output. See [Agent Skill Setup](#agent-skill-setup) in the Installation section above for where to drop it in for Claude Code, Codex, and Opencode.
+A companion skill teaching the full Docket CLI workflow and command/flag reference is maintained in [ALT-F4-LLC/dotfiles.vorpal](https://github.com/ALT-F4-LLC/dotfiles.vorpal) at `src/user/claude_code/skills/docket/`, so your agent doesn't need to re-derive usage from `--help` output. See [Agent Skill Setup](#agent-skill-setup) in the Installation section above.
 
 <details>
 <summary>Verbose JSON examples</summary>
@@ -237,6 +218,8 @@ docket plan --json --root DKT-3
 docket issue list --json -s todo -s in-progress -p high
 ```
 
+Listings — `issue list`, `next`, `plan`, and `board` — emit summary rows under `--json`: every issue field except `description`, plus `description_bytes`. Read one issue's full description with `issue show`, or pass `--with-body` to include every description in the listing.
+
 </details>
 
 <details>
@@ -306,9 +289,16 @@ docket issue list --json -s todo -s in-progress -p high
 | Command | Description |
 |---------|-------------|
 | `docket next` | Show work-ready issues (unblocked, sorted by priority) |
-| `docket plan` | Compute a phased execution plan from the dependency graph (filterable by `--status`/`-s`, `--label`/`-l`, `--priority`/`-p`, `--type`/`-T`, `--assignee`/`-a`) |
+| `docket plan` | Compute a phased execution plan from the dependency graph (filterable by `--status`/`-s`, `--label`/`-l`, `--priority`/`-p`, `--size`, `--type`/`-T`, `--assignee`/`-a`) |
 | `docket board` | Kanban board view in the terminal |
 
+### Report Commands
+
+| Command | Description |
+|---------|-------------|
+| `docket run report RUN-N` | Roll up one run's budget, steps, gates, actions, artifacts, findings, and metadata |
+| `docket report executors` | Group fix-loop routings, override-pass rulings, reaps, and cluster corroboration per executor hint and voter name across runs (`--since RUN-N` or a date, `--all-projects`); read-only, never consulted by `next` |
+
 ### Top-Level Commands
 
 | Command | Description |
@@ -375,7 +365,9 @@ one.
 ### Consolidating legacy per-repo stores
 
 Move an old repo-local database into the shared store with export/import —
-colliding ids are remapped automatically, nothing is dropped:
+ids colliding with another project's rows are remapped automatically, nothing
+is dropped. Merging a project's own export back with `--merge` skips the rows
+it already holds:
 
 ```bash
 DOCKET_PATH=/path/to/repo/.docket docket export -f repo.json
@@ -462,7 +454,8 @@ scripts/
 ```bash
 git clone https://github.com/ALT-F4-LLC/docket.git
 cd docket
-make build          # Build to ./bin/docket
+make bin            # Build to ./bin/docket
+make build          # Run the compile gate (scripts/qa/build.sh)
 make test           # Run unit tests
 make lint           # Run staticcheck + go vet
 make clean          # Remove build artifacts

diff --git a/cmd/docket/main.go b/cmd/docket/main.go
@@ -1,3 +1,4 @@
+// Command docket is the CLI entry point for Docket.
 package main
 
 import (

diff --git a/cmd/vorpal/main.go b/cmd/vorpal/main.go
@@ -11,14 +11,7 @@ import (
 
 func main() {
 	ctx := config.GetContext()
-	ctxTarget := ctx.GetTarget()
-
-	systems := []string{
-		"aarch64-darwin",
-		"aarch64-linux",
-		"x86_64-darwin",
-		"x86_64-linux",
-	}
+	ctxTarget := ctx.GetTargetStr()
 
 	ffmpeg, err := ctx.FetchArtifactAlias("ffmpeg:8.0.1")
 	if err != nil {
@@ -81,7 +74,7 @@ func main() {
 	}
 
 	_, err = artifact.
-		NewDevelopmentEnvironment("docket-shell", systems).
+		NewDevelopmentEnvironment("docket-shell", config.SYSTEMS).
 		WithArtifacts([]*string{
 			ffmpeg,
 			gobin,
@@ -104,7 +97,7 @@ func main() {
 		log.Fatalf("error building project environment: %v", err)
 	}
 
-	_, err = language.NewGo("docket", systems).
+	_, err = language.NewGo("docket", config.SYSTEMS).
 		WithBuildDirectory("cmd/docket").
 		WithIncludes([]string{
 			"cmd/docket",

diff --git a/docs/design/engine-core.md b/docs/design/engine-core.md
@@ -352,7 +352,7 @@ consequences, mechanically:
   so no torn state exists.
 - **Dispatcher session dies** ⇒ nothing happens. Leases lapse; the run sits `active`
   with a ready set. Any new dispatcher session picks up exactly where things stood —
-  the reference harness injects `docket run status --active` at session start so
+  the reference harness injects `docket run status` at session start so
   resumption is automatic (upstream 03 §7). There is no handoff narrative, no
   crash-recovery doctrine.
 - **Docket contention** ⇒ SQLite WAL + busy timeout + single-transaction claims