agentforge-framework 0.2.0__tar.gz → 0.2.1__tar.gz

{agentforge_framework-0.2.0 → agentforge_framework-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentforge-framework
-Version: 0.2.0
+Version: 0.2.1
 Summary: A modular framework for coordinating specialized software agents.
 Author: Yash Mhatre
 License-Expression: Apache-2.0
@@ -20,7 +20,7 @@ Dynamic: license-file
 
 AgentForge is a standalone Python framework for coordinating specialized software agents through reusable workflows.
 
-A human states a Task. The Orchestrator files a GitHub issue carrying a frozen plan and the Roster of Roles that will execute it. `agentforge implement <n>` runs the Issue's Workflow and opens a draft pull request for a human to sign off. No workflow ever merges.
+A human states a Task. The Orchestrator grills them on it, writes a spec, cuts the spec into Slices, and files a GitHub issue for each -- every one carrying a frozen plan, the Roster of Roles that will execute it, and the issues that block it. `agentforge implement <n>` runs one Issue's Workflow and opens a draft pull request for a human to sign off. No workflow ever merges.
 
 ![An Issue carries the frozen plan and the Roster. Each Agent reads that Issue and appends its result as the Run Log. The Workflow ends at a draft pull request that only a human can merge.](docs/assets/one-issue-number.svg)
 
@@ -42,11 +42,26 @@ Answer them, or press Enter on an empty line to plan with what it has.
   Retry on 5xx only, or timeouts too?
   > both, cap it at three attempts
 
+This cuts into 1 Slice(s), each filed as its own issue:
+
+  1. Add a bounded retry to the orders loader  [retry]
+       Delivers: The orders loader retries a failed fetch up to three times.
+       Blocked by: nothing -- can start immediately
+       - A 5xx or a timeout is retried; a 4xx is not.
+
+Blockers are filed first, and a Slice waits for the ones it names.
+
+File these? [y/N] y
+
+Interview: 2 question(s) answered
+
 Filed issue #12: https://github.com/acme/pipelines/issues/12
+  Add a bounded retry to the orders loader
   Roster: implementer (standard)
-  Interview: 2 question(s) answered
 
-Run it with:  agentforge implement 12
+Start with:  agentforge implement 12
+
+  Cost: $0.41
 
 $ agentforge implement 12 --allow-commands
   [ok] implementer (standard) — Wrapped the fetch in a bounded retry.
@@ -127,9 +142,14 @@ without notice. See
 
 ## Install
 
-AgentForge publishes to no package index yet, so neither route below is
-`pip install agentforge-framework`. Both put the same `agentforge` command on
-your path.
+```console
+$ pip install agentforge-framework
+$ agentforge --version
+agentforge 0.2.1
+```
+
+That is the whole of it. The two routes below the naming note are for a machine
+that cannot reach PyPI, and for working on AgentForge itself.
 
 The distribution is `agentforge-framework` and it imports as
 `agentforge_framework`, because an older and larger project holds `agentforge`
@@ -143,15 +163,13 @@ other project installed, because its 0.5.0 through 0.6.5 declare an `agentforge`
 command too and whichever was installed last wins. See
 [ADR-0013](docs/adr/0013-the-name-stays-the-import-path-moves.md).
 
-**From a release wheel**, to run AgentForge against your own repositories.
-Download the wheel attached to the
-[latest release](https://github.com/yashmhatre/AgentForge/releases/latest) and
-install the file you downloaded:
+**From a release wheel**, for a machine with no route to PyPI. Every release
+attaches the same wheel and sdist that were uploaded to the index; download one
+from the [latest release](https://github.com/yashmhatre/AgentForge/releases/latest)
+and install the file:
 
 ```console
-$ pip install agentforge_framework-0.2.0-py3-none-any.whl
-$ agentforge --version
-agentforge 0.2.0
+$ pip install agentforge_framework-0.2.1-py3-none-any.whl
 ```
 
 Publishing a release is a wizard rather than a checklist:
@@ -170,6 +188,7 @@ $ cd AgentForge
 $ pip install -e ".[dev]"
 ```
 
+Step by step, with every command and flag: [docs/GUIDE.md](docs/GUIDE.md).
 What each release contains is in [CHANGELOG.md](CHANGELOG.md).
 
 ## Requirements
@@ -185,8 +204,9 @@ AgentForge never touches a model API and handles no credentials of its own. What
 
 | Command | What it does |
 | --- | --- |
-| `agentforge plan "<task>"` | Runs the Orchestrator at the `deep` tier and files an issue carrying the plan and roster. |
-| `agentforge implement <n>` | Reads Issue `<n>`, runs its Workflow on a branch, posts each Agent Result, and opens a draft PR. Add `--allow-commands` when the Workflow must execute a suite. |
+| `agentforge plan "<task>"` | Grills you on the task, writes a spec, cuts it into Slices, and files one issue per Slice carrying the plan, the roster, and the issues that block it. Add `--yes` to file without reviewing the cut. |
+| `agentforge decompose <path>` | The same pipeline over a plan document you already wrote. Use it when the plan is longer than a sentence and already lives in the repository. |
+| `agentforge implement <n>` | Reads Issue `<n>`, runs its Workflow on a branch, posts each Agent Result, and opens a draft PR. Refuses to start while an issue it declares as a blocker has not signed off; `--ignore-blockers` overrides. Add `--allow-commands` when the Workflow must execute a suite. |
 | `agentforge run [<command> args]` | Runs a chore a Plugin contributes -- `agentforge run scaffold-dbt-model orders` writes the files and exits. With no command name it lists what this repository has. No issue, no Run, no model involved. |
 | `agentforge unslop <file>` | Scans prose for machine-writing tells. Deterministic; no model involved. |
 

{agentforge_framework-0.2.0 → agentforge_framework-0.2.1}/README.md

@@ -2,7 +2,7 @@
 
 AgentForge is a standalone Python framework for coordinating specialized software agents through reusable workflows.
 
-A human states a Task. The Orchestrator files a GitHub issue carrying a frozen plan and the Roster of Roles that will execute it. `agentforge implement <n>` runs the Issue's Workflow and opens a draft pull request for a human to sign off. No workflow ever merges.
+A human states a Task. The Orchestrator grills them on it, writes a spec, cuts the spec into Slices, and files a GitHub issue for each -- every one carrying a frozen plan, the Roster of Roles that will execute it, and the issues that block it. `agentforge implement <n>` runs one Issue's Workflow and opens a draft pull request for a human to sign off. No workflow ever merges.
 
 ![An Issue carries the frozen plan and the Roster. Each Agent reads that Issue and appends its result as the Run Log. The Workflow ends at a draft pull request that only a human can merge.](docs/assets/one-issue-number.svg)
 
@@ -24,11 +24,26 @@ Answer them, or press Enter on an empty line to plan with what it has.
   Retry on 5xx only, or timeouts too?
   > both, cap it at three attempts
 
+This cuts into 1 Slice(s), each filed as its own issue:
+
+  1. Add a bounded retry to the orders loader  [retry]
+       Delivers: The orders loader retries a failed fetch up to three times.
+       Blocked by: nothing -- can start immediately
+       - A 5xx or a timeout is retried; a 4xx is not.
+
+Blockers are filed first, and a Slice waits for the ones it names.
+
+File these? [y/N] y
+
+Interview: 2 question(s) answered
+
 Filed issue #12: https://github.com/acme/pipelines/issues/12
+  Add a bounded retry to the orders loader
   Roster: implementer (standard)
-  Interview: 2 question(s) answered
 
-Run it with:  agentforge implement 12
+Start with:  agentforge implement 12
+
+  Cost: $0.41
 
 $ agentforge implement 12 --allow-commands
   [ok] implementer (standard) — Wrapped the fetch in a bounded retry.
@@ -109,9 +124,14 @@ without notice. See
 
 ## Install
 
-AgentForge publishes to no package index yet, so neither route below is
-`pip install agentforge-framework`. Both put the same `agentforge` command on
-your path.
+```console
+$ pip install agentforge-framework
+$ agentforge --version
+agentforge 0.2.1
+```
+
+That is the whole of it. The two routes below the naming note are for a machine
+that cannot reach PyPI, and for working on AgentForge itself.
 
 The distribution is `agentforge-framework` and it imports as
 `agentforge_framework`, because an older and larger project holds `agentforge`
@@ -125,15 +145,13 @@ other project installed, because its 0.5.0 through 0.6.5 declare an `agentforge`
 command too and whichever was installed last wins. See
 [ADR-0013](docs/adr/0013-the-name-stays-the-import-path-moves.md).
 
-**From a release wheel**, to run AgentForge against your own repositories.
-Download the wheel attached to the
-[latest release](https://github.com/yashmhatre/AgentForge/releases/latest) and
-install the file you downloaded:
+**From a release wheel**, for a machine with no route to PyPI. Every release
+attaches the same wheel and sdist that were uploaded to the index; download one
+from the [latest release](https://github.com/yashmhatre/AgentForge/releases/latest)
+and install the file:
 
 ```console
-$ pip install agentforge_framework-0.2.0-py3-none-any.whl
-$ agentforge --version
-agentforge 0.2.0
+$ pip install agentforge_framework-0.2.1-py3-none-any.whl
 ```
 
 Publishing a release is a wizard rather than a checklist:
@@ -152,6 +170,7 @@ $ cd AgentForge
 $ pip install -e ".[dev]"
 ```
 
+Step by step, with every command and flag: [docs/GUIDE.md](docs/GUIDE.md).
 What each release contains is in [CHANGELOG.md](CHANGELOG.md).
 
 ## Requirements
@@ -167,8 +186,9 @@ AgentForge never touches a model API and handles no credentials of its own. What
 
 | Command | What it does |
 | --- | --- |
-| `agentforge plan "<task>"` | Runs the Orchestrator at the `deep` tier and files an issue carrying the plan and roster. |
-| `agentforge implement <n>` | Reads Issue `<n>`, runs its Workflow on a branch, posts each Agent Result, and opens a draft PR. Add `--allow-commands` when the Workflow must execute a suite. |
+| `agentforge plan "<task>"` | Grills you on the task, writes a spec, cuts it into Slices, and files one issue per Slice carrying the plan, the roster, and the issues that block it. Add `--yes` to file without reviewing the cut. |
+| `agentforge decompose <path>` | The same pipeline over a plan document you already wrote. Use it when the plan is longer than a sentence and already lives in the repository. |
+| `agentforge implement <n>` | Reads Issue `<n>`, runs its Workflow on a branch, posts each Agent Result, and opens a draft PR. Refuses to start while an issue it declares as a blocker has not signed off; `--ignore-blockers` overrides. Add `--allow-commands` when the Workflow must execute a suite. |
 | `agentforge run [<command> args]` | Runs a chore a Plugin contributes -- `agentforge run scaffold-dbt-model orders` writes the files and exits. With no command name it lists what this repository has. No issue, no Run, no model involved. |
 | `agentforge unslop <file>` | Scans prose for machine-writing tells. Deterministic; no model involved. |
 

{agentforge_framework-0.2.0 → agentforge_framework-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentforge-framework"
-version = "0.2.0"
+version = "0.2.1"
 description = "A modular framework for coordinating specialized software agents."
 readme = "README.md"
 requires-python = ">=3.11"

{agentforge_framework-0.2.0 → agentforge_framework-0.2.1}/src/agentforge_framework/__init__.py

@@ -1,3 +1,3 @@
 """AgentForge — coordination of specialized software agents through reusable workflows."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"

agentforge_framework-0.2.1/src/agentforge_framework/agents/decomposer.py

@@ -0,0 +1,440 @@
+"""The Decomposer: a Task becomes a set of Issues, in dependency order.
+
+Every planning pass comes through here, whether the source was typed at a shell
+(`agentforge plan`) or read from a document the project already keeps
+(`agentforge decompose`). The two differ in where the text comes from and in
+nothing else, so there is one pipeline rather than a small one and a large one
+that drift apart.
+
+It does in four movements what a single Orchestrator pass used to do in one:
+
+- **Grill.** `grill-with-docs`, the same interview `agentforge plan` runs, aimed
+  at the document instead of a sentence. A plan document is longer than a Task
+  and no less ambiguous -- it records what its author decided and rarely what
+  they rejected, and it is the rejected alternatives that a Slice boundary turns
+  on.
+- **Spec.** `to-spec`, which synthesizes and does not interview. It has the
+  document and the grill transcript, and it commits to one reading of them.
+- **Cut.** `to-tickets`, which turns that reading into Slices: vertical, each
+  sized for one fresh context window, each naming the Slices that block it.
+- **Plan.** One ordinary Orchestrator planning pass per approved Slice, so that
+  what gets filed is an Issue like any other and `agentforge implement` learns
+  nothing new.
+
+Four stages rather than one prompt because they are four jobs, and a single pass
+asked to interview and commit to a breakdown at once commits to the breakdown it
+had before it asked. The cut is shown to the human before anything is filed:
+fifteen wrong Issues take longer to close than one wrong plan takes to reject.
+
+See ADR-0021.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+from ..core.contracts import (
+    AgentResult,
+    ContextPack,
+    ModelTier,
+    Outcome,
+    PlanDocument,
+    Slice,
+    Task,
+)
+from ..core.plan_format import (
+    SLICES_CLOSE,
+    SLICES_OPEN,
+    SPEC_CLOSE,
+    SPEC_OPEN,
+    PlanFormatError,
+    extract_slices,
+    extract_spec,
+    order_slices,
+)
+from .orchestrator import (
+    ORCHESTRATOR,
+    Exchange,
+    Interviewer,
+    Orchestrator,
+    render_transcript,
+)
+
+#: The skill each stage is delivered. One per stage, and never two: a pass given
+#: both `to-spec` and `to-tickets` has been handed the method for a job it is not
+#: doing yet, and both skills end by publishing to a tracker.
+SPEC_SKILLS = ("to-spec",)
+SLICE_SKILLS = ("to-tickets",)
+
+#: Slices one document may be cut into. Past this the breakdown is not a
+#: breakdown, it is the plan re-typed, and no human is reading forty of them
+#: before approving. The cut is asked to merge rather than truncated, because a
+#: list cut off at the cap silently drops the end of the plan.
+MAX_SLICES = 25
+
+SPEC = """\
+You are the Orchestrator in AgentForge, synthesizing what a human gave you into \
+a spec that one breakdown pass can cut into work.
+
+Do not interview. The questions have been asked; what came back is below, and it \
+is part of the source now. Where the source and an answer disagree, the answer \
+is later and wins. Where neither settles something, say so in the spec rather \
+than choosing quietly -- an unresolved question named in a spec gets resolved, \
+and one you resolved by yourself gets discovered during implementation.
+
+## What the human gave you
+
+{source}
+
+{document}
+{interview}
+## The repository
+
+You are running in {cwd}. Read whatever you need in order to synthesize \
+accurately -- existing structure, conventions, tests, and any CONTEXT.md, \
+AGENTS.md, or docs/adr/ the project keeps. Use the project's own vocabulary \
+throughout. Do not change any files. This is a synthesis pass.
+
+## What you do not do
+
+You have no issue tracker and no triage labels. AgentForge files every Issue \
+itself, later, through its own GitHub boundary, and this pass files nothing. Do \
+not publish the spec, do not open an issue, and do not apply a label.
+
+## Required output
+
+End your reply with this block and nothing after it. Markdown inside it, not \
+JSON:
+
+{spec_open}
+## Problem Statement
+...
+
+## Solution
+...
+
+## User Stories
+...
+
+## Implementation Decisions
+...
+
+## Testing Decisions
+...
+
+## Out of Scope
+...
+{spec_close}
+
+Cover the whole source. Anything in it that reaches no user story reaches no \
+Issue and does not get built. Scale the spec to what you were given: a \
+one-sentence Task earns a short spec, and padding one out invents scope nobody \
+asked for.\
+"""
+
+SLICES = """\
+You are the Orchestrator in AgentForge, cutting a spec into the Slices that will \
+be filed as Issues.
+
+A Slice is a tracer bullet: a narrow but complete path through every layer the \
+work touches, demoable or verifiable on its own. It is not a layer -- "the \
+schema changes" is not a Slice, and neither is "the tests".
+
+Two rules decide the size:
+
+- **One Slice is one fresh context window.** Each will be planned and executed \
+by an Agent that has never seen this spec, starting from nothing and stopping \
+when it opens a pull request. A Slice it cannot finish in one sitting is one it \
+finishes badly.
+- **Together the Slices are the whole spec.** Every user story lands in exactly \
+one. Anything the spec put out of scope stays out.
+
+A wide refactor is the exception to cutting vertically. Where one mechanical \
+change fans across the codebase and no vertical slice can land green, sequence \
+it expand-migrate-contract instead: add the new form beside the old, migrate the \
+call sites in batches each blocked by the expand, then delete the old form in a \
+Slice blocked by every batch.
+
+Give each Slice the Slices that must be finished before it can start. A Slice \
+with no blockers can start immediately, and there must be at least one of those \
+or nothing can begin. Do not invent an edge to express a preference: an edge \
+means the later Slice genuinely cannot be built until the earlier one is, and \
+every edge you add is a Slice that cannot run beside another.
+
+Cut as many Slices as the spec has work in it and no more. A spec that is \
+genuinely one sitting's work cuts to one Slice, and manufacturing a breakdown \
+for it files Issues nobody needed and puts edges between them. Never cut more \
+than {cap}: if the spec seems to need more, the Slices are too small, so merge \
+the ones that share a seam rather than dropping any of the spec.
+
+## The spec
+
+{spec}
+
+## The repository
+
+You are running in {cwd}. Read whatever you need. Title each Slice in the \
+project's own vocabulary. Do not change any files.
+
+## What you do not do
+
+You have no issue tracker and no triage labels. AgentForge files these itself, \
+in the order your blocking edges imply, through its own GitHub boundary. Do not \
+publish anything, do not open an issue, and do not apply a label.
+
+## Required output
+
+End your reply with this block and nothing after it:
+
+{slices_open}
+```json
+{{
+  "slices": [
+    {{
+      "id": "a short slug, unique, referenced by other slices",
+      "title": "what a human reads in a list of thirty issues",
+      "delivers": "the end-to-end behaviour this Slice makes work, from the user's perspective, not a layer-by-layer implementation list",
+      "acceptance": ["how this Slice is known to be done, checkable by reading the repository"],
+      "blocked_by": ["the ids of the Slices that must finish first, or an empty list"]
+    }}
+  ]
+}}
+```
+{slices_close}\
+"""
+
+#: What one approved Slice looks like when it is handed to a planning pass. The
+#: Spec travels with it: the Slice says what to build and the Spec says what the
+#: rest of the work is, which is how a planning pass knows what not to build
+#: here. The blockers are named because a Slice that assumes work an earlier one
+#: does should say so rather than repeating it.
+SLICE_TASK = """\
+{delivers}
+
+This is one Slice of a larger plan, filed as its own Issue. Plan this Slice and \
+nothing else: the rest of the plan is other Issues, and work you do here that \
+belongs to one of them is work done twice.
+
+## Acceptance criteria for this Slice
+
+{acceptance}
+
+## What is already done when this starts
+
+{blockers}
+
+## The wider spec, for context only
+
+Everything below is the whole plan. It is here so that you know where this Slice \
+sits and what it must not duplicate. Do not plan any of it.
+
+{spec}\
+"""
+
+
+@dataclass(frozen=True)
+class Filed:
+    """One Slice, once a planning pass has turned it into something fileable."""
+
+    slice: Slice
+    document: PlanDocument
+    #: Issue numbers, filled in by the runtime as blockers are filed. A Slice
+    #: names its blockers by id; only the runtime knows what number each got.
+    blocked_by: tuple[int, ...] = ()
+
+
+@dataclass(frozen=True)
+class Decomposed:
+    """What a decomposition pass produced, or the reason there is nothing."""
+
+    #: Every invocation the pass made, in order, so the caller can price it and
+    #: say which stage stopped when one did.
+    results: tuple[AgentResult, ...] = ()
+    spec: str = ""
+    slices: tuple[Slice, ...] = ()
+    interview: tuple[Exchange, ...] = ()
+    #: Set when a stage did not produce what the next one needs. The pass stops
+    #: there; nothing is filed.
+    failure: AgentResult | None = None
+
+    @property
+    def ok(self) -> bool:
+        return self.failure is None and bool(self.slices)
+
+
+class Decomposer:
+    """Runs the stages that turn one document into an approved breakdown."""
+
+    def __init__(self, provider, tier: ModelTier | None = None) -> None:
+        self.provider = provider
+        self.tier = tier or ORCHESTRATOR.tier
+
+    # --- the stages --------------------------------------------------------
+
+    def _invoke(self, skills: Sequence[str], prompt: str, cwd: Path) -> AgentResult:
+        role = replace(ORCHESTRATOR.at_tier(self.tier), skills=tuple(skills))
+        return self.provider.invoke(
+            role=role, prompt=prompt, context=ContextPack(), tier=self.tier, cwd=cwd
+        )
+
+    def synthesize(
+        self, document: str, source: str, cwd: Path, exchanges: Sequence[Exchange] = ()
+    ) -> AgentResult:
+        interview = ""
+        if exchanges:
+            interview = (
+                "\n## What the human told you when you asked\n\n"
+                + render_transcript(exchanges)
+                + "\n\nThese answers are part of the plan now.\n"
+            )
+        return self._invoke(
+            SPEC_SKILLS,
+            SPEC.format(
+                document=document.strip(),
+                source=source,
+                interview=interview,
+                cwd=cwd,
+                spec_open=SPEC_OPEN,
+                spec_close=SPEC_CLOSE,
+            ),
+            cwd,
+        )
+
+    def cut(self, spec: str, cwd: Path) -> AgentResult:
+        return self._invoke(
+            SLICE_SKILLS,
+            SLICES.format(
+                spec=spec.strip(),
+                cwd=cwd,
+                cap=MAX_SLICES,
+                slices_open=SLICES_OPEN,
+                slices_close=SLICES_CLOSE,
+            ),
+            cwd,
+        )
+
+    # --- the pass ----------------------------------------------------------
+
+    def decompose(
+        self,
+        document: str,
+        source: str,
+        cwd: Path,
+        interviewer: Interviewer | None = None,
+    ) -> Decomposed:
+        """Grill, synthesize, cut. Nothing here files anything.
+
+        Each stage stops the pass rather than degrading into the next one. A
+        breakdown cut from a spec that was never written is a breakdown of
+        whatever the model remembered of the document, which is the one failure
+        that would not look like a failure.
+        """
+        task = Task(statement=document)
+        exchanges = (
+            Orchestrator(self.provider, tier=self.tier).interview(task, cwd, interviewer)
+            if interviewer
+            else ()
+        )
+
+        spec_result = self.synthesize(document, source, cwd, exchanges)
+        results: tuple[AgentResult, ...] = (spec_result,)
+        if spec_result.outcome is not Outcome.COMPLETED:
+            return Decomposed(results=results, interview=exchanges, failure=spec_result)
+
+        try:
+            spec = extract_spec(spec_result.raw)
+        except PlanFormatError as exc:
+            return Decomposed(
+                results=results,
+                interview=exchanges,
+                failure=_failed(
+                    self.tier, f"the synthesis pass wrote no usable spec: {exc}", spec_result
+                ),
+            )
+
+        cut_result = self.cut(spec, cwd)
+        results += (cut_result,)
+        if cut_result.outcome is not Outcome.COMPLETED:
+            return Decomposed(results=results, spec=spec, interview=exchanges, failure=cut_result)
+
+        try:
+            slices = order_slices(extract_slices(cut_result.raw))
+        except PlanFormatError as exc:
+            return Decomposed(
+                results=results,
+                spec=spec,
+                interview=exchanges,
+                failure=_failed(
+                    self.tier, f"the breakdown pass wrote no usable slices: {exc}", cut_result
+                ),
+            )
+
+        if len(slices) > MAX_SLICES:
+            return Decomposed(
+                results=results,
+                spec=spec,
+                interview=exchanges,
+                failure=_failed(
+                    self.tier,
+                    f"the breakdown pass cut {len(slices)} Slices against a cap of "
+                    f"{MAX_SLICES}; the plan document wants splitting before it is decomposed",
+                    cut_result,
+                ),
+            )
+
+        return Decomposed(results=results, spec=spec, slices=slices, interview=exchanges)
+
+
+def slice_task(one: Slice, spec: str, blockers: Sequence[Slice] = ()) -> Task:
+    """One Slice, phrased as the Task a planning pass is given."""
+    acceptance = "\n".join(f"- {criterion}" for criterion in one.acceptance) or (
+        "- None stated. Write acceptance criteria the executing Role can check."
+    )
+    done = "\n".join(
+        f"- {blocker.title}: {blocker.delivers}".rstrip(": ") for blocker in blockers
+    ) or "- Nothing. This Slice starts from the repository as it is."
+
+    return Task(
+        statement=SLICE_TASK.format(
+            delivers=(one.delivers or one.title).strip(),
+            acceptance=acceptance,
+            blockers=done,
+            spec=spec.strip(),
+        )
+    )
+
+
+def render_breakdown(slices: Sequence[Slice]) -> list[str]:
+    """The cut, as the human is shown it before anything is filed."""
+    by_id = {one.id: one for one in slices}
+    lines: list[str] = []
+    for index, one in enumerate(slices, start=1):
+        lines.append(f"{index}. {one.title}  [{one.id}]")
+        if one.delivers:
+            lines.append(f"     Delivers: {one.delivers}")
+        blockers = ", ".join(by_id[b].title for b in one.blocked_by if b in by_id)
+        lines.append(f"     Blocked by: {blockers or 'nothing -- can start immediately'}")
+        for criterion in one.acceptance:
+            lines.append(f"     - {criterion}")
+    return lines
+
+
+def _failed(tier: ModelTier, summary: str, source: AgentResult) -> AgentResult:
+    """A stage that answered, but not in the shape the next stage needs."""
+    return AgentResult(
+        role=ORCHESTRATOR.name,
+        tier=tier,
+        outcome=Outcome.FAILED,
+        summary=summary,
+        detail=source.raw,
+        raw=source.raw,
+        usage=source.usage,
+    )
+
+
+#: The human, as a callable, answering once. `None` where nobody is attached --
+#: and there the breakdown is not filed, because approving fifteen Issues on
+#: somebody's behalf is not a default worth having.
+Approver = Callable[[Sequence[Slice]], bool]