Delivery Workbench

Delivery Workbench helps a person and their AI team deliver repository work without losing the plan, the review, or the proof. It keeps the answer to five questions close at hand:

• What is the current work?
• Is there a blocker or decision?
• What progress and cost can the saved facts prove?
• What permission remains?
• What is the next step?

Start with .githooks/dw status. It shows readiness, current work, progress, any blocker, and one source-backed next step. Use .githooks/dw setup when you want to compare ordinary work, one bounded delivery, and an optional multi-phase delivery. Reading either view starts no work and changes no saved state.

Work is complete only after its declared checks run and their proof is saved. The final commit check then makes sure the reviewed files still match that proof. Humans and agents use the same commands and see the same delivery facts.

For a complete first journey—from arrival through setup, review, recovery, and completion—read Everyday delivery. The whole-task journey proof shows how those same tasks are replayed from a fresh installed wheel while retaining exact technical inspection.

Technical overview

Plans are Markdown files in the repository, organized as phases and stories. Story evidence records exact command runs. A stamped commit contract binds the reviewed stage, branch, and commit facts; local hooks re-derive those facts before commit, while history verification catches bypassed hooks.

The optional bounded-run and multi-phase program engines add exact compiled policy, finite grants, replayed ledgers, and guarded control actions. Those protocols remain opt-in and do not change ordinary roadmap delivery. Their machine contracts and architecture are documented in Interop, Orchestration, and Programs.

Install

pipx install delivery-workbench
# or
brew install karolswdev/tap/delivery-workbench

Then set up any Git repository:

dw install /path/to/repo --skip-bootstrap

This copies the hooks, the CLI, and the MCP server into the repo's .githooks/ directory and points core.hooksPath at it. Commits are gated by the copy inside the repo, not by the global install. dw update /path/to/repo refreshes the copy; dw update /path/to/repo --check reports if it is stale.

Start from an empty directory

Create the directory, then let dw init initialize Git and install the same vendored rails:

mkdir my-project
dw init my-project

The command stops after the rails are healthy. It does not create a roadmap project or start an agent. Next, open the directory in Claude Code and run /dw-scope. The build-mode conversation writes one inert draft to .tmp/setup-proposal.json; review and setup remain separate steps. If the empty directory sits inside another Git repository, pass --inside-existing-repo to explicitly make it an independent nested repo.

For a project with existing history, there is an adoption flow that inspects the repo and drafts a roadmap for you. See the framework README.

The daily loop

.githooks/dw status                     # is this repo ready, and what is safe next?
.githooks/dw setup myapp                # compare ordinary, bounded, and optional-program delivery
.githooks/dw step myapp                 # preview one state-bound, allowlisted action
# review the preview; run its exact "Apply command" when it is applicable
.githooks/dw story status myapp 2 3 in-progress
# ... do the work ...
.githooks/dw evidence capture myapp 2 3 -- npm test
.githooks/dw story status myapp 2 3 done    # refuses if no evidence exists
git add -A
.githooks/dw contract new               # stamps verified facts into .tmp/CONTRACT.md
# read the contract, verify each rule actually holds, check its boxes
git commit                              # the hook re-verifies everything

Checking the contract's boxes is deliberately manual: it is the attestation that each rule was verified. No command or tool does it.

sequenceDiagram
  participant Dev as Human or agent
  participant DW as dw CLI
  participant Git as git commit
  participant Gate as pre-commit gate

  Dev->>DW: dw story status ... in-progress
  Dev->>Dev: do the work
  Dev->>DW: dw evidence capture ... -- <verify command>
  Dev->>DW: dw story status ... done (refuses without evidence)
  Dev->>DW: dw contract new (stamps verified facts)
  Dev->>Dev: verify each rule, check its boxes
  Dev->>Git: git commit
  Git->>Gate: re-derive every stamped fact
  Gate-->>Git: pass, or block naming the failed rule
  Git->>Git: stamp PMO trailers, archive the contract

Tracing a commit

The artifact chain:

flowchart LR
  C[commit + PMO trailers] --> S[story file]
  S --> E[evidence file with captured runs]
  C --> A[archived contract in .git]
  P[current-phase-status] --> S
  E -.proves.-> S

This repository uses its own gate, so the chain can be inspected here. One commit:

$ git log -1 --format='%h %s%n%(trailers:key=PMO-Story)%(trailers:key=PMO-Contract-Digest)' ec1fb4a
ec1fb4a Complete WLA-10-03: guarded mutation tools on the MCP surface
PMO-Story: WLA-10-03
PMO-Contract-Digest: sha256:2700dd6a9c8e8ee8ec6053e7a741ace4123ba6750b8946bf2331af9ecadc3777

The trailer names the story. The story file states the acceptance criteria. Its paired evidence file contains the recorded run that justified marking it done, including the exact command, exit code, and staged-tree hash at capture time:

### Captured run — 2026-07-03T19:59:44Z

- **Command:** `bash -c ... bash pmo-roadmap/tests/mcp-server.sh; python3 pmo-roadmap/tests/dw-core-tests.py ...`
- **Exit code:** 0
- **Index-tree:** b1c5aaa6e7845d8143d9f3cf24c039d491e7e1fd

The certified contract is archived under .git/pmo-contract-archive/<sha>. Because hooks only run where they are installed, dw verify re-checks the structural rules from pushed history, and CI catches commits that bypassed a local gate:

$ .githooks/dw verify --all
dw verify: ok (45 commits verified, 17 pre-epoch skipped)

The CLI

All commands have stable exit codes. dw status exits 0 for ready and 1 for attention; its JSON is a versioned contract suitable for an agent's first repository read. dw step is its separate explicit act boundary: preview is pure, stale tokens start nothing, and every invocation stops after one child. Applied leases cannot replay even when the action was read-only; JSON apply returns the versioned result and human apply renders the same bounded streams. See docs/deliberate-step.md. The specialist orientation commands support --json or --porcelain output.

The optional dw program namespace now spans pure list|validate|simulate|plan, exact grant start, canonical show, explicit preview→tick|supervise|request|pause|resume|revoke|cancel, verified tail, and bounded stream. MCP, localhost HTTP, SSE, and the progressively disclosed Workbench #/programs control room adapt the same content-safe projection and exact-token acts. Run and program control rooms now lead each bounded action with affected work, permission, limits, cost, and distinct consequences; decisions come only from the exact outstanding response set, and refusals name unchanged state plus a safe recovery step. No program configuration remains a healthy ordinary mode, and opening a read or the Workbench starts no program, poller, stream, process, or notification.

Parked work is first-class: a story goes on-hold only with a recorded reason, whole phases pause and resume (dw phase pause --reason / resume), and dw next skips parked work while naming what it skipped. Every board card and holds entry carries its receipt paths and workbench links, so a machine can walk card → story → evidence without knowing the tree layout; the contract over every supported CLI, HTTP, and MCP surface is docs/interop.md.

The MCP server

dw install also vendors .githooks/dw-mcp and writes an entry into the repo's .mcp.json, which Claude Code and other MCP clients pick up automatically. The server exposes 31 tools backed by the same code as the CLI: orientation, browse, verification, guarded roadmap mutations, pure orchestration reads/previews, and exact-token run acts. Run tools accept selectors, run ids, bounded parameters, and fresh intent tokens; they never accept score bodies, provider configuration, prompts, or check commands from the caller.

An agent can take a story from backlog to done through tool calls alone, with the same refusals the CLI gives. Two operations are deliberately absent: certifying a contract and creating a commit. Schemas and design are in docs/mcp.md.

dw step --json is the shared preview handrail: CLI, MCP, and the workbench HTTP API return the same state-bound document. Applying its exact token runs at most the one closed-table action and returns the same bounded receipt on all three transports; callers cannot supply argv, certify, commit, or loop. See the deliberate-step contract.

The web view

dw-workbench --root /path/to/repo serves a page for browsing the roadmap. Its overview opens with the same briefing as dw status: verdict, selected project, workspace/contract/gate state, and one tokenized argv or explicitly manual next action. For an applicable action, “review one deliberate step” opens a separate confirmation with the exact token, authorized argv, and CLI fallback; applying runs at most that one step, refreshes, and stops. Manual, certification, and commit states explain why no apply control exists. The specialist views retain phase tables, story and evidence pairs, a health console, the kanban board at #/board (drag moves ride the same guarded preview-then-apply flow — a park demands its reason, done still demands evidence), and the trace from a story to the commits that shipped it. It can edit roadmap files through a guarded preview-then-apply flow. It never stages, certifies, or commits. Bound to localhost by default; reachable over your own Tailscale network too (a .ts.net Host header is allowed, since that name only resolves through your own authenticated tailnet).

Roadmap changes also contains the adoption review at ?proposal=<repository-relative-file>#/edit/adoption_review. It reads a setup proposal and shows the project idea, phase sequence, first story proofs, provenance, unresolved questions, and every path setup would save. Tracked roadmap and policy files are shown separately from the .git-local driver bindings under the label "configuration, not permission." Review marks are browser-memory notes only. They do not save files or create permission. The page hands the reviewer back to dw setup preview <proposal-file> in the terminal for the next act.

At #/orchestration, the same local Workbench now visually authors exact coordination scores: typed agent/check/rail/approval/collect nodes, parallel research and fan-in, prompts and context, output conventions, checks and red failure routes, finite budgets, and terminal handoffs. Design, Validate, and canonical JSON share one compiler; save/delete is a stale-safe preview→diff→apply act and never grants or starts a run. The Run tab replays an authorized execution on the same graph: attempts, agent/check sessions, typed artifact lineage, budgets, repair routes, checkpoints, ledger receipts, and explicit pause/resume/revoke/cancel decisions. Refresh and stream opens are deliberate; there is no hidden poller, generic terminal, certification button, or commit shortcut.

At #/program-studio, delivery setup first asks which project and phase are being delivered, then compares ordinary roadmap work, one bounded delivery, and an optional delivery program without preselecting a higher mode. Each choice explains what setup creates, what could change later, what stays off, and which separate permission would still be required. Leaving or inspecting Technical details starts and writes nothing. Explicit family routes then open on a task-shaped plan: delivery scope, work flow, quality and review, decision points, repair and escalation, stop conditions, and finite limits. Each section states the question it answers, links incomplete source facts to the affected decision, and contributes to one readable summary before save. Programs can edit scope, work routes, phase decisions, stops, and limits; work flows can edit inputs and ordinary work/check/review/decision steps. Organization routes open on Team & review and answer who does each kind of work, who reviews independently, who decides disagreements, where escalation goes, and who audits review or architecture. The same stamped view describes live assigned ownership. It distinguishes compatible policy from runtime-proven identity/work-area/session separation; provider and model names never stand in for independence. Nested flows, bounded repair, discussion cells, exact conditions, graph layout, and lossless JSON remain editable under Technical details. Every view uses the existing Python compilers and edits the same source document, so valid imports preserve semantic and layout identity. Unknown fields remain visible and make save refuse safely instead of being dropped. Save/delete still uses one stale-safe preview→diff→fingerprint→apply boundary scoped to the selected tracked file. Saving starts no work and provides no permission. With no pm/programs, pm/workflows, or pm/organizations, the Studio is a neutral optional empty state: #/ remains ordinary Delivery Workbench, with no setup prompt, background poller, or runtime state.

Tracked pm/rubrics/*.json policies use the same optional boundary. dw rubric list|validate compiles exact criteria, evidence/citation rules, mechanical versus judgment types, aggregation/veto policy, and freshness; the wheel's example is never installed as project policy. The shared pure verdict engine accepts mechanical facts only from typed check/rail receipts, binds agent/meta/architect judgments to independently assigned read-only principals, preserves independent-panel dissent and superseded verdicts, and emits a pass/fail/pending/refused gate proof. Replay-derived council decisions remain a separate input: rule outcomes name no agent decider, judge outcomes bind the preassigned seat and full execution provenance, and every decision carries an explicit obligations list. A green proof still starts nothing and grants no integration, evidence, Git, or roadmap authority.

The optional program authority core now supplies the missing consent boundary: one pure start preview freezes scope, policy hashes, worst-case budgets, operator intent, every deterministic seat reachable across the granted scope, and each seat's provider/model/auth execution binding; exact start creates only a finite local grant and hash-chained ledger under .git. Advisory grants permit no claims; checkpointed and continuous grants reserve only named capabilities through exclusive idempotent claims. Replay re-derives budgets and legal transitions, child grants are strict non-delegable intersections, and pause/resume/revoke/ cancel use current-head generation-bound decisions. This remains invisible to ordinary and bounded-run use unless a program is explicitly planned and granted.

The embedded restart-safe program conductor now consumes that authority through one deterministic tick_program. Every tick locks and replays the program ledger, verifies immutable receipts, reconciles an already-dispatched operation before retry, rebuilds the exact selection/team/workflow frontier, claims at most one act, and stops. The delivered path covers isolated implementation, deterministic fan-out/fan-in, built-in checks, independent verification with finite repair, replay-derived council decisions and meta-audit, obligation ingestion, typed finite workflow loops, and final-story phase-architecture review. It also consumes already-observed Phase 25 signal facts by hash, delivers only program-declared finite nudges to an already-run agent under nudge:deliver, causally re-runs the declared downstream verification path, carries non-blocking obligations across exact story/phase selection, stops on blocking obligations, and enters complete only after the pure planner proves the full granted scope done. Each completed loop round has its own claim and immutable receipt binding the typed predicate observation, producer receipt, carried artifact hashes, exact round lineage, and success/continue/exhaustion route; restart cannot spend or record that round twice. The conductor itself still never integrates, certifies, commits, or edits roadmap status. The separate WLA-26-10 program_delivery core now performs those acts only from a pure exact preview and one claim per patch/evidence/roadmap/contract/ certification/commit/push effect, with crash reconciliation and no-force remote leases. WLA-26-11 now exposes this same state and authority boundary through CLI, MCP, HTTP, read-only SSE cursor replay, and the Workbench control room. Its view explains the selected story/workflow/team, resolved execution seats, active nested work, evidence/verdict/dissent/obligation gates, delivery, budgets, controls, and exact stop reason without exposing credentials or raw streams. Every mutation still requires a fresh matching exact token; bounded supervision is an explicit finite invocation, never a hidden scheduler.

The installed-wheel exit exam composes the complete program path after one continuous grant: three stories across two phases, one independent reject/repair/pass, one bounded council with preserved dissent, a full meta-audit, architect gates, exact evidence/integration/certification/commit/ push rails, and planted crash recovery. A second fresh consumer proves that no-program use creates none of this state or activity.

More screenshots and two terminal recordings are in demos/.

Mission control: steer from anywhere

The same roadmap state that gates commits is also a feed you can watch and act on from outside the terminal. Three read-only CLI documents make it a substrate any client can consume:

.githooks/dw state --json      # the roadmap: phases, stories, next actionable
.githooks/dw sessions --json   # which live agent is on which story
.githooks/dw events            # what happened on the rails (gate verdicts, flips)

Several clients consume that substrate today, including the workbench web view above, which renders it as a read-only belt at #/mc. A Telegram interface (integrations/telegram/) puts mission control in your pocket: bind a chat topic to a repo and it renders phases, stories, and gate refusals; a blocked agent's question reaches your phone in about a second through an installed hook — with arrow/Enter buttons that drive the agent's actual prompt when the session is bound and armed; and once you bind a session, you talk to the agent by just typing, and your words relay into its terminal pane. The pane itself arrives as a picture: /screen renders it to a PNG with colors intact, /live keeps the picture refreshing, and a configurable button toolbar covers the common keys. In a group, consent belongs to the person who paired, not to the room. A Desk conveyor on the HoldSpeak side renders the same feed as a belt.

Everything that changes the rails stays gated. The owner is bound by a one-time pairing token, not a hardcoded id. Story flips and project creation are proposals that execute on an approval tap, through the same allow-listed commands the CLI uses. The dw gate still refuses a dishonest done-flip and relays the banner back into the chat. Steering a terminal is guarded by explicit, expiring session binding and a pane-ownership check on every keystroke; sending a file runs it past seven refusal locks first. The design is in docs/mission-control.md and docs/absorption-ccgram.md.

Other components

• Local work logs: consent-gated daily notes of what each commit delivered.
• A Claude Code plugin with slash commands and a skill covering the operating loop.
• A managed CLAUDE.md block installed into adopted repos.
• A copyable verify-history CI job that re-checks pushed history on every pull request.

This repo runs on it

Every phase and story of the framework was shipped through its own gate: each story with evidence, every commit with trailers and an archived contract, the full history passing dw verify --all. The trail is in pmo-roadmap/pm/roadmap/work-log-automation/.

Documentation

• Everyday delivery: the task-first path from arrival and setup through plan review, live progress, recovery, proof, and completion
• Everyday product language: the Phase 27 vocabulary, presentation-only application-view boundary, complete surface inventory, technical-details escape hatch, and executable drift contract
• Whole-task usability journeys: the Phase 27 journey contract, reachable state fixtures, current-friction baseline, screen ownership, and deterministic usability proof
• Workbench accessibility: keyboard paths, focus and live-update behavior, assistive semantics, narrow/wide layout rules, and the executable 13-journey review record
• Delivery setup and first arrival: the three deliberate operating modes, pure shared model, Workbench/CLI parity, safe exits, preflight, and proof
• Delivery-plan authoring: the seven task-shaped decisions, readable pre-save summary, decision-shaped corrections, lossless Technical-details editing, and no-side-effect proof
• Team and review design: five responsibility questions, policy-ready versus runtime-proven independence, progressive decision/audit rules, exact provenance, lossless editing, and shared live reuse
• Comprehensive solution overview: current architecture, workflows, trust model, proof snapshot, strengths, gaps, and delivered response
• Status briefing contract: the Phase 22 one-answer model, readiness semantics, and guided action order
• Deliberate step contract: the Phase 23 state-bound preview/apply seam and closed executable action table
• Visual orchestration contract: the Phase 24 score editor, roles/research, outputs, checks/failures, grants, scheduling, drivers, recovery, and authority model
• Optional autonomous-program contract: the Phase 26 capability ladder, multi-phase scope, hierarchical workflows, organizations, independent verification, bounded councils/loops, grants, restart-safe conductor, and exact advancement boundaries
• Front-door setup-proposal contract: the inert idea-to-roadmap draft, optional tracked policy, local non-secret driver bindings, provenance, journey states, and refusal rules
• Architecture, with the test that proves each claim
• Framework README: install, update, adopt, operate
• The contract rules
• Remote verification design
• Contribution rails: what survives a pull request
• MCP surface design
• The interop contract: every supported surface over CLI, HTTP, and MCP, with its schema version
• Riders: the symbiosis contract: one brief, every agent surface (Claude Code, Codex, pi, HoldSpeak)
• The journal: the worked example, phases delivered on their own rails, written in the moment with refusals and dead ends included (through the mission-control and ccgram-absorption phases)
• Distribution design
• Contributing and changelog

Tests

The suites live in pmo-roadmap/tests/ and run standalone. CI runs all of them on ubuntu and macos, the unit suite on python 3.9 (the floor), and history verification on every push. Two packaged exit exams create fresh consumers: guided-status-loop.sh follows the shared briefing; deliberate-step-loop.sh separately authorizes each CLI/MCP/HTTP lease without reconstructing argv, proves same-action staleness, and keeps certification and commit manual. Both reach real evidence, gate pass, trailers, archive, and history verification.

License

MIT. The PyPI badge above states the current version; the changelog tells each release's story.