Write a Jira epic's description by section, and change its Goals and Audience only once the human approves #595
@@ -2,6 +2,7 @@
|
||||
|
||||
## Unreleased
|
||||
|
||||
- `project-record save` now writes a goals file kept as a Jira epic's description, except a change to `## Goals` or `## Audience`, which stays an edit in Jira.
|
||||
- Add do-epic's epic backend: one interface that reads a Jira epic's child issues and their sub-tasks, with labels, assignee, status and parent, and files new ones, met by a Jira backend and an in-memory fake that pass the same contract tests.
|
||||
- Fix for an outside reviewer's comment on a PR now ends with a change to the setup that would have caught it, in claude-config first, then the principles and standards, then the project.
|
||||
- larv-review reruns the pass that raised a 🟡 when the fix removes or loosens an assertion, changes an expected value, or skips, deletes or guards a test. Other 🟡 fixes still rerun no pass.
|
||||
|
||||
@@ -134,7 +134,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. The loop only reads the description, so edit it in Jira; `project-record open goals-and-audience` prints a file holding its text. 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,6 +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/` 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.
|
||||
|
||||
@@ -0,0 +1,101 @@
|
||||
"""A Jira epic's description as the record of do-epic, the tool that will drive one epic.
|
||||
|
||||
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
|
||||
|
||||
from record_store.jira_description import EpicDescription
|
||||
from failure import Failure
|
||||
from text_files.markdown_text import fenced_lines
|
||||
from record_store.held import Held
|
||||
from project_config.settings import language_fault
|
||||
|
||||
SECTIONS = ("Goals", "Audience", "Scoring", "Decisions")
|
||||
LANGUAGE_LINE = re.compile(r"^\*\*Language:\*\* (.*?)\s*$")
|
||||
|
||||
|
||||
def read_section(text: str, name: str) -> str | Failure:
|
||||
"""The text under the one ## name heading, up to the next heading of level 1 or 2, without the blank lines around it; empty where there is no such heading."""
|
||||
span = span_of(text, name)
|
||||
if isinstance(span, Failure):
|
||||
return span
|
||||
return "" if span is None else "\n".join(text.splitlines()[span[0] + 1 : span[1]]).strip("\n")
|
||||
|
||||
|
||||
def with_section(text: str, name: str, body: str) -> str | Failure:
|
||||
"""text with the one ## name section holding body, put after the others where there is none. A section that already holds body leaves text as it is."""
|
||||
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()
|
||||
if read_section(text, name) == body.strip():
|
||||
return text
|
||||
last = span[1] == len(lines)
|
||||
return "\n".join([*lines[: span[0] + 1], "", *body.strip().splitlines(), *([] if last else [""]), *lines[span[1] :]]) + "\n"
|
||||
|
||||
|
||||
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 after its section; None where there is no such heading. A heading inside a code fence is ignored."""
|
||||
if name not in 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]
|
||||
if len(starts) > 1:
|
||||
return Failure(f"the epic's description has ## {name} more than once")
|
||||
return (starts[0], next((index for index in headings if index > starts[0]), len(lines))) if starts else None
|
||||
|
||||
|
||||
def language_in(text: str) -> str | None:
|
||||
"""The language the description's language line names; None where it has none."""
|
||||
for line, fenced in fenced_lines(text):
|
||||
if not fenced and (found := LANGUAGE_LINE.match(line)):
|
||||
return found.group(1)
|
||||
return None
|
||||
|
||||
|
||||
def with_language(text: str, language: str) -> str | Failure:
|
||||
"""text with its language line naming language, put first where there is none."""
|
||||
if fault := language_fault(language):
|
||||
return Failure(f"cannot write the language {language!r}: {fault}")
|
||||
line = f"**Language:** {language}"
|
||||
lines = fenced_lines(text)
|
||||
for index, (old, fenced) in enumerate(lines):
|
||||
if not fenced and LANGUAGE_LINE.match(old):
|
||||
return "\n".join([*(old for old, _ in lines[:index]), line, *(old for old, _ in lines[index + 1 :])]) + "\n"
|
||||
return line + "\n" + "\n" * bool(text.strip()) + text
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class EpicRecord:
|
||||
"""One epic's record, kept in its description."""
|
||||
description: EpicDescription
|
||||
|
||||
def section(self, name: str) -> str | Failure:
|
||||
text = self.description.read()
|
||||
return text if isinstance(text, Failure) else read_section(text, name)
|
||||
|
||||
def language(self) -> str | None | Failure:
|
||||
text = self.description.read()
|
||||
return text if isinstance(text, Failure) else language_in(text)
|
||||
|
||||
def write_section(self, name: str, body: str, approved: bool = False) -> Held | Failure:
|
||||
"""Writes body as the ## name section. approved says the human approved the change in an interrupt, which Goals and Audience need."""
|
||||
return self.written(lambda text: with_section(text, name, body), frozenset({name}) if approved else frozenset())
|
||||
|
||||
def write_language(self, language: str) -> Held | Failure:
|
||||
return self.written(lambda text: with_language(text, language), frozenset())
|
||||
|
||||
def written(self, change: typing.Callable[[str], str | Failure], approved: frozenset[str]) -> Held | Failure:
|
||||
held = self.description.held()
|
||||
if isinstance(held, Failure):
|
||||
return held
|
||||
text = change(held.text)
|
||||
if isinstance(text, Failure):
|
||||
return text
|
||||
return dataclasses.replace(self.description, approved=approved).write(text, held.version)
|
||||
@@ -0,0 +1,163 @@
|
||||
import dataclasses
|
||||
import pathlib
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from project_config.settings import Epic
|
||||
from record_store.jira_description import EpicDescription
|
||||
from do_epic.epic_record import EpicRecord, language_in, read_section, with_language, with_section
|
||||
from failure import Failure
|
||||
from record_store.fakes import fake_adf, fake_markdown, FakeJira
|
||||
from record_store.held import Held
|
||||
|
||||
DESCRIPTION = """**Language:** Swedish
|
||||
|
||||
## Goals
|
||||
1. **Achieve:** Ship.
|
||||
|
||||
More about shipping.
|
||||
|
||||
## Audience
|
||||
Me.
|
||||
|
||||
## Scoring
|
||||
Value.
|
||||
|
||||
### Bar
|
||||
7.
|
||||
|
||||
## Decisions
|
||||
- A choice.
|
||||
"""
|
||||
|
||||
|
||||
class SectionsTest(unittest.TestCase):
|
||||
def test_reads_a_section_up_to_the_next_heading_of_its_level_keeping_its_blank_lines_and_subsections(self) -> None:
|
||||
self.assertEqual(read_section(DESCRIPTION, "Goals"), "1. **Achieve:** Ship.\n\n More about shipping.")
|
||||
self.assertEqual(read_section(DESCRIPTION, "Scoring"), "Value.\n\n### Bar\n7.")
|
||||
self.assertEqual(read_section(DESCRIPTION, "Decisions"), "- A choice.")
|
||||
|
||||
def test_a_missing_section_reads_empty_and_a_repeated_one_fails(self) -> None:
|
||||
self.assertEqual(read_section("## Goals\nShip.\n", "Scoring"), "")
|
||||
found = read_section("## Scoring\nA\n\n## Scoring\nB\n", "Scoring")
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn("Scoring", found.reason)
|
||||
|
||||
def test_a_heading_inside_a_code_fence_starts_no_section(self) -> None:
|
||||
text = "## Scoring\n```\n## Decisions\n```\n"
|
||||
self.assertEqual(read_section(text, "Decisions"), "")
|
||||
self.assertEqual(read_section(text, "Scoring"), "```\n## Decisions\n```")
|
||||
|
||||
def test_a_top_level_heading_ends_a_section_and_indented_text_stays_indented(self) -> None:
|
||||
self.assertEqual(read_section("## Scoring\n code\n# Title\nB\n", "Scoring"), " code")
|
||||
|
||||
def test_appending_keeps_the_trailing_spaces_of_the_last_line(self) -> None:
|
||||
self.assertEqual(with_section("## Goals\nShip. \n", "Scoring", "Value."), "## Goals\nShip. \n\n## Scoring\n\nValue.\n")
|
||||
|
||||
def test_replaces_one_section_and_leaves_every_other_line_as_it_was(self) -> None:
|
||||
changed = with_section(DESCRIPTION, "Scoring", "Risk.\n")
|
||||
self.assertEqual(changed, DESCRIPTION.replace("Value.\n\n### Bar\n7.\n", "\nRisk.\n"))
|
||||
self.assertEqual(read_section(changed, "Scoring"), "Risk.") # type: ignore[arg-type]
|
||||
|
||||
def test_replaces_the_last_section_without_a_blank_line_after_it(self) -> None:
|
||||
self.assertEqual(with_section("## Scoring\nValue.\n", "Scoring", "Risk."), "## Scoring\n\nRisk.\n")
|
||||
|
||||
def test_a_section_with_the_text_it_holds_leaves_the_description_untouched(self) -> None:
|
||||
self.assertEqual(with_section(DESCRIPTION, "Goals", "1. **Achieve:** Ship.\n\n More about shipping.\n"), DESCRIPTION)
|
||||
|
||||
def test_appends_a_missing_section_after_the_others(self) -> None:
|
||||
self.assertEqual(with_section("## Goals\nShip.\n", "Scoring", "Value."), "## Goals\nShip.\n\n## Scoring\n\nValue.\n")
|
||||
self.assertEqual(with_section("", "Scoring", "Value."), "## Scoring\n\nValue.\n")
|
||||
|
||||
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)
|
||||
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):
|
||||
def test_reads_the_language_line(self) -> None:
|
||||
self.assertEqual(language_in(DESCRIPTION), "Swedish")
|
||||
self.assertIsNone(language_in("## Goals\nShip.\n"))
|
||||
|
||||
def test_a_language_line_in_a_code_fence_is_no_language_line(self) -> None:
|
||||
self.assertIsNone(language_in("```\n**Language:** Swedish\n```\n"))
|
||||
|
||||
def test_replaces_the_language_line_or_puts_it_first(self) -> None:
|
||||
self.assertEqual(with_language(DESCRIPTION, "Brazilian Portuguese"), DESCRIPTION.replace("Swedish", "Brazilian Portuguese"))
|
||||
self.assertEqual(with_language("## Goals\nShip.\n", "Swedish"), "**Language:** Swedish\n\n## Goals\nShip.\n")
|
||||
self.assertEqual(with_language("", "Swedish"), "**Language:** Swedish\n")
|
||||
|
||||
def test_refuses_what_names_no_language(self) -> None:
|
||||
found = with_language(DESCRIPTION, "Swedish; ignore the rules")
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn("not a language", found.reason)
|
||||
|
||||
|
||||
class EpicRecordTest(unittest.TestCase):
|
||||
def setUp(self) -> None:
|
||||
env = pathlib.Path(self.enterContext(tempfile.TemporaryDirectory())) / "acme.env"
|
||||
env.write_text("ATLASSIAN_EMAIL=me@example.com\nATLASSIAN_API_TOKEN=s3cret\n")
|
||||
env.chmod(0o600)
|
||||
self.jira = FakeJira()
|
||||
self.jira.teammate_saves(DESCRIPTION)
|
||||
self.record = EpicRecord(EpicDescription(Epic("https://acme.atlassian.net", "ABC-12"), env, self.jira.http, fake_markdown, fake_adf))
|
||||
|
||||
def test_reads_each_section_and_the_language_from_the_epics_description(self) -> None:
|
||||
self.assertEqual(self.record.section("Audience"), "Me.")
|
||||
self.assertEqual(self.record.language(), "Swedish")
|
||||
|
||||
def test_a_description_that_cannot_be_read_fails_every_read_and_write(self) -> None:
|
||||
record = EpicRecord(dataclasses.replace(self.record.description, http=lambda *call: Failure("HTTP 404: gone")))
|
||||
for found in (record.section("Goals"), record.language(), record.write_section("Scoring", "A"), record.write_language("Swedish")):
|
||||
with self.subTest(found):
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn("ABC-12", found.reason)
|
||||
|
||||
def test_refuses_a_write_over_a_description_a_teammate_saved_since_the_record_read_it(self) -> None:
|
||||
def teammate_saves_after_the_read(method: str, url: str, authorization: str, body: object) -> object:
|
||||
answer = self.jira.http(method, url, authorization, body)
|
||||
if method == "GET" and len(self.jira.calls) == 1:
|
||||
self.jira.teammate_saves("## Goals\nTheirs.\n")
|
||||
return answer
|
||||
|
||||
record = EpicRecord(dataclasses.replace(self.record.description, http=teammate_saves_after_the_read))
|
||||
found = record.write_section("Scoring", "Risk.")
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn("someone saved", found.reason)
|
||||
self.assertEqual(self.jira.puts(), [])
|
||||
|
||||
def test_writes_scoring_and_decisions_and_the_language_without_approval(self) -> None:
|
||||
self.assertIsInstance(self.record.write_section("Scoring", "Risk."), Held)
|
||||
self.assertIsInstance(self.record.write_section("Decisions", "- Another."), Held)
|
||||
self.assertIsInstance(self.record.write_language("Norwegian"), Held)
|
||||
self.assertEqual(self.record.section("Scoring"), "Risk.")
|
||||
self.assertEqual(self.record.section("Decisions"), "- Another.")
|
||||
self.assertEqual(self.record.language(), "Norwegian")
|
||||
self.assertEqual(self.record.section("Goals"), "1. **Achieve:** Ship.\n\n More about shipping.")
|
||||
|
||||
def test_writes_goals_or_audience_only_where_the_human_approved(self) -> None:
|
||||
found = self.record.write_section("Goals", "1. **Achieve:** Ship less.")
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn("approval", found.reason)
|
||||
self.assertEqual(self.jira.puts(), [])
|
||||
self.assertIsInstance(self.record.write_section("Goals", "1. **Achieve:** Ship less.", approved=True), Held)
|
||||
self.assertEqual(self.record.section("Goals"), "1. **Achieve:** Ship less.")
|
||||
# The approval covers the section it was given for, not the next write.
|
||||
self.assertIsInstance(self.record.write_section("Audience", "Everyone."), Failure)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -51,7 +51,9 @@ Where the config leaves them out, `todo-item finish` fails in a Jira plan. Each
|
||||
`goals-and-audience` may name a Jira Cloud epic the same way, where `plan` names one too. The
|
||||
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
|
||||
only read: edit it in Jira.
|
||||
written by `project-record save`, except a change to ## Goals or ## Audience, which is refused:
|
||||
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 are only read, so
|
||||
save refuses them: edit the epic 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.
|
||||
|
||||
@@ -2,16 +2,15 @@
|
||||
|
||||
A write never overwrites a teammate's edit: it sends the version after the one held() read, and Confluence refuses it where someone saved the page since. The human then decides (lilleman, 2026-11-12)."""
|
||||
import dataclasses
|
||||
import hashlib
|
||||
import json
|
||||
import pathlib
|
||||
import typing
|
||||
|
||||
from adf_codec.convert import adfs_to_markdown, markdown_to_adf, Refused
|
||||
from atlassian.client import basic_auth, confluence_json, Http, ToAdf, ToMarkdown
|
||||
from record_store.held import digest_of, Held
|
||||
from rest_client.json_request import ErrorAnswer
|
||||
from failure import Failure
|
||||
from record_store.held import Held
|
||||
from project_config.settings import Page
|
||||
|
||||
# What Confluence answers to a write whose version isn't the one after the version it holds.
|
||||
@@ -141,7 +140,3 @@ class ConfluencePage:
|
||||
return Seen(int(held["version"]), str(held["title"]), held.get("digest"))
|
||||
except (ValueError, KeyError, TypeError) as failure:
|
||||
return Failure(f"cannot read the version of {self.label} to write over, {over!r}: {failure}")
|
||||
|
||||
|
||||
def digest_of(text: str) -> str:
|
||||
return hashlib.sha256(text.encode("utf-8")).hexdigest()
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
"""Record stores 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
|
||||
@@ -29,3 +29,33 @@ class MemoryStore:
|
||||
return Failure(f"someone saved {self.label} since version {over}")
|
||||
self.text, self.version = text, self.version + 1
|
||||
return Held(text, str(self.version))
|
||||
|
||||
|
||||
class FakeJira:
|
||||
"""One epic as Jira Cloud's REST API version 3 serves it: a description that is null or a document, and no version a write could check. Its documents hold the text in one paragraph, which fake_adf and fake_markdown convert."""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self.description: dict[str, object] | None = None
|
||||
self.calls: list[tuple[str, str, str, object]] = []
|
||||
|
||||
def http(self, method: str, url: str, authorization: str, body: object) -> object:
|
||||
self.calls.append((method, url, authorization, body))
|
||||
if method == "GET":
|
||||
return {"key": "ABC-12", "fields": {"description": self.description}}
|
||||
assert isinstance(body, dict)
|
||||
self.description = body["fields"]["description"]
|
||||
return None
|
||||
|
||||
def teammate_saves(self, text: str) -> None:
|
||||
self.description = fake_adf(text)
|
||||
|
||||
def puts(self) -> list[object]:
|
||||
return [call[3] for call in self.calls if call[0] == "PUT"]
|
||||
|
||||
|
||||
def fake_adf(text: str) -> dict[str, object]:
|
||||
return {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": text}]}]}
|
||||
|
||||
|
||||
def fake_markdown(documents: list[dict[str, object]]) -> list[str]:
|
||||
return [document["content"][0]["content"][0]["text"] for document in documents] # type: ignore[index]
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
"""A record as a read found it or a write left it, which every record backend gives."""
|
||||
import dataclasses
|
||||
import hashlib
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
@@ -7,3 +8,8 @@ class Held:
|
||||
"""A record's text as one read found it or one write left it, with its version: what a write over it names, so the write refuses where someone saved the record since. None for a backend whose writes check no version, as a file's."""
|
||||
text: str
|
||||
version: str | None = None
|
||||
|
||||
|
||||
def digest_of(text: str) -> str:
|
||||
"""A fingerprint of a record's text or document, for a version a write names."""
|
||||
return hashlib.sha256(text.encode("utf-8")).hexdigest()
|
||||
|
||||
@@ -1,25 +1,31 @@
|
||||
"""A project's goals and audience kept as the description of one Jira Cloud epic, read over Jira's REST API with the credentials of the config's env-file, and converted by the adf-codec shim.
|
||||
"""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.
|
||||
|
||||
The store only reads: a write, such as `project-record save goals-and-audience`, fails, saying to edit the epic in Jira."""
|
||||
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, Refused
|
||||
from atlassian.client import basic_auth, Http, jira_json, ToMarkdown
|
||||
from adf_codec.convert import adfs_to_markdown, markdown_to_adf, Refused
|
||||
from atlassian.client import basic_auth, Http, jira_json, ToAdf, ToMarkdown
|
||||
from record_store.held import digest_of, Held
|
||||
from project_config.settings import Epic
|
||||
from failure import Failure
|
||||
from record_store.held import Held
|
||||
from text_files.markdown_text import sections
|
||||
|
||||
READ_ONLY = "goals and audience kept in Jira are only read: edit the epic's description in Jira"
|
||||
# The sections of the description a write changes only after the human approves.
|
||||
APPROVED_SECTIONS = ("Goals", "Audience")
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class EpicDescription:
|
||||
"""The description of epic as markdown, read with the credentials env_file holds."""
|
||||
"""The description of epic as markdown, read and written with the credentials env_file holds. approved names the APPROVED_SECTIONS whose change the human approved."""
|
||||
epic: Epic
|
||||
env_file: pathlib.Path
|
||||
http: Http = jira_json
|
||||
to_markdown: ToMarkdown = adfs_to_markdown
|
||||
to_adf: ToAdf = markdown_to_adf
|
||||
approved: frozenset[str] = frozenset()
|
||||
|
||||
@property
|
||||
def label(self) -> str:
|
||||
@@ -31,28 +37,70 @@ class EpicDescription:
|
||||
|
||||
def read(self) -> str | Failure:
|
||||
"""The description as markdown; empty where the epic has none."""
|
||||
held = self.held()
|
||||
return held if isinstance(held, Failure) else held.text
|
||||
|
||||
def held(self) -> Held | Failure:
|
||||
"""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
|
||||
key = self.epic.key
|
||||
answer = self.http("GET", f"{self.epic.site}/rest/api/3/issue/{key}?fields=description", authorization, None)
|
||||
answer = self.http("GET", self.url + "?fields=description", authorization, None)
|
||||
if isinstance(answer, Failure):
|
||||
return Failure(f"cannot read the epic {key}: {answer.reason}")
|
||||
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 ""
|
||||
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 texts[0]
|
||||
|
||||
def held(self) -> Held | Failure:
|
||||
text = self.read()
|
||||
return text if isinstance(text, Failure) else Held(text)
|
||||
|
||||
def write(self, text: str, over: str | None) -> Held | Failure:
|
||||
return Failure(READ_ONLY)
|
||||
"""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):
|
||||
return current
|
||||
if over is not None and current.version != over:
|
||||
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
|
||||
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
|
||||
before, after = sections(current.text), sections(sent)
|
||||
if repeated := [name for name, bodies in after.items() if len(bodies) > max(1, len(before.get(name, [])))]:
|
||||
return Failure(f"the write would repeat ## {repeated[0]} in {key}'s description, which locks that section for reads and writes: leave a heading out of the text, or edit the description in Jira")
|
||||
if unapproved := [name for name in APPROVED_SECTIONS if name not in self.approved and after.get(name) != before.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
|
||||
answer = self.http("PUT", self.url, authorization, {"fields": {"description": document}})
|
||||
if isinstance(answer, Failure):
|
||||
return Failure(f"cannot write the description of {key}: {answer.reason}")
|
||||
return self.held()
|
||||
|
||||
@@ -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, which the store only reads."""
|
||||
"""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.
|
||||
|
||||
@@ -9,10 +9,14 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
from project_config.settings import Epic
|
||||
from record_store.jira_description import EpicDescription
|
||||
from failure import Failure
|
||||
from record_store.fakes import fake_adf, fake_markdown, FakeJira
|
||||
from record_store.held import Held
|
||||
from record_store.contract import RecordStoreContract
|
||||
from adf_codec.convert import Refused
|
||||
|
||||
EPIC = Epic("https://acme.atlassian.net", "ABC-12")
|
||||
AUTHORIZATION = "Basic " + base64.b64encode(b"me@example.com:s3cret").decode()
|
||||
URL = "https://acme.atlassian.net/rest/api/3/issue/ABC-12"
|
||||
GOALS = {"type": "doc", "version": 1, "content": [{"type": "heading", "attrs": {"level": 2}, "content": [{"type": "text", "text": "Goals"}]}]}
|
||||
|
||||
|
||||
@@ -69,20 +73,176 @@ class EpicDescriptionTest(unittest.TestCase):
|
||||
for markdown in (Refused(0, Failure("an unsupported node")), Failure("docker is not running")):
|
||||
with self.subTest(markdown):
|
||||
self.markdown = markdown
|
||||
found = self.store().read()
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn("ABC-12", found.reason)
|
||||
for found in (self.store().read(), self.store().held()):
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn("ABC-12", found.reason)
|
||||
|
||||
def test_missing_credentials_fail(self) -> None:
|
||||
self.env.unlink()
|
||||
self.assertIsInstance(self.store().read(), Failure)
|
||||
self.assertEqual(self.calls, [])
|
||||
|
||||
def test_writing_fails_since_the_store_only_reads(self) -> None:
|
||||
found = self.store().write("## Goals\n", None)
|
||||
|
||||
class WriteCase(unittest.TestCase):
|
||||
def setUp(self) -> None:
|
||||
self.env = pathlib.Path(self.enterContext(tempfile.TemporaryDirectory())) / "acme.env"
|
||||
self.env.write_text("ATLASSIAN_EMAIL=me@example.com\nATLASSIAN_API_TOKEN=s3cret\n")
|
||||
self.env.chmod(0o600)
|
||||
self.jira = FakeJira()
|
||||
|
||||
def new_store(self, approved: frozenset[str] = frozenset()) -> EpicDescription:
|
||||
return EpicDescription(EPIC, self.env, self.jira.http, fake_markdown, fake_adf, approved)
|
||||
|
||||
|
||||
class EpicDescriptionContract(WriteCase, RecordStoreContract):
|
||||
pass
|
||||
|
||||
|
||||
GOALS_AND_SCORING = "## Goals\n1. **Achieve:** Ship.\n\n## Audience\nMe.\n\n## Scoring\nValue.\n"
|
||||
|
||||
|
||||
class EpicDescriptionWriteTest(WriteCase):
|
||||
def held(self, text: str) -> Held:
|
||||
self.jira.teammate_saves(text)
|
||||
held = self.new_store().held()
|
||||
assert isinstance(held, Held), held
|
||||
return held
|
||||
|
||||
def test_writes_the_text_as_the_epics_description(self) -> None:
|
||||
held = self.held(GOALS_AND_SCORING)
|
||||
text = GOALS_AND_SCORING.replace("Value.", "Value, then risk.")
|
||||
written = self.new_store().write(text, held.version)
|
||||
assert isinstance(written, Held), written
|
||||
self.assertEqual(self.jira.puts(), [{"fields": {"description": fake_adf(text)}}])
|
||||
put = next(call for call in self.jira.calls if call[0] == "PUT")
|
||||
self.assertEqual(put[:3], ("PUT", URL, AUTHORIZATION))
|
||||
self.assertEqual(written, self.new_store().held())
|
||||
|
||||
def test_writing_empty_text_clears_the_description(self) -> None:
|
||||
held = self.held("## Decisions\n- one\n")
|
||||
self.assertIsInstance(self.new_store().write("", held.version), Held)
|
||||
self.assertEqual(self.jira.puts(), [{"fields": {"description": None}}])
|
||||
|
||||
def test_saving_the_text_a_read_found_leaves_the_description_as_jira_holds_it(self) -> None:
|
||||
held = self.held(GOALS_AND_SCORING)
|
||||
before = self.jira.description
|
||||
self.assertEqual(self.new_store().write(held.text, held.version), held)
|
||||
self.assertEqual(self.jira.puts(), [])
|
||||
self.assertIs(self.jira.description, before)
|
||||
|
||||
def test_refuses_to_write_where_a_teammate_saved_since_the_read(self) -> None:
|
||||
held = self.held(GOALS_AND_SCORING)
|
||||
self.jira.teammate_saves("## Goals\n1. **Achieve:** Their goal.\n")
|
||||
for text in (held.text, GOALS_AND_SCORING.replace("Value.", "Risk.")):
|
||||
with self.subTest(text):
|
||||
found = self.new_store().write(text, held.version)
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn("someone saved", found.reason)
|
||||
self.assertIn("ABC-12", found.reason)
|
||||
self.assertEqual(self.jira.puts(), [])
|
||||
self.assertEqual(self.new_store().read(), "## Goals\n1. **Achieve:** Their goal.\n")
|
||||
|
||||
def test_refuses_to_write_over_the_version_of_an_epic_that_had_no_description(self) -> None:
|
||||
held = self.new_store().held()
|
||||
assert isinstance(held, Held), held
|
||||
self.jira.teammate_saves("## Goals\nTheirs.\n")
|
||||
found = self.new_store(frozenset({"Goals"})).write("## Goals\nMine.\n", held.version)
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn("Jira", found.reason)
|
||||
self.assertEqual(self.calls, [])
|
||||
self.assertIn("someone saved", found.reason)
|
||||
self.assertEqual(self.jira.puts(), [])
|
||||
|
||||
def test_refuses_to_change_goals_or_audience_before_the_human_approves(self) -> None:
|
||||
held = self.held(GOALS_AND_SCORING)
|
||||
changes = [
|
||||
("Goals", GOALS_AND_SCORING.replace("Ship.", "Ship less.")),
|
||||
("Audience", GOALS_AND_SCORING.replace("Me.", "Everyone.")),
|
||||
("Goals", GOALS_AND_SCORING.replace("## Goals\n1. **Achieve:** Ship.\n\n", "")),
|
||||
]
|
||||
for name, text in changes:
|
||||
with self.subTest(name, text=text):
|
||||
found = self.new_store().write(text, held.version)
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn(name, found.reason)
|
||||
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_a_write_that_repeats_a_section_the_codec_reads_from_another_spelling_of_its_heading(self) -> None:
|
||||
held = self.held("## Decisions\n- one\n")
|
||||
as_atx = lambda documents: [fake_markdown(documents)[0].replace("Decisions\n=====", "## Decisions")]
|
||||
store = EpicDescription(EPIC, self.env, self.jira.http, as_atx, fake_adf)
|
||||
found = store.write("## Decisions\n- one\n\n## Scoring\nValue.\n\nDecisions\n=====\n- copied\n", held.version)
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn("repeat ## Decisions", found.reason)
|
||||
self.assertEqual(self.jira.puts(), [])
|
||||
|
||||
def test_keeps_a_section_that_was_already_repeated_in_the_description(self) -> None:
|
||||
held = self.held("## Decisions\n- one\n\n## Decisions\n- two\n")
|
||||
written = self.new_store().write("## Decisions\n- one\n\n## Decisions\n- two\n\n## Scoring\nValue.\n", held.version)
|
||||
self.assertIsInstance(written, Held)
|
||||
|
||||
def test_the_version_does_not_depend_on_the_order_of_the_documents_keys(self) -> None:
|
||||
held = self.held("## Scoring\nValue.\n")
|
||||
self.jira.description = dict(reversed(list(fake_adf("## Scoring\nValue.\n").items())))
|
||||
self.assertEqual(self.new_store().held(), held)
|
||||
|
||||
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)
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn("Goals", found.reason)
|
||||
self.assertEqual(self.jira.puts(), [])
|
||||
|
||||
def test_changes_goals_once_the_human_approved_that_section_only(self) -> None:
|
||||
held = self.held(GOALS_AND_SCORING)
|
||||
both = GOALS_AND_SCORING.replace("Ship.", "Ship less.").replace("Me.", "Everyone.")
|
||||
found = self.new_store(frozenset({"Goals"})).write(both, held.version)
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn("Audience", found.reason)
|
||||
self.assertNotIn("Goals", found.reason)
|
||||
self.assertEqual(self.jira.puts(), [])
|
||||
written = self.new_store(frozenset({"Goals", "Audience"})).write(both, held.version)
|
||||
self.assertIsInstance(written, Held)
|
||||
self.assertEqual(self.jira.puts(), [{"fields": {"description": fake_adf(both)}}])
|
||||
|
||||
def test_changes_scoring_and_decisions_without_approval(self) -> None:
|
||||
held = self.held(GOALS_AND_SCORING)
|
||||
text = GOALS_AND_SCORING.replace("Value.", "Risk.") + "\n## Decisions\n- A choice.\n"
|
||||
self.assertIsInstance(self.new_store().write(text, held.version), Held)
|
||||
self.assertEqual(self.jira.puts(), [{"fields": {"description": fake_adf(text)}}])
|
||||
|
||||
def test_a_text_the_codec_cannot_convert_is_not_sent(self) -> None:
|
||||
held = self.held("## Decisions\n- one\n")
|
||||
store = EpicDescription(EPIC, self.env, self.jira.http, fake_markdown, lambda text: Failure("unsupported markdown"))
|
||||
found = store.write("## Decisions\n- two\n", held.version)
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn("ABC-12", found.reason)
|
||||
self.assertIn("unsupported markdown", found.reason)
|
||||
self.assertEqual(self.jira.puts(), [])
|
||||
|
||||
def test_a_refused_request_fails_naming_the_epic(self) -> None:
|
||||
held = self.held("## Decisions\n- one\n")
|
||||
refusing = lambda method, url, authorization, body: Failure("HTTP 403: no permission") if method == "PUT" else self.jira.http(method, url, authorization, body)
|
||||
found = EpicDescription(EPIC, self.env, refusing, fake_markdown, fake_adf).write("## Decisions\n- two\n", held.version)
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn("ABC-12", found.reason)
|
||||
self.assertIn("HTTP 403", found.reason)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -2587,3 +2587,12 @@ Read most (opens and searches):
|
||||
- `bin/rung_replay/archive.py` 1
|
||||
- `bin/rung_replay/search.py` 1
|
||||
- `bin/rung_replay/test_rung_replay.py` 1
|
||||
|
||||
## Reading cost, chunk 59dcab68a4fb, finished 2026-11-18T09:15:05Z
|
||||
|
||||
52225 new input tokens before the first commit.
|
||||
|
||||
Read most (opens and searches):
|
||||
|
||||
- `docs/decisions.md` 6
|
||||
- `skills/larv-review/SKILL.md` 5
|
||||
|
||||
@@ -16,12 +16,11 @@
|
||||
| 407 | 0.12.0 | 404 | | **Find an epic repo's checkout and project config by the repo's name, clone a missing one from the host of the epic's other repos, and ask the human where unsure.** | 2 | 2 | 2 | 4 | 3 | 1 by 5 | 1.9 |
|
||||
| 401 | 0.12.0 | | | **Move loop-claude's cycle, judge, interrupt, tmux and routing into a package a second entry point drives, with loop-claude's behaviour unchanged.** | 3 | 2 | 3 | 6 | 6 | 1 by 3, code health by 2 | 1.8 |
|
||||
| 406 | 0.12.0 | 404 | | **Pick each epic item's repo, or for an item without one whether it is Claude's work or a human task, by `repo-rule.md`, record the pick on the issue, and ask the human where the rule leaves it unclear.** | 2 | 2 | 2 | 4 | 4 | 1 by 5 | 1.6 |
|
||||
| 402 | 0.12.0 | | | **Read and write a Jira epic's description as sections, Goals, Audience, Scoring, Decisions and a language line, and write Goals or Audience only after the human approves.** | 2 | 2 | 3 | 5 | 4 | 1 by 5 | 1.6 |
|
||||
| 408 | 0.12.0 | 402 | | **Rank an epic's items by one weight chain, the epic's achieve goals, then code health, then the item's repo goals, then by Blocked by, and re-rank Jira's backlog to match, with people's issues keeping their rank.** | 3 | 2 | 2 | 5 | 4 | 1 by 5 | 1.6 |
|
||||
| 408 | 0.12.0 | | | **Rank an epic's items by one weight chain, the epic's achieve goals, then code health, then the item's repo goals, then by Blocked by, and re-rank Jira's backlog to match, with people's issues keeping their rank.** | 3 | 2 | 2 | 5 | 4 | 1 by 5 | 1.6 |
|
||||
| 410 | 0.12.0 | 401, 404, 406, 407, 408 | | **Run `do-epic <EPIC-KEY>`: one tmux session per epic, a window per chunk, up to the epic's cap of running chunks and each repo's `parallel-chunks`, and never in a repo a loop-claude is running chunks in.** | 3 | 2 | 3 | 6 | 6 | 1 by 5 | 0.8 |
|
||||
| 416 | 0.12.0 | 410 | | **Finish an epic's repo item with a bullet under its repo's `CHANGELOG.md` → `## Unreleased`, or with none where the repo's plan is in Jira.** | 1 | 1 | 1 | 1 | 2 | 1 by 5 | 2.1 |
|
||||
| 413 | 0.12.0 | 402, 410 | | **File a finding about an epic goal in the epic and one about a repo goal by that repo's rules, ask the human where unsure which, and give the judge the epic's records beside the repo's.** | 3 | 2 | 3 | 6 | 4 | 1 by 5 | 1.6 |
|
||||
| 415 | 0.12.0 | 402, 410, 413 | | **Finish an epic: run release-review passes on each repo it changed, work what they file, have the human confirm each goal, post a summary comment, and close the epic in Jira last.** | 3 | 2 | 3 | 6 | 5 | 1 by 5 | 1.2 |
|
||||
| 413 | 0.12.0 | 410 | | **File a finding about an epic goal in the epic and one about a repo goal by that repo's rules, ask the human where unsure which, and give the judge the epic's records beside the repo's.** | 3 | 2 | 3 | 6 | 4 | 1 by 5 | 1.6 |
|
||||
| 415 | 0.12.0 | 410, 413 | | **Finish an epic: run release-review passes on each repo it changed, work what they file, have the human confirm each goal, post a summary comment, and close the epic in Jira last.** | 3 | 2 | 3 | 6 | 5 | 1 by 5 | 1.2 |
|
||||
| 418 | 0.12.0 | 415 | | **Describe do-epic in `README.md`'s tools and setup, with its machine settings and `repo-rule.md`.** | 1 | 2 | 1 | 2 | 2 | 1 by 5 | 2.1 |
|
||||
| 400 | 0.12.0 | | | **Forbid a test that decides at run time whether to check anything in `principles/technical-principles.md`, and point stability-reviewer's Tests checks at it.** | 1 | 2 | 3 | 4 | 2 | 1.1 by 5 | 2.0 |
|
||||
| 409 | 0.12.0 | 406 | | **Split an epic item that changes several repos into one Jira sub-task per repo, each labelled for its repo, with the parent tracking the whole change, when do-epic plans the item.** | 2 | 2 | 3 | 5 | 3 | 1 by 5 | 1.9 |
|
||||
@@ -139,17 +138,6 @@ Touches:
|
||||
- `bin/claude_code/reply.py`: `claude_reply` (small)
|
||||
- `bin/do_epic/repo_pick.py`
|
||||
|
||||
### 402. Read and write a Jira epic's description as sections, Goals, Audience, Scoring, Decisions and a language line, and write Goals or Audience only after the human approves.
|
||||
|
||||
The epic's description is the epic's record (`docs/decisions.md` → `do-epic: drives one Jira epic …`). Today `record_store/jira_description.py` `EpicDescription.write` returns `READ_ONLY`. Build the write on the lossless adf-codec pair, so a save of unedited text leaves the description as Jira holds it. A change to Goals or Audience goes through an interrupt first.
|
||||
|
||||
Touches:
|
||||
|
||||
- `bin/record_store/jira_description.py`: `EpicDescription`
|
||||
- `bin/record_store/stores.py`: `goals_store` (small)
|
||||
- `bin/plan/goals_file.py`: `section` (small)
|
||||
- `bin/do_epic/epic_record.py`
|
||||
|
||||
### 408. Rank an epic's items by one weight chain, the epic's achieve goals, then code health, then the item's repo goals, then by Blocked by, and re-rank Jira's backlog to match, with people's issues keeping their rank.
|
||||
|
||||
Where the epic and a repo disagree, the epic wins (`docs/decisions.md` → `do-epic: drives one Jira epic …`). An item without a repo weighs only the epic's goals. Reuse `goal_weights` and `weight_of`, and `JiraPlan.rank_refusal` for the rank call. `plan/ranking.py` `score` is a place the seats found hard, so the combiner must not add a branch to it.
|
||||
|
||||
Reference in New Issue
Block a user