Print one section of a markdown file, picked by a fragment of its heading, with markdown-section
CI / tests (pull_request) Successful in 4m23s

This commit is contained in:
2026-11-17 09:16:46 +01:00
parent 641645c081
commit d051c4ffe8
8 changed files with 219 additions and 2 deletions
+3
View File
@@ -74,6 +74,9 @@
!bin/loop_state/*.py
!bin/machine_load/
!bin/machine_load/*.py
!bin/markdown-section
!bin/markdown_section/
!bin/markdown_section/*.py
!bin/metric-bench
!bin/metric_bench/
!bin/metric_bench/*.py
+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.
- **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.
- **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.
+2 -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`.
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.
- `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.
@@ -184,6 +184,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `judge-replay <model>` replays loop-claude's judge on archived verdicts of the projects run on the model, and prints what each rung a review climbs to misses, and the lowest rung below them that, like each candidate above it, returns them; `judge-replay --help` states the replay.
- `larv-review <command>` holds larv-review's mechanical rules: the chunk's review folder, the paired ruling's base and vote count, each pass's round count and the opening of its round commit's title, the scoring run's trigger and setup; the comprehension history's format, its latest places and its count of how often seats agree; and each reviewer's prompt header. `larv-review --help` states them. `settings.json` → `hooks` runs `larv-review reviewer-context` as each subagent starts. A reviewer under `agents/` whose frontmatter has `omitClaudeMd: true` starts without `CLAUDE.md`, and the command hands it that file's "Shared goal", "Prose" and "Vocabulary" sections.
- `loop-claude <task>` runs a project's next chunks, each in its own tmux window, cycle after cycle; `loop-claude --help` states its contract.
- `markdown-section <file> <fragment>` prints the section of a markdown file under the first heading that holds the fragment, to the next heading of its level or a higher one, instead of a `grep -n` and a guessed `sed -n` range; `markdown-section --help` says what it does where several headings match.
- `metric-bench [history]` benches cheap static metrics of a project's Python against the places its comprehension history names as hardest; `metric-bench --help` states the metrics and the scores.
- `mutate-changes [--base <ref>] [--prefix <shell text>] [--jobs <n>]` mutation-tests the lines a branch changes and prints each mutant its tests don't kill; `mutate-changes --help` says which tool it runs for each language.
- `notify [<message>]` sends a message, or else stdin, as a DM from the bot of the project's `notifier`, Mattermost or Slack, to the human; the project's `env-file` holds the bot's token, the recipient and, for Mattermost, the server, and `notify --help` names its keys. `loop-claude --help` says when loop-claude sends one.
+9
View File
@@ -0,0 +1,9 @@
#!/usr/bin/env python3
import pathlib
import sys
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
from markdown_section import main
sys.exit(main.main(sys.argv[1:]))
View File
+73
View File
@@ -0,0 +1,73 @@
"""Print one section of a markdown file, picked by a fragment of its heading.
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.
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.
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}(```|~~~)")
def main(argv: list[str]) -> int:
if argv[:1] in (["-h"], ["--help"]):
print(__doc__.strip())
return 0
if len(argv) != 2:
print("usage: markdown-section <file> <fragment>", file=sys.stderr)
return 2
try:
text = pathlib.Path(argv[0]).read_text()
except (OSError, UnicodeDecodeError) as error:
print(f"markdown-section: {error}", file=sys.stderr)
return 1
found = section(text, argv[1])
if isinstance(found, Failure):
print(f"markdown-section: {found.reason}", file=sys.stderr)
return 1
print(found, end="")
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."""
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)):
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()]
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"
@@ -0,0 +1,115 @@
import pathlib
import subprocess
import sys
import tempfile
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from failure import Failure
from markdown_section import main
TOOL = pathlib.Path(__file__).resolve().parents[1] / "markdown-section"
DOCUMENT = """# Title
Intro.
## Alpha
Alpha text.
### Alpha detail
Detail text.
## Beta Gamma
Beta text.
```
## Not a heading
```
## Delta
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'"))
self.assertEqual(main.section(DOCUMENT, "## beta"), Failure("no heading holds '## beta'"))
def test_holds_its_sub_sections(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)
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_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'"))
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")
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()
+16
View File
@@ -2525,3 +2525,19 @@ Read most (opens and searches):
- `bin/loop_claude/cycle/run.py` 4
- `bin/loop_claude/loop/close.py` 3
- `bin/model_routing/test_review_choice.py` 3
## Reading cost, chunk cfb3b6b8c710, finished 2026-11-17T08:13:19Z
182657 new input tokens before the first commit.
Read most (opens and searches):
- `docs/decisions.md` 13
- `README.md` 5
- `skills/larv-review/SKILL.md` 4
- `CLAUDE.md` 3
- `CHANGELOG.md` 1
- `bin/loop_claude/cycle/prompts.py` 1
- `bin/todo-item` 1
- `rules/decisions.md` 1
- `todo.md` 1