Key project-record's copies per worktree
CI / tests (pull_request) Successful in 2m8s

This commit is contained in:
2026-11-15 22:45:04 +01:00
parent 70e3c0b9de
commit 4873ee9e74
5 changed files with 55 additions and 14 deletions
+12 -5
View File
@@ -10,8 +10,9 @@ save refuses them: edit the epic 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
path is a copy under ~/.local/state/project-record/<key>/, written afresh with the record as it
stands, so open it again before each edit. A record that doesn't exist yet has no file at the path:
path is a copy under ~/.local/state/project-record/<key>/<worktree>/, a folder of the worktree
that ran open, so two worktrees of one project don't share a copy. The copy is written afresh with
the record as it stands, so open it again before each edit. A record that doesn't exist yet has no file at the path:
create it there.
save stores the file's text in the record, and prints one line saying so. Where the record is kept
@@ -24,6 +25,7 @@ writes the copy afresh.
Exit 2 on bad arguments, and 1, saying why, on any other failure.
"""
import hashlib
import pathlib
import sys
@@ -34,7 +36,7 @@ from project_config.settings import ProjectConfig
# Not git's verbs, such as checkout and commit: those read as acting on the repo.
COMMANDS = ("open", "save")
# Where the copy of a record kept outside files goes, under the user's home, in a folder per project.
# Where the copy of a record kept outside files goes, under the user's home, in a folder per project and worktree.
COPIES = ".local/state/project-record"
# The goals file opens like a record, though it is a setting of its own.
GOALS = "goals-and-audience"
@@ -58,11 +60,16 @@ def main(argv: list[str]) -> int:
def opened(config: ProjectConfig, name: str, home: pathlib.Path) -> tuple[RecordStore, pathlib.Path]:
"""The store of the record called name, and the copy it gets where it isn't kept as a file. A store that keeps the version it read, for a later save, keeps it beside the copy."""
copy = home / COPIES / config.key / f"{name}.md"
"""The store of the record called name, and the copy it gets where it isn't kept as a file. A store that keeps the version it read, for a later save, keeps it beside the copy. The copy is the worktree's own, so two chunks of one project don't overwrite each other's unsaved edit."""
copy = home / COPIES / config.key / worktree_folder(config.top) / f"{name}.md"
return (goals_store(config) if name == GOALS else store(config, name, copy.with_suffix(".version"))), copy
def worktree_folder(top: pathlib.Path) -> str:
"""The folder name of the worktree at top: its own name, for a reader, and a hash of its path, since two worktrees in different folders may share a name."""
return f"{top.name}-{hashlib.sha256(str(top).encode()).hexdigest()[:8]}"
def act(command: str, record: RecordStore, copy: pathlib.Path) -> str | Failure:
"""What command, one of COMMANDS, prints for record. copy is where a record kept outside files gets its file."""
if command == "open":
+24 -7
View File
@@ -17,19 +17,36 @@ from project_config.settings import Page, ProjectConfig
TOOL = pathlib.Path(__file__).resolve().parents[1] / "project-record"
COPIES = pathlib.Path("/home/me/.local/state/project-record/acme")
def worktree_config(top: str, **kept: Page) -> ProjectConfig:
return ProjectConfig("acme", pathlib.Path("/home/me/.claude-projects/acme"), pathlib.Path(top), {"goals-and-audience": pathlib.Path(top, "README.md")}, pathlib.Path("/home/me/acme.env"), pages=kept)
class Opened(unittest.TestCase):
def test_a_record_on_a_confluence_page_keeps_the_version_it_read_beside_its_copy(self):
page = Page("https://acme.atlassian.net", "2293761", "confluence:https://acme.atlassian.net/wiki/spaces/ENG/pages/2293761")
config = ProjectConfig("acme", pathlib.Path("/home/me/.claude-projects/acme"), pathlib.Path("/code/acme"), {}, pathlib.Path("/home/me/acme.env"), pages={"decisions": page})
record, copy = main.opened(config, "decisions", pathlib.Path("/home/me"))
self.assertEqual(copy, pathlib.Path("/home/me/.local/state/project-record/acme/decisions.md"))
record, copy = main.opened(worktree_config("/code/acme", decisions=page), "decisions", pathlib.Path("/home/me"))
self.assertEqual((copy.parent.parent, copy.name), (COPIES, "decisions.md"))
assert isinstance(record, ConfluencePage), record
self.assertEqual(record.kept, pathlib.Path("/home/me/.local/state/project-record/acme/decisions.version"))
self.assertEqual(record.kept, copy.with_suffix(".version"))
def test_the_goals_file_opens_through_the_goals_store(self):
config = ProjectConfig("acme", pathlib.Path("/home/me/.claude-projects/acme"), pathlib.Path("/code/acme"), {"goals-and-audience": pathlib.Path("/code/acme/README.md")})
record, copy = main.opened(config, "goals-and-audience", pathlib.Path("/home/me"))
self.assertEqual((record.label, copy), ("/code/acme/README.md", pathlib.Path("/home/me/.local/state/project-record/acme/goals-and-audience.md")))
record, copy = main.opened(worktree_config("/code/acme"), "goals-and-audience", pathlib.Path("/home/me"))
self.assertEqual((record.label, copy.parent.parent, copy.name), ("/code/acme/README.md", COPIES, "goals-and-audience.md"))
def test_two_worktrees_of_one_project_get_copies_that_differ_and_one_worktree_always_the_same(self):
home = pathlib.Path("/home/me")
main_checkout, other = (main.opened(worktree_config(top), "goals-and-audience", home)[1] for top in ("/code/acme", "/code/acme-item-5"))
again = main.opened(worktree_config("/code/acme"), "goals-and-audience", home)[1]
self.assertNotEqual(main_checkout, other)
self.assertEqual(main_checkout, again)
def test_two_worktrees_named_alike_in_different_folders_get_copies_that_differ(self):
home = pathlib.Path("/home/me")
first, second = (main.opened(worktree_config(top), "goals-and-audience", home)[1] for top in ("/code/acme-item-5", "/other/acme-item-5"))
self.assertNotEqual(first, second)
class Act(unittest.TestCase):
+1 -1
View File
@@ -299,7 +299,7 @@ Valid while the later fixes per finished chunk, which `score-outcomes` and the r
- **A bench of readers picked the spelling.** Three fresh readers, seated as the person who writes a client's `config.toml`, each picked `decisions = "confluence:https://<site>/wiki/spaces/<space>/pages/<page ID>"`, pasted from the browser with or without the title at its end, over the bare address, a page ID beside a `confluence-site` key, and a table. Each named the match with `jira:`. Any of the five records may name a page; the goals file, the plan, the working rules and the principles may not.
- **`decisions` and `comprehension-history` may name a page only where `plan` names a Jira epic.** rule-hook ranks a plan kept as a file before tool calls, inside its 30-second limit, and ranking reads those two records. A Confluence read and two adf-codec container runs would hold up every guarded tool call, and fail it while Confluence is down. `load` refuses goals in Jira beside a plan in a file for the same reason.
- **A write sends the version number the store read, plus one, and Confluence refuses it with 409 where someone saved the page since.** The store then fails, saying to ask the human, and doesn't write the page; the loop never overwrites a teammate's edit on its own (lilleman, 2026-11-12). A write with no read before it replaces the page as it stands, as the record contract asks.
- **`project-record` keeps the version `open` read in a file beside its copy**, `~/.local/state/project-record/<key>/<record>.version`, since `save` runs in a later process. The store keeps the version itself, so `write` still takes only the text. Every other tool reads and writes a record in one process, and its store keeps the version in memory, so a read by another tool, such as larv-review's, never moves the version an edit in `project-record` rests on.
- **`project-record` keeps the version `open` read in a file beside its copy**, `~/.local/state/project-record/<key>/<worktree>/<record>.version`, since `save` runs in a later process. The store keeps the version itself, so `write` still takes only the text. Every other tool reads and writes a record in one process, and its store keeps the version in memory, so a read by another tool, such as larv-review's, never moves the version an edit in `project-record` rests on.
- **The page holds ADF, which adf-codec converts both ways**, so a teammate reads the record as Confluence renders it. Where adf-codec cannot convert the markdown, the write fails with adf-codec's error. A node markdown cannot hold reads as text: a mention as its name, a macro as `_(<macro> not included)_`. So the next write replaces it with that text, and a record page should hold only what markdown can.
## project config: a tool that reads a file's commits says where it does not support that file, and the work goes on
+17
View File
@@ -2266,3 +2266,20 @@ Read most (opens and searches):
- `bin/loop_claude/loop/main.py` 2
- `rules/todo-items.md` 2
- `README.md` 1
## Reading cost, chunk 8026e60ea27c, finished 2026-11-15T21:44:03Z
199967 new input tokens before the first commit.
Read most (opens and searches):
- `docs/decisions.md` 11
- `bin/chunk_pr/test_chunk_pr.py` 8
- `skills/larv-review/SKILL.md` 8
- `CLAUDE.md` 5
- `README.md` 5
- `bin/chunk_pr/main.py` 5
- `bin/project_config/templates.py` 4
- `rules/todo-items.md` 4
- `bin/project_config/main.py` 3
- `bin/chunk_pr/approval.py` 2
+1 -1
View File
@@ -2,7 +2,7 @@
paths:
- "**/AGENTS.md"
- "**/docs/decisions.md"
- "**/project-record/*/decisions.md"
- "**/project-record/*/*/decisions.md"
---
# Decisions: one home, each linked to a goal or a technical principle