Answer stability round 1: 1 🔴, 4 🟡 (0 misread); check Goals and Audience on the document that is sent, report an unknown section as a Failure, refuse a section body that holds a heading, correct the stale read-only text
This commit is contained in:
@@ -128,7 +128,7 @@ Claude Code reads this section by its heading when it compacts a conversation. K
|
||||
- **chunk** — the unit of work, shipped as one PR; "Working loop" says what it holds.
|
||||
- **cycle** — in `loop-claude`, worker runs and the judge's verdict on each, until the chunk closes or is left for the next cycle. In between, the human answers any interrupt, or the worker resumes with an answer the judge quoted from the premises or the judge's records.
|
||||
- **gate** — the merge gate: the checks a PR passes before it merges.
|
||||
- **goals file** — the file holding a project's `## Goals` and `## Audience`: the one its config names as `goals-and-audience`. Read it in the file `~/.claude/bin/project-record open goals-and-audience` prints. It is `README.md`, unless a client's project keeps it in the config's folder, or in a Jira epic's description, which the loop only reads.
|
||||
- **goals file** — the file holding a project's `## Goals` and `## Audience`: the one its config names as `goals-and-audience`. Read it in the file `~/.claude/bin/project-record open goals-and-audience` prints. It is `README.md`, unless a client's project keeps it in the config's folder, or in a Jira epic's description, whose `## Goals` and `## Audience` the loop only reads.
|
||||
- **interrupt** — `loop-claude` asking the human, on its terminal, for a decision that is theirs. They type a one-line answer there, or `/talk` to open the worker's session there with `claude --resume`. A release ready to cut opens that session at once. A routing call opens claude on that terminal too, in `~/code/claude-config`, the checkout where this setup is developed.
|
||||
- **judge** — the headless claude that reads a worker's transcript each cycle and decides whether to interrupt and whether the chunk is finished.
|
||||
- **judge's records** — the files the judge reads beside the premises: the project's `AGENTS.md` and `docs/decisions.md`, then the human's `~/.claude/CLAUDE.md` and the `.md` files in `~/.claude/rules/`, then those in the project's review standards.
|
||||
|
||||
@@ -134,7 +134,7 @@ The loop reads such a plan and files items into it, each as a Task under the epi
|
||||
|
||||
`todo-item edit` and `move` change only an issue the loop filed. Of an issue a person filed, `edit` sets only the scores, and posts its `--comment` on the issue to tell the team why; the summary, description and Fix Version stay the team's to change in Jira, as do its links. On an issue the loop filed, `edit --blocked-by` makes and deletes the links to the epic's open items. For `todo-item finish`, the config names the workflow transition that finishes an item and the status it leads to, both as Jira shows them: `jira-finish-transition = "Mark as done"` and `jira-finish-status = "Done"`. Finish then moves the item's issue by that transition. It refuses a transition that leads to another status, or to one Jira doesn't count as done, and fails where the config sets neither. The four things not supported for a plan outside the checkout, above, are not supported for a plan in Jira either.
|
||||
|
||||
A client that keeps its goals and audience in an epic's description names that epic as the goals file: `goals-and-audience = "jira:https://acme.atlassian.net/browse/ABC-12"`, which may be the plan's own epic. Such a config keeps its plan in Jira too, and reads both with the same `env-file`. The description needs `## Goals` and `## Audience` as headings, level-2 headings in Jira's editor. `project-record open goals-and-audience` prints a file holding the description's text, and `project-record save` writes it back, refusing a change to `## Goals` or `## Audience`, which only `do-epic` makes, after the human approves it in an interrupt; edit those two in Jira. Whoever may edit that description sets the premises every worker and judge follows, so keep its edit rights to the people who own the project's goals.
|
||||
A client that keeps its goals and audience in an epic's description names that epic as the goals file: `goals-and-audience = "jira:https://acme.atlassian.net/browse/ABC-12"`, which may be the plan's own epic. Such a config keeps its plan in Jira too, and reads both with the same `env-file`. The description needs `## Goals` and `## Audience` as headings, level-2 headings in Jira's editor. `project-record open goals-and-audience` prints a file holding the description's text, and `project-record save` writes it back, except a change to `## Goals` or `## Audience`: edit those two in Jira. A save rewrites the whole description from markdown, which keeps no mention, macro or block id that markdown can't hold. Whoever may edit that description sets the premises every worker and judge follows, so keep its edit rights to the people who own the project's goals.
|
||||
|
||||
To name a chunk's branch, worktree, commits and pull request by the issue key, as in `ABC-123` and `ABC-123 - …`, set these three templates, with your Jira project's key in place of `ABC`: `branch = "ABC-{id}"`, `commit-title = "ABC-{id} - {summary}"` and `pull-request-title = "ABC-{id} - {summary}"`. `project-config --help` says how the templates work.
|
||||
|
||||
@@ -213,7 +213,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
|
||||
- `branch_chunks/` cuts a default branch into chunks and finds, for each, the items it shipped and the later chunks that fixed its code, for `score_outcomes` and `routing_figures`. It imports `reading_cost`'s record path.
|
||||
- `command_lines/` reads a shell command: its simple commands, and a docker call's subcommand and memory limits, for `command_patterns`, `reading_cost`, `routing_figures`, `rule_hook` and `run_heavy`.
|
||||
- `deploy_release` imports `release_plan`'s `release_standing`.
|
||||
- `do_epic/` holds `do-epic`'s parts. `epic_record.py` reads and writes a Jira epic's description by section and language line, through `record_store`'s `EpicDescription`.
|
||||
- `do_epic/` will hold the tool that drives one Jira epic. So far `epic_record.py` reads and writes an epic's description by section and language line, through `record_store`'s `EpicDescription`.
|
||||
- `forge/` tells a GitHub origin from a Gitea one and runs that forge's CLI (`commands.py`), and finds a pull request and waits for its checks (`pulls.py`), for `chunk_preflight`, `chunk_pr`, `deploy_release` and `larv_review`.
|
||||
- `git_cli/` runs git for every tool (`git_repo.py`), and reads the git calls in a shell command (`git_command.py`).
|
||||
- `judge_replay` imports `loop_claude`'s judge, verdicts, premises and records.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
"""A Jira epic's description as do-epic's record: a language line and the sections Goals, Audience, Scoring (the formula and the bar) and Decisions, read and written one at a time through `EpicDescription`, so a write leaves every other line as it was.
|
||||
"""A Jira epic's description as the record of do-epic, the tool that will drive one epic.
|
||||
|
||||
Goals and Audience change only where the human approved in an interrupt, which `write_section` takes as `approved`; `EpicDescription` refuses the change otherwise."""
|
||||
The description holds a language line and the sections Goals, Audience, Scoring (the formula and the bar) and Decisions. They are read and written one at a time through `EpicDescription`, and a write leaves every other line of the markdown as it was. Goals and Audience change only where the human approved in an interrupt, which `write_section` takes as `approved`; `EpicDescription` refuses the change otherwise."""
|
||||
import dataclasses
|
||||
import re
|
||||
import typing
|
||||
@@ -28,6 +28,8 @@ def with_section(text: str, name: str, body: str) -> str | Failure:
|
||||
span = span_of(text, name)
|
||||
if isinstance(span, Failure):
|
||||
return span
|
||||
if any(line.startswith(("# ", "## ")) and not fenced for line, fenced in fenced_lines(body)):
|
||||
return Failure(f"the body of ## {name} holds a level 1 or 2 heading, which would start another section")
|
||||
if span is None:
|
||||
return text.rstrip("\n") + "\n\n" * bool(text.strip()) + f"## {name}\n\n{body.strip()}\n"
|
||||
lines = text.splitlines()
|
||||
@@ -38,9 +40,9 @@ def with_section(text: str, name: str, body: str) -> str | Failure:
|
||||
|
||||
|
||||
def span_of(text: str, name: str) -> tuple[int, int] | None | Failure:
|
||||
"""The index of the one ## name heading's line and of the line that ends its section; None where there is no such heading. Fenced lines start and end no section."""
|
||||
"""The index of the one ## name heading's line and of the line after its section; None where there is no such heading. A heading inside a code fence is ignored."""
|
||||
if name not in SECTIONS:
|
||||
raise ValueError(f"{name} is not a section of an epic's description; the sections are {', '.join(SECTIONS)}")
|
||||
return Failure(f"{name} is not a section of an epic's description; the sections are {', '.join(SECTIONS)}")
|
||||
lines = fenced_lines(text)
|
||||
headings = [index for index, (line, fenced) in enumerate(lines) if not fenced and (line.startswith("# ") or line.startswith("## "))]
|
||||
starts = [index for index in headings if lines[index][0].startswith("## ") and lines[index][0][3:].strip() == name]
|
||||
|
||||
@@ -74,8 +74,17 @@ class SectionsTest(unittest.TestCase):
|
||||
|
||||
def test_refuses_a_repeated_section_and_a_name_that_is_no_section(self) -> None:
|
||||
self.assertIsInstance(with_section("## Scoring\nA\n\n## Scoring\nB\n", "Scoring", "C"), Failure)
|
||||
with self.assertRaisesRegex(ValueError, "Language is not a section.*Goals, Audience, Scoring, Decisions"):
|
||||
read_section(DESCRIPTION, "Language")
|
||||
for found in (read_section(DESCRIPTION, "Language"), with_section(DESCRIPTION, "Language", "Swedish")):
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn("Language is not a section of an epic's description; the sections are Goals, Audience, Scoring, Decisions", found.reason)
|
||||
|
||||
def test_refuses_a_body_that_would_start_another_section(self) -> None:
|
||||
for body in ("A\n## Goals\nB", "# Title"):
|
||||
with self.subTest(body):
|
||||
found = with_section(DESCRIPTION, "Scoring", body)
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn("level 1 or 2 heading", found.reason)
|
||||
self.assertIsInstance(with_section(DESCRIPTION, "Scoring", "```\n## Goals\n```\n### Bar"), str)
|
||||
|
||||
|
||||
class LanguageTest(unittest.TestCase):
|
||||
|
||||
@@ -52,7 +52,8 @@ Where the config leaves them out, `todo-item finish` fails in a Jira plan. Each
|
||||
epic's description is then the goals file, with ## Goals and ## Audience as headings, and
|
||||
`project-config goals-and-audience` prints the setting as the config spells it. The description is
|
||||
written by `project-record save`, except a change to ## Goals or ## Audience, which is refused:
|
||||
edit those two in Jira.
|
||||
edit those two in Jira. A save rewrites the whole description from markdown, which keeps no
|
||||
mention, macro or block id that markdown can't hold.
|
||||
|
||||
Each record, `decisions`, `score-anchors`, `comprehension-history`, `reading-cost` and `changelog`,
|
||||
may name a Confluence Cloud page in place of a path, as "confluence:" and the page's address, with or
|
||||
|
||||
@@ -5,8 +5,8 @@ usage: project-record open <record>
|
||||
|
||||
Run inside a checkout, or a worktree of one. <record> is one of decisions, score-anchors,
|
||||
comprehension-history, reading-cost and changelog, each kept where the project's config names it,
|
||||
or goals-and-audience, the goals file. Goals kept in a Jira epic's description save like any
|
||||
record, except that a change to its ## Goals or ## Audience is refused: edit those two in Jira.
|
||||
or goals-and-audience, the goals file. Save refuses a change to the ## Goals or ## Audience of goals
|
||||
kept in a Jira epic's description: edit those two in Jira.
|
||||
|
||||
open prints the path of a file holding the record's text, and nothing else. Read and edit that
|
||||
file. Where the record is kept as a file, the path is that file. Where it is kept elsewhere, the
|
||||
@@ -20,8 +20,8 @@ save stores the file's text in the record, and prints one line saying so. Where
|
||||
as a file, there is nothing left to store, and save says so. Run it after every edit, so the same
|
||||
steps work wherever a project keeps the record.
|
||||
|
||||
For a record kept on a Confluence page, save refuses where someone saved the page after open read
|
||||
it or after save last wrote it, and the human decides what follows. The copy keeps the unsaved edit
|
||||
For a record kept on a Confluence page or in a Jira epic's description, save refuses where someone
|
||||
saved it after open read it or after save last wrote it, and the human decides what follows. The copy keeps the unsaved edit
|
||||
until open runs again and writes the copy afresh.
|
||||
|
||||
Exit 2 on bad arguments, and 1, saying why, on any other failure.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
"""Record stores and a Jira for tests, held to record_store.contract like every backend."""
|
||||
"""Record stores for tests, held to record_store.contract like every backend, and a fake Jira."""
|
||||
import dataclasses
|
||||
|
||||
from failure import Failure
|
||||
|
||||
@@ -11,5 +11,5 @@ class Held:
|
||||
|
||||
|
||||
def digest_of(text: str) -> str:
|
||||
"""A fingerprint of a record's text, for a backend whose service keeps no version a write could name."""
|
||||
"""A fingerprint of a record's text or document, for a version a write names."""
|
||||
return hashlib.sha256(text.encode("utf-8")).hexdigest()
|
||||
|
||||
@@ -1,8 +1,10 @@
|
||||
"""A project's goals and audience kept as the description of one Jira Cloud epic, read and written over Jira's REST API with the credentials of the config's env-file, and converted by the adf-codec shim.
|
||||
|
||||
Jira keeps no version of a description, so the version a read gives is a digest of its markdown, and a write refuses where the description no longer has that digest. A write changes ## Goals or ## Audience only where the store was told the human approved that section in an interrupt (`approved`)."""
|
||||
Jira keeps no version of a description, so the version a read gives is a digest of the document, and a write refuses where the description no longer has that digest. A write changes ## Goals or ## Audience only where the store was told the human approved that section in an interrupt (`approved`)."""
|
||||
import dataclasses
|
||||
import json
|
||||
import pathlib
|
||||
import typing
|
||||
|
||||
from adf_codec.convert import adfs_to_markdown, markdown_to_adf, Refused
|
||||
from atlassian.client import basic_auth, Http, jira_json, ToAdf, ToMarkdown
|
||||
@@ -39,7 +41,19 @@ class EpicDescription:
|
||||
return held if isinstance(held, Failure) else held.text
|
||||
|
||||
def held(self) -> Held | Failure:
|
||||
"""The description as markdown, with its digest as the version a write over it names."""
|
||||
"""The description as markdown, with a digest of the document Jira holds as the version a write over it names."""
|
||||
description = self.fetched()
|
||||
if isinstance(description, Failure):
|
||||
return description
|
||||
text = "" if description is None else self.markdown_of(description)
|
||||
return text if isinstance(text, Failure) else Held(text, digest_of(json.dumps(description, sort_keys=True)))
|
||||
|
||||
@property
|
||||
def url(self) -> str:
|
||||
return f"{self.epic.site}/rest/api/3/issue/{self.epic.key}"
|
||||
|
||||
def fetched(self) -> dict[str, typing.Any] | None | Failure:
|
||||
"""The description as Jira holds it, an ADF document; None where the epic has none."""
|
||||
authorization = basic_auth(self.env_file)
|
||||
if isinstance(authorization, Failure):
|
||||
return authorization
|
||||
@@ -50,21 +64,19 @@ class EpicDescription:
|
||||
fields = answer.get("fields") if isinstance(answer, dict) else None
|
||||
if not isinstance(fields, dict) or "description" not in fields or not isinstance(fields["description"], dict | None):
|
||||
return Failure(f"the epic {key} is not in the shape Jira Cloud's REST API version 3 documents: its description field is missing, or neither a document nor null")
|
||||
if fields["description"] is None:
|
||||
return Held("", digest_of(""))
|
||||
texts = self.to_markdown([fields["description"]])
|
||||
return fields["description"]
|
||||
|
||||
def markdown_of(self, document: dict[str, typing.Any]) -> str | Failure:
|
||||
key = self.epic.key
|
||||
texts = self.to_markdown([document])
|
||||
if isinstance(texts, Refused):
|
||||
return Failure(f"{key}'s description: {texts.failure.reason}")
|
||||
if isinstance(texts, Failure):
|
||||
return Failure(f"cannot convert {key}'s description to markdown: {texts.reason}")
|
||||
return Held(texts[0], digest_of(texts[0]))
|
||||
|
||||
@property
|
||||
def url(self) -> str:
|
||||
return f"{self.epic.site}/rest/api/3/issue/{self.epic.key}"
|
||||
return texts[0]
|
||||
|
||||
def write(self, text: str, over: str | None) -> Held | Failure:
|
||||
"""Replaces the description with text, over the version held() gave. A text that is the description as read sends nothing, since converting it back would drop each block's localId and Jira's spacing paragraphs. The check of over is a read just before the request: Jira would still take an edit made between the two."""
|
||||
"""Replaces the description with text, over the version held() gave. A text that is the description as read leaves it as Jira holds it, since converting the markdown back would drop each block's localId and Jira's spacing paragraphs; any other text rewrites the whole description, which keeps only what markdown can hold. Jira checks no version, so the check of over is a read just before the request, and an edit a teammate saves between the two is overwritten."""
|
||||
key = self.epic.key
|
||||
current = self.held()
|
||||
if isinstance(current, Failure):
|
||||
@@ -73,11 +85,15 @@ class EpicDescription:
|
||||
return Failure(f"someone saved the description of {key} since the loop read it, so the loop didn't write it: never overwrite their edit, but ask the human what to do")
|
||||
if text == current.text:
|
||||
return current
|
||||
if unapproved := [name for name in APPROVED_SECTIONS if name not in self.approved and sections(text).get(name) != sections(current.text).get(name)]:
|
||||
return Failure(f"the write changes ## {unapproved[0]} of {key}'s description, which needs the human's approval in an interrupt first")
|
||||
document = self.to_adf(text) if text else None
|
||||
if isinstance(document, Failure):
|
||||
return Failure(f"cannot convert the text for {key}'s description to ADF: {document.reason}")
|
||||
# The sections of the description Jira will hold, as the codec reads them: a heading spelt another way than `## Goals` still counts.
|
||||
sent = "" if document is None else self.markdown_of(document)
|
||||
if isinstance(sent, Failure):
|
||||
return sent
|
||||
if unapproved := [name for name in APPROVED_SECTIONS if name not in self.approved and sections(sent).get(name) != sections(current.text).get(name)]:
|
||||
return Failure(f"the write changes ## {unapproved[0]} of {key}'s description without the human's approval: have the human approve it in an interrupt, or edit the section in Jira")
|
||||
authorization = basic_auth(self.env_file)
|
||||
if isinstance(authorization, Failure):
|
||||
return authorization
|
||||
|
||||
@@ -87,7 +87,7 @@ def touch_predictions_store(config: ProjectConfig) -> RecordStore | None:
|
||||
|
||||
|
||||
def goals_store(config: ProjectConfig) -> RecordStore:
|
||||
"""The store config names for the goals file, which holds ## Goals and ## Audience: a markdown file, or a Jira epic's description, whose ## Goals and ## Audience the store changes only once the human approved."""
|
||||
"""The store config names for the goals file, which holds ## Goals and ## Audience: a markdown file, or a Jira epic's description. This store is built without an approval, so it refuses a change to the epic's ## Goals or ## Audience."""
|
||||
if config.goals_epic is None:
|
||||
return FileStore(config.paths["goals-and-audience"], config.tracked("goals-and-audience"))
|
||||
# load refuses a config that names an epic and no env-file.
|
||||
|
||||
@@ -166,6 +166,23 @@ class EpicDescriptionWriteTest(WriteCase):
|
||||
self.assertIn("approval", found.reason)
|
||||
self.assertEqual(self.jira.puts(), [])
|
||||
|
||||
def test_counts_a_heading_the_codec_reads_as_goals_even_where_the_markdown_spells_it_another_way(self) -> None:
|
||||
held = self.held("## Scoring\nValue.\n")
|
||||
as_atx = lambda documents: [fake_markdown(documents)[0].replace("Goals\n=====", "## Goals")]
|
||||
store = EpicDescription(EPIC, self.env, self.jira.http, as_atx, fake_adf)
|
||||
found = store.write("Goals\n=====\nShip.\n\n## Scoring\nValue.\n", held.version)
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn("## Goals", found.reason)
|
||||
self.assertEqual(self.jira.puts(), [])
|
||||
|
||||
def test_refuses_to_write_where_a_teammate_saved_a_change_the_markdown_does_not_show(self) -> None:
|
||||
held = self.held("## Scoring\nValue.\n")
|
||||
self.jira.description = {**fake_adf("## Scoring\nValue.\n"), "localId": "teammate"}
|
||||
found = self.new_store().write("## Scoring\nRisk.\n", held.version)
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn("someone saved", found.reason)
|
||||
self.assertEqual(self.jira.puts(), [])
|
||||
|
||||
def test_refuses_to_add_a_goals_section_before_the_human_approves(self) -> None:
|
||||
held = self.held("## Scoring\nValue.\n")
|
||||
found = self.new_store().write("## Goals\n1. **Achieve:** Ship.\n\n## Scoring\nValue.\n", held.version)
|
||||
|
||||
@@ -407,6 +407,8 @@ Messages keep each file's usual name, such as `todo.md`, as its label, since the
|
||||
|
||||
2026-11-17, claude, through item 391. Serves goal 1.6: a team's Jira and Confluence keep each block's localId and the empty paragraphs Jira uses for spacing, and agents, the judge and people still read the text easily, which keeps goal 1.4's reading cost down. adf-codec converts markdown and ADF by two pairs of calls, as `bin/adf_codec/convert.py` says. The lossless pair keeps the localIds and spacing paragraphs, but wraps every block in two `!adf:` marker lines: a five-line detail became 17 lines in a trial (larvit/adf-codec#185). The portable pair drops both. So the loop reads by the portable pair, and leaves a document alone where a save's text is the text a read showed. `JiraPlan.shows` compares a new detail with the description converted again. `ConfluencePage` keeps the digest of the text it read in the version a write names, and checks that the page still holds that version. Valid while the lossless markdown wraps every block in marker lines. A save that changes one line still rewrites the whole document by the portable pair, and so drops every localId and spacing paragraph, until `todo.md` item 395 keeps each block the save didn't change.
|
||||
|
||||
2026-11-18, claude, item 402. Serves goal 1.6. A Jira epic's description is written by the portable pair too, though the item named the lossless pair: that pair shows the loop marker lines around its blocks, which this decision rejects for the reading cost. `EpicDescription.write` sends nothing for the text a read showed, refuses a write over a description whose document differs from the one read, and refuses a change to `## Goals` or `## Audience` unless the human approved that section. Until item 395, a save that changes one section also reduces a mention or macro in Goals or Audience to its text, which `project-config`'s help and the README tell the reader.
|
||||
|
||||
## project config: `tooling-on-host = true` lets a project with no container setup run its language runtime, package manager, tests and task runner on the host
|
||||
|
||||
2026-11-12, lilleman, through todo item 358. Serves goal 1.6: a legacy product may have no container setup, and the loop works in it without its owners adding one. `CLAUDE.md`'s container rule and the stability reviewer follow the setting. rule-hook checks only how a container starts, its memory limits and its image's pin, never where a runtime runs, so it needs no change. A decision may still put one tool on the host where the project has containers, as this repo's `bin/` decision does. Readers seated as the person who writes the config picked the key, 2 of 3. Valid while the loop runs on the machine that holds the checkout.
|
||||
|
||||
Reference in New Issue
Block a user