ddflow-mcp 0.1.1__py3-none-any.whl

ddflow/__init__.py

@@ -0,0 +1,15 @@
+"""ddflow — a portable, agent-agnostic work-queue kernel for AI coding agents.
+
+The whole system rests on one decision: **the append-only event log is the source of
+truth**, and every other artefact (the SQLite index, the markdown boards, the lessons
+search index, the session replay bundle) is a *derived projection* that can be thrown
+away and re-folded from the log at any time.
+
+Read `docs/ARCHITECTURE.md` for why, and `docs/RESEARCH.md` for the probes that
+decided each choice.
+"""
+
+#: One of the SIX places the version is declared; `scripts/bump.sh` moves them together
+#: and `tests/test_packaging.py::test_the_declared_versions_agree` holds them equal.
+#: This one sat at 0.1.0 through the 0.1.1 release because neither knew it existed.
+__version__ = "0.1.1"

ddflow/__main__.py

@@ -0,0 +1,3 @@
+from .surfaces.cli import main
+
+raise SystemExit(main())

ddflow/api/__init__.py

@@ -0,0 +1,242 @@
+"""The application layer: one typed entry point per operation, for both surfaces.
+
+`surfaces/mcp.py` reached `surfaces/cli.py` — a protocol adapter depending on a
+presentation layer — and the edge was carried by **strings**. Typed MCP arguments were
+flattened to argv, re-parsed by argparse, and the result recovered by scraping stdout
+plus an exit code. Two costs are visible in the code itself:
+
+* `mcp._opt(..., clearable=True)` exists only to rebuild the "absent vs empty"
+  distinction argv erased. `ddflow_update(id="X", needs="")` silently did nothing while
+  `ddflow update X --needs ""` cleared the field — and breaking a dependency cycle is
+  exactly the operation that needs it, and the one the loop detector tells you to do.
+  In a typed call `None` and `""` are simply different values and no helper is needed.
+* `mcp._run_cli` swapped process-global `sys.stdout`/`sys.stderr` for every call — not
+  reentrant, which forecloses concurrency in a server for a tool whose entire purpose is
+  parallel agents. **Both are gone.** The migration completed on 2026-09-27: every one of
+  the 63 tools dispatches through this layer, `ARGV_TOOLS_CEILING` is 0, and `_run_cli`
+  was deleted with the last tool that needed it (B97). `surfaces/mcp.py` no longer imports
+  `surfaces/cli.py` at all, so the latent `mcp <-> cli` cycle is structurally impossible
+  rather than merely guarded.
+
+Parity was held by ratchets where types would hold it structurally, and those ratchets
+catch a *missing* flag, never a *changed encoding*.
+
+**Migration, not a rewrite — and it is finished.** Each operation here is one a surface
+used to implement inline, moved one family at a time across twelve slices, each with its
+own mutation-verified probes. `ARGV_TOOLS_CEILING` went 62 -> 0 and may never rise: a new
+tool goes through this layer. A big-bang port of ~60 commands would have been one
+unreviewable change against a suite that cannot tell which half broke.
+
+Every function takes plain values and returns an `Outcome` — one description of a
+result, from which both the machine view (`data`) and the human view are derived. It is
+never both surfaces describing the same thing independently, which is the shape that
+produced the bug still commented in `cmd_complete`: a coverage gap printed in human
+mode only, invisible to the agent reading JSON that most needed it.
+"""
+
+from __future__ import annotations
+
+# Re-exported so `api.progress(...)` keeps working after the split. The surfaces reach
+# this layer through the PACKAGE (`_api().progress`), never through a family module, so
+# moving an operation between families is not a breaking change.
+from ._base import _load
+from .completion import completion_verdict
+from .decisions import (
+    decision_add,
+    decision_applicable,
+    decision_list,
+    decision_search,
+    decision_show,
+    decision_supersede,
+)
+from .flow import (
+    flow_choose,
+    flow_show,
+    pr_status,
+    pr_sync,
+    promote_add,
+    promote_status,
+    version_cut,
+    version_show,
+)
+from .gates import Evidence as GateEvidence
+from .gates import record as gate_record
+from .gates import run as gate_run
+from .gates import status as gate_status
+from .gates import verify as gate_verify
+from .items import DEFAULT_PRIORITY, ItemEdit, phase_add, resolve, split, task_add, update
+from .jobs import job_add, job_end, job_list, job_run
+from .knowledge import (
+    Finding as ResearchFinding,
+)
+from .knowledge import (
+    LessonDraft,
+    bug_fixed,
+    bug_found,
+    history,
+    lesson_add,
+    lesson_search,
+    lessons_verify,
+    memory_add,
+    memory_forget,
+    memory_list,
+    recall,
+    research_add,
+    session_end,
+    session_note,
+    session_prompt,
+    session_start,
+)
+from .lifecycle import (
+    DEFAULT_CHECK_RECOVERY,
+    DEFAULT_NEXT_KIND,
+    abandon,
+    block,
+    brief,
+    claim,
+    complete,
+    heartbeat,
+    unblock,
+)
+from .lifecycle import merge as merge_item
+from .lifecycle import next_ as next_item
+from .lifecycle import release as release_item
+from .lifecycle import remove as remove_item
+from .operations import cadence, cleanup, external_sync, import_project, import_verify, pins
+from .reporting import (
+    DEFAULT_RENDER_DIR,
+    board,
+    doctor,
+    loops,
+    progress,
+    rebuild,
+    recover,
+    render,
+    replay,
+    show,
+    status,
+)
+from .review import review as run_review
+from .review import reviewers_detect, reviewers_list
+
+# `run_review`, not `review`: a name re-exported here SHADOWS the submodule of the same
+# name, so `from ddflow.api import review` would bind the function and every
+# `review.reviewers_list` would raise `'function' object has no attribute`. Caught by
+# `test_no_reexport_shadows_a_submodule`, which exists because of this line.
+from .setup import (
+    Adoption,
+    ConfigEdit,
+    Registration,
+    companions_add,
+    configure,
+    help_topic,
+    hooks,
+    prompts,
+)
+from .setup import companions as companions_list
+from .setup import setup as adopt_project
+from .workflow import GateEdit as WorkflowGateEdit
+from .workflow import drop as workflow_drop
+from .workflow import gate as workflow_gate
+from .workflow import pipeline as workflow_pipeline
+from .workflow import show as workflow_show
+
+__all__ = [
+    "DEFAULT_CHECK_RECOVERY",
+    "DEFAULT_NEXT_KIND",
+    "DEFAULT_PRIORITY",
+    "DEFAULT_RENDER_DIR",
+    "Adoption",
+    "ConfigEdit",
+    "GateEvidence",
+    "ItemEdit",
+    "LessonDraft",
+    "Registration",
+    "ResearchFinding",
+    "WorkflowGateEdit",
+    "_load",
+    "abandon",
+    "adopt_project",
+    "block",
+    "board",
+    "brief",
+    "bug_fixed",
+    "bug_found",
+    "cadence",
+    "claim",
+    "cleanup",
+    "companions_add",
+    "companions_list",
+    "complete",
+    "completion_verdict",
+    "configure",
+    "decision_add",
+    "decision_applicable",
+    "decision_list",
+    "decision_search",
+    "decision_show",
+    "decision_supersede",
+    "doctor",
+    "external_sync",
+    "flow_choose",
+    "flow_show",
+    "gate_record",
+    "gate_run",
+    "gate_status",
+    "gate_verify",
+    "heartbeat",
+    "help_topic",
+    "history",
+    "hooks",
+    "import_project",
+    "import_verify",
+    "job_add",
+    "job_end",
+    "job_list",
+    "job_run",
+    "lesson_add",
+    "lesson_search",
+    "lessons_verify",
+    "loops",
+    "memory_add",
+    "memory_forget",
+    "memory_list",
+    "merge_item",
+    "next_item",
+    "phase_add",
+    "pins",
+    "pr_status",
+    "pr_sync",
+    "progress",
+    "promote_add",
+    "promote_status",
+    "prompts",
+    "rebuild",
+    "recall",
+    "recover",
+    "release_item",
+    "remove_item",
+    "render",
+    "replay",
+    "research_add",
+    "resolve",
+    "reviewers_detect",
+    "reviewers_list",
+    "run_review",
+    "session_end",
+    "session_note",
+    "session_prompt",
+    "session_start",
+    "show",
+    "split",
+    "status",
+    "task_add",
+    "unblock",
+    "update",
+    "version_cut",
+    "version_show",
+    "workflow_drop",
+    "workflow_gate",
+    "workflow_pipeline",
+    "workflow_show",
+]

ddflow/api/_base.py

@@ -0,0 +1,42 @@
+"""What every operation in this layer needs before it can answer anything.
+
+Separate from `__init__` so a family module can import it without importing the
+package that imports the family module. One file, one import edge, no cycle.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..config import Config
+from ..core.model import State, fold
+from ..infra.log import EventLog, resolve_agent_id
+
+
+def _load(repo: Path, agent: str = "") -> tuple[EventLog, Config, State]:
+    """Config FIRST, then the log — because the identity depends on the config.
+
+    This used to be `EventLog(repo, agent)` with an empty `agent`, which falls to
+    `default_agent_id()` and reads neither `DDFLOW_AGENT` nor `[agent].id`. The argv
+    path resolved all four layers; this one resolved one. Same connection, same call,
+    two identities, two shards.
+    """
+    cfg = Config.load(repo)
+    # Resolved AND written back, exactly as `surfaces/context.Ctx` does. Resolving without
+    # writing back is a third copy of the same drift: `config --explain` reported
+    # `agent.id = ""  [default]` from this path while the argv path reported the value the
+    # env var actually set. The identity is a fact about this invocation, and a config
+    # object that does not carry it is a config object two surfaces disagree about.
+    resolved, layer = resolve_agent_id(repo, cfg, agent)
+    if resolved != cfg.agent.id:
+        cfg.agent.id = resolved
+        # The layer that actually WON, not a guess from comparing values.
+        cfg.sources["agent.id"] = layer
+    log = EventLog(repo, resolved, lock_timeout_s=cfg.lease.acquire_timeout_s, log_cfg=cfg.log)
+    st = fold(log.read_all(), strict=False)
+    # Workflow choices recorded in the log fill in wherever the config file is silent --
+    # HERE, once, so every operation reads `cfg.flow.*` and sees the same answer.
+    from ..services.choices import overlay
+
+    overlay(cfg, st)
+    return log, cfg, st

ddflow/api/completion.py

@@ -0,0 +1,38 @@
+"""May this item complete, and did it?"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..core import outcome as O
+from ._base import _load
+
+
+def completion_verdict(repo: Path, item: str, *, model: str = "") -> O.Outcome:
+    """Would this item complete, and if not, why not? Reads only.
+
+    Exposed as its own operation because "may I" and "do it" are different questions,
+    and an agent that can only ask by *attempting* learns the answer by causing the
+    thing it was checking for.
+    """
+    from ..services import completion as CM
+
+    _log, cfg, st = _load(repo)
+    v = CM.verdict(st, cfg, item, repo=repo, model=model)
+    data: dict[str, Any] = {
+        "id": item,
+        "may_complete": v.may_complete,
+        "blockers": v.blockers,
+        "warnings": v.warnings,
+        "coverage_gaps": v.coverage_gaps,
+        "coverage_note": v.coverage_note,
+        "independence": v.independence,
+    }
+    if v.may_complete:
+        return O.ok("completion.verdict", **data)
+    return O.refused(
+        "completion.verdict",
+        f"{len(v.blockers)} unmet condition(s): " + "; ".join(v.blockers),
+        **data,
+    )

ddflow/api/decisions.py

@@ -0,0 +1,205 @@
+"""Architectural decisions: record them, consult them, supersede them.
+
+The CONSULT half is why this family is worth a typed layer. A decision nobody reads is
+a filed document; `applicable()` is the mechanism that turns it into something an agent
+about to write a set of paths is HANDED, without having to know it exists or guess a
+search term. That only works if both surfaces can ask the same question and get the
+same answer, which is what an `Outcome` per operation buys.
+
+Every function here returns one. The human renderings live in
+`surfaces/commands/decisions.py` and derive from `data` — they do not recompute.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ..config import Config, csv_list
+from ..core import outcome as O
+from ..core.ids import auto_id
+from ..core.plain import plain as _plain
+from ..infra.store import Store
+from ._base import _load
+
+
+def _store(repo: Path, log, cfg: Config) -> Store:
+    st = Store(repo, cfg)
+    st.ensure(log)
+    return st
+
+
+@dataclass
+class Draft:
+    """The decision record, named once.
+
+    These twelve fields were spelled out three times — argparse flags, the MCP input
+    schema, and the event payload — and a field added to one of them is a field the
+    other two silently drop. A dataclass with defaults also answers the lint that
+    `decision_add(repo, title, decision, context, consequences, alternatives, globs,
+    tags, sources, status, by, item, supersedes, ...)` was a 15-argument function: the
+    argument count was a symptom of the missing type, not a reason to shorten the name.
+
+    `globs`, `tags`, `sources` and `supersedes` arrive as comma-separated strings
+    because that is what both an argparse flag and a JSON string field give you;
+    `csv_list` is the ONE parser for that notation.
+    """
+
+    title: str
+    decision: str = ""
+    id: str = ""
+    context: str = ""
+    consequences: str = ""
+    alternatives: str = ""
+    globs: str = ""
+    tags: str = ""
+    sources: str = ""
+    status: str = "accepted"
+    by: str = ""
+    item: str = ""
+    supersedes: str = ""
+
+
+def decision_add(repo: Path, draft: Draft, *, agent: str = "") -> O.Outcome:
+    """Record a decision. Refuses without a stated DECISION, not merely a discussion.
+
+    The refusal is the point: a record saying what was *discussed* is indistinguishable
+    from notes, and the next agent cannot act on it.
+    """
+    if not draft.decision:
+        return O.failed(
+            "decision.recorded",
+            "--decision is required: the record must say what was DECIDED, not only "
+            "what was discussed.",
+        )
+    log, _cfg, _st = _load(repo, agent)
+    did = draft.id or auto_id("D", draft.title, draft.decision)
+    fields: dict[str, Any] = {
+        "title": draft.title,
+        "context": draft.context,
+        "decision": draft.decision,
+        "consequences": draft.consequences,
+        "alternatives": draft.alternatives,
+        "globs": csv_list(draft.globs),
+        "tags": csv_list(draft.tags),
+        "sources": csv_list(draft.sources),
+        "status": draft.status,
+        "decided_by": draft.by,
+        "item": draft.item,
+        "supersedes": csv_list(draft.supersedes),
+    }
+    log.append("decision.recorded", did, fields)
+    return O.ok(
+        "decision.recorded",
+        id=did,
+        status=draft.status,
+        supersedes=fields["supersedes"],
+        # Carried so BOTH surfaces can warn. A decision with no globs cannot be
+        # surfaced automatically to an agent working the code it governs -- it will
+        # only ever be found by someone who already went looking. That warning used to
+        # print in human mode only.
+        ungoverned=not fields["globs"],
+    )
+
+
+def decision_supersede(
+    repo: Path, item: str, *, by: str = "", reason: str = "", agent: str = ""
+) -> O.Outcome:
+    """Replace a decision. Never deletes one: how the architecture got here is the part
+    a rebuild most needs."""
+    log, _cfg, st = _load(repo, agent)
+    if item not in st.decisions:
+        return O.failed("decision.superseded", f"no such decision {item!r}", id=item)
+    if not by:
+        return O.failed(
+            "decision.superseded",
+            "--by <new decision id> is required: a decision is never simply deleted, "
+            "it is replaced by one that says what is true now.",
+            id=item,
+        )
+    log.append("decision.superseded", item, {"by": by, "reason": reason})
+    # Built directly: `reason` is a WIRE field here (why the decision was replaced) and
+    # also the Outcome's own, and the helpers refuse to guess which one you meant.
+    return O.Outcome(kind="decision.superseded", data={"id": item, "by": by, "reason": reason})
+
+
+def decision_show(repo: Path, item: str) -> O.Outcome:
+    """One decision in full. The wire body is the decision object itself."""
+    _log, _cfg, st = _load(repo)
+    d = st.decisions.get(item)
+    if not d:
+        return O.failed("decision.show", f"no such decision {item!r}", id=item, decision=None)
+    return O.ok("decision.show", id=item, decision=_plain(d))
+
+
+def decision_applicable(repo: Path, item: str) -> O.Outcome:
+    """Decisions governing an item's declared files.
+
+    Exit 2 when nothing governs it: "no decision applies" is an answer, and reporting
+    it as success is how a caller comes to believe it consulted something.
+    """
+    from ..core.schedule import conflicts
+
+    _log, _cfg, st = _load(repo)
+    it = st.items.get(item)
+    if it is None or it.removed:
+        gone = " (it was removed from the queue)" if it is not None else ""
+        return O.failed(
+            "decision.applicable",
+            f"no such item {item!r}{gone}",
+            id=item,
+            applicable=[],
+            project_wide=[],
+        )
+    hits = [d for d in st.decisions.values() if d.live and d.globs and conflicts(it.globs, d.globs)]
+    wide = [d for d in st.decisions.values() if d.live and not d.globs]
+    data: dict[str, Any] = {
+        "id": item,
+        "globs": list(it.globs),
+        "applicable": [_plain(d) for d in hits],
+        "project_wide": [_plain(d) for d in wide],
+    }
+    if not hits and not wide:
+        return O.nothing(
+            "decision.applicable",
+            f"No architectural decisions govern {item}'s files "
+            f"({', '.join(it.globs) or 'no globs declared'}).",
+            **data,
+        )
+    return O.ok("decision.applicable", **data)
+
+
+def decision_search(repo: Path, query: str, *, limit: int = 20) -> O.Outcome:
+    """Free-text search across decisions."""
+    log, cfg, _st = _load(repo)
+    hits = _store(repo, log, cfg).search("decisions", query, limit)
+    data: dict[str, Any] = {"query": query, "hits": hits, "count": len(hits)}
+    if not hits:
+        return O.nothing("decision.search", "no matching decisions", **data)
+    return O.ok("decision.search", **data)
+
+
+def decision_list(repo: Path, *, all: bool = False) -> O.Outcome:
+    """Decisions in force; `all` includes the superseded ones."""
+    _log, _cfg, st = _load(repo)
+    live = [d for d in st.decisions.values() if d.live]
+    dead = [d for d in st.decisions.values() if not d.live]
+    rows = live + dead if all else live
+    data: dict[str, Any] = {
+        "rows": [_plain(d) for d in sorted(rows, key=lambda x: x.at)],
+        "live": len(live),
+        # How many exist but were not shown -- so the human renderer can say so without
+        # folding a second time, and a machine caller can tell "none recorded" from
+        # "none in force".
+        "hidden": 0 if all else len(dead),
+        "all": all,
+    }
+    if not rows:
+        return O.nothing(
+            "decision.list",
+            "No architectural decisions recorded.\n"
+            "  ddflow decision add --title '...' --decision '...' --globs 'src/x/*'",
+            **data,
+        )
+    return O.ok("decision.list", **data)