Deploy releases to ~/.claude with deploy-release and develop in ~/code/claude-config

This commit is contained in:
2026-10-29 21:15:55 +01:00
parent 7681c2b4c0
commit 687ff858d3
9 changed files with 255 additions and 21 deletions
+3
View File
@@ -27,6 +27,9 @@
!bin/claude_code/
!bin/claude_code/*.py
!bin/comprehension_history.py
!bin/deploy-release
!bin/deploy_release/
!bin/deploy_release/*.py
!bin/docker_command.py
!bin/failure.py
!bin/file_writes.py
+2 -1
View File
@@ -7,6 +7,7 @@ Decisions live in `docs/decisions.md`:
- bin/: the tools support only the latest stable Python, and the tests, written in plain unittest, run on it in four pytest-xdist workers
- chunks: a chunk takes every unblocked item of its release that fires the same review passes, whatever its purpose, and an item above R 5 ships alone
- comprehension floor: every dimension and the overall at 7.0 or above is the target, and blocks no merge or release
- deploy: `~/.claude` holds only a release, which `deploy-release` moves it to; this repo is developed in `~/code/claude-config`, where loop-claude runs its chunks like any project's
- larv-review: within a chunk lifting a project towards the comprehension floor, work on the project's lowest-scoring dimension comes first, and the floor doesn't block anything
- loop-claude: a `claude` that cannot start is a failed worker run, retried
- loop-claude: a judge decides each interrupt and each quoted answer from the transcript, the README's premises, `AGENTS.md`, `docs/decisions.md`, `~/.claude/CLAUDE.md`, `~/.claude/rules/` and larv-review's standards, and holds a chunk open while an answer the human typed in it is recorded nowhere; the worker's own account of which goal settles a choice decides nothing
@@ -63,7 +64,7 @@ Decisions live in `docs/decisions.md`:
## Working rules
- `routing-calls-raised.md` sits at the root of loop-claude's archive (`$LOOP_CLAUDE_TRANSCRIPTS`, default `~/.claude/loop-claude-transcripts`). Each of its lines is a call or a `Reset`, with a stamp. A call is new when it is stamped after the latest `Reset` and after the latest stamp that `todo.md` or `docs/decisions.md` → `routing:` cites. When there are new calls, file one `todo.md` item to settle them, or refresh the item already filed. Its detail quotes those calls with their stamps, and the routed-chunks table of `routing-figures.md` beside it, never the project names its other tables hold. A change to the ladder, its steps or the delegation rule is the human's. The chunk that settles the calls cites the latest stamp it settled in `docs/decisions.md` → `routing:`, whatever the human decided, so they are not filed again. Once a chunk that changes the ladder, its steps or the delegation rule has merged, append `- <UTC time> Reset` to `routing-calls-raised.md`: the figures then count only chunks finished after it, and its calls may be raised again.
- When `~/.claude/settings.json` has uncommitted changes, commit them on a branch of their own and merge them through a PR: Claude Code writes that file from any session. Read their diff first: `git diff HEAD -- settings.json`, which shows staged changes too. An empty diff means only the model or the key order changed: `git add settings.json` takes the file off `git status`, with nothing to commit. When the diff holds a credential, such as a token in `env` or `mcpServers`, ask the human to move it out of the file, and commit only once it is gone. A token in `env` moves to the shell profile; a server in `mcpServers` moves to `~/.claude.json` with `claude mcp add --scope user`.
- When `~/.claude/settings.json` has uncommitted changes, carry them into `~/code/claude-config` on a branch of their own and merge them through a PR: Claude Code writes that file from any session, and `deploy-release` refuses to move `~/.claude` until a release holds them. Read their diff first: `git -C ~/.claude diff HEAD -- settings.json`. An empty diff means only the model or the key order changed, which `deploy-release` takes as no change. When the diff holds a credential, such as a token in `env` or `mcpServers`, ask the human to move it out of the file, and commit only once it is gone. A token in `env` moves to the shell profile; a server in `mcpServers` moves to `~/.claude.json` with `claude mcp add --scope user`.
## Scoring run
+6
View File
@@ -2,6 +2,12 @@
## Unreleased
- `~/.claude` now holds only a release, and this repo is developed in a clone, `~/code/claude-config`. A new tool, `deploy-release`, moves `~/.claude` to the newest `v*` tag and prints `CHANGELOG.md`'s section for each version it moved past. It refuses while a tracked file there has an uncommitted change the new tag doesn't hold, such as a hook Claude Code wrote into `settings.json`, or where the move would drop commits no release holds; a model picked with `/model` is no such change. To switch a machine over:
1. Stop any `loop-claude` running in `~/.claude`, and finish or move its open chunk.
2. Clone this repo to `~/code/claude-config`, and run `git config filter.settings.clean bin/settings_filter.py` there.
3. Run `~/code/claude-config/bin/deploy-release`. Where `~/.claude` is on a branch, it refuses until a release holds that branch's commits.
4. Run loop-claude for this repo from `~/code/claude-config`. It asks for the project's model, since the project is new to it.
- larv-review's architecture and principles passes now run only in a new release review: the chunk that runs once a release holds no item and changes are unreleased, before the release is ready to cut. Each reads the whole project, may refactor boldly and takes up to five rounds; their fixes take the stability, security, overrides and prose passes, two rounds each. No other chunk runs either pass, so a chunk that changes code no longer waits on the principles audit. Between releases, the product-owner pass now also reviews changes to routes, request and response shapes, events, webhooks, published file formats, CLI flags and exit codes, which the architecture trigger used to cover. The comprehension check's paired ruling moves to the release review too.
- `chunk-preflight` now reports a release review due where it reported a release ready to cut, until a commit titled `Release review of <release>` follows the newest `v*` tag on the default branch. Open the review's branch with that commit.
- rule-hook's `round-cap` and `larv-review round-count` allow the architecture and principles passes five rounds.
+13 -20
View File
@@ -37,16 +37,19 @@ Me, on my own machines, which take tagged releases. Nobody else depends on it.
Take this checkout only onto a machine that is a sandbox with no direct access to a production environment, such as a dedicated VM: `settings.json` runs Claude Code in auto mode with the dangerous-mode prompt skipped.
Claude Code may already have created `~/.claude`, where `git clone` refuses to run, so make the repository in place:
Each machine holds two checkouts. `~/.claude` is the one Claude Code reads, and it holds only a release: `deploy-release` moves it from tag to tag. Develop in a clone under `~/code`, where loop-claude runs this repo's chunks like any project's.
Claude Code may already have created `~/.claude`, where `git clone` refuses to run, so make the repository in place, then clone it for development:
```sh
mkdir -p ~/.claude && cd ~/.claude
git init
git remote add origin ssh://git@gitea.larvit.se:21022/lilleman/claude-config.git
git fetch --tags origin
git checkout -f "$(git tag -l 'v*' --sort=-v:refname | head -n 1)"
git clone ssh://git@gitea.larvit.se:21022/lilleman/claude-config.git ~/code/claude-config
```
Then run Update's commands, skipping `git add settings.json`: the new repository tracks no file yet.
Have the latest stable Python, today 3.14, as `python3` on `PATH`, and for Rust projects `rust-analyzer` on `PATH`, which the `rust-analyzer-lsp` plugin needs. Install every plugin `settings.json` enables:
```sh
@@ -56,7 +59,7 @@ claude plugin install code-review@claude-plugins-official
claude plugin install rust-analyzer-lsp@claude-plugins-official
```
Have git store `settings.json` without `"model"`, so a model you pick with `/model` stays on this machine and never reaches a commit:
Have git store `settings.json` without `"model"`, so a model you pick with `/model` stays on this machine and never reaches a commit. Run this in each checkout, `~/.claude` and `~/code/claude-config`:
```sh
git config filter.settings.clean bin/settings_filter.py
@@ -64,38 +67,28 @@ git config filter.settings.clean bin/settings_filter.py
Then pick a model with `/model`.
After a pick, `git status` may list `settings.json`, and a `git pull` that changes the file refuses to run. `git add settings.json` stages no change and clears both. Once it is staged, such a pull goes through and drops the model: pick it again.
Link `loop-claude` and `loop-inbox` onto `PATH`: `ln -s ~/.claude/bin/loop-claude ~/.local/bin/loop-claude` and `ln -s ~/.claude/bin/loop-inbox ~/.local/bin/loop-inbox`. Every claude they start, the interactive ones included, skips every permission prompt.
## Update
Move a machine that takes tagged releases to the latest tag. The move discards every uncommitted change to a file the latest tag tracks, such as a hook Claude Code wrote into `settings.json`. Git counts a model pick as such a change until `git add settings.json`, so stage it first. List the uncommitted changes to files the checkout tracks, and the tag it is on:
Move `~/.claude` to the newest release:
```sh
cd ~/.claude
git add settings.json
git fetch --tags origin
git status
~/code/claude-config/bin/deploy-release
```
To keep an uncommitted change, merge it per `AGENTS.md` → "Working rules" and cut a release ("Release") before moving: a machine gets only what a tag holds. Then move:
```sh
git checkout -f "$(git tag -l 'v*' --sort=-v:refname | head -n 1)"
```
Then, where the tag changed `settings.json`, pick the model again with `/model`, and do what `CHANGELOG.md` asks of each version since the old tag, such as a new step under Install.
It refuses while a file `~/.claude` tracks has an uncommitted change, such as a hook Claude Code wrote into `settings.json`: merge that per `AGENTS.md` → "Working rules", then cut a release. A model picked with `/model` is no such change. It prints `CHANGELOG.md`'s section for each version it moved past: do what each asks, such as a new step under Install. `deploy-release --help` says what else it checks.
## Release
Rename `## Unreleased` in `CHANGELOG.md` to the version, commit, tag that commit `v<version>`, and push both.
In `~/code/claude-config`, rename `## Unreleased` in `CHANGELOG.md` to the version, commit, tag that commit `v<version>`, and push both. Then run Update on each machine.
## Tools
Install puts only `loop-claude` and `loop-inbox` on `PATH`; call the others by their path, such as `~/.claude/bin/metric-bench`, from the project's checkout.
Install puts only `loop-claude` and `loop-inbox` on `PATH`; call the others by their path, such as `~/.claude/bin/metric-bench`, from the project's checkout. Those under `~/.claude` are the release's; test a change to one from `~/code/claude-config/bin`.
- `chunk-preflight` finds the mechanical facts a chunk starts from and makes its worktree; `loop-claude` runs it before it routes each chunk, and `chunk-preflight --help` lists the facts.
- `deploy-release [<checkout>]` moves `~/.claude`, or the checkout named, to the newest release, as Update says.
- `judge-replay <model>` replays loop-claude's judge on archived verdicts of the projects run on the model, and prints the lowest rung that, like each rung above it, returns them; `judge-replay --help` states the replay.
- `larv-review <command>` holds larv-review's mechanical rules: the chunk's review folder, the paired ruling's base and vote count, each pass's round count, the scoring run's trigger, and the comprehension history's format and latest places, and its count of how often seats agree; `larv-review --help` states them.
- `loop-claude <task>` runs a project's next chunk cycle after cycle; `loop-claude --help` states its contract.
+9
View File
@@ -0,0 +1,9 @@
#!/usr/bin/env python3
import pathlib
import sys
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
from deploy_release import main
sys.exit(main.main(sys.argv[1:]))
View File
+100
View File
@@ -0,0 +1,100 @@
"""Move the checkout Claude Code reads its configuration from to this repo's newest release.
usage: deploy-release [<checkout>]
<checkout> defaults to ~/.claude. The tool fetches origin's tags and checks out the newest v* tag,
detached, so the checkout holds only what a release holds. Development happens in another clone,
such as ~/code/claude-config. It prints the version it moved from and to, then CHANGELOG.md's
section for each version since, so you can do what each asks, such as a new step under Install.
Where the move changed settings.json, it asks you to pick the model again with /model, since git's
clean filter keeps the model out of every commit.
It refuses, exit 1, and leaves the checkout as it was where a file the checkout tracks has an
uncommitted change the newest tag doesn't hold: such as a hook Claude Code wrote into settings.json.
Merge the change through the development clone and cut a release first. A model picked with /model
is no such change. It
also refuses where the newest tag doesn't hold the checkout's commit, since the move would drop
work no release holds. Untracked files, such as Claude Code's sessions and memory, stay as they are.
"""
import pathlib
import re
import sys
from failure import Failure
from git_repo import git
from todo_table import release_of
from markdown_text import sections
def main(argv: list[str]) -> int:
if argv[:1] in (["-h"], ["--help"]):
print(__doc__.strip())
return 0
if len(argv) > 1:
print("deploy-release: usage: deploy-release [<checkout>]", file=sys.stderr)
return 1
checkout = argv[0] if argv else str(pathlib.Path.home() / ".claude")
moved = deploy(checkout)
if isinstance(moved, Failure):
print(f"deploy-release: {moved.reason}", file=sys.stderr)
return 1
print(moved)
return 0
def deploy(checkout: str) -> str | Failure:
"""What the move of checkout to the newest release did, as the tool prints it; a Failure where it refused or git failed."""
fetched = git("fetch", "--quiet", "--tags", "origin", cwd=checkout)
if isinstance(fetched, Failure):
return fetched
newest = git("-c", "versionsort.suffix=-", "tag", "--list", "v*", "--sort=-v:refname", cwd=checkout)
if isinstance(newest, Failure):
return newest
if not newest.split():
return Failure("origin has no v* tag to move to")
tag = newest.split()[0]
# Re-reads each file through the clean filter, so a model pick alone leaves settings.json unchanged.
git("update-index", "-q", "--refresh", cwd=checkout)
changed = git("diff", "--name-only", "HEAD", cwd=checkout)
if isinstance(changed, Failure):
return changed
unreleased = git("diff", "--name-only", tag, "--", *changed.split(), cwd=checkout) if changed.split() else ""
if isinstance(unreleased, Failure):
return unreleased
if unreleased.split():
return Failure(f"{checkout} has uncommitted changes that {tag} doesn't hold, to {', '.join(unreleased.split())}: merge them through the development clone and cut a release first")
old = git("describe", "--tags", "--abbrev=0", "--match", "v*", "HEAD", cwd=checkout)
old_tag = None if isinstance(old, Failure) else old.strip()
at_tag = git("describe", "--tags", "--exact-match", "--match", "v*", "HEAD", cwd=checkout)
if not isinstance(at_tag, Failure) and at_tag.strip() == tag:
return f"Already on {tag}, the newest release."
if isinstance(git("merge-base", "--is-ancestor", "HEAD", tag, cwd=checkout), Failure):
return Failure(f"{tag} doesn't hold the checkout's commit, so the move would drop work no release holds: cut a release that holds it first")
settings_changed = isinstance(git("diff", "--quiet", "HEAD", tag, "--", "settings.json", cwd=checkout), Failure)
# The tag holds each uncommitted change, so undoing them loses nothing, and lets the checkout below take the tag's copy.
if changed.split():
restored = git("checkout", "--quiet", "HEAD", "--", *changed.split(), cwd=checkout)
if isinstance(restored, Failure):
return restored
moved = git("checkout", "--quiet", "--detach", tag, cwd=checkout)
if isinstance(moved, Failure):
return moved
changelog = git("show", f"{tag}:CHANGELOG.md", cwd=checkout)
lines = [f"Moved from {old_tag or 'an untagged commit'} to {tag}."]
if settings_changed:
lines.append("settings.json changed: pick the model again with /model.")
if not isinstance(changelog, Failure):
lines += newer_sections(changelog, old_tag)
return "\n\n".join(lines)
def newer_sections(changelog: str, old_tag: str | None) -> list[str]:
"""Each `## <version>` section of changelog newer than old_tag, newest first, as it reads."""
since = release_of(old_tag.removeprefix("v")) if old_tag and re.fullmatch(r"v[0-9]+\.[0-9]+\.[0-9]+", old_tag) else None
found = []
for heading, bodies in sections(changelog).items():
if not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+", heading):
continue
if since is None or release_of(heading) > since:
found.append(f"## {heading}\n\n" + "\n".join(bodies))
return found
+118
View File
@@ -0,0 +1,118 @@
import pathlib
import subprocess
import sys
import tempfile
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from test_env import isolated_env
TOOL = pathlib.Path(__file__).resolve().parents[1] / "deploy-release"
class DeployRelease(unittest.TestCase):
def setUp(self):
self.temp = pathlib.Path(tempfile.mkdtemp())
self.addCleanup(subprocess.run, ["rm", "-rf", str(self.temp)])
self.origin = self.temp / "origin.git"
self.git(self.temp, "init", "-q", "--bare", "-b", "main", str(self.origin))
self.source = self.temp / "source"
self.git(self.temp, "clone", "-q", str(self.origin), str(self.source))
self.release("0.1.0", "- First.\n", '{"theme": "dark"}\n')
self.target = self.temp / "dot-claude"
self.git(self.temp, "clone", "-q", str(self.origin), str(self.target))
self.git(self.target, "checkout", "-q", "--detach", "v0.1.0")
def git(self, cwd: pathlib.Path, *args: str) -> str:
return subprocess.run(["git", "-c", "user.name=t", "-c", "user.email=t@t", *args], capture_output=True, check=True, cwd=cwd, env=isolated_env(), text=True).stdout
def release(self, version: str, entry: str, settings: str) -> None:
"""Commit a CHANGELOG.md whose newest section is version's, holding entry, and settings.json, then tag it and push both."""
changelog = self.source / "CHANGELOG.md"
earlier = changelog.read_text().removeprefix("# Changelog\n\n") if changelog.exists() else ""
changelog.write_text(f"# Changelog\n\n## {version}\n\n{entry}\n{earlier}")
(self.source / "settings.json").write_text(settings)
self.git(self.source, "add", "-A")
self.git(self.source, "commit", "-q", "-m", f"Cut release {version}")
self.git(self.source, "tag", f"v{version}")
self.git(self.source, "push", "-q", "origin", "main", "--tags")
def deploy(self) -> subprocess.CompletedProcess[str]:
return subprocess.run([sys.executable, str(TOOL), str(self.target)], capture_output=True, env=isolated_env(), text=True)
def head(self) -> str:
return self.git(self.target, "describe", "--tags", "--exact-match", "HEAD").strip()
def test_moves_the_checkout_to_the_newest_tag_and_prints_each_newer_versions_changelog(self):
self.release("0.2.0", "- Second.\n", '{"theme": "dark"}\n')
self.release("0.3.0", "- Third: run `make thing` once.\n", '{"theme": "dark"}\n')
(self.source / "CHANGELOG.md").write_text("# Changelog\n\n## Unreleased\n\n- Later.\n\n" + (self.source / "CHANGELOG.md").read_text().removeprefix("# Changelog\n\n"))
self.git(self.source, "commit", "-q", "-am", "Later work")
self.git(self.source, "push", "-q", "origin", "main")
ran = self.deploy()
self.assertEqual(ran.returncode, 0, ran.stderr)
self.assertEqual(self.head(), "v0.3.0")
self.assertIn("Moved from v0.1.0 to v0.3.0.", ran.stdout)
self.assertIn("## 0.3.0\n\n- Third: run `make thing` once.", ran.stdout)
self.assertIn("## 0.2.0\n\n- Second.", ran.stdout)
self.assertNotIn("First.", ran.stdout)
self.assertNotIn("Later.", ran.stdout)
self.assertNotIn("/model", ran.stdout)
def test_says_so_where_the_checkout_is_on_the_newest_tag_already(self):
ran = self.deploy()
self.assertEqual((ran.returncode, ran.stdout), (0, "Already on v0.1.0, the newest release.\n"))
def test_refuses_an_uncommitted_change_to_a_tracked_file_and_leaves_the_checkout_as_it_was(self):
self.release("0.2.0", "- Second.\n", '{"theme": "dark"}\n')
(self.target / "CHANGELOG.md").write_text("Edited here.\n")
(self.target / "projects").mkdir()
(self.target / "projects" / "session.jsonl").write_text("{}\n")
ran = self.deploy()
self.assertEqual(ran.returncode, 1)
self.assertIn("CHANGELOG.md", ran.stderr)
self.assertNotIn("projects", ran.stderr, "an untracked file is Claude Code's own state, not a change")
self.assertEqual(self.head(), "v0.1.0")
def test_takes_an_uncommitted_change_the_new_release_holds_as_no_change(self):
(self.target / "settings.json").write_text('{"theme": "light"}\n')
self.release("0.2.0", "- Second.\n", '{"theme": "light"}\n')
ran = self.deploy()
self.assertEqual(ran.returncode, 0, ran.stderr)
self.assertEqual(self.head(), "v0.2.0")
def test_refuses_to_move_a_checkout_back_from_commits_no_release_holds(self):
self.git(self.target, "switch", "-q", "main")
(self.source / "new.md").write_text("Unreleased.\n")
self.git(self.source, "add", "-A")
self.git(self.source, "commit", "-q", "-m", "Unreleased work")
self.git(self.source, "push", "-q", "origin", "main")
self.git(self.target, "pull", "-q", "--ff-only")
ran = self.deploy()
self.assertEqual(ran.returncode, 1)
self.assertIn("v0.1.0 doesn't hold", ran.stderr)
self.assertEqual(self.git(self.target, "branch", "--show-current").strip(), "main")
def test_takes_a_model_picked_with_the_clean_filter_set_as_no_change(self):
self.release("0.2.0", "- Second.\n", '{\n "theme": "dark"\n}\n')
self.git(self.target, "fetch", "-q", "--tags", "origin")
self.git(self.target, "checkout", "-q", "--detach", "v0.2.0")
(self.target / ".gitattributes").write_text("/settings.json filter=settings\n")
self.git(self.target, "config", "filter.settings.clean", f"{sys.executable} {TOOL.parent / 'settings_filter.py'}")
(self.target / "settings.json").write_text('{"model": "claude-opus-5-5", "theme": "dark"}\n')
self.release("0.3.0", "- Third.\n", '{\n "theme": "dark"\n}\n')
ran = self.deploy()
self.assertEqual(ran.returncode, 0, ran.stderr)
self.assertEqual(self.head(), "v0.3.0")
self.assertIn('"model"', (self.target / "settings.json").read_text(), "a release that leaves settings.json as it was keeps the pick")
def test_asks_for_the_model_again_where_the_release_changes_settings_json(self):
self.release("0.2.0", "- Second.\n", '{"theme": "light"}\n')
ran = self.deploy()
self.assertEqual(ran.returncode, 0, ran.stderr)
self.assertIn("settings.json changed: pick the model again with /model.", ran.stdout)
if __name__ == "__main__":
unittest.main()
+4
View File
@@ -28,6 +28,10 @@ The cap is 5, `bin/todo_table.py`'s `BUNDLE_MAX_R`, from the same chunks: by the
2026-09-27, lilleman, restating the 2026-09-24 target and extending it to the overall. Serves goal 1. 2026-10-13, lilleman: the floor blocks nothing, and `review: the comprehension check records …` says why. Valid while the scoring run keeps its four seats.
## deploy: `~/.claude` holds only a release, which `deploy-release` moves it to; this repo is developed in `~/code/claude-config`, where loop-claude runs its chunks like any project's
2026-10-29, lilleman. Serves goal 1.3 and goal 2. `~/.claude` was this repo's development checkout, so every merge reached every session on the machine at once, its unfinished work included, while other machines took only tags. Now each machine takes only releases: what a release holds is what every session runs, and cutting one is the human's step that ships it. `deploy-release` automates README → Update. It refuses an uncommitted change to a tracked file that the new tag doesn't hold, such as a hook Claude Code wrote into `settings.json`, and a move that would drop commits no release holds; a model pick, which the clean filter drops, is no change. Valid while Claude Code reads its configuration from one directory per machine.
## larv-review: within a chunk lifting a project towards the comprehension floor, work on the project's lowest-scoring dimension comes first, and the floor doesn't block anything
2026-09-20, lilleman. Serves goal 1. Across six projects scored with the four seats, Locality or Self-sufficiency was the lowest dimension at every seat and Navigation at none, so a layout fix would not lift a project under the floor. Valid while the scoring run keeps those four seats.