From d051c4ffe87b1ed611ca3dbfb33dfb3c26e382a9 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Tue, 17 Nov 2026 09:16:46 +0100 Subject: [PATCH] Print one section of a markdown file, picked by a fragment of its heading, with markdown-section --- .gitignore | 3 + CLAUDE.md | 2 +- README.md | 3 +- bin/markdown-section | 9 ++ bin/markdown_section/__init__.py | 0 bin/markdown_section/main.py | 73 +++++++++++ bin/markdown_section/test_markdown_section.py | 115 ++++++++++++++++++ docs/reading-cost.md | 16 +++ 8 files changed, 219 insertions(+), 2 deletions(-) create mode 100755 bin/markdown-section create mode 100644 bin/markdown_section/__init__.py create mode 100644 bin/markdown_section/main.py create mode 100644 bin/markdown_section/test_markdown_section.py diff --git a/.gitignore b/.gitignore index 86886bec..9f3ba4ff 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/CLAUDE.md b/CLAUDE.md index 0d15cac1..35c1fb1a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 `, 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 `, 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 `, which prints that one entry: `` 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. diff --git a/README.md b/README.md index ea6e70cb..817fb8a7 100644 --- a/README.md +++ b/README.md @@ -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 ` 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 ` 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 ` runs a project's next chunks, each in its own tmux window, cycle after cycle; `loop-claude --help` states its contract. +- `markdown-section ` 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 ] [--prefix ] [--jobs ]` 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 []` 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. diff --git a/bin/markdown-section b/bin/markdown-section new file mode 100755 index 00000000..81e9d818 --- /dev/null +++ b/bin/markdown-section @@ -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:])) diff --git a/bin/markdown_section/__init__.py b/bin/markdown_section/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/bin/markdown_section/main.py b/bin/markdown_section/main.py new file mode 100644 index 00000000..d78db40a --- /dev/null +++ b/bin/markdown_section/main.py @@ -0,0 +1,73 @@ +"""Print one section of a markdown file, picked by a fragment of its heading. + +usage: markdown-section + +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 ` 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=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" diff --git a/bin/markdown_section/test_markdown_section.py b/bin/markdown_section/test_markdown_section.py new file mode 100644 index 00000000..44a2cabc --- /dev/null +++ b/bin/markdown_section/test_markdown_section.py @@ -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 ", ran.stderr) + + def test_help_prints_the_usage(self): + ran = self.run_tool("--help") + self.assertEqual(ran.returncode, 0) + self.assertIn("usage: markdown-section ", ran.stdout) + + +if __name__ == "__main__": + unittest.main() diff --git a/docs/reading-cost.md b/docs/reading-cost.md index bea8be9c..b318d15f 100644 --- a/docs/reading-cost.md +++ b/docs/reading-cost.md @@ -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