Stop work on an item without completing it, with a reason. Use when a task turns out to be unnecessary or impossible. DIFFERENT from blocking: a blocked item is waiting and will resume; an abandoned one will not, and so it stops holding its phase open — which an unfinished task otherwise does forever, since nothing can ever finish it.

Mark an item blocked on something outside the queue — a missing decision, an upstream outage, a question for the operator. Better than silently leaving it claimed: a blocked item states its reason, while a claimed one that nobody is working just looks busy until the lease expires.

The whole work queue as a readable board, with the critical path.

START HERE every session. Returns a budgeted pack: work recoverable after a crash, the current item, what is ready to start now, why everything else is blocked, and the past lessons ranked as relevant to this task. Use this INSTEAD of reading the project's lesson or rule files — it is the same information retrieved for the task at hand, at a fraction of the tokens.

Close a bug. Requires the name of the regression test that would catch it again — write the test, watch it FAIL against the unfixed code, then close.

Report a bug the moment you find it, BEFORE fixing it. Recording it first is what makes the fix accountable: ddflow_bug_fixed refuses to close one without naming the regression test, so a bug that was never opened is a fix that never had to prove itself. Bug hunts that record nothing look identical to bug hunts that found nothing.

Which periodic whole-repo passes are due — integration tests, architecture review, mutation testing, dedupe sweep, lessons compression. Derived from completed work, so there is no state file to drift.

Lease an item and create its isolated git worktree. Refuses (exit 3) if another agent holds it or holds an item whose file globs overlap, and names what you could take instead. NEVER steals an expired lease: a crashed agent's worktree often holds finished work.

Classify every ddflow worktree and branch: merged (safe to remove), unmerged (carries commits nobody landed), dirty (uncommitted edits — a human looks), orphan, or stale branch. Reports by default; with apply=true it removes merged worktrees and branches and lands commits for items the queue already considers done. A dirty tree is NEVER touched automatically, whatever you pass — it is the only thing here that exists nowhere else.

Which companion MCP servers serve this project's gates, which are installed on this machine, and which are wired into an agent's config. ddflow imposes the pipeline; it does not perform the judgement inside most gates — standards wants an automated standards review, research wants documentation to check a claim against, rules wants memory. A project with none of them has agent gates passing on assertion alone. Exit 2 means a default companion is missing or unregistered. Read-only: it detects and advises, it never installs anything.

Register companion MCP servers that are ALREADY installed into an agent's MCP config, merging rather than overwriting what is there. Refuses (exit 3) to register one that is not installed, because that writes a launch command which fails mid-task, at the moment a gate told the agent to reach for it.

Finish an item. Refuses (exit 3) when a required gate has not passed, when a phase still has open tasks, or when no reviewer came from a different model family than the author. Pass your own model as 'model'.

Read or write .ddflow/config.toml. With no arguments it prints every knob, its value, its source and what it does. With toml, it APPENDS that TOML to the config — the usual use is setting your project's test command: [gate.unit_tests] command = "pytest -q" This is how a project is configured without a shell.

Record an architectural decision so the project stays consistent and the reasoning survives. Use when you or the operator settle a question about HOW the software is built — a data representation, a boundary, a library choice, an invariant.

ALWAYS set globs to the code it governs: that is what lets the decision be surfaced automatically to whoever works those files later, instead of only being findable by someone who already suspects it exists. Record alternatives too — without it the next agent re-proposes what was rejected.

The architectural decisions that govern a specific item's declared files. CALL THIS BEFORE IMPLEMENTING: it is how a decision reaches the person writing the code, without them having to know it exists. Returns project-wide decisions too.

Every architectural decision in force. Superseded ones are hidden unless you ask for them — they are kept, never deleted, because how the architecture got here is what a rebuild needs.

Read ONE architectural decision in full — its context, what was decided, the consequences, and what was rejected. ddflow_decision_list gives you the titles; this is what you read before working against one, and especially before proposing something it already considered.

Mark a decision replaced by a newer one. Decisions are never edited or deleted; a reversal is a new decision that names the old one.

Integrity and health check: log corruption, dependency cycles, unknown dependencies, orphaned worktrees, stale index.

Record the outcome of a gate you performed (research, a review, a bug hunt). outcome is one of passed/failed/unavailable/partial/skipped. IMPORTANT: if a reviewer or tool could not run, record 'unavailable' with a reason — recording it as 'passed' is how an entire review silently vanishes. Pass the reviewer's model so family independence can be checked.

Execute a command gate (tests, linters) and record the result with its evidence. Agent gates cannot be run this way; they are recorded with ddflow_gate_record.

Skip a gate ON THE RECORD, with a mandatory reason. This is the auditable escape hatch, and it is the one to reach for: gates.require_outcome means a gate left silent BLOCKS completion, so the alternative to skipping is forcing past everything at once. A skip names the single step you are dropping and why, and that reason is in the event log permanently. Skipping a gate listed in gates.required still blocks — those are not optional.

Where an item stands in its quality pipeline, which gate is next, and the instruction for that gate. Gates marked '?' did not run — that is a coverage gap, never a pass.

Break what a gate guards and require it to NOTICE. Applies each mutation registered on the gate, runs it, requires a non-zero exit, and restores the file.

This is the anti-vacuous-pass check turned on the checks themselves. A gate that cannot fail is worse than no gate: it reports success on every change and everyone downstream reads that as evidence. Exit 1 means the gate did NOT catch its mutation — or that nobody has registered one, which is the same problem earlier.

A mutation whose old text is absent or ambiguous is a FAILURE, not a skip: the edit never happened, so the gate ran on pristine source and passing proves the opposite of what it claims.

Renew the lease on an item. Call periodically during long work, or the lease expires and another agent may take the item.

What ddflow IS, what it can do, and what the workflow is. Call this first if you have not used it before — the other tool descriptions explain one tool each to someone who already knows which to pick, and the connection instructions describe THIS repository right now. Neither answers 'how am I meant to work here'.

With no argument: the loop from picking work to landing it, what the exit codes mean, and every capability grouped by what it is for. With a topic: workflow, import, gates, parallel, memory, recovery, config.

Read-only. The pages are templates a project can override, so what this returns may be this project's own instructions rather than the defaults.

ONE timeline of everything that happened, in the order it happened: claims, releases, gates, bugs, decisions, lessons, completions. The other views answer 'what is true now'; this one answers 'how did it get like this', which is the question you have when something looks wrong.

Filter with item for one task's whole life, kind for one family ('gate', 'lease.acquired', 'decision,bug'), since for a time window. Exit 2 means nothing matched — which is an answer, not a failure.

Inspect or install the enforcement git hook — the one layer of this workflow that does not depend on the agent agreeing. It refuses a commit touching paths no live lease of yours covers. status reports whether it is installed AND whether the policy actually blocks, since a block policy with no hook installed enforces nothing.

For a project that ALREADY HAS HISTORY and is adopting ddflow now: read its todo checklists, lessons corpus, ADR files and unmerged branches, and propose them as queue items. Reports by default and writes NOTHING until apply is true.

Call this right after ddflow_setup on any repository that is not brand new. A queue that starts empty tells you nothing is in flight about a project that may have three branches in flight.

The proposal is a GUESS about structure — headings became phases, checkboxes became tasks, and almost nothing has globs. Use the import-existing-project prompt, which walks through fixing that with the operator. Exit 2 means nothing was found.

Was this project's history imported, is that import still true, and did anyone FINISH it? Read-only; writes nothing.

Three answers in one call. STATUS: how many phases, tasks, branches, lessons, decisions, research notes, journal entries and memories carry import provenance, and when. STILL TRUE: whether the source files have moved on since (and what a re-run would add), and whether any imported item names a source file that no longer exists. FINISHED: the half the import-existing-project prompt asks a human for and nothing else checks — imported tasks with no globs, which the conflict detector cannot protect, and phases whose heading claims the work shipped while a task under them is still open.

Call it after any import, and whenever you are about to hand out imported work. Exit 1 means findings you should put to the operator; exit 2 means nothing was ever imported, which is an answer, not a failure. It does not repeat what ddflow_doctor covers — unresolved dependencies, duplicate globs, cycles — so run that too.

Record a lesson so it is never re-learned. Use after any bug, any operator correction, any surprise. Make the rule transferable — a future agent on a different task must be able to apply it.

Search past lessons by relevance (BM25). Use before starting work, and whenever something surprises you.

Detect circular references and runtime loops: dependency cycles, an item claimed and given up over and over, a gate whose verdict keeps flipping, work completed and reopened repeatedly, duplicate items writing the same files, and a queue where events keep arriving but nothing advances. CALL THIS WHEN WORK FEELS REPETITIVE — it is the check that tells you to stop and re-plan rather than trying the same thing again. Returns [] when there is nothing wrong.

Merge an item's branch into the base branch from the primary checkout, without ever switching its branch.

What may be started RIGHT NOW, and for everything that may not, the reason. Independent items in the ready set can be run in parallel worktrees by separate agents. Returns ready=[] when nothing is actionable — that is a result, not an error, and it never means 'pick something anyway'.

Add a phase to the queue. A phase is a unit of REVIEW: it gets its own research, its own whole-phase test pass and live smoke run, and it merges as one coherent feature. Group tasks into a phase when they only make sense shipped together.

What work has ACTUALLY been done, aggregated from the event log: attempts per item, wall-clock held, gate runs, commits produced, and who did them. Use it to answer 'how much effort has gone into this' and to see an item's full gate history including the outcomes that were not passes.

Inspect the prompt templates this project uses, and where each comes from (shipped default, project override, or an explicit config path). Use eject to copy the shipped ones into .ddflow/prompts/ so the project can edit them as plain text — reviewer instructions and workflow commands are operator-tunable behaviour, not code.

Re-derive the search index from the event log. The index is a disposable cache; this is never a data-loss operation.

'HAVE WE BEEN HERE BEFORE?' — one search across everything this project remembers: architectural decisions, lessons learned, research verdicts, past bugs, similar tasks, and the operator's own earlier prompts.

CALL THIS BEFORE STARTING ANY NON-TRIVIAL WORK. It exists so the operator does not have to say the same thing twice and you do not have to learn the same thing twice. Results are labelled by kind, because a binding decision, a transferable lesson and a prompt from three weeks ago should change what you do in different ways. A decision marked superseded names its replacement — follow the replacement.

Find work left behind by a crashed agent: expired leases, orphaned worktrees, items stuck running. Reports what each worktree contains and never deletes anything. Run this at the start of any session that follows an interruption.

Give up a lease without completing the item — when you are handing off, stopping, or recovering someone else's abandoned work after inspecting it. The note is recorded in the log and is often the only lasting explanation of why a claim was broken.

Take an item out of the queue. The log is append-only, so this RECORDS a removal rather than erasing anything — the item stays in the history and in replay, which keeps the record honest about work that was planned and then dropped. Refuses if another item depends on it.

Regenerate the human-readable markdown views (queue, lessons, research) under docs/ddflow/.

Reconstruct the project's whole decision history from the log: every operator prompt in order, every architectural decision, every research verdict, every lesson, and the shape of the queue. This is what rebuilds the project if the code is lost — it reproduces the DECISIONS, not the bytes.

Record a research finding. verdict MUST be CONFIRMED, REFUTED or THEORETICAL, and CONFIRMED/REFUTED require a probe — a verdict with no probe behind it is an opinion. A REFUTED entry is as valuable as an adopted one: it stops the next session re-researching it.

Run the configured cross-family reviewer over an item's diff and record the result. This is the critic gate performed by ddflow rather than claimed by you — it calls a real endpoint, parses the verdict, and records the evidence. If no reviewer is configured, or the endpoint is unreachable, or the model returns no verdict, it records UNAVAILABLE and never a pass.

Probe well-known local ports for an OpenAI-compatible model server (ollama, vLLM, LM Studio, llama.cpp, sglang) and report what is serving, with each model's pretraining family. Use this to find a reviewer from a DIFFERENT family than yourself — which the critic gate requires. Pass write=true to add what it finds to .ddflow/config.toml.

Show the configured reviewers, their families and which gates they serve.

Close a session with a summary of what it achieved. The summary is what a later reader sees before deciding whether to open the whole transcript, so write it for someone who was not there.

Record something that happened during a session which is neither an operator prompt nor a decision — a surprise, a dead end, why you changed approach. It goes into the reconstruction alongside the prompts, and a dead end recorded is a dead end nobody walks down twice.

Record the operator's prompt verbatim. This is what makes the project reconstructible from the log alone if everything else is lost. Secrets are redacted before anything touches disk. Call it once per operator turn.

Open a session for provenance logging. Returns the session id.

Install ddflow into this repository: creates .ddflow/, writes the driver and the AGENTS.md section, and registers nothing else. Run this ONCE per project, then set your test command with ddflow_configure. Safe to re-run — it updates a managed block and leaves your own prose alone.

Everything known about one phase or task: state, dependencies, declared globs, the lease and who holds it, the worktree path you can cd to, and every gate's outcome with its evidence. Use it to check your own work before calling ddflow_complete.

Split an item into sub-tasks IN PLACE when the work turns out to be two things. Use this the moment you discover it — mid-task discovery is the normal case, not an exception.

The original keeps its id and history and becomes an umbrella that completes when its children do; closing it and opening two new ones instead would lose the thread between what was planned and what happened. Children inherit the parent's globs, so give each its own afterwards if they write different files — until then they cannot run in parallel.

The state of the whole project in one answer: how many tasks are done and which, what is in flight and who holds it, what is ready to start, what is blocked, how many agent-hours and commits went in, and whether anything is looping or waiting to be recovered. This is the tool for 'what is the status of this project?' and 'what has been completed?'.

Add a task to a phase. ALWAYS set globs to the paths this task will write: they are what lets two agents work in parallel safely, and an unset glob means the conflict detector cannot protect you.

Change an item's fields. MOST IMPORTANT USE: widening globs when your work turns out to touch files outside what you claimed. Do that BEFORE writing them — the conflict detector and the commit hook both work from the declared globs, so an undeclared file is a file no one is protecting and the commit will be refused.

The rules THIS project runs by, in one answer: the gates every task and phase passes through in order, which are commands and which you perform yourself, which are required, which need evidence, which need a different-family reviewer, which have been PROVEN able to fail — plus the completion rules, the parallelism caps, the reviewers, and where each value came from (a default, this project's config, or the environment).

Call it before your first ddflow_claim in a session, and after any workflow change: the connection instructions are computed once when the server starts, so a pipeline edited mid-session is not reflected there.

Exit 1 means the workflow does not hang together — most importantly a pipeline naming a gate that has no definition, which blocks every item that reaches it forever. Read-only.

Take a gate out of both pipelines, and out of required so it does not become a requirement that quietly requires nothing. WRITES to config.

The gate's DEFINITION is left in place, so putting it back is one call. Exit 2 means it was in neither pipeline.

Ask the operator first: a gate in a pipeline is a check somebody added on purpose, and removing it weakens every future item.

Define or change one gate, and optionally put it in a pipeline. WRITES to this project's config.

command makes it a COMMAND gate: ddflow runs it and the exit code is the evidence. prompt makes it an AGENT gate: you perform it and record what you did. A gate needs one of the two — one with neither tells an agent nothing and gives a reviewer no contract, so it is refused.

into adds it to a pipeline (after places it; default is last). required means an item cannot complete without it.

Ask the operator first, and prefer dry_run to show them the change.

Set the ordered list of gates a task or a phase must pass. WRITES to this project's config.

Validated before anything is written: a gate id with no definition is REFUSED and the error names the near miss, because an undefined gate in a pipeline blocks every item that reaches it and cannot be recorded or skipped. Define the gate first with ddflow_workflow_gate.

Ask the operator before changing a pipeline. It governs every future item, not the one you are working on, and removing a gate removes a check somebody added deliberately. Use dry_run to show them what it would do.