Refuse a Touches: list touch-predictions cannot read in todo-item add and edit, and in rank_todo.py --check

This commit is contained in:
2026-11-18 16:17:23 +01:00
parent 2f4442ea13
commit 83714f095c
6 changed files with 90 additions and 9 deletions
+11 -2
View File
@@ -11,6 +11,7 @@ from plan import ranking
from record_store.stores import RecordStore
from text_files.file_writes import replace_file
from plan_store.scoring import weighing_texts
from touch_predictions.prediction import predicted
# What the reader of a missing todo.md is told.
MISSING = "every project keeps a todo.md, and rank_todo.py --help shows one"
@@ -84,7 +85,7 @@ class FilePlan:
return ranked
def check(self) -> list[str]:
"""Why `rank_todo.py --check` fails on the file, empty when it passes: the file is not ranked, or an item scores under the bar."""
"""Why `rank_todo.py --check` fails on the file, empty when it passes: the file is not ranked, an item scores under the bar, or an item's `Touches:` list is one touch-predictions cannot read."""
texts = self.texts()
if isinstance(texts, Failure):
return [texts.reason]
@@ -92,7 +93,7 @@ class FilePlan:
if isinstance(ranked, Failure):
return [ranked.reason]
unranked = [] if ranked.text == texts[0] else [f"{self.path}: not ranked; run rank_todo.py on it"]
return unranked + [f"{self.path}: {line}" for line in ranked.under_bar]
return unranked + [f"{self.path}: {line}" for line in ranked.under_bar + unreadable_touches(texts[0])]
def reported(self, ranked: ranking.Ranked) -> list[str]:
"""Ranking's notes and under-bar lines, each prefixed with the file's path, as a tool prints them on stderr."""
@@ -115,6 +116,14 @@ class FilePlan:
return weighing if isinstance(weighing, Failure) else (plan, *weighing)
def unreadable_touches(todo: str) -> list[str]:
"""Why touch-predictions cannot read each item's `Touches:` list that it cannot. Every item is read, not only the next release's: a later item moves into the next release with its detail, and the list is fixed most cheaply where it was written."""
details = item_details(todo)
if isinstance(details, Failure):
return [details.reason]
return [f"item {id_}: {read.reason}" for id_, detail in details.items() if isinstance(read := predicted(detail), Failure)]
def plan_of(todo: str) -> Plan | Failure:
"""The plan a todo.md's text holds."""
found = items(todo)
+3 -2
View File
@@ -11,7 +11,8 @@ question rows come first, then security rows, then the rest, each group by score
then by ID. Then it moves each blocker, an item another's Blocked by cell names, that ranks below
an item it blocks to just above the first such item. Orders the details to match. Writes each
item's R, and adds the Blocked by and R columns to a table without them. --check doesn't write
anything and fails when the file is not ranked as it would be.
anything and fails when the file is not ranked as it would be, or when an item's detail holds a
`Touches:` list that touch-predictions cannot read, as `touch-predictions --help` spells it.
A valid todo.md; ## Details and each item's detail are optional:
@@ -87,7 +88,7 @@ Exit 1, saying why, on bad arguments, a checkout no config names or a config tha
file given that is not the config's plan, a file that cannot be read or written, a todo.md, goals file or docs/decisions.md that breaks the
rules above, a scoring run on docs/comprehension-history.md's newest scored commit with no Mean row
ending in its overall, an item that is not exempt scoring under the bar, or --check finding the file
unranked.
unranked or a `Touches:` list it cannot read.
"""
import pathlib
import sys
+20
View File
@@ -11,6 +11,7 @@ from project_config.test_project_config import configured
from plan.test_ranking import DECISIONS, OLD_SHAPE, README, TODO
from project_config.settings import DEFAULT_FLOOR
from plan import goals_file, ranking
from todo_item.test_todo_item import READABLE_TOUCHES, UNREADABLE_BULLETS
import rank_todo
@@ -102,6 +103,25 @@ class Main(unittest.TestCase):
self.assertEqual(self.run_main(str(todo)), (1, f"{todo}: {under}\n"))
self.assertEqual(self.run_main("--check", str(todo)), (1, f"{todo}: {under}\n"))
def test_check_fails_on_each_item_whose_touches_list_it_cannot_read(self):
with tempfile.TemporaryDirectory() as temp:
todo = pathlib.Path(temp, "todo.md")
configured(self, pathlib.Path(temp))
self.enterContext(contextlib.chdir(temp))
pathlib.Path(temp, "README.md").write_text(README)
pathlib.Path(temp, "docs").mkdir()
pathlib.Path(temp, "docs", "decisions.md").write_text(DECISIONS)
for bullet in UNREADABLE_BULLETS:
with self.subTest(bullet):
# Item 1 sits in a later release than item 3: the check reads every item's list, not only the next release's.
todo.write_text(TODO.replace("Fast detail.", READABLE_TOUCHES).replace("Later detail.", f"Touches:\n\n{bullet}"))
self.assertEqual(self.run_main(str(todo))[0], 0)
code, said = self.run_main("--check", str(todo))
self.assertEqual(code, 1)
self.assertTrue(said.startswith(f"{todo}: item 1: "), said)
self.assertIn(repr(bullet), said)
self.assertEqual(said.count("\n"), 1)
def test_says_to_reshape_an_old_shape_table_but_passes_the_check(self):
with tempfile.TemporaryDirectory() as temp:
todo = pathlib.Path(temp, "todo.md")
+14 -4
View File
@@ -27,7 +27,8 @@ list and show read only the plan, and print no Score: an item's place in list's
add files the item under the next free ID, with the tagline in bold, and the detail it reads from
stdin, if any. The detail may hold no ## or ### heading.
It prints `Filed item <ID> in <plan>.` It doesn't write anything where ranking fails or scores the item under the bar.
It prints `Filed item <ID> in <plan>.` It doesn't write anything where ranking fails or scores the item under the bar,
or where the detail holds a `Touches:` list that touch-predictions cannot read, as `touch-predictions --help` spells it.
In a Jira epic, add files a Task under the epic, and <ID> is the new issue's number. The release
must be one of the Jira project's Fix Versions, named as 1.2.0 or v1.2.0 there, and --exempt
security also labels the issue `security`. The item scores by the config's `jira-score-formula`, and
@@ -41,7 +42,8 @@ edit sets the cells whose flag is given and leaves the rest; an empty value, as
empties the cell. --detail replaces the detail with the text on stdin, and --clear-detail removes it.
Text on stdin without --detail, and --detail without text on stdin, are refused, so no detail is
dropped or wiped by mistake. It prints `Edited item <ID> in <plan>.` It doesn't write anything where
ranking fails or scores the item under the bar.
ranking fails or scores the item under the bar, or where a new detail holds a `Touches:` list that
touch-predictions cannot read.
In a Jira epic, edit changes an issue the loop filed: its summary, description and scores, the label
`security` with --exempt, and its "is blocked by" links with --blocked-by: it makes a link for each
blocker added and deletes the link of each blocker dropped. Each blocker must be an open child of the
@@ -92,6 +94,7 @@ from plan_store.stores import store as plan_store
from record_store.stores import RecordStore, store
from todo_item.table import shown, table
from todo_item.edits import with_bullet
from touch_predictions.prediction import predicted
# Each score flag, as --l or --L, and the field it sets.
LETTERS = ("L", "E", "I", "S")
@@ -115,7 +118,8 @@ def main(argv: list[str], folder: pathlib.Path = pathlib.Path(), stdin: typing.T
case "show":
done = show(args, plan)
case "add":
done = reported(plan.add(fields(args), piped(stdin)), "not filed", lambda written: f"Filed item {written.id} in {plan.label}.")
detail = piped(stdin)
done = unreadable(detail, "not filed") or reported(plan.add(fields(args), detail), "not filed", lambda written: f"Filed item {written.id} in {plan.label}.")
case "edit":
done = edit(args, plan, piped(stdin))
case "move":
@@ -194,6 +198,12 @@ def reported(written: Written | Failure, refusal: str, done: typing.Callable[[Wr
return done(written)
def unreadable(detail: str | None, refusal: str) -> Failure | None:
"""A Failure opened with refusal where detail holds a `Touches:` list touch-predictions cannot read; checked here, before the plan's backend gets the detail, so a plan in Jira is held to it too. chunk-preflight reads the list first, and on such a list starts no chunk beside the item without saying why."""
read = None if detail is None else predicted(detail)
return Failure(f"{refusal}: {read.reason}") if isinstance(read, Failure) else None
def list_(args: argparse.Namespace, plan: PlanStore) -> str | Failure:
read = plan.read()
if isinstance(read, Failure):
@@ -220,7 +230,7 @@ def edit(args: argparse.Namespace, plan: PlanStore, text: str) -> str | Failure:
detail = text if args.detail else "" if args.clear_detail else None
if not fields(args) and detail is None:
return Failure("not edited: no flag names a change; todo-item --help lists them")
return reported(plan.edit(args.id, fields(args), detail, args.comment), "not edited", lambda written: f"Edited item {written.id} in {plan.label}.")
return unreadable(detail, f"not edited: item {args.id}'s detail") or reported(plan.edit(args.id, fields(args), detail, args.comment), "not edited", lambda written: f"Edited item {written.id} in {plan.label}.")
def finish(args: argparse.Namespace, plan: PlanStore, changelog: RecordStore | None) -> str | Failure:
+41
View File
@@ -25,6 +25,16 @@ CHANGELOG = "# Changelog\n\n## Unreleased\n\n- Older news.\n\n## 0.1.0\n\n- Firs
# ## Details of the ranked fixture, without the trailing ## Notes.
HEADER = "| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves |\n|---|---|---|---|---|---|---|---|---|---|---|\n"
DETAILS = "## Details\n\n### 3. Make it fast, `a | b`.\n\nFast detail.\n\n### 1. Ship the later thing.\n\nLater detail.\n\n"
# The bullets six items held on 2026-11-18, which touch-predictions cannot read: `(small)` after a bare path, and a part not in backticks.
UNREADABLE_BULLETS = (
"- `bin/judge_replay/main.py` (small)",
"- `bin/do_epic/main.py` (small)",
"- `principles/technical-principles.md`: the tests bullet group, `A valuable test checks behaviour` (small)",
"- `README.md`: loop-claude's section (small)",
"- `bin/rule_hook/rules.py`: the rule table (small)",
"- `settings.json`: the PreToolUse matcher (small)",
)
READABLE_TOUCHES = "Why.\n\nTouches:\n\n- `bin/a.py`: `main`, `Plan.branch` (small)\n- `bin/run.sh`: lines 10-20\n- `docs/new.md`\n"
class Terminal(io.StringIO):
@@ -488,6 +498,37 @@ class Edit(TodoItem):
self.assertEqual(self.todo.read_text(), before)
class UnreadableTouches(TodoItem):
"""A `Touches:` list touch-predictions cannot read is refused when written, since chunk-preflight would silently start no chunk beside the item."""
def test_add_and_edit_refuse_each_bullet_that_stalled_the_loop_and_write_nothing(self):
for bullet in UNREADABLE_BULLETS:
for argv, refusal in ((ADD, "not filed: "), (["edit", "3", "--detail"], "not edited: item 3's detail: ")):
with self.subTest(bullet=bullet, command=argv[0]):
before = self.todo.read_text()
code, out, err = self.run_main(*argv, stdin=f"Why.\n\nTouches:\n\n- `bin/a.py`: `main`\n{bullet}\n")
self.assertEqual((code, out), (1, ""))
self.assertTrue(err.startswith(refusal), err)
self.assertIn(repr(bullet), err)
self.assertEqual(self.todo.read_text(), before)
def test_add_and_edit_take_a_readable_list_and_a_detail_without_one(self):
for detail in (READABLE_TOUCHES, "Why, without a list.\n"):
with self.subTest(detail):
self.assertEqual(self.run_main(*ADD, stdin=detail)[0], 0)
self.assertEqual(self.run_main("edit", "3", "--detail", stdin=detail)[0], 0)
self.assertIn(detail, self.todo.read_text())
def test_a_plan_in_jira_gets_no_unreadable_list_either(self):
self.config.write_text(self.config.read_text().replace('"checkout:todo.md"', f'"{JIRA_PLAN}"') + 'env-file = "~/acme.env"\n' + JIRA_SCORING)
plan = MemoryPlan({3: {"Release": "0.1.0", "Item": "**Count the runs.**", "L": "1", "E": "2", "I": "3", "S": "1"}})
self.enterContext(unittest.mock.patch.object(main, "plan_store", return_value=plan))
detail = f"Touches:\n\n{UNREADABLE_BULLETS[0]}\n"
self.assertEqual(self.run_main(*ADD, stdin=detail)[:2], (1, ""))
self.assertEqual(self.run_main("edit", "3", "--detail", stdin=detail)[:2], (1, ""))
self.assertEqual((list(plan.rows), plan.details), ([3], {}))
class Move(TodoItem):
def test_sets_the_items_release_and_keeps_the_rest(self):
self.assertEqual(self.run_main("move", "3", "--release", "0.2.0"), (0, f"Moved item 3 to release 0.2.0 in {self.todo}.\n", ""))
+1 -1
View File
@@ -30,4 +30,4 @@ paths:
- **The Exempt cell keeps an item whatever its score:** `security` for a security finding, `defect` for a 🔴 finding or an item that restores a maintain goal the project breaks today, `question` for a question only the human can answer, which ranks first in its release, `decision` for an item `docs/decisions.md` cites, `owner` for an item the human told you to keep, and, where no other reason fits, `principle` for a 🟡 finding against a file in the config's principles folder, whose item's detail names that principle. Every item `docs/decisions.md` cites carries one of these reasons.
- **A maintain goal vetoes an item that breaks it,** whatever the item scores: redesign the item so it holds the goal, or drop it.
- **When you remove an item that no chunk built, title the commit `Drop item <ID>: <why>`,** or `Drop items 12, 14 and 15: <why>` for several. Such an item was deleted under the bar, vetoed, superseded or moot; a finished item is not one. Without the title, `score-outcomes` credits the item with the work of the chunk that removed it, where that chunk changed more than `todo.md`.
- **Predict, in the detail of each item of the next release, what the item will touch.** When you plan the next release, or file or move an item into it, give the item's detail a `Touches:` line, then one bullet per file the item will change. Each bullet names the file, then the parts of it the item will change: a function, a class or a section heading, or line ranges where the file has none of these. A path alone means the whole file. Read the code first; a prediction from the item's text alone misses. `~/.claude/bin/touch-predictions --help` shows the spelling and how a part is named; a name that holds a backtick takes a longer run of backticks with a space inside each end, as a Markdown code span does. Mark a part `(small)` where the item changes only a few lines of it. Leave out the plan and the project's records, which every chunk writes. `chunk-preflight` reads the predictions to name the items that may start chunks at once, and `touch-predictions record` keeps each beside what its chunk touched.
- **Predict, in the detail of each item of the next release, what the item will touch.** When you plan the next release, or file or move an item into it, give the item's detail a `Touches:` line, then one bullet per file the item will change. Each bullet names the file, then the parts of it the item will change: a function, a class or a section heading, or line ranges where the file has none of these. A path alone means the whole file. Read the code first; a prediction from the item's text alone misses. `~/.claude/bin/touch-predictions --help` shows the spelling and how a part is named; a name that holds a backtick takes a longer run of backticks with a space inside each end, as a Markdown code span does. Mark a part `(small)` where the item changes only a few lines of it. `(small)` follows a part, never a bare path, and a part is a name in backticks or `lines <first>-<last>`. BANNED: ``- `bin/a.py` (small)``, ``- `README.md`: loop-claude's section (small)``. GOOD: ``- `bin/a.py`: `main` (small)``, ``- `README.md`: `## Loop` (small)``. `todo-item add`, `todo-item edit` and `rank_todo.py --check` refuse a list touch-predictions cannot read. Leave out the plan and the project's records, which every chunk writes. `chunk-preflight` reads the predictions to name the items that may start chunks at once, and `touch-predictions record` keeps each beside what its chunk touched.