ddflow

Stop believing a memory that is no longer true. It is kept, with the reason: 'we thought X until Y' is what stops the next agent re-learning X. Correct a fact instead with ddflow_memory_add and its id.

The project's operational memories, newest first -- or ranked against `query`. What an agent must know before touching anything on this machine; read them at session start if ddflow_brief truncated the list.

Land an item's branch without ever switching a checkout's branch. With [flow].integration = 'pr' it pushes and opens (or updates) a pull request instead, releases your lease and parks the item in REVIEW — take the next item; `ddflow_pr_sync` completes it once a person merges it.

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.

BEFORE compressing or rewording an instruction file (a rulebook, a driver, AGENTS.md, CLAUDE.md, a prompt template): which of its text a test pins, which suites to re-run afterwards, and the longest stretches no test holds. A sentence that reads like rationale is often a rule a test asserts. Exit 2: no Python suite to read pins from -- then treat ALL of it as pinned. Free text is a lower bound, not permission.

Every item's pull request as last recorded — review, checks, target, rounds of changes and when it was last looked at. Reads the log only; `ddflow_pr_sync` asks the forge.

Ask the forge (GitHub/GitLab) what reviewers did with every request in REVIEW and record it: a merged request completes its item (and retargets what is stacked on it), requested changes return the item to the queue WITH the review text, a closed one is parked for a person, an approved green one is merged when [flow].pr_merge = 'on_approval'. `ddflow_next` does this itself with [flow].sync_on_next. Exit 2: the forge could not be asked -- NOT 'nothing changed'.

An item's review threads, read live from the forge. With `thread`, `reply` on it and/or `resolve` it, so the reviewer sees what was addressed. Exit 2 = forge not reached; 3 = refused.

A .pre-commit-config.yaml proposed for THIS repository: its stacks (Python, shell, Docker, JS, Go, Rust; YAML/TOML/JSON checks) mapped to pinned hooks, plus ddflow's check-commit and check-msg as local hooks, so pre-commit owns .git/hooks/ (remove ddflow's own first; the body names them). Proposes; installs nothing. `write` creates the file, REFUSED (exit 3) when one exists. The body names missing programs. Installing pre-commit is the operator's call.

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.

File a PROMOTION to an environment branch ([flow].environments): a task that merges the branch immediately upstream into it, runs the promotion pipeline and lands by merge or request -- always one step downstream. Exit 2 = nothing to promote; exit 3 = refused (unknown environment, one open, branch missing).

Record the sha a deploy put LIVE in an environment (from the deploy hook); promote_status then shows what runs there. Exit 3 = refused.

Each environment: head, commits behind its upstream, open promotion, auto_promote, and the live (deployed) sha. Reads only.

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: decisions, lessons, research verdicts, operational memories, past bugs, similar tasks and the operator's earlier prompts. CALL THIS BEFORE STARTING ANY NON-TRIVIAL WORK, so nothing is said or learned twice. Results are labelled by kind (a binding decision, a transferable lesson and an old prompt change what you do differently); a superseded decision names its replacement -- follow that.

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, the one-paragraph lessons summary, 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.

Settle a CONTESTED item: two clones each added the same id with different content, or each claimed it, and a merge brought both in (`ddflow_doctor` names them, `ddflow_show` lists the rivals, `ddflow_next` withholds them). `keep` names the definition (event id or agent) and/or the lease holder to keep; the losing claim is released in the same transaction; a losing DEFINITION comes back in `lost`: re-add it under a new id with `refile_as`, or it stays only in the log. Refused (exit 3) when not contested.

Run the configured cross-family reviewer over an item's diff and record the result: the critic gate, performed by ddflow. No reviewer, endpoint or verdict records UNAVAILABLE, never a pass. A gate gets [review].max_rounds (default 2) full rounds, then delta=true and ddflow_review_triage.

Record your triage of ONE finding of an item's recorded `ddflow review`: it is refuted (probe = the run that shows it false) or confirmed (probe = the fix or test that answers it). The finding number is the #N the review printed. The gate stays failed -- a review that reported findings is not re-recorded as passed; the log shows each finding's fate instead (decision D-review-triage).

Probe well-known local ports for an OpenAI-compatible model server (ollama, vLLM, LM Studio, llama.cpp, sglang) and report what serves, with each model's pretraining family: how to find a reviewer from a DIFFERENT family than yourself, which the critic gate requires. write=true records it in the git-ignored .ddflow/local/reviewers.toml (this machine's, never committed).

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

Add a project rule; duplicate-checked like every add (answer new | extends:ID | duplicate_of:ID | related:ID).

Change fields of an existing rule; omitted fields stay. Recorded in the manifest.

List the project's rules, filtered by tag or scope: what governs the current work.

Delete a rule from the manifest; the removal is logged as an event.

Search rules by title or content, ranked by relevance, for an area or topic.

One rule with all its metadata: title, content, tags, scope, priority, globs, timestamps.

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, task or bug (a bug id works too): 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.

'IS THIS ALREADY FILED?' -- the existing records most like a text, BEFORE you file it as a bug, task, lesson or other record. Read-only. Candidates cross kinds and include closed records (a bug that repeats a fixed one is caught); each carries id, kind, title, state, score (0-1), shared words and flags, per [dedupe] show_floor, max_candidates and kinds. A score is a prompt to LOOK, not a verdict. Nothing close: exit 2.

Split an item into sub-tasks IN PLACE when the work turns out to be two things -- the moment you discover it; mid-task discovery is normal. The original keeps its id and history and becomes an umbrella that completes when its children do; closing it and opening two new ones would lose the thread between what was planned and what happened. Children inherit the parent's globs: give each its own afterwards if they write different files, or 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.

AFTER EACH CHANGE: the tests your change reaches (changed tests, tests importing a changed module directly or one step removed, tests named after it, a changed conftest's), each with why, and a command running them IN PARALLEL. Run it; do not reason about which matter. Never a pass: unit_tests runs the WHOLE suite. `item`: diff that item's worktree. Exit 2: no test reaches the change.

Release a BLOCKED item -- and every blocked item beneath it -- back into the queue, so `next` can offer them again. The inverse of ddflow_block, and how deferred work, or a whole archived section an import landed as blocked, becomes work once the OPERATOR says so: pass a phase id to release its section. Do not release held work on your own judgement. Returns nothing-to-do (exit 2) when nothing there is blocked.

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 commit hook work from the declared globs, so an undeclared file is unprotected and the commit is refused.

Re-check a done task's claims; fails if one does not hold. No id: sweep all, worst first.

Tag the next version. trunk: tags the base branch. gitflow: release/X from develop, merged to production, tagged, tag merged back; with pull requests, opens the release request (`ddflow_pr_sync` tags it once merged). Exit 2 = nothing to release.

The current version (highest `<tag_prefix>X.Y.Z` tag reachable from the release branch), the next one, the bump and why (Conventional Commits plus the tags of finished items), and the release notes. Reads only.