Answer stability round 1: 1 🔴, 3 🟡 (0 misread); reuse the markdown reader, list rival headings, test by table

This commit is contained in:
2026-11-17 11:52:36 +01:00
parent 1a9df179a8
commit 4cdc1c4be9
4 changed files with 79 additions and 98 deletions
+1 -1
View File
@@ -13,7 +13,7 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
- **Open every chunk with one line:** the last version cut, how many changes are unreleased (the entries under `CHANGELOG.md` → `## Unreleased`, or else the commits since the last tag), and the release this chunk ships into. A repo that doesn't publish anything says so once.
- **A client project's `CLAUDE.md` and `AGENTS.md` in its repo belong to its team.** Read both at the start of each chunk there. Propose each change that aligns them with this setup in a pull request of its own, never inside a chunk's; the one edit a chunk makes there is a decision's title in `AGENTS.md`. Until the team accepts a proposal, and after it declines or doesn't answer, follow the team's rule unless it breaks one of the project's goals. Record each such conflict as a decision in the `decisions` record, as `rules/decisions.md` asks: which rule you follow, why, and the open proposal's PR. Then nobody is asked twice.
- **Read the goals file's `## Goals` and `## Audience` before starting a chunk, unless your prompt quotes them.** The chunk's items set its scope. The goals choose between ways to deliver those items, and never add to them.
- **Read the plan and the decisions only as far as the chunk needs.** Where your prompt quotes `chunk-preflight`'s facts, they hold the next item's L, E + I, tagline and detail, and each item that may join it with its L, E + I, S, tagline and detail; run `todo-item` only for what they leave out. Otherwise run `~/.claude/bin/todo-item list`, which prints every item's row in the plan's order, without details. Then read the details of only the items the chunk takes, with `~/.claude/bin/todo-item show <ID>`, which prints an item's row and detail. `AGENTS.md` lists the project principles and the title of each decision no project principle covers. Read an entry in `docs/decisions.md` only where the project principle or the title leaves open what the chunk or the review needs, with `~/.claude/bin/markdown-section <file> <fragment of its title>`, which prints that one entry: `<file>` is what `~/.claude/bin/project-record open decisions` prints.
- **Read the plan and the decisions only as far as the chunk needs.** Where your prompt quotes `chunk-preflight`'s facts, they hold the next item's L, E + I, tagline and detail, and each item that may join it with its L, E + I, S, tagline and detail; run `todo-item` only for what they leave out. Otherwise run `~/.claude/bin/todo-item list`, which prints every item's row in the plan's order, without details. Then read the details of only the items the chunk takes, with `~/.claude/bin/todo-item show <ID>`, which prints an item's row and detail. `AGENTS.md` lists the project principles and the title of each decision no project principle covers. Read an entry in `docs/decisions.md` only where the project principle or the title leaves open what the chunk or the review needs. Print one entry with `~/.claude/bin/markdown-section <file> <fragment of its title>`, where `<file>` is what `~/.claude/bin/project-record open decisions` prints.
- **Work one chunk at a time, and put every item that can share its review into it.** Every review has a fixed cost, so a chunk takes the next plan item plus every other item for which three things hold: they name one release; they fire the same review passes (`larv-review` §3); and no item outside the chunk blocks one of them. The items need not share a purpose. An item whose risk R, in the plan, is above 5 ships alone: it joins no chunk, and none joins it. The next plan item is the first that does not wait: an item waits while it is marked `question`, until the human answers, or while an item that blocks it is still in the plan. Tiny items, a few lines of change each, need not fire the same passes: bundle up to ten that name one release, and that no item outside the chunk blocks, into one chunk. Split a milestone into items in the plan before starting it. Fix a finding in the chunk's own change within the chunk. File a finding about anything else in `todo.md`.
- **Ask, don't guess.** Three choices are always the human's: a goal; a release, meaning the items planned into it and when it is cut; and a change to loop-claude's routing ladder, its rungs included. Any other rule that asks the human's approval reserves that choice too. Ask about a reserved choice. For any other choice, first check whether the goals already answer it. If they nearly do, propose a change to the goals and show how it answers this case: an answer settles one question, a goal settles every question like it. Otherwise take the option you would recommend, and record it with its reason: in the item's detail, or, where it governs later work, as the next sentence says. A recommendation you can give a reason for is not a guess. Ask only where you have no recommendation. Write every answer once, where it belongs, never only in chat: a goal in the goals file, a working rule in `AGENTS.md`, a standing choice in a comment at the one place it governs, or in `docs/decisions.md` once made in more than one place. When an answer holds a goal and a choice, write the goal in the goals file, and record as a choice only what the goal leaves open.
- **Bench a syntax with the people who write it.** Before a new or changed spelling of something users read or write ships — markdown, HTML, a config key, a CLI flag — a panel of fresh-context readers, seated as those users from the goals file's `## Audience`, picks it.
+3 -1
View File
@@ -174,7 +174,7 @@ It renames `## Unreleased` in `CHANGELOG.md` to the version and merges that thro
## Tools
Install puts only `loop-claude` on `PATH`; call the others by their path, such as `~/.claude/bin/metric-bench`, from the project's checkout. Those under `~/.claude` are the release's; test a change to one from `~/code/claude-config/bin`. The list is in alphabetical order.
Install puts only `loop-claude` on `PATH`; call the others by their path, such as `~/.claude/bin/metric-bench`, from the project's checkout. Those under `~/.claude` are the release's; test a change to one from `~/code/claude-config/bin`. The tools are listed in alphabetical order, and the packages under `bin/` follow under their own heading.
- `chunk-pr open|sync|ready|merge|clean` opens a chunk's pull request as a draft, brings its branch level with origin's default branch, marks it ready and merges it once its checks pass, with `gh` on a GitHub origin and `tea` elsewhere. The chunks of one project merge one at a time: in its turn, `merge` brings the branch level again, finishes the plan items its `--finish` flags name, and waits for the checks; once the pull request is merged, `clean` removes the chunk's worktree and branch and fast-forwards the main checkout. `chunk-pr --help` states the steps.
- `chunk-preflight` finds the mechanical facts a chunk starts from, and with `--worktree` makes its worktree; `loop-claude` runs it with `--worktree` before it routes each chunk, and `chunk-preflight --help` lists the facts.
@@ -204,6 +204,8 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `touch-predictions record <ID>...` appends what a chunk's items were predicted to touch, under `Touches:` in their details, beside the files and parts its branch touched, to the record the config names as `touch-predictions`; `touch-predictions --help` shows the spelling and how a part is named. `chunk-preflight` reads the same predictions to name the items that may start chunks at once.
- `wait-for <file> [<pattern>] [--timeout <seconds>]` waits until a file a background job writes holds a line matching the pattern, and prints it.
### Packages under `bin/`
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests. Beside the packages, `bin/`'s root holds only the launchers, the tools of one file with their tests, `test_env.py`, `failure.py` and `setup.cfg`. `failure.py`'s `Failure`, which modules across `bin/` return for a failed step, belongs to no single package. `atlassian/`, `branch_chunks/`, `claude_code/`, `command_lines/`, `forge/`, `git_cli/`, `loop_effects/`, `loop_state/`, `machine_load/`, `model_routing/`, `notifier/`, `plan/`, `plan_store/`, `record_store/`, `release_plan/`, `review_rules/`, `rung_replay/`, `text_files/` and `transcript_archive/` serve more than one tool. No package imports one that imports it back, which `repo_checks/test_package_cycles.py` checks.
- `adf_codec/` converts markdown to ADF, the rich text of Jira Cloud and Confluence, and back, in a throwaway container running a pinned `@larvit/adf-codec`. It builds the container's image inside a heavy slot.
+28 -32
View File
@@ -2,32 +2,31 @@
usage: markdown-section <file> <fragment>
The section runs from the first heading whose text holds the fragment, whatever its case, to the
line before the next heading of the same or a higher level, so it holds its sub-sections. The
heading's text is what follows its `#`s. A line inside a fenced code block is never a heading.
Print a record kept outside the checkout through the file `project-record open <record>` prints.
The section starts at the heading whose text holds the fragment, in any case, and ends before the
next heading of the same or a higher level, so it holds its sub-sections. A heading's text is what
follows its `#`s. A line inside a fenced code block is never a heading.
Where no heading holds the fragment, it fails saying so. Where another heading outside that section
holds it too, it fails listing each such heading with its line number, and prints no section: pass
more of the heading you want.
Where no heading holds the fragment, it fails saying so. Where several headings do, it fails
listing each with its line number and prints no section: pass more of the heading you want.
A heading whose text is the fragment, in any case, is the one picked even where longer headings
hold it too.
To read a record kept outside the checkout, pass the file `project-record open <record>` prints.
Exit 2 on bad arguments, and 1, saying why, on any other failure.
"""
import pathlib
import re
import sys
from failure import Failure
HEADING = re.compile(r"^ {0,3}(#{1,6})[ \t]+(.*?)[ \t]*$")
FENCE = re.compile(r"^ {0,3}(```|~~~)")
from text_files.markdown_text import fenced_lines, HEADING
def main(argv: list[str]) -> int:
if argv[:1] in (["-h"], ["--help"]):
print(__doc__.strip())
return 0
if len(argv) != 2:
if len(argv) != 2 or not argv[1].strip():
print("usage: markdown-section <file> <fragment>", file=sys.stderr)
return 2
try:
@@ -43,31 +42,28 @@ def main(argv: list[str]) -> int:
return 0
def headings(lines: list[str]) -> list[tuple[int, int, str]]:
"""Each heading outside a fenced code block, as its index in lines, its level and its text."""
def headings(text: str) -> list[tuple[int, int, str]]:
"""Each heading of text outside a fenced code block, as its line's index, its level and its text."""
found = []
fence = ""
for index, line in enumerate(lines):
opened = FENCE.match(line)
if opened and fence in ("", opened.group(1)):
fence = "" if fence else opened.group(1)
elif not fence and (heading := HEADING.match(line)):
for index, (line, fenced) in enumerate(fenced_lines(text)):
if not fenced and (heading := HEADING.match(line)):
found.append((index, len(heading.group(1)), heading.group(2)))
return found
def section(text: str, fragment: str) -> str | Failure:
"""The section of text under the first heading that holds fragment, or a Failure where none does or several do."""
lines = text.splitlines(keepends=True)
found = headings(lines)
matching = [at for at, (_, _, title) in enumerate(found) if fragment.lower() in title.lower()]
"""The section of text under the heading that fragment picks, or a Failure where no heading holds it or several do."""
found = headings(text)
wanted = fragment.strip().lower()
matching = [heading for heading in found if wanted in heading[2].lower()]
if len(matching) > 1:
matching = [heading for heading in matching if heading[2].lower() == wanted] or matching
if not matching:
return Failure(f"no heading holds '{fragment}'")
start, level, _ = found[matching[0]]
end = next((index for index, deeper, _ in found[matching[0] + 1:] if deeper <= level), len(lines))
# A matching heading inside the first one's section is part of what is printed, not a rival.
rivals = [at for at in matching if found[at][0] >= end]
if rivals:
listed = "\n".join(f"{found[at][0] + 1}: {lines[found[at][0]].rstrip()}" for at in [matching[0], *rivals])
return Failure(f"{len(rivals) + 1} headings hold '{fragment}', so use more of one:\n{listed}")
return "".join(lines[start:end]).rstrip("\n") + "\n"
lines = text.splitlines()
if len(matching) > 1:
listed = "\n".join(f"{index + 1}: {lines[index]}" for index, _, _ in matching)
return Failure(f"{len(matching)} headings hold '{fragment}', so use more of one:\n{listed}")
start, level, _ = matching[0]
end = next((index for index, deeper, _ in found if index > start and deeper <= level), len(lines))
return "\n".join(lines[start:end]).rstrip("\n") + "\n"
+47 -64
View File
@@ -40,40 +40,49 @@ Delta text.
class Section(unittest.TestCase):
def test_the_fragment_is_matched_against_the_heading_text_without_its_hashes(self):
self.assertEqual(main.section(DOCUMENT, "Alpha text"), Failure("no heading holds 'Alpha text'"))
def test_a_section_runs_to_the_next_heading_of_its_level_or_a_higher_one(self):
cases = {
"a sub-section stops at a higher level heading": ("alpha detail", "### Alpha detail\n\nDetail text.\n"),
"the text under a heading isn't a heading": ("alpha text", Failure("no heading holds 'alpha text'")),
"the last section runs to the end of the file": ("delta", "## Delta\n\nDelta text.\n"),
"a level one heading holds the rest of the document": ("title", DOCUMENT),
"a fenced line that looks like a heading doesn't end it": ("beta", "## Beta Gamma\n\nBeta text.\n\n```\n## Not a heading\n```\n"),
}
for name, (fragment, expected) in cases.items():
with self.subTest(name):
self.assertEqual(main.section(DOCUMENT, fragment), expected)
def test_the_fragment_matches_any_part_of_the_heading_text_in_any_case(self):
for fragment in ("gamma", "BETA g", " beta gamma "):
with self.subTest(fragment):
self.assertEqual(str(main.section(DOCUMENT, fragment)).splitlines()[0], "## Beta Gamma")
self.assertEqual(main.section(DOCUMENT, "## beta"), Failure("no heading holds '## beta'"))
def test_holds_its_sub_sections(self):
def test_a_heading_whose_text_is_the_fragment_wins_over_longer_ones(self):
self.assertEqual(main.section(DOCUMENT, "Alpha"), "## Alpha\n\nAlpha text.\n\n### Alpha detail\n\nDetail text.\n")
def test_a_sub_section_stops_at_a_higher_level_heading(self):
self.assertEqual(main.section(DOCUMENT, "alpha detail"), "### Alpha detail\n\nDetail text.\n")
def test_the_fragment_matches_any_part_of_the_heading_whatever_its_case(self):
self.assertTrue(str(main.section(DOCUMENT, "gamma")).startswith("## Beta Gamma\n"))
def test_a_fenced_line_that_looks_like_a_heading_neither_ends_nor_matches(self):
self.assertEqual(main.section(DOCUMENT, "Beta"), "## Beta Gamma\n\nBeta text.\n\n```\n## Not a heading\n```\n")
self.assertEqual(main.section(DOCUMENT, "not a heading"), Failure("no heading holds 'not a heading'"))
def test_the_last_section_runs_to_the_end_of_the_file(self):
self.assertEqual(main.section(DOCUMENT, "delta"), "## Delta\n\nDelta text.\n")
def test_a_level_one_heading_holds_the_rest_of_the_document(self):
self.assertEqual(main.section(DOCUMENT, "title"), DOCUMENT)
self.assertEqual(main.section("## Plan\n\na\n\n## Plan b\n", "PLAN"), "## Plan\n\na\n")
def test_several_matching_headings_fail_listing_each_with_its_line(self):
listed = main.section("## Plan one\n\ntext\n\n## Plan two\n", "plan")
self.assertEqual(listed, Failure("2 headings hold 'plan', so use more of one:\n1: ## Plan one\n5: ## Plan two"))
def test_what_counts_as_a_heading_or_a_fence(self):
cases = {
"a hash with no space after it is no heading": ("#hashtag\n\n## Real\n", "hashtag", Failure("no heading holds 'hashtag'")),
"a fence with an info string closes on a bare fence": ("```python\n## In\n```\n## Out\n\ntext\n", "out", "## Out\n\ntext\n"),
"a fence of four backticks holds a line of three": ("````\n```\n## In\n````\n## Out\n", "out", "## Out\n"),
"a tilde fence holds a heading": ("~~~\n## In\n~~~\n## Out\n", "in", Failure("no heading holds 'in'")),
"an indented fence holds a heading": (" ```\n## In\n ```\n", "in", Failure("no heading holds 'in'")),
"an unclosed fence holds the rest": ("## A\n\n```\n## In\n", "a", "## A\n\n```\n## In\n"),
}
for name, (text, fragment, expected) in cases.items():
with self.subTest(name):
self.assertEqual(main.section(text, fragment), expected)
def test_only_blank_lines_are_cut_from_the_end_of_a_section(self):
self.assertEqual(main.section("## A\n\nends in X\n\n\n## B\n", "a"), "## A\n\nends in X\n")
self.assertEqual(main.section("## A\n\ncode \n\n", "a"), "## A\n\ncode \n")
def test_a_heading_needs_a_space_after_its_hashes(self):
self.assertEqual(main.section("#hashtag\n\n## Real\n", "hashtag"), Failure("no heading holds 'hashtag'"))
def test_no_heading_is_a_failure(self):
self.assertEqual(main.section(DOCUMENT, "zeta"), Failure("no heading holds 'zeta'"))
@@ -95,14 +104,19 @@ class Main(unittest.TestCase):
def test_a_failure_is_printed_to_stderr_with_exit_1(self):
self.assertEqual(self.run_main(str(self.file), "zeta"), (1, "", "markdown-section: no heading holds 'zeta'\n"))
def test_an_unreadable_file_exits_1_naming_it(self):
code, out, err = self.run_main(str(self.file.with_name("missing.md")), "a")
self.assertEqual((code, out), (1, ""))
self.assertRegex(err, r"^markdown-section: .*missing\.md")
def test_a_file_that_cant_be_read_exits_1_naming_it(self):
self.file.write_bytes(b"\xff\xfe## A\n")
missing = self.file.with_name("missing.md")
for unreadable, reason in ((missing, "missing.md"), (self.file, "decode")):
with self.subTest(reason):
code, out, err = self.run_main(str(unreadable), "a")
self.assertEqual((code, out), (1, ""))
self.assertRegex(err, rf"^markdown-section: .*{reason}")
def test_wrong_arguments_exit_2_with_the_usage(self):
for args in ((), (str(self.file),), (str(self.file), "a", "b")):
self.assertEqual(self.run_main(*args), (2, "", "usage: markdown-section <file> <fragment>\n"), args)
for args in ((), (str(self.file),), (str(self.file), "a", "b"), (str(self.file), " ")):
with self.subTest(args):
self.assertEqual(self.run_main(*args), (2, "", "usage: markdown-section <file> <fragment>\n"))
def test_help_prints_the_usage_and_exits_0(self):
code, out, err = self.run_main("-h")
@@ -110,44 +124,13 @@ class Main(unittest.TestCase):
self.assertTrue(out.startswith("Print one section of a markdown file"))
class BlackBox(unittest.TestCase):
def setUp(self) -> None:
self.file = pathlib.Path(self.enterContext(tempfile.TemporaryDirectory())) / "notes.md"
self.file.write_text(DOCUMENT)
def run_tool(self, *args: str) -> subprocess.CompletedProcess[str]:
return subprocess.run([sys.executable, str(TOOL), *args], capture_output=True, text=True)
def test_prints_the_section(self):
ran = self.run_tool(str(self.file), "delta")
class Launcher(unittest.TestCase):
def test_the_launcher_runs_the_tool(self):
file = pathlib.Path(self.enterContext(tempfile.TemporaryDirectory())) / "notes.md"
file.write_text(DOCUMENT)
ran = subprocess.run([sys.executable, str(TOOL), str(file), "delta"], capture_output=True, text=True)
self.assertEqual((ran.returncode, ran.stdout, ran.stderr), (0, "## Delta\n\nDelta text.\n", ""))
def test_exits_1_saying_why_where_no_heading_matches(self):
ran = self.run_tool(str(self.file), "zeta")
self.assertEqual((ran.returncode, ran.stdout, ran.stderr), (1, "", "markdown-section: no heading holds 'zeta'\n"))
def test_exits_1_listing_the_headings_where_several_match(self):
ran = self.run_tool(str(self.file), "a")
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
self.assertIn("headings hold 'a'", ran.stderr)
self.assertIn("5: ## Alpha", ran.stderr)
def test_exits_1_where_the_file_cant_be_read(self):
ran = self.run_tool(str(self.file.with_name("missing.md")), "alpha")
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
self.assertIn("markdown-section: ", ran.stderr)
def test_exits_2_with_the_usage_on_wrong_arguments(self):
for args in ([], [str(self.file)], [str(self.file), "a", "b"]):
ran = self.run_tool(*args)
self.assertEqual((ran.returncode, ran.stdout), (2, ""), args)
self.assertIn("usage: markdown-section <file> <fragment>", ran.stderr)
def test_help_prints_the_usage(self):
ran = self.run_tool("--help")
self.assertEqual(ran.returncode, 0)
self.assertIn("usage: markdown-section <file> <fragment>", ran.stdout)
if __name__ == "__main__":
unittest.main()