Answer stability round 1: 0 🔴, 5 🟡 (0 misread); lock an epic's decisions while one is appended, and test the epic's key, the approval and the quote sources

This commit is contained in:
2026-11-18 23:40:28 +01:00
parent 7d245dcdce
commit 24cb6b2af0
10 changed files with 159 additions and 53 deletions
+1 -1
View File
@@ -216,7 +216,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `branch_chunks/` cuts a default branch into chunks and finds, for each, the items it shipped and the later chunks that fixed its code, for `score_outcomes` and `routing_figures`. It imports `reading_cost`'s record path.
- `command_lines/` reads a shell command: its simple commands, and a docker call's subcommand and memory limits, for `command_patterns`, `reading_cost`, `routing_figures`, `rule_hook` and `run_heavy`.
- `deploy_release` imports `release_plan`'s `release_standing`.
- `do_epic/` holds `do-epic`, the tool that drives one Jira epic. `main.py` starts the epic's chunks and runs one chunk's cycles in its window, through `agent_cycle`. `scheduler.py` says which issues run now: as many as the epic's cap and each repo's `parallel-chunks` allow, and none in a repo where loop-claude runs chunks. Beside it, `chunk_prompt.py` words what a chunk's worker reads. `findings.py` is what that worker writes into the epic: `do-epic <EPIC-KEY> --file` files a finding as an issue of the epic, and `--record-decision` appends a decision to its description. `config.py` reads its machine-wide settings, importing `project_config`'s settings and `model_routing`'s ladder file, and `epic_record.py` reads and writes an epic's description by section, language line and cap line, through `record_store`'s `EpicDescription`. `repos.py` finds a repo's checkout and project config by its name, and clones a missing checkout from the host and owner of the epic's other repos, through `forge`'s `url_beside`. `repo_pick.py` asks claude, by `repo-rule.md`, where an epic item is worked, and records the answer as a label on the issue. `split.py` has claude predict from the code which repos an item changes, and files a sub-task per repo under it where there are several. `ranking.py` orders an epic's items by score over one chain of goals, the epic's, then code health, then the item's repo's, through `plan`'s ranking, and re-ranks the tracker's backlog to that order through `backend/`. `backend/` reads, files and ranks the epic's issues, adds the labels `repo_pick.py` and `split.py` record, and posts comments.
- `do_epic/` holds `do-epic`, the tool that drives one Jira epic. `main.py` starts the epic's chunks and runs one chunk's cycles in its window, through `agent_cycle`. `scheduler.py` says which issues run now: as many as the epic's cap and each repo's `parallel-chunks` allow, and none in a repo where loop-claude runs chunks. Beside it, `chunk_prompt.py` words what a chunk's worker reads. Through `findings.py` that worker files a finding as an issue of the epic, with `--file`, and appends a decision to its description, with `--record-decision`. `config.py` reads its machine-wide settings, importing `project_config`'s settings and `model_routing`'s ladder file, and `epic_record.py` reads and writes an epic's description by section, language line and cap line, through `record_store`'s `EpicDescription`. `repos.py` finds a repo's checkout and project config by its name, and clones a missing checkout from the host and owner of the epic's other repos, through `forge`'s `url_beside`. `repo_pick.py` asks claude, by `repo-rule.md`, where an epic item is worked, and records the answer as a label on the issue. `split.py` has claude predict from the code which repos an item changes, and files a sub-task per repo under it where there are several. `ranking.py` orders an epic's items by score over one chain of goals, the epic's, then code health, then the item's repo's, through `plan`'s ranking, and re-ranks the tracker's backlog to that order through `backend/`. `backend/` reads, files and ranks the epic's issues, adds the labels `repo_pick.py` and `split.py` record, and posts comments.
- `forge/` tells a GitHub origin from a Gitea one, names a repo beside an origin's and runs that forge's CLI (`commands.py`), and finds a pull request and waits for its checks (`pulls.py`), for `chunk_preflight`, `chunk_pr`, `deploy_release`, `do_epic` and `larv_review`.
- `git_cli/` runs git for every tool (`git_repo.py`), and reads the git calls in a shell command (`git_command.py`).
- `judge_replay` imports `agent_cycle`'s judge and verdicts, and `loop_claude`'s premises, records and `ANSWER_DESTINATIONS`.
+5 -4
View File
@@ -3,6 +3,7 @@ from do_epic.backend.protocol import EpicIssue
from do_epic import findings
from loop_claude.project.records import HUMAN_RULE_NAMES, RECORD_FILES
from text_files.markdown_text import listed
import pathlib
from model_routing.ladder import ProjectRung
from loop_claude.cycle import prompts
from model_routing.route import Route
@@ -11,10 +12,10 @@ from model_routing.route import Route
DRIVER = "do-epic"
def task(issue: EpicIssue, epic: str, checkout: str | None) -> str:
"""The task of the chunk that works issue, of the epic with the key epic: in checkout, or without a repo where it is None."""
def task(issue: EpicIssue, epic: str, checkout: str | None, launcher: pathlib.Path, language: str) -> str:
"""The task of the chunk that works issue, of the epic with the key epic: in checkout, or without a repo where it is None. launcher is the do-epic that runs the chunk, and language the one the epic's Jira text is in."""
where = f"in the checkout {checkout}, on the branch {issue.key}" if checkout else "which changes no repo: work in the folder you start in"
return f"Work the Jira issue {issue.key} of the epic {epic} as one chunk, {where}. {findings.instructions(epic)} Its summary: {issue.summary}" + (f"\n\nIts description:\n\n{issue.detail}" if issue.detail else "")
return f"Work the Jira issue {issue.key} of the epic {epic} as one chunk, {where}. {findings.instructions(epic, launcher, language)} Its summary: {issue.summary}" + (f"\n\nIts description:\n\n{issue.detail}" if issue.detail else "")
CODE_HEALTH = '~/.claude/CLAUDE.md → "Shared goal"'
@@ -28,7 +29,7 @@ def fresh(task: str, premises: str, route: Route, project: ProjectRung | None, f
# The worker names no plan items: the chunk's one item is its issue.
# The epic's records come first, as its goals do; a chunk without a repo has only those and the human's rules.
# The epic's records come first, as its goals do; a chunk without a repo is handed only those and the human's rules, so the names that mention a repo's then name nothing it reads.
NAMES = prompts.RecordNames(
quote_sources=listed(("the epic's description", "the repo's goals file's Goals and Audience", *RECORD_FILES, *HUMAN_RULE_NAMES), "or"),
answer_destinations="the epic's description under ## Decisions, the repo's goals file's Goals or Audience, " + ", ".join(RECORD_FILES) + ", the repo's plan or a comment",
+32 -10
View File
@@ -89,6 +89,19 @@ def with_language(text: str, language: str) -> str | Failure:
return line + "\n" + "\n" * bool(text.strip()) + text
def decision_titled(decisions: str, title: str) -> str | None:
"""The entry under the ### title heading of decisions, a ## Decisions section's body; None where it has no such heading."""
found: list[str] | None = None
for line, fenced in fenced_lines(decisions):
if not fenced and line.startswith("### "):
if found is not None:
break
found = [] if line[4:].strip() == title else None
elif found is not None:
found.append(line)
return None if found is None else "\n".join(found).strip()
@dataclasses.dataclass(frozen=True)
class EpicRecord:
"""One epic's record, kept in its description."""
@@ -110,18 +123,27 @@ class EpicRecord:
"""Writes body as the ## name section. approved says the human approved the change in an interrupt, which Goals and Audience need."""
return self.written(lambda text: with_section(text, name, body), frozenset({name}) if approved else frozenset())
def append_decision(self, title: str, entry: str) -> Held | Failure:
"""Adds entry under a ### title heading at the end of ## Decisions, leaving the decisions before it as they are."""
if not title.strip() or "\n" in title:
def append_decision(self, title: str, entry: str) -> bool | Failure:
"""Adds entry under a ### title heading at the end of ## Decisions, leaving the decisions before it as they are. False where the section already holds that entry under that title, so recording a decision twice keeps one; a Failure where it holds another entry under it, so one title names one decision."""
title, entry = title.strip(), entry.strip()
if not title or "\n" in title:
return Failure("the title must be one line of text")
if not entry.strip():
if not entry:
return Failure("pipe the decision's text in")
def appended(text: str) -> str | Failure:
before = read_section(text, "Decisions")
return before if isinstance(before, Failure) else with_section(text, "Decisions", f"{before}\n\n### {title.strip()}\n\n{entry.strip()}".strip())
return self.written(appended, frozenset())
held = self.description.held()
if isinstance(held, Failure):
return held
before = read_section(held.text, "Decisions")
if isinstance(before, Failure):
return before
same = decision_titled(before, title)
if same is not None:
return False if same == entry else Failure(f"## Decisions already holds another decision titled {title!r}: give this one a title of its own")
text = with_section(held.text, "Decisions", f"{before}\n\n### {title}\n\n{entry}".strip())
if isinstance(text, Failure):
return text
wrote = dataclasses.replace(self.description, approved=frozenset()).write(text, held.version)
return wrote if isinstance(wrote, Failure) else True
def write_language(self, language: str) -> Held | Failure:
return self.written(lambda text: with_language(text, language), frozenset())
+42 -16
View File
@@ -1,36 +1,56 @@
"""What a chunk's worker writes into its epic: a finding, filed as an issue, and a decision, appended to the description.
A finding about one of the epic's goals is filed in the epic, and one about a repo's goals by that repo's rules (docs/decisions.md → `do-epic: drives one Jira epic …` → "Findings"). A decision that governs the epic goes under the description's ## Decisions, where the judge of each later chunk reads it."""
import contextlib
import fcntl
import pathlib
import typing
from do_epic.backend.protocol import EpicStore
from do_epic.repo_pick import CLAUDE_LABEL, HUMAN_LABEL, of_label, REPO_PREFIX
from do_epic.epic_record import EpicRecord
from do_epic.backend.protocol import EpicStore
from failure import Failure
from text_files.piped_text import piped
# Three readers, seated as the human and as a chunk's worker, ranked four spellings of each flag: `<EPIC-KEY> --file` came first, second and second, ahead of `--file <EPIC-KEY>`, `add` and `--finding`; `--record-decision` won 2-1 over `--decision`, since `--decide` reads as do-epic deciding.
# Three readers, seated as the human and as a chunk's worker, picked each spelling from four: `<EPIC-KEY> --file` over `--file <EPIC-KEY>`, `add` and `--finding`, and `--record-decision` over `--decision` and `--decide`.
FILE = "--file"
LABEL = "--label"
RECORD_DECISION = "--record-decision"
# The labels that say where an issue is worked, as do-epic's scheduler reads them.
LABELS = f"`{REPO_PREFIX}<name>` for the repo that works it, `{CLAUDE_LABEL}` for work of Claude's that changes no repo, or `{HUMAN_LABEL}` for a task of the human's"
# Under the epic's folder, the file a do-epic holds locked while it appends a decision.
DECISIONS_LOCK = "decisions.lock"
USAGE = f"""do-epic <EPIC-KEY> {FILE} <summary> [{LABEL} <label>] [<<'EOF' detail EOF]
do-epic <EPIC-KEY> {RECORD_DECISION} <title> <<'EOF' entry EOF"""
HELP = f"""{FILE} files a finding about one of the epic's goals as an open issue of the epic, with the markdown piped in as its description.
{LABEL} names its repo, or says the work changes no repo; without one the issue waits.
{LABEL} is {LABELS}; without one the issue waits until someone labels it.
A finding about a repo's own goals goes into that repo's plan instead.
{RECORD_DECISION} appends a decision that governs the epic to its description's ## Decisions, under the title, with the markdown piped in as its text."""
def instructions(epic: str) -> str:
"""What a chunk's first prompt says about filing a finding and recording a decision in the epic with the key epic."""
def instructions(epic: str, launcher: pathlib.Path, language: str) -> str:
"""What a chunk's first prompt says about filing a finding and recording a decision in the epic with the key epic. launcher is the do-epic that runs the chunk, and language the one the epic's Jira text is in."""
return (
f"File a finding about one of the epic's goals in the epic, with `do-epic {epic} {FILE} \"<summary>\" [{LABEL} <label>]` and its detail on stdin. "
"File one about a repo's goals by that repo's rules. Where unsure which, ask the human. "
f"Record a decision that governs the epic, such as an answer the human typed, with `do-epic {epic} {RECORD_DECISION} \"<title>\"` and its text on stdin."
f"File a finding about one of the epic's goals in the epic, with `{launcher} {epic} {FILE} \"<summary>\" {LABEL} <label>` and its detail on stdin. "
f"The label is {LABELS}; leave it out where you cannot tell, and the issue waits for the human. "
"Where filing fails and says the issue may exist, ask the human to look before you file it again. "
"File a finding about a repo's goals by that repo's rules. Where unsure which, ask the human. "
f"Record a decision that governs the epic, such as an answer the human typed, with `{launcher} {epic} {RECORD_DECISION} \"<title>\"` and its text on stdin. "
f"Write the issue and the decision in {language}, the epic's language."
)
@contextlib.contextmanager
def decisions_locked(folder: pathlib.Path) -> typing.Iterator[None]:
"""Holds the epic's DECISIONS_LOCK, in its folder, so two chunks that record a decision at once write one after the other. Raises OSError where the file cannot be made or locked."""
folder.mkdir(parents=True, exist_ok=True)
with open(folder / DECISIONS_LOCK, "w") as lock:
fcntl.flock(lock, fcntl.LOCK_EX)
yield
def parsed(words: list[str]) -> tuple[str, str, str | None] | None:
"""The flag, its one value and the label of the words after the epic's key; None where they aren't a filing or a decision spelt as USAGE has them. A word that opens with `--` is no summary, title or label."""
"""What the words after the epic's key ask for: the flag, the summary or title, and the label, None without one. None where they aren't spelt as USAGE has them. A word that opens with `--` is no summary, title or label."""
if not words or words[0] not in (FILE, RECORD_DECISION):
return None
label: str | None = None
@@ -45,15 +65,21 @@ def parsed(words: list[str]) -> tuple[str, str, str | None] | None:
return words[0], rest[0], label
def written(epic: str, flag: str, value: str, label: str | None, store: EpicStore, record: EpicRecord, stdin: typing.TextIO) -> str | Failure:
"""Files the finding or records the decision, as flag says, and answers the line to print."""
def written(epic: str, flag: str, value: str, label: str | None, store: EpicStore, record: EpicRecord, stdin: typing.TextIO, folder: pathlib.Path) -> str | Failure:
"""Files the finding or records the decision, as flag says, and answers the line to print. folder is the epic's, where the lock for its decisions lies."""
text = piped(stdin)
if flag == FILE:
if label and of_label(label) is None:
return Failure(f"cannot file the finding in the epic {epic}: do-epic doesn't read the label {label!r}; write {LABELS}")
key = store.file(epic, value, text, (label,) if label else ())
if isinstance(key, Failure):
return Failure(f"cannot file the finding in the epic {epic}: {key.reason}")
return f"Filed {key} in the epic {epic}." + ("" if label else " It waits until a label names its repo.")
recorded = record.append_decision(value, text)
if isinstance(recorded, Failure):
return Failure(f"cannot record the decision in the epic {epic}'s description: {recorded.reason}")
return f"Recorded the decision in the epic {epic}'s description."
return f"Filed {key} in the epic {epic}." + ("" if label else f" It waits until someone labels it: {LABELS}.")
try:
with decisions_locked(folder):
added = record.append_decision(value, text)
except OSError as failure:
return Failure(f"cannot record the decision in the epic {epic}'s description: cannot lock {failure.filename or folder / DECISIONS_LOCK}: {failure.strerror}")
if isinstance(added, Failure):
return Failure(f"cannot record the decision in the epic {epic}'s description: {added.reason}")
return f"Recorded the decision in the epic {epic}'s description." if added else f"The epic {epic}'s description already holds that decision."
+5 -2
View File
@@ -116,7 +116,7 @@ def epic_written(key: str, writes: tuple[str, str, str | None], paths: Paths, ba
config = load(paths.home)
if isinstance(config, Failure):
return Stop(1, config.reason)
done = findings.written(key, *writes, *backend(config, key), stdin)
done = findings.written(key, *writes, *backend(config, key), stdin, paths.home / scheduler.STATE / key)
return Stop(1, done.reason) if isinstance(done, Failure) else Stop(0, done)
@@ -255,6 +255,9 @@ def next_cycle(loop_run: LoopRun, loop: Loop, in_repo: bool, epic: EpicRun) -> C
premises = premises_read(loop.root if in_repo else None, epic)
if isinstance(premises, Failure):
return Stop(1, premises.reason)
language = epic.record.language()
if isinstance(language, Failure):
return Stop(1, language.reason)
records = records_read(loop.root if in_repo else None, epic)
if isinstance(records, Failure):
return Stop(1, records.reason)
@@ -271,7 +274,7 @@ def next_cycle(loop_run: LoopRun, loop: Loop, in_repo: bool, epic: EpicRun) -> C
project = ladder.project_rung(models.worker)
route = routed(loop_run.route, project, models.worker, lambda: archived_route(archive_folder, loop), lambda: RoutingIssue(issue) if "L" in issue.scores else None)
say(f"\n=== cycle {loop_run.cycle_number}, worker on {route.rung} ===", epic.effects, stdout=True)
return Cycle(config=setup_version(epic.paths.claude_dir, epic.effects.git), effects=epic.effects, facts="", judge=judge_rung(ladder, models.judge), premises=premises, project=project, project_archive=archive_folder, records=records, root=loop.root, route=route, session=loop.session, task=chunk_prompt.task(issue, epic.key, loop.root if in_repo else None), prompts=chunk_prompt.WORKER, taken_in=lambda entries: TakenIn(), unfinished_evidence=loop_run.unfinished_evidence, window=loop.window)
return Cycle(config=setup_version(epic.paths.claude_dir, epic.effects.git), effects=epic.effects, facts="", judge=judge_rung(ladder, models.judge), premises=premises, project=project, project_archive=archive_folder, records=records, root=loop.root, route=route, session=loop.session, task=chunk_prompt.task(issue, epic.key, loop.root if in_repo else None, epic.launcher, language or epic.config.language), prompts=chunk_prompt.WORKER, taken_in=lambda entries: TakenIn(), unfinished_evidence=loop_run.unfinished_evidence, window=loop.window)
def repoless_models(epic: EpicRun) -> Models:
+57 -16
View File
@@ -1,26 +1,29 @@
import contextlib
import dataclasses
import fcntl
import io
import pathlib
import sys
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from do_epic import main
from do_epic.backend.fake import MemoryEpic
from do_epic.epic_record import EpicRecord
from do_epic.test_main import DESCRIPTION, DoEpicTest
from do_epic.epic_record import EpicRecord
from failure import Failure
from loop_claude.test_loop_claude import FakeEffects
from loop_state.paths import paths_from
from record_store.held import Held
from do_epic import main
from do_epic.backend.fake import MemoryEpic
from loop_state.paths import paths_from
@dataclasses.dataclass(frozen=True)
class WrittenDescription:
"""Stands in for an epic's description in Jira that takes writes: kept holds each text it held, the last one now."""
"""Stands in for an epic's description in Jira that takes writes: kept holds each text it held, the last one now. It refuses a write that claims the human's approval, and notes in locked whether lock was held during each write."""
kept: list[str]
approved: frozenset[str] = frozenset()
lock: pathlib.Path
locked: list[bool] = dataclasses.field(default_factory=list)
approved: frozenset[str] | None = frozenset()
@property
def text(self) -> str:
@@ -33,6 +36,14 @@ class WrittenDescription:
return Held(self.text)
def write(self, text: str, version: str | None) -> Held | Failure:
if self.approved != frozenset():
return Failure(f"approved is {self.approved!r}")
with open(self.lock, "a") as other:
try:
fcntl.flock(other, fcntl.LOCK_EX | fcntl.LOCK_NB)
self.locked.append(False)
except BlockingIOError:
self.locked.append(True)
self.kept.append(text)
return Held(text)
@@ -41,9 +52,11 @@ class FindingsTest(DoEpicTest):
def setUp(self) -> None:
super().setUp()
self.store = MemoryEpic("ABC-12", list(self.issues))
self.written = WrittenDescription([DESCRIPTION])
self.written = WrittenDescription([DESCRIPTION], self.home / ".local/state/do-epic/ABC-12/decisions.lock")
self.keys: list[str] = []
def backend(self, config: object, key: str) -> tuple[MemoryEpic, EpicRecord]:
self.keys.append(key)
return self.store, EpicRecord(self.written) # type: ignore[arg-type]
def run_with(self, argv: list[str], stdin: str = "") -> tuple[int, str, str, FakeEffects]:
@@ -55,24 +68,29 @@ class FindingsTest(DoEpicTest):
class FilingAFinding(FindingsTest):
def test_files_an_issue_under_the_epic_with_the_detail_piped_in_and_starts_nothing(self) -> None:
def test_files_an_issue_under_the_epic_with_the_detail_piped_in_and_doesnt_start_anything(self) -> None:
code, out, err, fake = self.run_with(["ABC-12", "--file", "Retry the import on a 503"], "The client times out.\n")
self.assertEqual((code, out, err), (0, "Filed ABC-102 in the epic ABC-12. It waits until a label names its repo.\n", ""))
self.assertEqual((code, out, err), (0, "Filed ABC-102 in the epic ABC-12. It waits until someone labels it: `repo:<name>` for the repo that works it, `do-epic-claude` for work of Claude's that changes no repo, or `do-epic-human` for a task of the human's.\n", ""))
self.assertEqual(self.keys, ["ABC-12"])
filed = self.store.issues[-1]
self.assertEqual((filed.key, filed.summary, filed.detail, filed.labels, filed.parent, filed.by_loop), ("ABC-102", "Retry the import on a 503", "The client times out.", (), "ABC-12", True))
self.assertEqual(fake.calls, [], "filing needs no tmux, clone or claude")
def test_a_label_names_the_issues_repo(self) -> None:
for argv in (["ABC-12", "--file", "Retry", "--label", "api"], ["ABC-12", "--file", "--label", "api", "Retry"]):
def test_a_label_says_where_the_issue_is_worked(self) -> None:
for argv, label in ((["ABC-12", "--file", "Retry", "--label", "repo:api"], "repo:api"), (["ABC-12", "--file", "--label", "do-epic-claude", "Retry"], "do-epic-claude"), (["ABC-12", "--file", "Retry", "--label", "do-epic-human"], "do-epic-human")):
with self.subTest(argv=argv):
code, out, _, _ = self.run_with(argv)
filed = self.store.issues[-1]
self.assertEqual((code, out, filed.labels, filed.detail), (0, f"Filed {filed.key} in the epic ABC-12.\n", ("api",), ""))
self.assertEqual((code, out, filed.labels, filed.detail), (0, f"Filed {filed.key} in the epic ABC-12.\n", (label,), ""))
def test_refuses_a_label_the_scheduler_doesnt_read(self) -> None:
for label in ("api", "repo:", "repo:a b"):
with self.subTest(label=label):
code, out, err, _ = self.run_with(["ABC-12", "--file", "Retry", "--label", label])
self.assertEqual((code, out, len(self.store.issues)), (1, "", 2))
self.assertEqual(err, f"cannot file the finding in the epic ABC-12: do-epic doesn't read the label {label!r}; write `repo:<name>` for the repo that works it, `do-epic-claude` for work of Claude's that changes no repo, or `do-epic-human` for a task of the human's\n")
def test_says_why_an_issue_was_not_filed(self) -> None:
code, out, err, _ = self.run_with(["ABC-12", "--file", "Retry", "--label", "a b"])
self.assertEqual((code, out, len(self.store.issues)), (1, "", 2))
self.assertEqual(err, "cannot file the finding in the epic ABC-12: the label 'a b' is empty or holds white space\n")
self.store.fails = "Jira answered 401"
code, _, err, _ = self.run_with(["ABC-12", "--file", "Retry"])
self.assertEqual((code, err), (1, "cannot file the finding in the epic ABC-12: Jira answered 401\n"))
@@ -98,9 +116,32 @@ class RecordingADecision(FindingsTest):
self.assertEqual(self.run_with(["ABC-12", "--record-decision", "Merges squash"], "Always.")[0], 0)
self.assertTrue(self.written.text.endswith("rate-limits.\n\n### Merges squash\n\nAlways.\n"), self.written.text)
self.assertIn("## Goals\nShip the import.\n\n## Audience\nThe client's team.\n", self.written.text)
self.assertEqual((self.keys, self.written.locked), (["ABC-12", "ABC-12"], [True, True]))
def test_recording_a_decision_twice_keeps_one(self) -> None:
self.run_with(["ABC-12", "--record-decision", "Merges squash"], "Always.\n\n```\n### not a title\n```\n")
self.run_with(["ABC-12", "--record-decision", "Imports retry"], "Three times.")
held = self.written.text
code, out, err, _ = self.run_with(["ABC-12", "--record-decision", " Merges squash "], "Always.\n\n```\n### not a title\n```")
self.assertEqual((code, out, err, self.written.text), (0, "The epic ABC-12's description already holds that decision.\n", "", held))
self.assertEqual(len(self.written.kept), 3)
def test_refuses_another_decision_under_a_title_the_description_holds(self) -> None:
self.run_with(["ABC-12", "--record-decision", "Merges squash"], "Always.")
held = self.written.text
code, out, err, _ = self.run_with(["ABC-12", "--record-decision", "Merges squash"], "Always")
self.assertEqual((code, out, self.written.text), (1, "", held))
self.assertEqual(err, "cannot record the decision in the epic ABC-12's description: ## Decisions already holds another decision titled 'Merges squash': give this one a title of its own\n")
def test_says_why_the_lock_was_not_taken(self) -> None:
self.written.lock.parent.parent.mkdir(parents=True)
self.written.lock.parent.write_text("")
code, out, err, _ = self.run_with(["ABC-12", "--record-decision", "Merges squash"], "Always.")
self.assertEqual((code, out, self.written.text), (1, "", DESCRIPTION))
self.assertRegex(err, f"^cannot record the decision in the epic ABC-12's description: cannot lock {self.written.lock.parent}: \\w")
def test_refuses_a_decision_without_a_title_or_a_body(self) -> None:
for argv, stdin, reason in ((["ABC-12", "--record-decision", "Merges squash"], " \n", "pipe the decision's text in"), (["ABC-12", "--record-decision", "two\nlines"], "Always.", "the title must be one line of text"), (["ABC-12", "--record-decision", "Merges squash"], "## Goals\nNone.", "the body of ## Decisions holds a level 1 or 2 heading, which would start another section")):
for argv, stdin, reason in ((["ABC-12", "--record-decision", "Merges squash"], " \n", "pipe the decision's text in"), (["ABC-12", "--record-decision", "two\nlines"], "Always.", "the title must be one line of text"), (["ABC-12", "--record-decision", " "], "Always.", "the title must be one line of text"), (["ABC-12", "--record-decision", "Merges squash"], "## Goals\nNone.", "the body of ## Decisions holds a level 1 or 2 heading, which would start another section")):
with self.subTest(argv=argv, stdin=stdin):
code, out, err, _ = self.run_with(argv, stdin)
self.assertEqual((code, out, err, self.written.text), (1, "", f"cannot record the decision in the epic ABC-12's description: {reason}\n", DESCRIPTION))
+5 -1
View File
@@ -158,7 +158,11 @@ class ACycleOfAChunkWithoutARepo(DoEpicTest):
self.assertEqual(self.cycle().premises, "the epic ABC-12's description:\n## Goals\nShip the import.\n\n## Audience\nThe client's team.")
def test_the_task_is_the_issue(self) -> None:
self.assertEqual(self.cycle().task, "Work the Jira issue ABC-21 of the epic ABC-12 as one chunk, which changes no repo: work in the folder you start in. File a finding about one of the epic's goals in the epic, with `do-epic ABC-12 --file \"<summary>\" [--label <label>]` and its detail on stdin. File one about a repo's goals by that repo's rules. Where unsure which, ask the human. Record a decision that governs the epic, such as an answer the human typed, with `do-epic ABC-12 --record-decision \"<title>\"` and its text on stdin. Its summary: Do ABC-21\n\nIts description:\n\nTidy the docs.")
task = self.cycle().task
self.assertTrue(task.startswith("Work the Jira issue ABC-21 of the epic ABC-12 as one chunk, which changes no repo: work in the folder you start in. File a finding"), task)
self.assertIn('with `/b/do-epic ABC-12 --file "<summary>" --label <label>` and its detail on stdin', task)
self.assertIn("Write the issue and the decision in English, the epic's language.", task)
self.assertTrue(task.endswith(" Its summary: Do ABC-21\n\nIts description:\n\nTidy the docs."), task)
def test_an_issue_without_scores_runs_on_the_projects_rung(self) -> None:
self.issues[1] = dataclasses.replace(self.issues[1], scores={})
+10 -1
View File
@@ -197,7 +197,16 @@ class StartingAnEpicsChunks(unittest.TestCase):
class TheFirstPrompt(unittest.TestCase):
def test_the_task_names_the_checkout_and_branch_and_quotes_a_description_only_where_there_is_one(self) -> None:
self.assertEqual(chunk_prompt.task(issue("ABC-20"), "ABC-12", "/code/api"), "Work the Jira issue ABC-20 of the epic ABC-12 as one chunk, in the checkout /code/api, on the branch ABC-20. File a finding about one of the epic's goals in the epic, with `do-epic ABC-12 --file \"<summary>\" [--label <label>]` and its detail on stdin. File one about a repo's goals by that repo's rules. Where unsure which, ask the human. Record a decision that governs the epic, such as an answer the human typed, with `do-epic ABC-12 --record-decision \"<title>\"` and its text on stdin. Its summary: Do ABC-20")
labels = "`repo:<name>` for the repo that works it, `do-epic-claude` for work of Claude's that changes no repo, or `do-epic-human` for a task of the human's"
told = (
f"File a finding about one of the epic's goals in the epic, with `/b/do-epic ABC-12 --file \"<summary>\" --label <label>` and its detail on stdin. The label is {labels}; leave it out where you cannot tell, and the issue waits for the human. "
"Where filing fails and says the issue may exist, ask the human to look before you file it again. File a finding about a repo's goals by that repo's rules. Where unsure which, ask the human. "
"Record a decision that governs the epic, such as an answer the human typed, with `/b/do-epic ABC-12 --record-decision \"<title>\"` and its text on stdin. Write the issue and the decision in Swedish, the epic's language."
)
self.assertEqual(chunk_prompt.task(issue("ABC-20"), "ABC-12", "/code/api", pathlib.Path("/b/do-epic"), "Swedish"), f"Work the Jira issue ABC-20 of the epic ABC-12 as one chunk, in the checkout /code/api, on the branch ABC-20. {told} Its summary: Do ABC-20")
def test_an_answer_the_judge_quoted_names_the_epics_description_first(self) -> None:
self.assertTrue(chunk_prompt.WORKER.answered("Q", "A", Route(Rung("off-the-ladder")), None, False).startswith("Your question: Q\n\nthe epic's description, "))
def test_opens_with_the_task_then_the_rung_then_the_premises(self) -> None:
rest = f"The issue sets the chunk's scope. The goals below choose between ways to deliver that scope, and never widen it. The epic's goals rank first, then code health ({chunk_prompt.CODE_HEALTH}), then the repo's.\n\nFrom P"
+1 -1
View File
@@ -187,7 +187,7 @@ def rungs_held(driver: str, route: Route, project: ProjectRung | None) -> str:
class RecordNames(typing.NamedTuple):
"""How an entry point names its project's records in a prompt; WorkerPrompts says what each field is."""
"""The names an entry point's prompts give the places that answer a question, the places that take an answer, and the records the judge reads; WorkerPrompts says what each field is."""
quote_sources: str = QUOTE_SOURCES
answer_destinations: str = ANSWER_DESTINATIONS
records_named: str = RECORDS_NAMED
+1 -1
View File
@@ -121,7 +121,7 @@ A fix meets every row it fits, except that a fix for a 🟡 meets only the 🟡
**Findings.** A reviewer rates each finding 🔴 must fix, 🟡 should fix, 🟢 nit, ❓ question, or 🔀 escalation naming the reviewer whose concern it is.
- **Outside the chunk.** A finding outside the chunk's change, whatever its pass or severity, is scored and filed in `todo.md` per `~/.claude/rules/todo-items.md`. A 🔴 is marked `defect`. A 🟡 against a file in the config's principles folder is marked `principle`, its detail naming the principle, where no other reason fits. One under the bar and not exempt is named in the summary with its score. A verified security HIGH is handled per "Security". In the release review the whole project is the chunk's change, so nothing lies outside it; "Release review" → "Findings" says which of its findings are filed.
- **Under do-epic.** In a chunk do-epic runs, a finding about one of the epic's goals is filed in the epic, with the command the chunk's prompt gives, in place of `todo.md`. One about a repo's goals is filed by that repo's rules, as above. Where unsure which, ask the human.
- **Under do-epic.** A chunk do-epic runs files a finding about one of the epic's goals in the epic, as its prompt says, in place of `todo.md`. Where unsure whether a finding is about the epic's goals or a repo's, ask the human.
- **Goal or decision.** A fix that would change a goal, or a `docs/decisions.md` entry the repo held before the chunk began, is asked; no user reachable → filed, marked `question`, the goal or decision left as is.
- **New decision.** Each decision a fix or an answer records in `docs/decisions.md` is checked against the project principles per `~/.claude/rules/decisions.md` → "Decisions: one home, each linked to a goal or a technical principle", "Check each new decision against the project's principles", before the commit that records it.
- **🔴.** A 🔴 is fixed, or shown factually wrong, and what disproved it recorded per the review standards' `comments.md` → "Where a choice goes": in a comment at the code the finding concerns, or in `docs/decisions.md` when it concerns more than one place. Never declined.