ddflow

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.

Which earlier test file makes `victim` fail only in full-suite order? Delta-debugs the files before it, running `cmd` many times. Exit 2: nothing to report.

Mark an item blocked on something outside the queue — a decision, an upstream outage, an operator question. Better than leaving it claimed: a blocked item states its reason. A DONE or ABANDONED item needs reopen.

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.

File a fix task for every open bug that has none (one-shot after an upgrade; `ddflow_bug_found` files one per bug by default).

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 makes the fix accountable: `ddflow_bug_fixed` refuses to close one without a regression test. A hunt that records nothing looks like one that found nothing.

Close a bug as a FALSE finding -- nothing was broken, so nothing was fixed. Never counts as a fix. Requires the reason; give the probe or test that showed it false as evidence. Refused (exit 3) for an unknown id or a bug already closed; a real bug is closed with `ddflow_bug_fixed` instead. `reopen`: instead UNDO a closure (fixed or invalid) made by mistake.

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.

CI parity: run the pre-push checks on the branch merged with the base (run) or show what would run (status).

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; apply=true removes merged worktrees and branches and lands commits for items the queue considers done. A dirty tree is NEVER touched automatically: it exists nowhere else.

Which companion MCP servers serve this project's gates, which are installed, which an agent launches. Without them, agent gates pass on assertion. Exit 2: a default one is missing or unregistered. Read-only; never installs or launches.

WRITES the agent config: registers companion MCP servers that are ALREADY installed (exit 3 for one that is not). dry_run=true FIRST; show the operator the entry: which servers an agent launches is their decision.

Launch MCP companions and require a JSON-RPC answer to `initialize`. SPAWNS processes (opt-in). Default: registered or installed ones. Exit 1: not an MCP server; 2: unsure.

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 (WRITES). No arguments: every knob with value, source and meaning. `set` edits one dotted key in place (preferred); `toml` APPENDS a fragment, e.g. [gate.unit_tests] command = "pytest -q -n auto" (needs pytest-xdist). The committed file is generic project policy; anything of THIS machine or operator (a reviewer endpoint, a host, a key variable, worker counts) goes with local=true to the git-ignored .ddflow/local/config.toml, read last and never committed. A reviewer there is a `[[reviewer]]` block; `ddflow_reviewers_detect` write=true writes one.

Record an architectural decision so the project stays consistent and the reasoning survives: HOW the software is built (a representation, boundary, library, invariant), settled by you or the operator. ALWAYS set `globs` to the code it governs, so it reaches whoever works those files; record `alternatives` too, or they get re-proposed.

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.

Documents from the log (roadmap, bugs, status, worklog, sessions, decisions, rules, changelog). No doc: list. doc: capped markdown (`truncated`). Writes only with write=true AND a repo path. action: list|enable|disable|validate (enable names you and how to stop it).

Observe the items in SIBLING repositories that this queue depends on (`needs = ['run_nemo_run:132.D']`, repositories named in [schedule] repos), and record what changed in this log. An external dependency is met only once it has been observed done here, so run this before `ddflow_next` when work waits on another project. Reads the other repository; never writes it.

Record a workflow choice for this project, attributed to you, with a reason the next agent will read. Make it when the operator told you, or when they left it to you -- a choice left unmade is defaulted at first use and followed from then on. The operator's config file wins over a recorded choice; the result says `in_effect: false` when it does.

How THIS project works: its branching model, release lines, and every workflow choice (model, integration, pr_merge, port_strategy, ...) with its value, the options, and who decided -- the operator's config, a recorded choice, or a default nobody chose. `pending` lists relevant choices nobody has made: ask the operator, or pick what suits the project with `ddflow_flow_choose`.

Record the outcome of a gate you performed (research, a review, a bug hunt). outcome is one of passed/failed/unavailable/partial/skipped. If a reviewer or tool could not run, record 'unavailable' with a reason, never 'passed'. Pass the reviewer's model for the family check.

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: the auditable escape hatch. `gates.require_outcome` means a silent gate BLOCKS completion, so the alternative to a skip is forcing past everything at once; a skip names the single step dropped and why, permanently in the log. A gate in `gates.required` still blocks when skipped.

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, restores the file. A gate that cannot fail reports success on every change. Exit 1: the gate did NOT catch its mutation, or none is registered. Exit 3 on a HUMAN-approval gate (nothing to mutate). A mutation whose `old` text is absent or ambiguous is a FAILURE, not a skip: the gate ran on pristine source.

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 descriptions explain one tool each and the connection instructions describe THIS repository; neither answers 'how am I meant to work here'. No argument: the loop from picking work to landing it, the exit codes, and every capability grouped by purpose. `topic`: workflow, import, gates, parallel, memory, recovery, config. Read-only; the pages are templates a project may override.

ONE timeline of everything that happened: claims, releases, gates, bugs, decisions, lessons, completions. Other views say what is true now; this says how it got that way. Filter with `item` (one task's life), `kind` (a family: 'gate', 'lease.acquired', 'decision,bug'), `since`, `by_agent`. Exit 2 means nothing matched: 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.

Declare WHO you are on this connection before anything that writes. Call it first when 2+ agents or subagents work this repository at once: identity attributes every claim, gate outcome and review, and the tree-derived default merges several agents in one tree into one identity with no error (a review would pass independence against itself). Pick a short stable name (your role), distinct from the others'. Idempotent. A SUBAGENT sharing its parent's connection must NOT call this; it passes `as_agent` on each call instead (the CLI's `--agent`).

For a project that ALREADY HAS HISTORY and is adopting ddflow now: reads its todo checklists, lessons corpus, ADR files and unmerged branches and proposes them as queue items. Reports by default; writes NOTHING until `apply` is true. Call it right after `ddflow_setup` on any repository that is not brand new. The proposal is a GUESS: the `import-existing-project` prompt walks through fixing it. Exit 2: nothing found.

Was this project's history imported, is that still true, and did anyone FINISH it? Read-only. STATUS: what carries import provenance. STILL TRUE: whether the sources moved on (what a re-run would add) or an imported item names a missing file. FINISHED: imported tasks with no globs (the conflict detector cannot protect them) and phases claiming shipped work while a task under them is open. Call after any import. Exit 1 = findings; exit 2 = nothing ever imported. `ddflow_doctor` covers the rest.

Register a long-running process you started some other way (torchrun, a launcher script), by pid, while it runs -- so its liveness can be checked by anyone later, including after a pid is reused.

Record that a job ended and how. Refused while the process is still running. The exit code defaults to the one its log recorded.

Long-running jobs and their LIVE status: running, exited (with the exit code its log recorded), gone (killed: no exit recorded), elsewhere (another host), or ended. Use it to decide whether to keep waiting, collect results, or restart. A long run is a WAIT, never a reason to stop working the queue.

Launch a LONG-RUNNING command for an item (a training run, a data generation, a model server) detached into its own session, so it outlives you, this server and a restarted remote-control service, and record it. Runs in the item's worktree; returns the job id, pid and log path. Then WAIT with ddflow_job_list rather than polling; `ddflow_brief` shows running jobs to the next session. Declare the item's `resources` (ddflow_update) so nobody else starts a run on the same GPUs.

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.

Re-scan every lesson that declared a code `pattern` and report the sites where it has REAPPEARED. Exit 1 names them; exit 2 means no lesson declares a pattern, which is NOT a pass — it means this project has no mechanical ratchet on its lessons yet. Run after a change that touches code a lesson governs.

Read-only lists, newest first, 25 rows unless `limit` (0 = the most: 1000, search 200); a cut says so. `kind`: task|phase|bug|research|session|search. Bugs: open unless `all`/`state`. History: ddflow_history.

Detect circular references and runtime loops: dependency cycles, an item claimed and given up over and over, a gate whose verdict keeps flipping, a gate failing again with identical output (repeated_failure), 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: stop and re-plan rather than retry the same thing. [] when nothing is wrong.

Remember ONE operational fact about this machine, repository or working state ('this box has 8 H200s', 'use -n 16, never -n auto'). Shown at the top of every ddflow_brief and found by ddflow_recall, in every worktree at once. Not for rules (ddflow_lesson_add), events (ddflow_session_note) or how the software is built (ddflow_decision_add). Never a secret: the log is committed. Refused over [memory] max_chars (default 280).