@giamme/forge 0.0.0-stage → 0.8.0

package/scripts/forge_jev/coupling.py

@@ -0,0 +1,244 @@
+"""Plan-time semantic wave coupling.
+
+`compute_waves` bounds parallelism structurally: two tasks share a wave only when their
+declared `files` are disjoint. Disjointness is blind to the conflict where task A changes
+an interface task B consumes -- both diffs pass review against their own baseline, and the
+merge is broken (see questions.wave_coupling). This asks about every pair `compute_waves`
+would actually run concurrently, before the wave runs, so the warning still lands while the
+plan can change.
+
+Nothing here writes to tasks.tsv or waves.tsv. Scoring is advisory and silent in shadow
+mode, exactly like routing.py and gates.py.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from . import threshold
+from .client import ask, noul
+from .questions import forward_dependency, wave_coupling
+
+# A wave of 12 tasks is 66 pairs; a plan-time gate must not become the slowest thing in
+# `forge plan`. Sorted before truncation (see pairs()) so the same plan always produces
+# the same capped set.
+MAX_PAIRS = 60
+
+# How many pairs a plan may warn about, however many clear the threshold.
+#
+# Rank is the signal here, not the absolute value. Over 11 pairs with known outcomes the
+# genuinely coupled ones took 4 of the top 5 places, but the absolute scores moved with
+# the plan: the same rubric put the whole distribution at 0.09-0.27 in one measurement
+# and 0.20-0.38 on the live 8-task plan. At a fixed 0.20 that live plan warned about 12
+# of its 21 pairs, and a gate that fires on more than half of everything teaches people
+# to ignore it -- which is the argument this file's own threshold comment makes about
+# using one number for several rubrics.
+#
+# So the threshold decides whether anything is worth saying and the ordering decides
+# what gets said. Three is what fits in a plan summary a human will actually read.
+MAX_WARNINGS = 3
+
+
+# Cross-wave pairs get their own budget rather than sharing MAX_PAIRS: a plan with one
+# big first wave would otherwise spend the whole allowance inside it and never ask the
+# ordering question at all, which is the one that shipped a defect.
+MAX_FORWARD_PAIRS = 40
+
+PROMPT_CHARS = 2500
+
+
+def parse_tasks(plan: Path) -> dict[str, dict]:
+    """id -> {id, title, files, deps, difficulty, prompt}, skipping comments and malformed rows."""
+    path = plan / 'tasks.tsv'
+    tasks = {}
+    try:
+        lines = path.read_text(errors='replace').splitlines()
+    except OSError:
+        return tasks
+    for line in lines:
+        if not line.strip() or line.startswith('#'):
+            continue
+        parts = line.split('\t')
+        if len(parts) < 7:
+            continue
+        task_id, deps, difficulty, files, _dwarf, _qa, title = parts[:7]
+        if not task_id:
+            continue
+        # The requirements, not the implementation. An interface dependency between two
+        # tasks is written down here and nowhere else -- certainly not in a one-line
+        # title, which is all this rubric used to get.
+        prompt = ''
+        prompt_file = plan / 'tasks' / task_id / 'prompt.md'
+        try:
+            if prompt_file.is_file():
+                prompt = prompt_file.read_text(errors='replace')[:PROMPT_CHARS]
+        except OSError:
+            prompt = ''
+        tasks[task_id] = dict(id=task_id, title=title, files=files, deps=deps,
+                              difficulty=difficulty, prompt=prompt)
+    return tasks
+
+
+def parse_waves(plan: Path) -> dict[str, list[str]]:
+    """wave number (as it appears in waves.tsv) -> ordered list of task ids."""
+    path = plan / 'waves.tsv'
+    waves: dict[str, list[str]] = {}
+    try:
+        lines = path.read_text(errors='replace').splitlines()
+    except OSError:
+        return waves
+    for line in lines:
+        parts = line.split('\t')
+        if len(parts) < 2:
+            continue
+        wave, task_id = parts[0], parts[1]
+        if not wave or not task_id:
+            continue
+        waves.setdefault(wave, []).append(task_id)
+    return waves
+
+
+def pairs(tasks: dict, waves: dict) -> list[tuple[str, str]]:
+    """Every same-wave task pair with both ids known, capped at MAX_PAIRS.
+
+    Sorted before truncation, same reasoning as gates.candidates: an unstable slice would
+    make the same plan warn about a different subset of pairs on two runs.
+    """
+    found = []
+    for ids in waves.values():
+        ordered = sorted(i for i in ids if i in tasks)
+        for i, first in enumerate(ordered):
+            for second in ordered[i + 1:]:
+                found.append((first, second))
+    found.sort()
+    return found[:MAX_PAIRS]
+
+
+def _wave_order(waves: dict) -> dict[str, int]:
+    """Task id -> wave position. Waves are numbered as strings in waves.tsv; sort them
+    numerically where possible so '10' follows '9' rather than '1'."""
+    def key(name):
+        try:
+            return (0, int(name))
+        except ValueError:
+            return (1, name)
+
+    order = {}
+    for position, wave in enumerate(sorted(waves, key=key)):
+        for task_id in waves[wave]:
+            order[task_id] = position
+    return order
+
+
+def forward_pairs(tasks: dict, waves: dict) -> list[tuple[str, str]]:
+    """Ordered (earlier, later) pairs across waves that nothing forces to be safe.
+
+    `pairs()` only looks inside a wave, so "task A is written against an interface task B
+    builds later" was structurally outside this gate's reach -- and that is what shipped:
+    jevscope's `readme` ran in wave 1 documenting the CLI that wave 2 built, passed its
+    own review, and described an interface nobody ever wrote.
+
+    A declared dependency is excluded, in the direction that matters: if LATER is named
+    in EARLIER's deps, forge would not have placed EARLIER first, so the pair cannot
+    arise. Nothing else about wave placement makes the order safe.
+    """
+    order = _wave_order(waves)
+    found = []
+    for earlier in sorted(tasks):
+        for later in sorted(tasks):
+            if earlier == later:
+                continue
+            if earlier not in order or later not in order:
+                continue
+            if order[earlier] >= order[later]:
+                continue
+            declared = {d.strip() for d in str(tasks[earlier].get('deps', '')).split(',')}
+            if later in declared:
+                continue
+            found.append((earlier, later))
+    found.sort()
+    return found[:MAX_FORWARD_PAIRS]
+
+
+def forward_dependencies(repo, *, tasks, waves, run_dir=None, config: dict | None = None):
+    """Earlier-wave tasks Jev thinks were written against work that lands later.
+
+    Same contract as coupled_pairs: [(earlier, later, probability), ...] highest first,
+    [] for "nothing to say", None for "no judgment could be made".
+    """
+    by_id = {t['id']: t for t in tasks if isinstance(t, dict) and t.get('id')}
+    candidates = forward_pairs(by_id, waves)
+    if not candidates:
+        return []
+
+    questions = {}
+    for i, (earlier, later) in enumerate(candidates):
+        earlier_desc = f"{earlier} ({by_id[earlier]['title']}) files: {by_id[earlier]['files']}"
+        later_desc = f"{later} ({by_id[later]['title']}) files: {by_id[later]['files']}"
+        questions[f'f{i}'] = forward_dependency(earlier_desc, later_desc)
+
+    involved = sorted({task_id for pair in candidates for task_id in pair})
+    state = dict(tasks=[dict(id=by_id[i]['id'], title=by_id[i]['title'],
+                             files=by_id[i]['files'],
+                             requirements=by_id[i].get('prompt', ''))
+                        for i in involved])
+    result = ask(state, questions, site='jev-forward', run_dir=run_dir, config=config)
+    if result is None:
+        return None
+
+    warn_at = threshold('forward_warn', config=config)
+    found = []
+    for i, (earlier, later) in enumerate(candidates):
+        probability = noul(result, f'f{i}')
+        if probability is not None and probability >= warn_at:
+            found.append((earlier, later, probability))
+    found.sort(key=lambda row: (-row[2], row[0], row[1]))
+    return found[:MAX_WARNINGS]
+
+
+def coupled_pairs(repo, *, tasks, waves, run_dir=None, config: dict | None = None):
+    """Same-wave task pairs Jev thinks would still conflict once merged.
+
+    `tasks` is a list of dicts with id/title/files/difficulty; `waves` maps a wave number
+    to the list of task ids placed in it -- the same shapes `compute_waves` produces.
+    Returns [(id_a, id_b, probability), ...] at or above threshold('gate_warn'), highest
+    probability first. Returns [] when there is nothing to warn about and None when no
+    judgment could be made, so a caller can tell "no coupling found" from "Jev did not
+    answer".
+    """
+    by_id = {t['id']: t for t in tasks if isinstance(t, dict) and t.get('id')}
+    candidate_pairs = pairs(by_id, waves)
+    if not candidate_pairs:
+        return []
+
+    questions = {}
+    for i, (first, second) in enumerate(candidate_pairs):
+        first_desc = f"{first} ({by_id[first]['title']}) files: {by_id[first]['files']}"
+        second_desc = f"{second} ({by_id[second]['title']}) files: {by_id[second]['files']}"
+        questions[f'p{i}'] = wave_coupling(first_desc, second_desc)
+
+    # No file CONTENTS in state -- the rubric asks about interfaces between tasks, not
+    # implementations, and sending diffs nobody wrote yet would only add noise and cost.
+    # The task's requirements are a different thing, and they are where an interface
+    # dependency is actually written down. Without them this rubric had no signal at all:
+    # measured over 11 pairs with known outcomes, the two that produced a defect that
+    # really shipped scored LOWEST of everything, below pairs that were unrelated. With
+    # them, 4 of the 5 coupled pairs rank above every independent one.
+    #
+    # Only the tasks appearing in a candidate pair are sent, not the whole plan.
+    involved = sorted({task_id for pair in candidate_pairs for task_id in pair})
+    state = dict(tasks=[dict(id=by_id[i]['id'], title=by_id[i]['title'],
+                             files=by_id[i]['files'],
+                             requirements=by_id[i].get('prompt', ''))
+                        for i in involved])
+    result = ask(state, questions, site='jev-coupling', run_dir=run_dir, config=config)
+    if result is None:
+        return None
+
+    warn_at = threshold('coupling_warn', config=config)
+    found = []
+    for i, (first, second) in enumerate(candidate_pairs):
+        probability = noul(result, f'p{i}')
+        if probability is not None and probability >= warn_at:
+            found.append((first, second, round(probability, 3)))
+    found.sort(key=lambda item: item[2], reverse=True)
+    return found[:MAX_WARNINGS]

package/scripts/forge_jev/features.py

@@ -0,0 +1,24 @@
+"""Plain numeric features of a task, for a decision model that reads a routing state.
+
+A task's size is the strongest regime signal in forge's run history: the median prompt of
+the newest runs is twice the older ones' and their first-pass rate is half. A model reading
+prose and a 40-entry sibling list can only estimate that, so the state spells it out.
+
+The dataset export adds this block to the routing state it trains on. Hosted Jev's live
+request does not carry it (changing that request changes every fixture key), so a local
+model wired in later must send the same block, with the exact plan size and decompose
+level: the live state caps siblings at 40 and has no level. No I/O here; callers pass values.
+"""
+from __future__ import annotations
+
+
+def _count(value) -> int:
+    if isinstance(value, (list, tuple)):
+        return len([v for v in value if v])
+    return len([w for w in str(value or '').replace(',', ' ').split() if w and w != '-'])
+
+
+def task_size(*, prompt: str, declared_files, plan_tasks: int, deps, decompose_level: str | None) -> dict:
+    return dict(prompt_chars=len(prompt or ''), declared_files=_count(declared_files),
+                plan_tasks=int(plan_tasks), deps=_count(deps),
+                decompose_level=decompose_level if decompose_level in ('low', 'medium', 'high') else None)

package/scripts/forge_jev/gates.py

@@ -0,0 +1,100 @@
+"""Plan-time `files` drift prediction.
+
+`decompose.md` calls the `files` column "a promise, not a prediction": a task that edits
+a file it never declared breaks wave disjointness, which is the only thing bounding
+parallelism. Forge already detects this, but afterwards, in `drift.txt` -- by which point
+the wave has run. Asking at plan time converts a post-mortem into a warning while the
+plan can still change.
+
+Measured before shipping (see references/jev.md): at the default `gate_warn` of 0.60 this
+rubric scored precision 1.000 on one repo and 0.934 on another, over 50 commits. Precision
+is the number that matters here -- a warning that fires on files nobody edits teaches
+people to ignore every future warning.
+"""
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from . import threshold
+from .client import ask, noul
+from .questions import drift_prediction
+
+# One request per task holds this many questions comfortably, and a plan-time gate must
+# not turn into the slowest thing in `forge plan`.
+CANDIDATE_CAP = 120
+
+# Files nobody means when they say "did this task edit something it did not declare".
+_SKIP_PREFIXES = ('.git/', '.forge/', 'node_modules/', 'vendor/', 'target/', 'dist/',
+                  'build/', '.venv/', 'venv/', '__pycache__/')
+_SKIP_SUFFIXES = ('.lock', '.min.js', '.map', '.png', '.jpg', '.jpeg', '.gif', '.svg',
+                  '.ico', '.pdf', '.zip', '.woff', '.woff2', '.ttf')
+# Lockfiles whose name the suffix list cannot catch. They are generated, enormous, and
+# genuinely do change whenever dependencies do, which is what would make a drift warning
+# about them both technically true and completely useless.
+_SKIP_NAMES = ('package-lock.json', 'npm-shrinkwrap.json', 'composer.lock',
+               'Gemfile.lock', 'go.sum', 'pnpm-lock.yaml', 'yarn.lock')
+
+
+def _tracked(repo: Path) -> list[str]:
+    try:
+        out = subprocess.run(['git', '-C', str(repo), 'ls-files', '-z'],
+                             capture_output=True, text=True, timeout=20)
+    except (OSError, subprocess.SubprocessError):
+        return []
+    if out.returncode != 0:
+        return []
+    return [name for name in out.stdout.split('\0') if name]
+
+
+def candidates(repo, declared: str) -> list[str]:
+    """Tracked files the task does NOT declare, capped.
+
+    Sorted before truncation so the slice is deterministic: an unstable candidate set
+    would make the same plan warn differently on two runs.
+    """
+    owned = set((declared or '').replace(',', ' ').split())
+    found = []
+    for name in sorted(_tracked(Path(repo))):
+        if name in owned:
+            continue
+        if name.startswith(_SKIP_PREFIXES) or name.endswith(_SKIP_SUFFIXES):
+            continue
+        if name.rsplit('/', 1)[-1] in _SKIP_NAMES:
+            continue
+        found.append(name)
+        if len(found) >= CANDIDATE_CAP:
+            break
+    return found
+
+
+def predict_drift(repo, *, goal: str, task_id: str, title: str, declared: str,
+                  approach: str = '', prompt: str = '', run_dir=None,
+                  config: dict | None = None):
+    """Undeclared files this task looks likely to edit, highest probability first.
+
+    Returns [] when there is nothing to say and None when no judgment could be made, so
+    a caller can tell "no drift predicted" from "Jev did not answer".
+    """
+    pool = candidates(repo, declared)
+    if not pool:
+        return []
+    questions = {f'f{i}': drift_prediction(name) for i, name in enumerate(pool)}
+    # Which files a task will really touch is stated in its requirements far more often
+    # than in its title -- "extend tests/test_events.py" is in the prompt, not the title.
+    state = dict(goal=goal, task=dict(id=task_id, title=title, declared_files=declared),
+                 prompt=prompt, approach=approach)
+    result = ask(state, questions, site='jev-drift', run_dir=run_dir, config=config)
+    if result is None:
+        return None
+
+    # drift_warn reads gate_warn until a model has its own measured value: a cutoff fitted
+    # to one model's probabilities is not a cutoff on another's.
+    warn_at = threshold('drift_warn', config=config, model=result.get('model'))
+    predicted = []
+    for i, name in enumerate(pool):
+        probability = noul(result, f'f{i}')
+        if probability is not None and probability >= warn_at:
+            predicted.append((name, round(probability, 3)))
+    predicted.sort(key=lambda item: item[1], reverse=True)
+    return predicted

package/scripts/forge_jev/memory.py

@@ -0,0 +1,163 @@
+"""Curation of what reaches `.forge/memory.md`.
+
+The stakes are asymmetric, and that shapes every default here. `memory.md` is injected
+into every dispatch of every future run, so a wrong fact is paid for forever and gets
+corrected only when a human happens to read it. The ledger is append-only and never
+injected, so **nothing recorded is ever lost** -- this gates injection, not recording.
+
+That asymmetry is why each judgment below fails toward today's behaviour rather than
+toward acting: an unreachable API, a missing key, a malformed answer and a disabled
+capability all leave the model's own category and key exactly as they were.
+"""
+from __future__ import annotations
+
+from . import threshold
+from .client import ask, choice, noul
+from .questions import memory_category, memory_durable, memory_same_fact
+
+CATEGORIES = ('verify', 'trap', 'finding')
+
+# Enough context to match a paraphrase without turning one dispatch's bookkeeping into
+# the largest request in the run.
+MAX_EXISTING = 40
+MAX_TEXT = 500
+
+
+def curate(*, category: str, text: str, existing=None, run_dir=None,
+           config: dict | None = None) -> dict | None:
+    """Three judgments in one request: is it a duplicate, is it durable, is it filed right.
+
+    Returns None when nothing could be judged, which callers must treat as "keep what the
+    model said". The returned dict carries only *suggestions*; `key` is None unless a
+    paraphrase was matched confidently enough to merge.
+    """
+    text = (text or '').strip()[:MAX_TEXT]
+    if not text:
+        return None
+    entries = [line for line in (existing or []) if line][:MAX_EXISTING]
+
+    questions = dict(durable=memory_durable(text), category=memory_category(text))
+    if entries:
+        # Choice needs at least two options; with no existing entries there is nothing
+        # to be a duplicate of, so the question is not worth asking.
+        questions['same'] = memory_same_fact(text, entries)
+
+    result = ask(dict(recorded=text, existing=entries), questions,
+                 site='jev-memory-curate', run_dir=run_dir, config=config)
+    if result is None:
+        return None
+
+    durable = noul(result, 'durable')
+    suggested, category_confidence = choice(result, 'category')
+    matched, match_confidence = (choice(result, 'same') if entries else (None, None))
+
+    out = dict(durable=durable, category=category, key=None, matched=None,
+               suggested_category=suggested, category_confidence=category_confidence)
+
+    # A paraphrase only merges above the threshold. Merging two facts that merely look
+    # alike loses one of them permanently, while a duplicate is only untidy -- so the
+    # bar sits on the side of keeping both.
+    if (matched and matched != 'none' and match_confidence is not None
+            and match_confidence >= threshold('memory_merge', config=config)):
+        out['matched'] = matched
+        out['match_confidence'] = match_confidence
+
+    # Category is corrected only toward a real category. 'none' means the model could not
+    # place it, which is a reason to leave the recorded category alone, not to discard it.
+    if (suggested in CATEGORIES and suggested != category
+            and category_confidence is not None
+            and category_confidence >= threshold('memory_recategorize', config=config)):
+        out['category'] = suggested
+
+    # The quality gate. Silence is the safe direction: a rejected line still lands in the
+    # ledger in full, so the only thing lost is injection into future prompts.
+    out['injectable'] = not (durable is not None and durable < threshold('gate_warn', config=config))
+
+    # A line that merged onto an existing entry is exempt, and the two judgments have to
+    # be read together to see why. `rebuild` skips a non-injectable row before it counts
+    # anything, and a `finding` needs two DISTINCT runs before it is promoted -- which is
+    # the whole reason dedup exists, since two runs wording one fact differently would
+    # otherwise never reach two. So a restatement judged not durable is dropped from the
+    # count of the fact it restates, defeating dedup in exactly the case it was built for.
+    #
+    # Measured: paraphrases score 0.44-0.83 on durability against 0.82-0.83 for the same
+    # facts stated fresh -- a restatement reads as less durable than the thing it
+    # restates, which is the wrong question. The entry it matched is already in
+    # memory.md, so its durability was settled when that entry was written; a line
+    # matching it is by definition not the one-off observation this gate is for.
+    if out['matched']:
+        out['injectable'] = True
+    return out
+
+
+# The number of facts a single dispatch is likely to act on. The existing 40-line / 4KB
+# cap stays the outer bound -- this only narrows within it, and never adds a line.
+SLICE_KEEP = 8
+FILE_CHARS = 4000
+
+
+def still_true(*, text: str, anchor_path, run_dir=None, config: dict | None = None):
+    """Has this fact gone false while the file it points at still exists?
+
+    Path-anchor staleness already drops an entry whose file was deleted. This catches
+    the other case: the file is still there and the fact about it stopped being true.
+    Returns None when nothing could be judged, which must be read as "keep the entry" --
+    dropping a fact on a failed request would quietly erase memory over time.
+    """
+    from .questions import memory_still_true
+    from pathlib import Path
+
+    try:
+        content = Path(anchor_path).read_text(errors='replace')[:FILE_CHARS]
+    except OSError:
+        return None
+    if not (text or '').strip():
+        return None
+    result = ask(dict(fact=text, file=str(anchor_path)),
+                 dict(still=memory_still_true(text, content)),
+                 site='jev-memory-stale', run_dir=run_dir, config=config)
+    if result is None:
+        return None
+    probability = noul(result, 'still')
+    if probability is None:
+        return None
+    # Its own threshold, well below gate_warn. Measured over six facts against real
+    # files: ones that had genuinely gone false scored 0.03-0.10, ones still true scored
+    # 0.47-0.96. gate_warn's 0.60 sits inside the true range and would have deleted a
+    # fact the file still supports. Dropping a fact is irreversible and silent, while
+    # keeping a stale one costs a line until someone notices, so the bar sits low enough
+    # that only a confident "this went false" acts.
+    return dict(probability=probability,
+                stale=probability < threshold('stale_drop', config=config))
+
+
+def relevant_lines(*, task: str, lines: list, keep: int = SLICE_KEEP,
+                   run_dir=None, config: dict | None = None):
+    """The subset of memory worth spending prompt space on for THIS task.
+
+    Returns None when no judgment could be made, so the caller injects everything it
+    would have injected before. Never returns more lines than it was given, and never
+    reorders them -- the section structure above these lines is what gives them meaning.
+    """
+    from .questions import memory_relevant
+
+    lines = [line for line in (lines or []) if line.strip()]
+    if len(lines) <= keep:
+        # Nothing to narrow, and asking would cost a request to learn that.
+        return None
+    questions = {f'l{i}': memory_relevant(line, task) for i, line in enumerate(lines)}
+    result = ask(dict(task=task, facts=lines), questions, site='jev-memory-slice',
+                 run_dir=run_dir, config=config)
+    if result is None:
+        return None
+
+    scored = []
+    for i, line in enumerate(lines):
+        probability = noul(result, f'l{i}')
+        if probability is None:
+            # An unscored line is kept: absence of a judgment is not evidence against.
+            probability = 1.0
+        scored.append((probability, i, line))
+    scored.sort(key=lambda item: (-item[0], item[1]))
+    chosen = {index for _p, index, _line in scored[:keep]}
+    return [line for i, line in enumerate(lines) if i in chosen]

package/scripts/forge_jev/outcome.py

@@ -0,0 +1,49 @@
+"""The state forge's outcome rubrics (first_pass, retry_pass) are asked on.
+
+One assembler for both sides of the measurement: the export rebuilds this state from
+stored events, live forge builds it from a plan dir. Each side hands over evidence it
+has already read; this only caps and arranges it, so the state a model is scored on and
+the state it answers in production cannot drift apart in shape. Pure: no file reads.
+
+The caps are the export's (`forge dataset export`), because those are the states
+Clef was measured on: goal and prompt are NOT cut here, unlike score-plan's request.
+"""
+from __future__ import annotations
+
+FILE_EXCERPT_CHARS = 600
+MAX_EXCERPT_FILES = 6
+MEMORY_CHARS = 4000
+MAX_SIBLINGS = 40
+SIBLING_TITLE_CHARS = 120
+REVIEW_CHARS = 12000
+
+
+def siblings(tasks, task_id: str) -> list[dict]:
+    """The rest of the plan, in plan order: [{id, title, files, deps}] without `task_id`."""
+    out = []
+    for row in tasks:
+        if row.get('id') == task_id:
+            continue
+        out.append(dict(id=row.get('id'), title=str(row.get('title', ''))[:SIBLING_TITLE_CHARS],
+                        files=row.get('files', ''), deps=row.get('deps', '')))
+        if len(out) >= MAX_SIBLINGS:
+            break
+    return out
+
+
+def assemble(*, goal: str, task_id: str, title: str, files: str, deps: str, prompt: str, approach: str,
+             plan_tasks: list, file_excerpts: dict, memory: str, dwarf: dict, reviewer: dict, size: dict) -> dict:
+    """The first-pass state: the task as planned, the plan around it, who runs and reviews it."""
+    # Values pass through as given: coercing a missing title to '' would change the body,
+    # and with it the case id, of every exported case that had none.
+    return dict(goal=goal, task=dict(id=task_id, title=title, files=files, deps=deps),
+                prompt=prompt, approach=approach, plan_tasks=plan_tasks,
+                file_excerpts=file_excerpts, memory=(memory or '')[:MEMORY_CHARS],
+                dwarf=dwarf, reviewer=reviewer, size=size)
+
+
+def retry(state: dict, *, attempt: int, previous_review: str) -> dict:
+    """The retry-pass state: the first-pass state plus which try this is and what it must fix."""
+    review = previous_review or ''
+    return dict(state, attempt=attempt, previous_review=review[:REVIEW_CHARS],
+                previous_review_truncated=len(review) > REVIEW_CHARS)