Answer stability round 1: 1 🔴, 3 🟡 (0 misread); reuse the markdown reader, list rival headings, test by table
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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()
|
||||
|
||||
Reference in New Issue
Block a user