Merge remote-tracking branch 'origin/main' into item-404
CI / tests (pull_request) Successful in 3m25s
CI / tests (pull_request) Successful in 3m25s
# Conflicts: # .gitignore # README.md # docs/reading-cost.md
This commit is contained in:
@@ -8,6 +8,7 @@
|
||||
!.gitignore
|
||||
!CHANGELOG.md
|
||||
!CLAUDE.md
|
||||
!LICENSE.md
|
||||
!README.md
|
||||
!ci.sh
|
||||
!settings.json
|
||||
@@ -55,6 +56,8 @@
|
||||
!bin/deploy_release/*.py
|
||||
!bin/do_epic/
|
||||
!bin/do_epic/*.py
|
||||
!bin/do_epic/backend/
|
||||
!bin/do_epic/backend/*.py
|
||||
!bin/failure.py
|
||||
!bin/forge/
|
||||
!bin/forge/*.py
|
||||
|
||||
@@ -2,6 +2,10 @@
|
||||
|
||||
## 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.
|
||||
- Add `markdown-section <file> <fragment>`, which prints the section of a markdown file under the heading the fragment picks, to the next heading of its level or a higher one. It fails, listing the headings, where several hold the fragment.
|
||||
- loop-claude and subagent-rung run an L 3 task one rung above the project's rung and an L 4 task two above it: on an Opus 5.5 project, Fable 5.2 at low and at medium.
|
||||
- Add `larv-review round-title <pass>`, which prints a review round commit's title prefix with the 🔴, 🟡 and misread counts taken from the round's report. rule-hook refuses a round commit whose counts differ from that report, where the report exists and can be counted; a report must head each finding `### 🔴` or `### 🟡`, optionally followed by ` [misread]`.
|
||||
|
||||
@@ -18,6 +18,12 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
|
||||
- **Ask, don't guess.** Three choices are always the human's: a goal; a release, meaning the items planned into it and when it is cut; and a change to loop-claude's routing ladder, its rungs included. Any other rule that asks the human's approval reserves that choice too. Ask about a reserved choice. For any other choice, first check whether the goals already answer it. If they nearly do, propose a change to the goals and show how it answers this case: an answer settles one question, a goal settles every question like it. Otherwise take the option you would recommend, and record it with its reason: in the item's detail, or, where it governs later work, as the next sentence says. A recommendation you can give a reason for is not a guess. Ask only where you have no recommendation. Write every answer once, where it belongs, never only in chat: a goal in the goals file, a working rule in `AGENTS.md`, a standing choice in a comment at the one place it governs, or in `docs/decisions.md` once made in more than one place. When an answer holds a goal and a choice, write the goal in the goals file, and record as a choice only what the goal leaves open.
|
||||
- **Bench a syntax with the people who write it.** Before a new or changed spelling of something users read or write ships — markdown, HTML, a config key, a CLI flag — a panel of fresh-context readers, seated as those users from the goals file's `## Audience`, picks it.
|
||||
- **Implement the simplest change that solves the item, and ship it with `/larv-review`.** Whenever a test can check the change, write that test first and see it fail. Take its expected values from the item, never from the code. larv-review's reviewers hold the change to the technical principles, and a finding against one names it. Read a file in the principles folder the project's config sets (`~/.claude/bin/project-config principles` prints it) only when the item changes it, a finding or a record you write names it, or you decline a finding.
|
||||
- **Change the setup for each reasonable fix an outside reviewer asked for on a PR.** An outside reviewer is a forge's auto-reviewer or a human, not one of larv-review's reviewer agents. When you fix a comment of theirs, ask why our review didn't catch the fault first, and change the setup so it would; a fix that only answers the comment leaves the same gap open for the next chunk. Put the change in the first place that fits:
|
||||
1. claude-config's core: the reviewers' agents, `larv-review`, the hooks and tools, so every project gains.
|
||||
2. claude-config's technical principles or review standards, where a rule was missing or too vague.
|
||||
3. The project's own settings, principles folder or `AGENTS.md`, only where the gap is that project's alone. A client repo's `AGENTS.md` changes by a proposal of its own, per "A client project's `CLAUDE.md` and `AGENTS.md`" above.
|
||||
|
||||
In claude-config, the change is a fix of the chunk. In another project, places 1 and 2 are an item in claude-config's plan: start a worktree of claude-config off `origin/main`, run `todo-item add` in it, commit the plan file, and ship it as a pull request of its own with `chunk-pr`, since claude-config's default branch may not take a direct push. Describe the gap without the client's name, code or comment text. File a change too big for the chunk as its own item. Where no place holds the gap, say so in the chunk's summary rather than inventing a change.
|
||||
- **Remove a finished item from the plan, and revise any decision that cites it.** If the repo publishes something others consume — a package, an image, an API — reword the item for them and move it to `CHANGELOG.md` under `## Unreleased`. A changelog is for the public, never for the next agent. Otherwise delete it; git history is the record. `~/.claude/bin/todo-item finish <ID>` removes the item with its detail, and adds the bullet you pass with `--changelog <bullet>`; it refuses while a decision cites the item. A plan kept in Jira takes no bullet, since the issues' history is its changelog: `finish` there refuses `--changelog`. A chunk finishes its items as it merges, through `chunk-pr merge --finish <ID>`, which takes the same flags (`larv-review` §5).
|
||||
- **Releases are the human's.** The version bump and the publishing credentials are theirs, whatever another rule says. Prepare everything else, so cutting a release is one decision.
|
||||
- **Open each plan item or ticket with a bold one-sentence tagline**, so the taglines alone say what a release holds. The tagline states the target state, checkable when done: an imperative verb plus what holds afterwards. A present-tense fact reads as the current state and doesn't say anything about what to do. Add "today X" only where the direction is otherwise ambiguous. GOOD: `**Accept undefined in MetadataValue and drop such keys on output.**` BANNED: `MetadataValue accepts undefined; such keys are dropped on output`.
|
||||
@@ -128,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.
|
||||
|
||||
+21
@@ -0,0 +1,21 @@
|
||||
# MIT License
|
||||
|
||||
Copyright (c) 2026 Larv IT AB
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
@@ -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,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` imports `project_config`'s settings and `model_routing`'s ladder file.
|
||||
- `do_epic/` will hold the tool that drives one Jira epic. So far `config.py` reads its machine-wide settings, importing `project_config`'s settings and `model_routing`'s ladder file, and `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,88 @@
|
||||
"""What every backend of an epic's plan must hold, as tests. A backend's test case inherits EpicStoreContract and unittest.TestCase, and builds an epic with no issues in new_store. Its assign and close change an issue as a person would in the tracker."""
|
||||
import re
|
||||
import typing
|
||||
|
||||
from do_epic.backend.protocol import EpicIssue, EpicStore
|
||||
from failure import Failure
|
||||
|
||||
|
||||
class EpicStoreContract:
|
||||
assertEqual: typing.Callable[..., None]
|
||||
assertIsInstance: typing.Callable[..., None]
|
||||
subTest: typing.Callable[..., typing.ContextManager[None]]
|
||||
|
||||
def new_store(self) -> EpicStore:
|
||||
raise NotImplementedError
|
||||
|
||||
def assign(self, store: EpicStore, key: str, name: str) -> None:
|
||||
"""Assigns the issue named key to the person whose display name is name."""
|
||||
raise NotImplementedError
|
||||
|
||||
def close(self, store: EpicStore, key: str, status: str) -> None:
|
||||
"""Moves the issue named key to the done status named status."""
|
||||
raise NotImplementedError
|
||||
|
||||
def filed(self, store: EpicStore, parent: str, summary: str, detail: str = "", labels: tuple[str, ...] = ()) -> str:
|
||||
key = store.file(parent, summary, detail, labels)
|
||||
assert isinstance(key, str), key
|
||||
return key
|
||||
|
||||
def issues(self, store: EpicStore) -> list[EpicIssue]:
|
||||
read = store.read()
|
||||
assert isinstance(read, list), read
|
||||
return read
|
||||
|
||||
def test_an_epic_with_no_issues_reads_empty(self) -> None:
|
||||
self.assertEqual(self.new_store().read(), [])
|
||||
|
||||
def test_reads_back_a_child_issue_it_filed(self) -> None:
|
||||
store = self.new_store()
|
||||
key = self.filed(store, store.epic_key, "Count the runs.", "Why it counts.\n\nA second paragraph.", ("security", "api"))
|
||||
self.assertEqual(self.issues(store), [EpicIssue(key, "Count the runs.", "Why it counts.\n\nA second paragraph.", ("api", "security"), None, "To Do", False, store.epic_key)])
|
||||
|
||||
def test_reads_back_a_sub_task_it_filed_after_its_parent(self) -> None:
|
||||
store = self.new_store()
|
||||
first = self.filed(store, store.epic_key, "Count the runs.")
|
||||
second = self.filed(store, store.epic_key, "Ship the later thing.")
|
||||
task = self.filed(store, first, "Count them in the api.", labels=("api",))
|
||||
read = self.issues(store)
|
||||
self.assertEqual([(issue.key, issue.parent) for issue in read], [(first, store.epic_key), (task, first), (second, store.epic_key)])
|
||||
self.assertEqual((read[1].summary, read[1].labels, read[1].detail), ("Count them in the api.", ("api",), ""))
|
||||
|
||||
def test_files_each_issue_under_its_own_key_in_the_epics_project(self) -> None:
|
||||
store = self.new_store()
|
||||
child = self.filed(store, store.epic_key, "Count the runs.")
|
||||
keys = [child, self.filed(store, store.epic_key, "Count the runs."), self.filed(store, child, "Count them in the api.")]
|
||||
self.assertEqual(len(set(keys)), 3)
|
||||
project = store.epic_key.rpartition("-")[0]
|
||||
self.assertEqual([re.fullmatch(f"{project}-[1-9][0-9]*", key) is not None for key in keys], [True] * 3)
|
||||
|
||||
def test_reads_the_assignee_and_a_done_status(self) -> None:
|
||||
store = self.new_store()
|
||||
first = self.filed(store, store.epic_key, "Count the runs.")
|
||||
second = self.filed(store, store.epic_key, "Ship the later thing.")
|
||||
self.assign(store, first, "Ada Lovelace")
|
||||
self.close(store, second, "Done")
|
||||
read = {issue.key: issue for issue in self.issues(store)}
|
||||
self.assertEqual((read[first].assignee, read[first].status, read[first].done), ("Ada Lovelace", "To Do", False))
|
||||
self.assertEqual((read[second].assignee, read[second].status, read[second].done), (None, "Done", True))
|
||||
|
||||
def test_refuses_to_file_under_a_sub_task(self) -> None:
|
||||
store = self.new_store()
|
||||
child = self.filed(store, store.epic_key, "Count the runs.")
|
||||
task = self.filed(store, child, "Count them in the api.")
|
||||
self.assertEqual(store.file(task, "Count more.", "", ()), Failure(f"{task} is neither the epic {store.epic_key} nor one of its child issues, so nothing can be filed under it"))
|
||||
self.assertEqual(len(self.issues(store)), 2)
|
||||
|
||||
def test_refuses_to_file_under_an_issue_outside_the_epic(self) -> None:
|
||||
store = self.new_store()
|
||||
for parent in ("ZZZ-1", "not a key"):
|
||||
with self.subTest(parent=parent):
|
||||
self.assertIsInstance(store.file(parent, "Count more.", "", ()), Failure)
|
||||
self.assertEqual(self.issues(store), [])
|
||||
|
||||
def test_refuses_a_label_with_white_space_and_a_summary_of_two_lines(self) -> None:
|
||||
store = self.new_store()
|
||||
self.assertEqual(store.file(store.epic_key, "Count the runs.", "", ("two words",)), Failure("the label 'two words' is empty or holds white space"))
|
||||
self.assertEqual(store.file(store.epic_key, "Count\nthe runs.", "", ()), Failure("the summary must be one line of text"))
|
||||
self.assertEqual(self.issues(store), [])
|
||||
@@ -0,0 +1,33 @@
|
||||
"""An epic held in memory, for do-epic's tests, held to contract.py like every backend."""
|
||||
import dataclasses
|
||||
|
||||
from do_epic.backend.protocol import EpicIssue, no_parent, unfit
|
||||
from failure import Failure
|
||||
|
||||
|
||||
@dataclasses.dataclass
|
||||
class MemoryEpic:
|
||||
"""An epic whose issues rank in the order filed. Where fails is set, every read and filing fails with it as the reason."""
|
||||
epic_key: str
|
||||
issues: list[EpicIssue] = dataclasses.field(default_factory=list)
|
||||
fails: str | None = None
|
||||
|
||||
def read(self) -> list[EpicIssue] | Failure:
|
||||
if self.fails:
|
||||
return Failure(self.fails)
|
||||
return [issue for child in self.issues if child.parent == self.epic_key for issue in (child, *(task for task in self.issues if task.parent == child.key))]
|
||||
|
||||
def file(self, parent: str, summary: str, detail: str, labels: tuple[str, ...]) -> str | Failure:
|
||||
if self.fails:
|
||||
return Failure(self.fails)
|
||||
if refused := unfit(summary, labels):
|
||||
return refused
|
||||
if parent != self.epic_key and parent not in {issue.key for issue in self.issues if issue.parent == self.epic_key}:
|
||||
return no_parent(self.epic_key, parent)
|
||||
key = f"{self.epic_key.rpartition('-')[0]}-{len(self.issues) + 100}"
|
||||
self.issues.append(EpicIssue(key, summary, detail.strip(), tuple(sorted(labels)), None, "To Do", False, parent))
|
||||
return key
|
||||
|
||||
def change(self, key: str, **fields: object) -> None:
|
||||
"""Changes the issue named key as a person would in the tracker, such as assignee="Ada Lovelace"."""
|
||||
self.issues = [dataclasses.replace(issue, **fields) if issue.key == key else issue for issue in self.issues] # type: ignore[arg-type]
|
||||
@@ -0,0 +1,148 @@
|
||||
"""An epic's plan kept as a Jira Cloud epic's child issues and their sub-tasks, read and filed over Jira's REST API version 3."""
|
||||
import dataclasses
|
||||
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
|
||||
from project_config.settings import Epic
|
||||
from do_epic.backend.protocol import EpicIssue, no_parent, unfit
|
||||
from failure import Failure
|
||||
from plan_store.jira_epic import ISSUE_KEY, ISSUE_TYPE, project_of, searched
|
||||
|
||||
FIELDS = ["summary", "description", "labels", "assignee", "status", "parent"]
|
||||
# How many child issues one search for sub-tasks names, which keeps its JQL well inside the length Jira takes.
|
||||
PARENTS_PER_SEARCH = 50
|
||||
PERHAPS_FILED = "unless Jira refused the request, the issue may exist: look under {parent} before filing it again"
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Found:
|
||||
"""An issue as Jira answered it, its description still in Jira's document format."""
|
||||
issue: EpicIssue
|
||||
description: dict[str, typing.Any] | None
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class JiraEpic:
|
||||
"""The issues of a Jira epic, read and filed with the credentials env_file holds."""
|
||||
epic: Epic
|
||||
env_file: pathlib.Path
|
||||
http: Http = jira_json
|
||||
to_markdown: ToMarkdown = adfs_to_markdown
|
||||
to_adf: ToAdf = markdown_to_adf
|
||||
|
||||
@property
|
||||
def epic_key(self) -> str:
|
||||
return self.epic.key
|
||||
|
||||
def read(self) -> list[EpicIssue] | Failure:
|
||||
authorization = basic_auth(self.env_file)
|
||||
if isinstance(authorization, Failure):
|
||||
return authorization
|
||||
found = self.found(authorization)
|
||||
if isinstance(found, Failure):
|
||||
return found
|
||||
# A container run converts every description at once. It comes after every other check, since a read that fails doesn't need it.
|
||||
described = [each for each in found if each.description is not None]
|
||||
texts = self.to_markdown([each.description for each in described if each.description is not None])
|
||||
if isinstance(texts, Refused):
|
||||
return Failure(f"{described[texts.index].issue.key}'s description: {texts.failure.reason}")
|
||||
if isinstance(texts, Failure):
|
||||
return Failure(f"cannot convert the descriptions of {self.epic_key}'s issues to markdown: {texts.reason}")
|
||||
details = {each.issue.key: text.strip() for each, text in zip(described, texts)}
|
||||
return [dataclasses.replace(each.issue, detail=details.get(each.issue.key, "")) for each in found]
|
||||
|
||||
def file(self, parent: str, summary: str, detail: str, labels: tuple[str, ...]) -> str | Failure:
|
||||
authorization = basic_auth(self.env_file)
|
||||
if isinstance(authorization, Failure):
|
||||
return authorization
|
||||
if refused := unfit(summary, labels) or self.not_a_parent(parent, authorization):
|
||||
return refused
|
||||
fields: dict[str, typing.Any] = {"project": {"key": project_of(parent)}, "parent": {"key": parent}, "summary": summary, "labels": list(labels)}
|
||||
kind = {"name": ISSUE_TYPE} if parent == self.epic_key else self.sub_task_type(project_of(parent), authorization)
|
||||
if isinstance(kind, Failure):
|
||||
return kind
|
||||
if detail.strip():
|
||||
description = self.to_adf(detail)
|
||||
if isinstance(description, Failure):
|
||||
return Failure(f"cannot convert the detail to a Jira description: {description.reason}")
|
||||
fields["description"] = description
|
||||
created = self.http("POST", f"{self.epic.site}/rest/api/3/issue", authorization, {"fields": fields | {"issuetype": kind}})
|
||||
if isinstance(created, Failure):
|
||||
return Failure(f"cannot file the issue under {parent}: {created.reason}; {PERHAPS_FILED.format(parent=parent)}")
|
||||
key = created.get("key") if isinstance(created, dict) else None
|
||||
if not isinstance(key, str) or not ISSUE_KEY.fullmatch(key):
|
||||
return Failure(f"Jira answered the new issue without an issue key; {PERHAPS_FILED.format(parent=parent)}")
|
||||
return key
|
||||
|
||||
def not_a_parent(self, parent: str, authorization: str) -> Failure | None:
|
||||
"""Why nothing can be filed under parent; None where it is the epic or one of its child issues."""
|
||||
if parent == self.epic_key:
|
||||
return None
|
||||
if not ISSUE_KEY.fullmatch(parent):
|
||||
return no_parent(self.epic_key, parent)
|
||||
# A search may not show an issue filed a moment ago, so the parent is asked for by its key.
|
||||
answered = self.http("GET", f"{self.epic.site}/rest/api/3/issue/{parent}?fields=parent", authorization, None)
|
||||
if isinstance(answered, Failure):
|
||||
return Failure(f"cannot read {parent} to file under it: {answered.reason}")
|
||||
fields = answered.get("fields") if isinstance(answered, dict) else None
|
||||
above = fields.get("parent") if isinstance(fields, dict) else None
|
||||
return None if isinstance(above, dict) and above.get("key") == self.epic_key else no_parent(self.epic_key, parent)
|
||||
|
||||
def found(self, authorization: str) -> list[Found] | Failure:
|
||||
"""Each child issue, each followed by its sub-tasks."""
|
||||
# The search answers no issues for an epic the account cannot see; asking for the epic itself tells that from an epic without children.
|
||||
seen = self.http("GET", f"{self.epic.site}/rest/api/3/issue/{self.epic_key}?fields=summary", authorization, None)
|
||||
if isinstance(seen, Failure):
|
||||
return Failure(f"cannot read the epic {self.epic_key}: {seen.reason}")
|
||||
children = self.searched(f"{self.epic_key}'s child issues", (self.epic_key,), authorization)
|
||||
if isinstance(children, Failure):
|
||||
return children
|
||||
keys = [each.issue.key for each in children]
|
||||
tasks: list[Found] = []
|
||||
for start in range(0, len(keys), PARENTS_PER_SEARCH):
|
||||
batch = self.searched(f"the sub-tasks of {self.epic_key}'s child issues", tuple(keys[start:start + PARENTS_PER_SEARCH]), authorization)
|
||||
if isinstance(batch, Failure):
|
||||
return batch
|
||||
tasks += batch
|
||||
return [each for child in children for each in (child, *(task for task in tasks if task.issue.parent == child.issue.key))]
|
||||
|
||||
def searched(self, what: str, parents: tuple[str, ...], authorization: str) -> list[Found] | Failure:
|
||||
"""The issues whose parent is one of parents, in rank order."""
|
||||
named = ", ".join(f'"{key}"' for key in parents)
|
||||
answered = searched(self.epic.site, what, f"parent in ({named}) ORDER BY Rank ASC", {"fields": FIELDS}, authorization, self.http)
|
||||
if isinstance(answered, Failure):
|
||||
return answered
|
||||
found = [found_of(raw) for raw in answered]
|
||||
return next((each for each in found if isinstance(each, Failure)), None) or [each for each in found if isinstance(each, Found)]
|
||||
|
||||
def sub_task_type(self, project: str, authorization: str) -> dict[str, str] | Failure:
|
||||
"""The project's sub-task issue type, by id, since sites name it differently, such as Subtask or Sub-task."""
|
||||
answered = self.http("GET", f"{self.epic.site}/rest/api/3/issue/createmeta/{project}/issuetypes", authorization, None)
|
||||
if isinstance(answered, Failure):
|
||||
return Failure(f"cannot read {project}'s issue types: {answered.reason}")
|
||||
types = answered.get("issueTypes") if isinstance(answered, dict) else None
|
||||
if not isinstance(types, list):
|
||||
return Failure(f"Jira answered {project}'s issue types in a shape its REST API version 3 doesn't document")
|
||||
found = next((kind["id"] for kind in types if isinstance(kind, dict) and kind.get("subtask") is True and isinstance(kind.get("id"), str)), None)
|
||||
return Failure(f"{project} has no sub-task issue type; turn sub-tasks on in Jira") if found is None else {"id": found}
|
||||
|
||||
|
||||
def found_of(raw: object) -> Found | Failure:
|
||||
"""The issue in one entry of a search's answer, or which issue is not in the shape Jira documents."""
|
||||
key = raw.get("key") if isinstance(raw, dict) else None
|
||||
if not isinstance(raw, dict) or not isinstance(key, str) or not ISSUE_KEY.fullmatch(key):
|
||||
return Failure("the search answered an issue without an issue key")
|
||||
# The answer's nested fields are read as Jira documents them; one missing or of another type ends the read here.
|
||||
try:
|
||||
fields = raw["fields"]
|
||||
summary, labels, assignee, status, parent, description = fields["summary"], fields["labels"], fields["assignee"], fields["status"], fields["parent"]["key"], fields["description"]
|
||||
name = assignee["displayName"] if assignee is not None else None
|
||||
state, done = status["name"], status["statusCategory"]["key"] == "done"
|
||||
except (AttributeError, KeyError, TypeError) as failure:
|
||||
return Failure(f"{key} is not in the shape Jira Cloud's REST API version 3 documents: {failure!r}")
|
||||
texts = (summary, *labels, state, parent) if isinstance(labels, list) else ()
|
||||
if not texts or not all(isinstance(text, str) for text in texts) or not isinstance(name, str | None) or not ISSUE_KEY.fullmatch(parent) or not isinstance(description, dict | None):
|
||||
return Failure(f"{key} is not in the shape Jira Cloud's REST API version 3 documents: its summary, labels, assignee, status, parent or description holds another kind of value")
|
||||
return Found(EpicIssue(key, summary.strip(), "", tuple(sorted(labels)), name, state, done, parent), description)
|
||||
@@ -0,0 +1,58 @@
|
||||
"""What every backend of an epic's plan reads and files: an EpicIssue, and the EpicStore protocol they all meet. do-epic reads an epic only through EpicStore, so another tracker can stand behind it; contract.py holds the tests every backend passes.
|
||||
|
||||
EpicStore is not plan_store's PlanStore. A PlanStore item names a release, but an epic item has none (`docs/decisions.md` → `do-epic: drives one Jira epic …`), and it may be a sub-task."""
|
||||
import dataclasses
|
||||
import re
|
||||
import typing
|
||||
|
||||
from failure import Failure
|
||||
|
||||
# What a tracker accepts as a label: Jira refuses a label holding white space.
|
||||
LABEL = re.compile(r"\S+")
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class EpicIssue:
|
||||
"""One of an epic's child issues, or a sub-task of one, as a read found it."""
|
||||
key: str
|
||||
summary: str
|
||||
# The description, as markdown; empty where the issue has none.
|
||||
detail: str
|
||||
# Sorted by name.
|
||||
labels: tuple[str, ...]
|
||||
# The assignee's display name; None where nobody is assigned.
|
||||
assignee: str | None
|
||||
# The status's name, such as "In Progress".
|
||||
status: str
|
||||
# Whether the status is one the tracker counts as done.
|
||||
done: bool
|
||||
# The epic's key for a child issue, the child's key for a sub-task.
|
||||
parent: str
|
||||
|
||||
|
||||
class EpicStore(typing.Protocol):
|
||||
"""The issues of one epic. A write that fails doesn't file anything, except where its Failure says the tracker may have taken it all the same."""
|
||||
|
||||
@property
|
||||
def epic_key(self) -> str:
|
||||
"""The parent of each child issue."""
|
||||
|
||||
def read(self) -> list[EpicIssue] | Failure:
|
||||
"""Each child issue, open or done, in the tracker's rank order, each followed by its sub-tasks in theirs."""
|
||||
|
||||
def file(self, parent: str, summary: str, detail: str, labels: tuple[str, ...]) -> str | Failure:
|
||||
"""Files an open issue under parent and answers its key: a child issue where parent is the epic, a sub-task where parent is one of its child issues. detail is markdown, and may be empty."""
|
||||
|
||||
|
||||
def unfit(summary: str, labels: tuple[str, ...]) -> Failure | None:
|
||||
"""Why no tracker can file an issue with this summary and these labels; None where one can."""
|
||||
if not summary.strip() or "\n" in summary:
|
||||
return Failure("the summary must be one line of text")
|
||||
if bad := next((label for label in labels if not LABEL.fullmatch(label)), None):
|
||||
return Failure(f"the label {bad!r} is empty or holds white space")
|
||||
return None
|
||||
|
||||
|
||||
def no_parent(epic_key: str, parent: str) -> Failure:
|
||||
"""What every backend says when asked to file under parent, which is neither the epic nor one of its child issues."""
|
||||
return Failure(f"{parent} is neither the epic {epic_key} nor one of its child issues, so nothing can be filed under it")
|
||||
@@ -0,0 +1,30 @@
|
||||
import pathlib
|
||||
import sys
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[2]))
|
||||
|
||||
from do_epic.backend.contract import EpicStoreContract
|
||||
from failure import Failure
|
||||
from do_epic.backend.fake import MemoryEpic
|
||||
|
||||
|
||||
class MemoryEpicContract(EpicStoreContract, unittest.TestCase):
|
||||
def new_store(self) -> MemoryEpic:
|
||||
return MemoryEpic("ABC-12")
|
||||
|
||||
def assign(self, store: MemoryEpic, key: str, name: str) -> None: # type: ignore[override]
|
||||
store.change(key, assignee=name)
|
||||
|
||||
def close(self, store: MemoryEpic, key: str, status: str) -> None: # type: ignore[override]
|
||||
store.change(key, status=status, done=True)
|
||||
|
||||
|
||||
class Failing(unittest.TestCase):
|
||||
def test_every_read_and_filing_fails_with_the_reason_given(self) -> None:
|
||||
store = MemoryEpic("ABC-12", fails="Jira is down")
|
||||
self.assertEqual((store.read(), store.file("ABC-12", "Count the runs.", "", ())), (Failure("Jira is down"), Failure("Jira is down")))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,190 @@
|
||||
import base64
|
||||
import dataclasses
|
||||
import pathlib
|
||||
import re
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
import unittest.mock
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[2]))
|
||||
|
||||
from project_config.settings import Epic
|
||||
from do_epic.backend.contract import EpicStoreContract
|
||||
from failure import Failure
|
||||
from plan_store import jira_epic
|
||||
from do_epic.backend.jira import JiraEpic
|
||||
from adf_codec.convert import Refused
|
||||
|
||||
SITE = "https://acme.atlassian.net"
|
||||
EPIC = Epic(SITE, "ABC-12")
|
||||
AUTHORIZATION = "Basic " + base64.b64encode(b"me@example.com:s3cret").decode()
|
||||
EPIC_URL = f"{SITE}/rest/api/3/issue/ABC-12?fields=summary"
|
||||
ISSUE_TYPES = f"{SITE}/rest/api/3/issue/createmeta/ABC/issuetypes"
|
||||
SEARCH = f"{SITE}/rest/api/3/search/jql"
|
||||
ISSUES = f"{SITE}/rest/api/3/issue"
|
||||
TO_DO = {"name": "To Do", "statusCategory": {"key": "new"}}
|
||||
TYPES = {"issueTypes": [{"id": "10001", "name": "Task", "subtask": False}, {"id": "10003", "name": "Subtask", "subtask": True}]}
|
||||
|
||||
|
||||
def to_adf(markdown: str) -> dict[str, object]:
|
||||
"""Stands in for the adf-codec shim: one paragraph holding the markdown."""
|
||||
return {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": markdown}]}]}
|
||||
|
||||
|
||||
def to_markdown(documents: list[dict[str, object]]) -> list[str]:
|
||||
return [document["content"][0]["content"][0]["text"] + "\n" for document in documents] # type: ignore[index]
|
||||
|
||||
|
||||
@dataclasses.dataclass
|
||||
class FakeJira:
|
||||
"""Jira Cloud's REST API as JiraEpic calls it. It holds issues as Jira answers them, in rank order. A search answers two issues a page, with only the fields it asks for. A call whose method and URL are in answers gets the answer held there instead."""
|
||||
issues: list[dict[str, object]] = dataclasses.field(default_factory=list)
|
||||
answers: dict[tuple[str, str], object] = dataclasses.field(default_factory=dict)
|
||||
calls: list[tuple[str, str]] = dataclasses.field(default_factory=list)
|
||||
|
||||
def __call__(self, method: str, url: str, authorization: str, body: object) -> object:
|
||||
self.calls.append((method, url))
|
||||
if authorization != AUTHORIZATION:
|
||||
return Failure("Jira answered 401")
|
||||
if (method, url) in self.answers:
|
||||
return self.answers[method, url]
|
||||
if method == "GET" and url == EPIC_URL:
|
||||
return {"key": "ABC-12"}
|
||||
if method == "GET" and url == ISSUE_TYPES:
|
||||
return TYPES
|
||||
if method == "POST" and url == SEARCH:
|
||||
return self.page(body)
|
||||
if method == "GET" and (held := next((issue for issue in self.issues if url == f"{ISSUES}/{issue['key']}?fields=parent"), None)):
|
||||
return {"key": held["key"], "fields": {"parent": held["fields"]["parent"]}} # type: ignore[index]
|
||||
if method == "POST" and url == ISSUES:
|
||||
return self.created(body)
|
||||
return Failure(f"Jira answered 404 for {method} {url}")
|
||||
|
||||
def page(self, body: object) -> object:
|
||||
assert isinstance(body, dict)
|
||||
matched = re.fullmatch(r'parent in \(("[A-Z]+-[0-9]+"(?:, "[A-Z]+-[0-9]+")*)\) ORDER BY Rank ASC', body["jql"])
|
||||
if matched is None:
|
||||
return Failure("Jira answered 400: the JQL is not valid")
|
||||
parents = re.findall(r'"([A-Z]+-[0-9]+)"', matched[1])
|
||||
found = [{"key": issue["key"], "fields": {name: value for name, value in issue["fields"].items() if name in body.get("fields", [])}} for issue in self.issues if issue["fields"]["parent"]["key"] in parents] # type: ignore[index, attr-defined]
|
||||
start = int(body.get("nextPageToken", 0))
|
||||
return {"issues": found[start:start + 2]} | ({"nextPageToken": str(start + 2)} if start + 2 < len(found) else {})
|
||||
|
||||
def created(self, body: object) -> object:
|
||||
assert isinstance(body, dict)
|
||||
fields = body["fields"]
|
||||
parent = fields["parent"]["key"]
|
||||
kind = {"name": "Task"} if parent == "ABC-12" else {"id": "10003"} if any(issue["key"] == parent for issue in self.issues) else None
|
||||
if fields["project"] != {"key": "ABC"} or kind is None or fields["issuetype"] != kind:
|
||||
return Failure("Jira answered 400: the project, parent or issue type is not valid")
|
||||
key = f"ABC-{len(self.issues) + 100}"
|
||||
self.issues.append({"key": key, "fields": {"summary": fields["summary"], "description": fields.get("description"), "labels": fields["labels"], "assignee": None, "status": TO_DO, "parent": {"key": parent}}})
|
||||
return {"id": "1", "key": key}
|
||||
|
||||
def change(self, key: str, **fields: object) -> None:
|
||||
next(issue for issue in self.issues if issue["key"] == key)["fields"].update(fields) # type: ignore[union-attr]
|
||||
|
||||
|
||||
class Case(unittest.TestCase):
|
||||
def setUp(self) -> None:
|
||||
folder = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(folder.cleanup)
|
||||
self.env_file = pathlib.Path(folder.name) / "jira.env"
|
||||
self.env_file.write_text("ATLASSIAN_EMAIL=me@example.com\nATLASSIAN_API_TOKEN=s3cret\n")
|
||||
self.env_file.chmod(0o600)
|
||||
self.jira = FakeJira()
|
||||
|
||||
def new_store(self) -> JiraEpic:
|
||||
return JiraEpic(EPIC, self.env_file, self.jira, to_markdown, to_adf)
|
||||
|
||||
|
||||
class JiraEpicContract(Case, EpicStoreContract):
|
||||
def assign(self, store: JiraEpic, key: str, name: str) -> None: # type: ignore[override]
|
||||
self.jira.change(key, assignee={"accountId": "5b10a2844c20165700ede21g", "displayName": name})
|
||||
|
||||
def close(self, store: JiraEpic, key: str, status: str) -> None: # type: ignore[override]
|
||||
self.jira.change(key, status={"name": status, "statusCategory": {"key": "done"}})
|
||||
|
||||
|
||||
class Jira(Case):
|
||||
def test_reads_the_sub_tasks_of_more_children_than_one_search_names(self) -> None:
|
||||
store = self.new_store()
|
||||
children = [store.file("ABC-12", f"Item {n}.", "", ()) for n in range(60)]
|
||||
tasks = [store.file(child, "A task.", "", ()) for child in children]
|
||||
read = store.read()
|
||||
assert isinstance(read, list), read
|
||||
self.assertEqual([issue.key for issue in read], [key for pair in zip(children, tasks) for key in pair])
|
||||
|
||||
def test_files_a_child_without_asking_for_issue_types(self) -> None:
|
||||
self.new_store().file("ABC-12", "Count the runs.", "", ())
|
||||
self.assertNotIn(("GET", ISSUE_TYPES), self.jira.calls)
|
||||
|
||||
def test_a_filing_jira_fails_or_answers_without_a_key_says_the_issue_may_exist(self) -> None:
|
||||
for answer, reason in ((Failure("Jira answered 503"), "cannot file the issue under ABC-12: Jira answered 503"), ({"id": "1"}, "Jira answered the new issue without an issue key"), (["ABC-100"], "Jira answered the new issue without an issue key")):
|
||||
with self.subTest(answer=answer):
|
||||
self.jira.answers[("POST", ISSUES)] = answer
|
||||
self.assertEqual(self.new_store().file("ABC-12", "Count the runs.", "", ()), Failure(f"{reason}; unless Jira refused the request, the issue may exist: look under ABC-12 before filing it again"))
|
||||
|
||||
def test_a_detail_the_codec_refuses_leaves_the_epic_as_it_was(self) -> None:
|
||||
store = JiraEpic(EPIC, self.env_file, self.jira, to_markdown, lambda markdown: Failure("adf-codec refused it"))
|
||||
self.assertEqual(store.file("ABC-12", "Count the runs.", "Why.", ()), Failure("cannot convert the detail to a Jira description: adf-codec refused it"))
|
||||
self.assertEqual(self.jira.issues, [])
|
||||
|
||||
def test_files_no_sub_task_where_the_project_has_no_sub_task_type_or_its_types_cannot_be_read(self) -> None:
|
||||
store = self.new_store()
|
||||
child = store.file("ABC-12", "Count the runs.", "", ())
|
||||
for answer, reason in ((Failure("Jira answered 403"), "cannot read ABC's issue types: Jira answered 403"), ({"issueTypes": [{"id": "10001", "subtask": False}]}, "ABC has no sub-task issue type; turn sub-tasks on in Jira"), ({}, "Jira answered ABC's issue types in a shape its REST API version 3 doesn't document"), ([], "Jira answered ABC's issue types in a shape its REST API version 3 doesn't document")):
|
||||
with self.subTest(answer=answer):
|
||||
self.jira.answers[("GET", ISSUE_TYPES)] = answer
|
||||
self.assertEqual(store.file(str(child), "A task.", "", ()), Failure(reason))
|
||||
self.assertEqual(len(self.jira.issues), 1)
|
||||
|
||||
def test_an_issue_in_another_shape_fails_the_read(self) -> None:
|
||||
valid = {"summary": "Count the runs.", "description": None, "labels": [], "assignee": None, "status": TO_DO, "parent": {"key": "ABC-12"}}
|
||||
shape = "ABC-34 is not in the shape Jira Cloud's REST API version 3 documents"
|
||||
for raw, reason in (
|
||||
("ABC-34", "the search answered an issue without an issue key"),
|
||||
({"fields": valid}, "the search answered an issue without an issue key"),
|
||||
({"key": "abc-34", "fields": valid}, "the search answered an issue without an issue key"),
|
||||
({"key": "ABC-34", "fields": {"summary": "Count the runs.", "parent": {"key": "ABC-12"}}}, shape + ": KeyError('labels')"),
|
||||
*((({"key": "ABC-34", "fields": valid | changed}, shape + ": its summary, labels, assignee, status, parent or description holds another kind of value") for changed in (
|
||||
{"summary": 3}, {"labels": "api"}, {"labels": [3]}, {"assignee": {"displayName": 0}}, {"status": {"name": 0, "statusCategory": {"key": "new"}}}, {"parent": {"key": "ABC"}}, {"parent": {"key": 12}}, {"description": "text"},
|
||||
))),
|
||||
):
|
||||
with self.subTest(raw=raw):
|
||||
self.jira.answers[("POST", SEARCH)] = {"issues": [raw]}
|
||||
self.assertEqual(self.new_store().read(), Failure(reason))
|
||||
|
||||
def test_a_description_the_codec_cannot_convert_fails_the_read(self) -> None:
|
||||
self.new_store().file("ABC-12", "Count the runs.", "Why.", ())
|
||||
for converted, reason in ((Refused(0, Failure("a table cell holds a list")), "ABC-100's description: a table cell holds a list"), (Failure("docker is not running"), "cannot convert the descriptions of ABC-12's issues to markdown: docker is not running")):
|
||||
with self.subTest(converted=converted):
|
||||
self.assertEqual(JiraEpic(EPIC, self.env_file, self.jira, lambda documents: converted, to_adf).read(), Failure(reason))
|
||||
|
||||
def test_a_search_that_does_not_end_names_the_issues_it_sought(self) -> None:
|
||||
store = self.new_store()
|
||||
children = [store.file("ABC-12", "Count the runs.", "", ()) for _ in range(2)]
|
||||
for _ in range(3):
|
||||
store.file(str(children[0]), "A task.", "", ())
|
||||
with unittest.mock.patch.object(jira_epic, "MAX_PAGES", 1):
|
||||
self.assertEqual(store.read(), Failure("the search for the sub-tasks of ABC-12's child issues did not end within 1 pages"))
|
||||
store.file("ABC-12", "Count the runs.", "", ())
|
||||
self.assertEqual(store.read(), Failure("the search for ABC-12's child issues did not end within 1 pages"))
|
||||
|
||||
def test_refuses_to_file_under_another_epics_child_or_an_issue_it_cannot_read(self) -> None:
|
||||
self.jira.issues.append({"key": "ABC-5", "fields": {"parent": {"key": "ABC-1"}}})
|
||||
store = self.new_store()
|
||||
self.assertEqual(store.file("ABC-5", "Count more.", "", ()), Failure("ABC-5 is neither the epic ABC-12 nor one of its child issues, so nothing can be filed under it"))
|
||||
self.assertEqual(store.file("ABC-77", "Count more.", "", ()), Failure(f"cannot read ABC-77 to file under it: Jira answered 404 for GET {ISSUES}/ABC-77?fields=parent"))
|
||||
self.jira.answers[("GET", f"{ISSUES}/ABC-78?fields=parent")] = ["ABC-12"]
|
||||
self.assertEqual(store.file("ABC-78", "Count more.", "", ()), Failure("ABC-78 is neither the epic ABC-12 nor one of its child issues, so nothing can be filed under it"))
|
||||
self.assertEqual([call for call in self.jira.calls if call[0] == "POST" and call[1] == ISSUES], [])
|
||||
|
||||
def test_an_epic_the_account_cannot_see_fails_the_read(self) -> None:
|
||||
store = JiraEpic(Epic(SITE, "ABC-99"), self.env_file, self.jira, to_markdown, to_adf)
|
||||
self.assertEqual(store.read(), Failure(f"cannot read the epic ABC-99: Jira answered 404 for GET {SITE}/rest/api/3/issue/ABC-99?fields=summary"))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -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()
|
||||
@@ -448,15 +448,15 @@ def children(epic: Epic, authorization: str, http: Http) -> list[object] | Failu
|
||||
seen = http("GET", f"{epic.site}/rest/api/3/issue/{epic.key}?fields=summary", authorization, None)
|
||||
if isinstance(seen, Failure):
|
||||
return Failure(f"cannot read the epic {epic.key}: {seen.reason}")
|
||||
body: dict[str, object] = {
|
||||
"jql": f'parent = "{epic.key}" AND statusCategory != Done ORDER BY Rank ASC',
|
||||
"fields": ["summary", "description", "fixVersions", "issuelinks"],
|
||||
"properties": [PROPERTY],
|
||||
"maxResults": PAGE,
|
||||
}
|
||||
return searched(epic.site, f"{epic.key}'s children", f'parent = "{epic.key}" AND statusCategory != Done ORDER BY Rank ASC', {"fields": ["summary", "description", "fixVersions", "issuelinks"], "properties": [PROPERTY]}, authorization, http)
|
||||
|
||||
|
||||
def searched(site: str, what: str, jql: str, asked: dict[str, object], authorization: str, http: Http) -> list[object] | Failure:
|
||||
"""Every issue a JQL search on site finds, page by page. The dict asked holds the request's `fields` and `properties` lists. The text what names the issues sought, in the Failure of a search that doesn't end."""
|
||||
body: dict[str, object] = {"jql": jql, "maxResults": PAGE} | asked
|
||||
found: list[object] = []
|
||||
for _ in range(MAX_PAGES):
|
||||
page = http("POST", f"{epic.site}/rest/api/3/search/jql", authorization, body)
|
||||
page = http("POST", f"{site}/rest/api/3/search/jql", authorization, body)
|
||||
if isinstance(page, Failure):
|
||||
return page
|
||||
if not isinstance(page, dict) or not isinstance(page.get("issues"), list):
|
||||
@@ -465,7 +465,7 @@ def children(epic: Epic, authorization: str, http: Http) -> list[object] | Failu
|
||||
if not page.get("nextPageToken"):
|
||||
return found
|
||||
body = body | {"nextPageToken": page["nextPageToken"]}
|
||||
return Failure(f"the search for {epic.key}'s children did not end within {MAX_PAGES} pages")
|
||||
return Failure(f"the search for {what} did not end within {MAX_PAGES} pages")
|
||||
|
||||
|
||||
def issue_of(raw: object) -> Issue | Failure:
|
||||
|
||||
@@ -54,7 +54,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__":
|
||||
|
||||
+5
-1
@@ -314,7 +314,7 @@ Valid while no published standard sets either number, the reading-cost window st
|
||||
|
||||
2026-10-08, lilleman. Serves goal 1.4: run beside the full scan, `/security-review` started seconds apart from it each round and returned a near-identical report. Valid while the full scan covers what `/security-review` reports.
|
||||
|
||||
## review: a fix for a 🔴 reruns the pass that found it, unless that pass is at its cap, and each pass whose row in `larv-review` §3's re-entry table the fix meets; from round 2 a pass reviews only the answers to its last round's findings and any other pass's fix that re-entered it; a fix for a 🟡, a 🟢, a ❓ or a prose finding reruns none; the stability pass doesn't rerun on a round's fixes where every 🔴 and 🟡 of that round asked only that a named mutant be killed or a named failing test pass, and the tests and the mutation command run clean on the fixes
|
||||
## review: a fix for a 🔴 reruns the pass that found it, unless that pass is at its cap, and each pass whose row in `larv-review` §3's re-entry table the fix meets; from round 2 a pass reviews only the answers to its last round's findings and any other pass's fix that re-entered it; a fix for a 🟢, a ❓ or a prose finding doesn't rerun any pass, and a fix for a 🟡 reruns the pass that raised it only when the fix weakens, skips or guards a test; the stability pass doesn't rerun on a round's fixes where every 🔴 and 🟡 of that round asked only that a named mutant be killed or a named failing test pass, and the tests and the mutation command run clean on the fixes
|
||||
|
||||
2026-10-08, lilleman. Serves goal 1.4. An audit of the four costliest archived chunks found nearly every finding that mattered in a pass's first round; when every fix, a nit's included, re-entered review, later rounds mostly re-checked the last fix, reworded what an earlier round wrote, or contradicted another round on the same line. A round 2 caught real bugs only where a fix changed behaviour, so stability still reruns on every fix that does, and security on every fix that opens an untrusted-input boundary or touches authn/authz, secrets or crypto. Valid while round-2 reviews of nit and prose fixes change only what a user wouldn't notice.
|
||||
|
||||
@@ -324,6 +324,8 @@ Valid while no published standard sets either number, the reading-cost window st
|
||||
|
||||
2026-11-12, lilleman through todo item 308. Serves goal 1.4. Since the worker runs the mutation command before each stability round, a finding that asks only that a named mutant be killed or a named failing test pass has an answer a run can check. The archive from 2026-09-30 to 2026-11-12 holds 326 stability reports of round 2 or later, from 13 projects, and 81 of those reports open with BLOCK (`stability-skip-count/`). For each of the 326, the 🔴 and 🟡 lines of the report before it were matched on mutant and test-failure wording. Every such line matched in 5 of those earlier reports. Read by hand, 1 of the 5 asked only that a failing test pass, and the round 2 after each of the 5 approved. So none of the 81 BLOCKs fell in a round this skips. The skip needs every 🟡 to be of that kind too: in one chunk on 2026-11-12, round 1's only 🔴 was a red suite, and round 2 blocked on a 🟡 whose answer was wrong, which no test or mutant showed. A fix may not edit the named failing test, since a test made to pass that way doesn't show anything. Fixes from such a round still rerun every other pass whose row they meet. Valid while code that such a skipped round's fixes wrote is rarely what a later chunk's 🔴 findings fix.
|
||||
|
||||
2026-11-18, lilleman through todo item 399. Serves goals 1.1 and 1.4. The 2026-10-29 entry's validity condition broke once. In a client project's pull request, stability round 1 raised a 🟡: an end-to-end payroll test passes on a used database. It proposed asserting the created row counts. The answer commit added that assertion behind a `test.skip` that runs when every count is zero. A broken payroll also creates zero rows, so a regression became a skip. The gate and the mutation run don't catch it, since a skipped test counts as passing; only the forge's auto-reviewer did. So a 🟡 fix that removes or loosens an assertion, changes an expected value, or skips, deletes or guards a test or assertion reruns the pass that raised it, as a 🔴 fix does. A 🟡 fix that only kills a named mutant or makes a named failing test pass doesn't, since the tests and the mutation command check it, and a skipped test kills no mutant. Every other 🟡 fix keeps the 2026-10-29 rule: the 2026-10-08 audit found that reruns of fixes to minor findings mostly re-checked wording. The rerun reviews only the answers, and the cap of two rounds still ends the pass. Valid while fixes of this kind are a small share of 🟡 fixes, so the extra round stays cheap.
|
||||
|
||||
## review: a comment is prose in any file; a branch changing only Markdown no agent follows runs only the prose pass and, for README or docs an outside reader lands on, the product-owner pass; plan rows a chunk files from a finding, re-scores or moves get no review
|
||||
|
||||
2026-10-29, lilleman. Serves goals 1.4 and 1.5. One project's chunk on 2026-10-29 changed a README paragraph, `todo.md` and three lines of `gate.yml`, and the principles, security and stability passes all ran on it, each twice: 6 of the chunk's 10 rounds. A change to config is one that changes what runs, so a comment in it fires only the prose pass, as a comment in code already did. A branch that changes only Markdown no agent follows changes no code, config or tests, so no pass that reads those runs on it. A plan row a chunk files from a finding, re-scores or moves is read by the chunk that ships it, so reviewing it at filing reviewed it twice: that chunk spent a prose round of 4 minutes on its plan change. Markdown an agent follows, such as a skill, is config, since a change there changes what agents do. Valid while defects in prose-only chunks stay rare in later chunks' fixes.
|
||||
@@ -405,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
|
||||
|
||||
@@ -87,18 +87,19 @@ Give a reviewer without Bash `git ls-files`'s output in its prompt, since some h
|
||||
- **Done.** A pass is done when its latest round leaves no 🔴 or 🟡 standing: none was reported, or each was shown factually wrong, declined, filed, or named under the bar per "Findings", or settled in the PR summary per "Comprehension check" → "Places", or, for the prose pass and a pass at its cap, fixed. A stability pass whose round's fixes skip the next round per "Re-entry" → "Mechanical answers" is done once that rule's run is clean. Resolve that round's 🟢s and ❓s per "Findings" too.
|
||||
- **Cap.** A pass takes at most two rounds per chunk, and the release review's architecture and principles passes five; don't ask the user for more. Answer its last round's findings per "Findings": those fixes merge once the gate passes, unreviewed by that pass. rule-hook's `round-cap` refuses a round commit that would take a pass past its cap, and no override waives it. A review the auto-reviewer posts after its second isn't a round: fix none of it and rerun no pass for it, but file a security finding it raises per `~/.claude/CLAUDE.md` → "Working loop", and any other 🔴 in `todo.md`.
|
||||
|
||||
**Re-entry.** A fix is a change no pass has seen. A fix for a 🟡, a 🟢, a ❓ or a prose finding reruns no pass, whatever it changes. A round's fixes for 🔴 findings re-enter together: run every pass that a row below names for any of them, a done pass included, in the waves of "Waves", then §4; "Mechanical answers" below names the one exception. A pass at its cap doesn't run again ("Round cap" → "Cap").
|
||||
**Re-entry.** A fix is a change no pass has seen. A fix for a 🟢, a ❓ or a prose finding doesn't rerun any pass, whatever it changes. A fix for a 🟡 meets only the 🟡 row below. A round's fixes for 🔴 findings, and its 🟡 fixes that meet that row, re-enter together: run every pass that a row below names for any of them, a done pass included, in the waves of "Waves", then §4; "Mechanical answers" below names the one exception. A pass at its cap doesn't run again ("Round cap" → "Cap").
|
||||
|
||||
| The fix | Reruns |
|
||||
|---------|--------|
|
||||
| answers a 🔴 of a pass other than prose | that pass |
|
||||
| answers a 🟡 of a pass other than prose, and removes or loosens an assertion, changes an expected value, or skips, deletes or guards a test or assertion with a condition or a catch, unless it only kills a named mutant or makes a named failing test pass | that pass |
|
||||
| carries an architectural decision, in the release review | Architecture |
|
||||
| changes code, config or tests, in the release review | Principles |
|
||||
| opens an untrusted-input boundary or touches authn/authz, secrets or crypto | Security, unless the full scan reruns on it |
|
||||
| made rule-hook log an override | Overrides |
|
||||
| changes behaviour: what the code or its tests do | Stability |
|
||||
|
||||
A fix meets every row it fits. Prose has no row, so a comment or doc edit inside a fix doesn't rerun any pass. Example: a fix for a stability 🔴 that changes code and a comment reruns Principles and Stability.
|
||||
A fix meets every row it fits, except that a fix for a 🟡 meets only the 🟡 row. Such a fix meets no row once §2's tests and mutation command run clean on it and the named failing test is unedited ("Mechanical answers"); a skipped test kills no mutant. Prose has no row, so a comment or doc edit inside a fix doesn't rerun any pass. Example: a fix for a stability 🔴 that changes code and a comment reruns Principles and Stability.
|
||||
|
||||
**Mechanical answers.** A stability round's fixes may skip the next stability round. That holds where the round reported a 🔴, and each of its 🔴 and 🟡 findings asked only that a named mutant be killed or a named failing test pass. Run §2's tests and mutation command on the fixes, and fix again per §2 until they leave no failing test and no surviving mutant that changes behaviour. Each named failing test must pass as the round found it, not edited or deleted. Then the stability pass doesn't run again, and the round's answer commit title ends `; tests and mutants clean at <commit>`. The fixes still rerun each other pass whose row they meet. Where the run can't be made clean, or a fix edits a named failing test, the stability pass runs again as the table says.
|
||||
|
||||
@@ -195,7 +196,7 @@ Launch prose-reviewer with what the diff touched and every section this review c
|
||||
3. The forge's checks: `chunk-pr merge` waits for them to pass (§5 step 4). A red check is a finding.
|
||||
4. No CI configured → the gate is local tests only; note it in the summary.
|
||||
5. The local tests green → mark the PR ready with `~/.claude/bin/chunk-pr ready '<final title>'`, which sets the title as it marks the PR ready.
|
||||
6. **External auto-reviewer**, when the repo has one — its config file (`.coderabbit.yaml` and the like), or its comments on earlier PRs; none → skip it, say so. Marking the PR ready is what summons it. Wait up to **10 minutes** for its first review, checking about once a minute; nothing by then → note it in the summary and carry on, never waiting twice. Its rounds, §3 → "Round cap". Once it has reviewed, each later return here before its cap, after a fix re-entered per §3, waits up to **5 minutes** for its re-review of the new commit.
|
||||
6. **External auto-reviewer**, when the repo has one — its config file (`.coderabbit.yaml` and the like), or its comments on earlier PRs; none → skip it, say so. Marking the PR ready is what summons it. Wait up to **10 minutes** for its first review, checking about once a minute; nothing by then → note it in the summary and carry on, never waiting twice. Its rounds, §3 → "Round cap". Once it has reviewed, each later return here before its cap, after a fix re-entered per §3, waits up to **5 minutes** for its re-review of the new commit. A fix of its finding ends with the setup change that `~/.claude/CLAUDE.md` → "Working loop", "Change the setup for each reasonable fix an outside reviewer asked for on a PR" asks for.
|
||||
|
||||
## 5. Goal alignment, then merge
|
||||
|
||||
@@ -206,7 +207,7 @@ Launch prose-reviewer with what the diff touched and every section this review c
|
||||
- **A merge conflict.** Resolve it, commit and push. Rerun only the passes whose triggers the resolution's own lines meet (§3), each in a round of its own.
|
||||
- **A paired ruling to run again.** `chunk-pr merge` has merged the default branch in and pushed. Run the ruling at that head, record it, commit and push. Don't return to §4 for it: the next turn waits for the checks at the new head.
|
||||
- **An owed scoring run, or a queue another pull request holds.** Record the run, or wait, as the message says.
|
||||
- **A reviewer's comment**, where the project's config sets `wait-for-approval` (`chunk-pr --help`) and the pull request waits for a human's approval. Answer it in its thread on the forge, and fix what it asks as a finding of the chunk. The wait doesn't hold the queue, so other chunks merge meanwhile.
|
||||
- **A reviewer's comment**, where the project's config sets `wait-for-approval` (`chunk-pr --help`) and the pull request waits for a human's approval. Answer it in its thread on the forge, and fix what it asks as a finding of the chunk. A fix of it ends with the same setup change (§4 step 6). The wait doesn't hold the queue, so other chunks merge meanwhile.
|
||||
|
||||
A repo whose `AGENTS.md` names another method merges that way with the forge's CLI instead, after it finishes the chunk's items with `todo-item finish` in the branch, and once the pull request's checks pass, `~/.claude/bin/larv-review scoring-run-owed` exits 0 and, where `~/.claude/bin/project-config wait-for-approval` prints `true`, GitHub reports the pull request approved. A repo withholds this in its `AGENTS.md` → leave the PR ready and unmerged, and say which line withheld it.
|
||||
5. Merged → run `~/.claude/bin/chunk-pr clean` in the chunk's worktree, and put a failure it prints in the summary.
|
||||
@@ -214,4 +215,4 @@ Launch prose-reviewer with what the diff touched and every section this review c
|
||||
|
||||
## 6. Wrap up
|
||||
|
||||
Summarize: PR URL and final state, every reviewer's verdict, rounds per pass, passes skipped, principles files left out with why, findings fixed vs answered vs declined vs open — each answer with what settles it, each decline with its reason, a 🟡's with the goal or technical principle it rests on — CI status, rule overrides with their rulings, decisions recorded (file paths), `todo.md`/`CHANGELOG.md` updated, and any 🔀 escalation left for the user.
|
||||
Summarize: PR URL and final state, every reviewer's verdict, rounds per pass, passes skipped, principles files left out with why, findings fixed vs answered vs declined vs open — each answer with what settles it, each decline with its reason, a 🟡's with the goal or technical principle it rests on — CI status, rule overrides with their rulings, decisions recorded (file paths), for each fixed outside-reviewer comment, the setup change it led to, or that no setup gap caused it, `todo.md`/`CHANGELOG.md` updated, and any 🔀 escalation left for the user.
|
||||
|
||||
@@ -6,31 +6,27 @@
|
||||
|
||||
`Bar = 0.1`
|
||||
|
||||
`Next ID = 419`
|
||||
`Next ID = 420`
|
||||
|
||||
## Items
|
||||
|
||||
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|
||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
||||
| 398 | 0.12.0 | | | **Make each reasonable fix an outside reviewer asks for on a PR trigger a reflection that changes the setup so review would have caught it, in this repo first.** | 2 | 2 | 3 | 5 | 3 | 1.1 by 6, 1.2 by 2 | 2.9 |
|
||||
| 399 | 0.12.0 | | | **Rerun the pass that raised a 🟡 when its fix changes what a test asserts or whether it runs.** | 2 | 2 | 3 | 5 | 3 | 1.1 by 6 | 2.2 |
|
||||
| 404 | 0.12.0 | | | **Read do-epic's machine-wide settings from `~/.claude-projects/do-epic/config.toml` and its prose repo rule from `repo-rule.md` beside it, and refuse to start while either is missing or misspelt.** | 2 | 1 | 1 | 2 | 3 | 1 by 5 | 1.9 |
|
||||
| 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 |
|
||||
| 403 | 0.12.0 | | | **Read and file an epic's child issues and sub-tasks, with labels, assignee, status and parent, through a plan backend interface with a Jira backend and an in-memory fake.** | 3 | 2 | 3 | 6 | 5 | 1 by 5 | 1.2 |
|
||||
| 406 | 0.12.0 | 403, 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, 403 | | **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, 403, 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 |
|
||||
| 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 |
|
||||
| 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 | 403, 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 |
|
||||
| 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 |
|
||||
| 411 | 0.12.0 | 410 | | **Park a chunk whose PR waits on a long gate, keeping its worktree, PR and session in a state file that survives a reboot, and resume its session when the gate passes or a reviewer comments.** | 3 | 2 | 3 | 6 | 5 | 1 by 5 | 1.2 |
|
||||
| 412 | 0.12.0 | 410, 411 | | **Print each chunk of an epic, running, parked with its gate and since when, or stopped, each human task and each open interrupt with `do-epic <key> --status`, and name a parked chunk's gate in its tmux window's name.** | 2 | 1 | 1 | 2 | 3 | 1 by 5 | 1.9 |
|
||||
| 414 | 0.12.0 | 403, 410 | | **DM the human through the notifier when a human-task issue blocks the epic's next item, and poll until it closes.** | 2 | 2 | 2 | 4 | 3 | 1 by 5 | 1.9 |
|
||||
| 414 | 0.12.0 | 410 | | **DM the human through the notifier when a human-task issue blocks the epic's next item, and poll until it closes.** | 2 | 2 | 2 | 4 | 3 | 1 by 5 | 1.9 |
|
||||
| 417 | 0.12.0 | 410 | | **Run do-epic end to end against a sandbox epic on a real Jira site with a command of its own, outside `run-tests`.** | 2 | 1 | 1 | 2 | 3 | 1 by 5 | 1.9 |
|
||||
| 299 | 0.12.0 | | | **Replay the archived judge verdicts through code rules and a classifier trained locally on the archive, and file an item for each verdict kind one of them decides with no missed interrupt.** | 2 | 2 | 2 | 4 | 3 | 1.4 by 3 | 1.0 |
|
||||
| 311 | 0.12.0 | | | **Hand each worker's claude a Bash output ceiling that saves longer output to a file, and refuse a Read of a session transcript under `~/.claude/projects`.** | 2 | 2 | 3 | 5 | 3 | 1.4 by 3 | 1.0 |
|
||||
@@ -39,6 +35,7 @@
|
||||
| 365 | 0.13.0 | | | **Have `score-outcomes` read the finished and dropped items of a plan outside the checkout, from the project repo's history or from Jira's issue changelogs.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 2, 1.1 by 2 | 1.2 |
|
||||
| 368 | 0.13.0 | | | **Call a release review due, call a release ready to cut, and tell whether a chunk owes a scoring run, for a plan outside the checkout, from the project repo's history or from Jira.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 2, 1.1 by 2 | 1.2 |
|
||||
| 309 | 0.13.0 | | | **Run a scoring run's second pass on one head with two seats in place of four, once `larv-review agreement` shows the seats agree with each other more than a run agrees with its rerun.** | 2 | 2 | 2 | 4 | 2 | 1.4 by 3 | 1.2 |
|
||||
| 419 | 0.13.0 | | | **Run the external auto-reviewer until its review of the PR's head has no findings, and answer each of its threads on the PR.** | 3 | 2 | 3 | 6 | 5 | 1.1 by 5 | 1.1 |
|
||||
| 366 | 0.13.0 | | | **Count the chunks of a project whose plan sits outside the checkout in the routing figures, from the project repo's history or from Jira.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 2, 1.4 by 2 | 1.1 |
|
||||
| 339 | 0.13.0 | | | **Lower the reading cost of the files a chunk reads most before its first commit.** | 2 | 2 | 1 | 3 | 3 | 1.4 by 3 | 1.0 |
|
||||
| 341 | 0.13.0 | 311 | | **Hand each worker's claude a lower Read limit through `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS`, kept only where replays of the archived review rounds find what two unchanged replays find.** | 2 | 2 | 3 | 5 | 3 | 1.4 by 3 | 1.0 |
|
||||
@@ -85,35 +82,6 @@
|
||||
|
||||
## Details
|
||||
|
||||
### 398. Make each reasonable fix an outside reviewer asks for on a PR trigger a reflection that changes the setup so review would have caught it, in this repo first.
|
||||
|
||||
Applies to any reviewer outside the review passes: a forge's auto-reviewer such as CodeRabbit, a human, or any other. When such a reviewer's feedback on a PR is reasonable and we fix it, we also ask why our setup didn't catch it first, and change the setup so it would. A fix that only answers the comment leaves the same gap open for the next chunk.
|
||||
|
||||
Where the change goes, in this order of preference:
|
||||
1. This repo's core: the reviewers' agents, `larv-review`, the hooks and tools, so every project gains.
|
||||
2. The technical principles or review standards, where a rule was missing or too vague.
|
||||
3. The project's own settings or instructions (`config.toml`, `AGENTS.md`), only where the gap is that project's alone.
|
||||
|
||||
Where the cause is a gap in none of these, say so in the chunk's summary rather than inventing a change. File a change too big for the chunk as its own item (`~/.claude/CLAUDE.md` → "Working loop"). The reflection is part of answering the feedback, so `larv-review` §4 step 6 and §3 → "Other scales" are the places to start.
|
||||
|
||||
Touches:
|
||||
|
||||
- `skills/larv-review/SKILL.md`: `## 4. Gate` (small), `## 3. Passes` (small)
|
||||
- `CLAUDE.md`: `## Working loop` (small)
|
||||
|
||||
### 399. Rerun the pass that raised a 🟡 when its fix changes what a test asserts or whether it runs.
|
||||
|
||||
In a client project's pull request, stability round 1 raised a 🟡: an end-to-end payroll test passes on a used database. It proposed asserting the created row counts. The answer commit added that assertion behind a `test.skip` that runs when every count is zero. A broken payroll also creates zero rows, so a regression became a skip. No pass reviewed the fix, because a 🟡 fix reruns none (`skills/larv-review/SKILL.md` §3 → "Re-entry"). The forge's auto-reviewer found it.
|
||||
|
||||
Neither the gate nor the mutation run catches a weakened test, since a skipped test counts as passing. The rerun reviews only the answers (`review-findings.md`), and the cap of two rounds still ends the pass.
|
||||
|
||||
Revise the decision `review: a fix for a 🔴 reruns the pass that found it…` in `docs/decisions.md`. Its 2026-10-29 entry holds only "while 🔴 findings in later chunks, fixing code a 🟡 fix wrote, stay rare".
|
||||
|
||||
Touches:
|
||||
|
||||
- `skills/larv-review/SKILL.md`: `**Re-entry.**` (small)
|
||||
- `docs/decisions.md`: `## review: a fix for a 🔴 reruns the pass that found it, unless that pass is at its cap, and each pass whose row in larv-review §3's re-entry table the fix meets`
|
||||
|
||||
### 404. Read do-epic's machine-wide settings from `~/.claude-projects/do-epic/config.toml` and its prose repo rule from `repo-rule.md` beside it, and refuse to start while either is missing or misspelt.
|
||||
|
||||
Settings: the Jira site, `env-file`, the folder repos are cloned into (`~/code` by default), the default language, and the model for a no-repo item (`docs/decisions.md` → `do-epic: drives one Jira epic …`). Reuse `project_config/settings.py`'s parsing helpers: `read`, `anywhere`, `Scalar`, `language_fault`, and the `env-file` check that keeps credentials outside a checkout.
|
||||
@@ -161,20 +129,6 @@ Touches:
|
||||
- `bin/rung_replay/search.py` (small)
|
||||
- `README.md`: `` ### Packages under `bin/` `` (small)
|
||||
|
||||
### 403. Read and file an epic's child issues and sub-tasks, with labels, assignee, status and parent, through a plan backend interface with a Jira backend and an in-memory fake.
|
||||
|
||||
Other backends come later (`docs/decisions.md` → `do-epic: drives one Jira epic …`), so do-epic reads the epic only through the interface. The fake passes the same contract tests as the Jira backend. Sub-task creation is a new POST.
|
||||
|
||||
Touches:
|
||||
|
||||
- `bin/plan_store/jira_epic.py`: `Issue`, `issue_of`, `children`, `JiraPlan.read`, `JiraPlan.add`, `JiraPlan.edit`
|
||||
- `bin/plan_store/plans.py`: `PlanStore`
|
||||
- `bin/plan_store/fakes.py`: `MemoryPlan`
|
||||
- `bin/plan_store/contract.py`: `PlanStoreContract`
|
||||
- `bin/do_epic/backend/protocol.py`
|
||||
- `bin/do_epic/backend/jira.py`
|
||||
- `bin/do_epic/backend/fake.py`
|
||||
|
||||
### 406. 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.
|
||||
|
||||
The pick is a headless claude call with a JSON schema, as the judge makes (`docs/decisions.md` → `do-epic: drives one Jira epic …`). A recorded pick is read back without a new call.
|
||||
@@ -184,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.
|
||||
@@ -415,6 +358,19 @@ Touches:
|
||||
- `skills/larv-review/SKILL.md`: `### Comprehension check`
|
||||
- `skills/comprehension-panel/SKILL.md`: `## The scoring run` (small)
|
||||
|
||||
### 419. Run the external auto-reviewer until its review of the PR's head has no findings, and answer each of its threads on the PR.
|
||||
|
||||
Today `larv-review` §3 → "Round cap" stops the auto-reviewer after two reviews. On a client project's pull request, CodeRabbit spent both reviews on the draft, before the internal passes were done, so its last finding got no answer on the PR. Change:
|
||||
|
||||
- §3 → "Round cap": drop the auto-reviewer's cap. Every finding it makes, whatever its severity, is fixed or shown wrong, and each push waits for its review of the new head. The pass is done when that review adds no finding.
|
||||
- §4 step 6: detect a clean review. CodeRabbit posts no review when it has no findings. Instead it updates its summary comment with "No actionable comments were generated in the recent review" and a `coveredCommitId` that matches the head. Wait for that, not for a new review.
|
||||
- Answer every thread in place, with the fix's commit or the reason for not making it.
|
||||
- `chunk-pr ready` and `chunk-pr merge` refuse while an auto-reviewer thread has neither our reply nor resolved status, read from the thread state GitHub's API reports.
|
||||
- `round-count`, rule-hook's round-cap and the "Answer … round" titles need no change, since the auto-reviewer's commits already take ordinary titles.
|
||||
- Once this ships, delete the first two bullets of the machine-local CodeRabbit rule file, which say the same thing for one machine.
|
||||
|
||||
The change touches `skills/larv-review/SKILL.md` "Re-entry", which the comprehension seats found hard to follow (Locality): make it easier to read while editing it.
|
||||
|
||||
### 366. Count the chunks of a project whose plan sits outside the checkout in the routing figures, from the project repo's history or from Jira.
|
||||
|
||||
One of 0.13.0's history ports, per lilleman's call of 2026-11-12.
|
||||
|
||||
Reference in New Issue
Block a user