lockmaster 0.0.1__tar.gz

lockmaster-0.0.1/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Arpit Arya
+
+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.
+
+SPDX-License-Identifier: MIT

lockmaster-0.0.1/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: lockmaster
+Version: 0.0.1
+Summary: Lands AI-agent changes into main one at a time, without ever losing work.
+Author: Arpit Arya
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/arpitarya/lockmaster
+Project-URL: Changelog, https://github.com/arpitarya/lockmaster/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/arpitarya/lockmaster/issues
+Keywords: git,merge-queue,ai-agents,worktree,claude-code
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# lockmaster
+
+**Lands AI-agent changes into `main`, one at a time, without ever losing work.**
+
+Several coding agents working in one repository collide: one commits another's
+half-done files, generated files conflict, worktrees pile up, finished work
+sits on branches nobody merged. lockmaster is the doorman. Each agent claims
+the files it will touch, works in its own worktree and hands its change in;
+lockmaster puts the changes onto `main` one at a time — only the claimed files,
+generated files rebuilt, your checks run — and cleans up after each. Like a
+canal lock-keeper: one boat through at a time, the water levels kept safe.
+
+> **Status: 0.0.1, pre-alpha.** 0.0.1 holds the name on PyPI. Claims, the
+> queue, landing, generated files, structural merges, the kit's hooks and
+> `install` are built and tested on scratch repositories; commands and files
+> may still change before 0.1.0. The design of
+> record is [SR-ARCHITECTURE](records/0101_architecture.md); what is left is
+> the queue in [`work/OPEN-WORK.md`](work/OPEN-WORK.md).
+
+## Install
+
+```bash
+pip install lockmaster            # Python ≥ 3.9, no dependencies
+lockmaster install .              # the work-system kit into this repository, pinned
+```
+
+## How a change moves
+
+```text
+lockmaster start W-12 --paths src/a.py src/b.py   # branch + worktree + claim
+cd .claude/worktrees/W-12                          # … the agent edits only the claimed files …
+lockmaster submit -m "W-12: the parser"            # joins the queue and lands it, one at a time
+lockmaster queue                                   # what is waiting, held, handed off, landed, or red
+lockmaster status                                  # sessions, changes, worktrees, disk use
+lockmaster doctor                                  # stale locks, orphan worktrees, unmerged branches
+```
+
+**Nobody has to remember to land.** In Claude Code the kit's `auto-land.py`
+hook lands a session's change at the end of every turn — the change stays
+open and its worktree follows `main`, so conflicts stay small — and lands and
+cleans it up when the session ends. A `claude --worktree` session is adopted
+the same way. `[land] auto = "off"` in `lockmaster.toml` turns it off.
+
+**From Cowork, or anywhere that edited `main`'s checkout directly:**
+
+```text
+lockmaster save -m "W-12: the parser" src/a.py     # lands it — or hands it off
+```
+
+Where the surface can commit, that lands it. Where it cannot — the Cowork
+bridge cannot remove files and sees the Mac's repository at another path —
+it records a handoff and exits 0; the next Claude Code session lands it
+(`lockmaster pickup`, run by the kit's hook). `lockmaster can-commit` says which.
+
+A change that cannot land cleanly — a real conflict, a failed check — goes
+**red**, is set aside so the next change still lands, and waits for its agent
+or a person. lockmaster never runs `--force`, `branch -D`, `reset --hard` or
+`git clean`; a worktree or branch is removed only when git itself shows nothing
+in it is missing from `main`.
+
+## What it is not
+
+Not a new version control system: every landing is a plain git commit, and
+`git log` reads the history with nothing else installed. Why not build our own,
+as Anthropic did for its monorepo: [`work/compare/source-control.compare.md`](work/compare/source-control.compare.md).
+
+## Per-repository config
+
+```toml
+# lockmaster.toml
+[main]
+branch = "main"
+
+[checks]                         # name = command; every one must pass before a landing
+tests = "pytest -q"
+
+[generated]                      # path or glob = command; rebuilt on landing, never merged
+"CHANGELOG.md" = "python3 scripts/gen-changelog.py"
+
+[merge]                          # structural merges: two new rows never conflict
+"work/WORKLOG.md" = "append-newest-first"
+"work/OPEN-WORK.md" = "table-rows"
+"work/LESSONS.md" = "append"
+```
+
+`lockmaster drivers` registers the merge drivers in `.git/config` and writes
+the `[merge]` paths into `.gitattributes`; plain `git merge` uses them too.
+`lockmaster install <repo>` puts the work-system kit — hooks, settings, the
+`docket` skill — into a repository, pinned in `.claude/lockmaster.lock`.
+
+## Working on lockmaster
+
+Python ≥ 3.9, standard library only.
+
+```bash
+PYTHONPATH=src python3 -m lockmaster install .   # once per clone: kit/ into .claude/ and .github/, the commit guard, the merge drivers
+PYTHONPATH=src python3 -m lockmaster --help      # every command
+python3 -m unittest discover tests               # the tests — scratch git repositories, one file per work item
+python3 scripts/check-work-system.py  # the work-system checks
+```
+
+Agents start at [`CLAUDE.md`](CLAUDE.md). Contributions: [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## Licence
+
+[MIT](LICENSE).

lockmaster-0.0.1/README.md

@@ -0,0 +1,106 @@
+# lockmaster
+
+**Lands AI-agent changes into `main`, one at a time, without ever losing work.**
+
+Several coding agents working in one repository collide: one commits another's
+half-done files, generated files conflict, worktrees pile up, finished work
+sits on branches nobody merged. lockmaster is the doorman. Each agent claims
+the files it will touch, works in its own worktree and hands its change in;
+lockmaster puts the changes onto `main` one at a time — only the claimed files,
+generated files rebuilt, your checks run — and cleans up after each. Like a
+canal lock-keeper: one boat through at a time, the water levels kept safe.
+
+> **Status: 0.0.1, pre-alpha.** 0.0.1 holds the name on PyPI. Claims, the
+> queue, landing, generated files, structural merges, the kit's hooks and
+> `install` are built and tested on scratch repositories; commands and files
+> may still change before 0.1.0. The design of
+> record is [SR-ARCHITECTURE](records/0101_architecture.md); what is left is
+> the queue in [`work/OPEN-WORK.md`](work/OPEN-WORK.md).
+
+## Install
+
+```bash
+pip install lockmaster            # Python ≥ 3.9, no dependencies
+lockmaster install .              # the work-system kit into this repository, pinned
+```
+
+## How a change moves
+
+```text
+lockmaster start W-12 --paths src/a.py src/b.py   # branch + worktree + claim
+cd .claude/worktrees/W-12                          # … the agent edits only the claimed files …
+lockmaster submit -m "W-12: the parser"            # joins the queue and lands it, one at a time
+lockmaster queue                                   # what is waiting, held, handed off, landed, or red
+lockmaster status                                  # sessions, changes, worktrees, disk use
+lockmaster doctor                                  # stale locks, orphan worktrees, unmerged branches
+```
+
+**Nobody has to remember to land.** In Claude Code the kit's `auto-land.py`
+hook lands a session's change at the end of every turn — the change stays
+open and its worktree follows `main`, so conflicts stay small — and lands and
+cleans it up when the session ends. A `claude --worktree` session is adopted
+the same way. `[land] auto = "off"` in `lockmaster.toml` turns it off.
+
+**From Cowork, or anywhere that edited `main`'s checkout directly:**
+
+```text
+lockmaster save -m "W-12: the parser" src/a.py     # lands it — or hands it off
+```
+
+Where the surface can commit, that lands it. Where it cannot — the Cowork
+bridge cannot remove files and sees the Mac's repository at another path —
+it records a handoff and exits 0; the next Claude Code session lands it
+(`lockmaster pickup`, run by the kit's hook). `lockmaster can-commit` says which.
+
+A change that cannot land cleanly — a real conflict, a failed check — goes
+**red**, is set aside so the next change still lands, and waits for its agent
+or a person. lockmaster never runs `--force`, `branch -D`, `reset --hard` or
+`git clean`; a worktree or branch is removed only when git itself shows nothing
+in it is missing from `main`.
+
+## What it is not
+
+Not a new version control system: every landing is a plain git commit, and
+`git log` reads the history with nothing else installed. Why not build our own,
+as Anthropic did for its monorepo: [`work/compare/source-control.compare.md`](work/compare/source-control.compare.md).
+
+## Per-repository config
+
+```toml
+# lockmaster.toml
+[main]
+branch = "main"
+
+[checks]                         # name = command; every one must pass before a landing
+tests = "pytest -q"
+
+[generated]                      # path or glob = command; rebuilt on landing, never merged
+"CHANGELOG.md" = "python3 scripts/gen-changelog.py"
+
+[merge]                          # structural merges: two new rows never conflict
+"work/WORKLOG.md" = "append-newest-first"
+"work/OPEN-WORK.md" = "table-rows"
+"work/LESSONS.md" = "append"
+```
+
+`lockmaster drivers` registers the merge drivers in `.git/config` and writes
+the `[merge]` paths into `.gitattributes`; plain `git merge` uses them too.
+`lockmaster install <repo>` puts the work-system kit — hooks, settings, the
+`docket` skill — into a repository, pinned in `.claude/lockmaster.lock`.
+
+## Working on lockmaster
+
+Python ≥ 3.9, standard library only.
+
+```bash
+PYTHONPATH=src python3 -m lockmaster install .   # once per clone: kit/ into .claude/ and .github/, the commit guard, the merge drivers
+PYTHONPATH=src python3 -m lockmaster --help      # every command
+python3 -m unittest discover tests               # the tests — scratch git repositories, one file per work item
+python3 scripts/check-work-system.py  # the work-system checks
+```
+
+Agents start at [`CLAUDE.md`](CLAUDE.md). Contributions: [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## Licence
+
+[MIT](LICENSE).

lockmaster-0.0.1/kit/claude/hooks/auto-land.py

@@ -0,0 +1,286 @@
+#!/usr/bin/env python3
+"""Auto-landing — SR-ARCHITECTURE decisions 19 and 20: finished work reaches main
+without anyone remembering to land it, and what Cowork could not commit,
+Claude Code does.
+
+    start  SessionStart      export CLAUDE_SESSION_ID for this session's commands,
+                             so `lockmaster start` records whose change it is;
+                             land waiting handoffs in the background
+    edit   PostToolUse       note each file this session writes in main's checkout
+    stop   Stop              say what earlier landings did (and, once, a landing
+                             waiting on main's checkout); tell the agent, once,
+                             about a landing held back, a handoff that did not
+                             land, or edits left in main's checkout; then land
+                             this session's open changes (they stay open) and
+                             the handoffs, in the background
+    end    SessionEnd        land and clean up this session's changes, in the
+                             background (the session is going away)
+
+lockmaster is found at `$LOCKMASTER_SRC`, in this repository's own `src/`
+(lockmaster itself), in a `lockmaster` checkout beside this repository, or as
+an installed package. Without it the hook does nothing.
+It never fails a session: every error is swallowed and the turn ends as usual.
+Python >= 3.9, standard library only.
+"""
+import hashlib
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def git(args, cwd):
+    try:
+        r = subprocess.run(["git"] + args, cwd=str(cwd), capture_output=True, text=True)
+    except OSError:
+        return None
+    return r.stdout.strip() if r.returncode == 0 else None
+
+
+def main_root(cwd):
+    """The primary checkout: the first `git worktree list` entry."""
+    out = git(["worktree", "list", "--porcelain"], cwd)
+    if not out:
+        return None
+    return Path(out.splitlines()[0][len("worktree "):])
+
+
+def candidates():
+    env = os.environ.get("LOCKMASTER_SRC")
+    if env:
+        yield Path(env)
+    yield ROOT / "src"
+    root = main_root(ROOT)
+    if root is not None:
+        yield root / "src"
+        yield root.parent / "lockmaster" / "src"
+
+
+def find_src():
+    """The directory to put on sys.path, "" when lockmaster is installed, None when absent."""
+    for c in candidates():
+        if (c / "lockmaster" / "land.py").is_file():
+            return str(c)
+    try:
+        import lockmaster  # noqa: F401
+        return ""
+    except ImportError:
+        return None
+
+
+def load():
+    src = find_src()
+    if src is None:
+        return None, None
+    if src:
+        sys.path.insert(0, src)
+    from lockmaster import land
+    from lockmaster.repo import Repo
+    return src, (land, Repo)
+
+
+def command(src):
+    return "PYTHONPATH={} python3 -m lockmaster".format(src) if src else "lockmaster"
+
+
+def detach(src, args, cwd):
+    """Run `lockmaster <args>` on its own, outliving this hook; output to the state dir's log."""
+    common = git(["rev-parse", "--git-common-dir"], cwd)
+    if not common:
+        return
+    log_dir = (Path(cwd) / common).resolve() / "lockmaster"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    env = dict(os.environ)
+    if src:
+        env["PYTHONPATH"] = src + (os.pathsep + env["PYTHONPATH"] if env.get("PYTHONPATH") else "")
+    with open(str(log_dir / "auto-land.log"), "a", encoding="utf-8") as log:
+        subprocess.Popen([sys.executable, "-m", "lockmaster"] + args, cwd=str(cwd), env=env,
+                         stdin=subprocess.DEVNULL, stdout=log, stderr=log, start_new_session=True)
+
+
+# ---------------------------------------------------------------- the session's own notes
+
+def notes_file(repo, sid):
+    safe = "".join(ch if ch.isalnum() or ch in "-_." else "_" for ch in sid)
+    return repo.state / "sessions" / (safe + ".json")
+
+
+def read_notes(repo, sid):
+    try:
+        return json.loads(notes_file(repo, sid).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {"edits": []}
+
+
+def write_notes(repo, sid, notes):
+    f = notes_file(repo, sid)
+    f.parent.mkdir(parents=True, exist_ok=True)
+    tmp = f.with_name(f.name + ".part")
+    tmp.write_text(json.dumps(notes, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    os.replace(str(tmp), str(f))
+
+
+# ---------------------------------------------------------------- modes
+
+def start(sid, hook):
+    env_file = os.environ.get("CLAUDE_ENV_FILE")
+    if env_file and sid:
+        with open(env_file, "a", encoding="utf-8") as fh:
+            fh.write("export CLAUDE_SESSION_ID={}\n".format(sid))
+    src = find_src()
+    if src is not None:
+        detach(src, ["pickup"], hook.get("cwd") or ROOT)
+    return None
+
+
+def edit(sid, hook):
+    raw = (hook.get("tool_input") or {}).get("file_path") or (hook.get("tool_input") or {}).get("notebook_path")
+    if not raw or not sid:
+        return None
+    src, mods = load()
+    if mods is None:
+        return None
+    _, Repo = mods
+    p = Path(raw)
+    if not p.is_absolute():
+        p = Path(hook.get("cwd") or os.getcwd()) / p
+    repo = Repo(hook.get("cwd") or ROOT)
+    root = os.path.realpath(str(repo.root))
+    full = os.path.realpath(str(p))
+    if not full.startswith(root + os.sep):
+        return None
+    rel = os.path.relpath(full, root).replace(os.sep, "/")
+    if rel.startswith(".claude/worktrees/") or repo.change_holding(full) is not None:
+        return None
+    notes = read_notes(repo, sid)
+    if rel not in notes["edits"]:
+        notes["edits"].append(rel)
+        write_notes(repo, sid, notes)
+    return None
+
+
+def stop(sid, hook):
+    """Report what earlier landings did, then land in the background: a
+    landing runs the repository's checks and rebuilds, which can take minutes
+    (fux), so a turn never waits on it. `LOCKMASTER_FOREGROUND=1` lands first
+    and reports at once (the tests)."""
+    src, mods = load()
+    if mods is None:
+        return None
+    land, Repo = mods
+    cwd = hook.get("cwd") or str(ROOT)
+    said, lines = [], []
+
+    def step(fn):
+        """Each step on its own: one failing never skips the others."""
+        try:
+            return fn()
+        except Exception as e:  # noqa: BLE001
+            print("auto-land.py stop: {}".format(e), file=sys.stderr)
+            return None
+
+    foreground = os.environ.get("LOCKMASTER_FOREGROUND") == "1"
+    if foreground:
+        step(lambda: land.sync(Repo(cwd), session=sid, cwd=cwd, out=lines.append))
+        step(lambda: land.pickup(Repo(cwd), out=lines.append))
+    repo = step(lambda: Repo(cwd))
+    if repo is None:
+        return None
+    notes = read_notes(repo, sid) if sid else {"edits": []}
+    since = notes.get("last_stop", 0)
+    landed = []
+    for c in step(repo.changes) or []:
+        if (c.get("landed_at") or 0) > since and land._mine(c, sid, cwd):
+            landed.append("landed {} as {}".format(c["item"], (c.get("landed") or "")[:10]))
+    # W-10: a landing waiting on main's checkout lands by itself; it is said, never blocks.
+    for item, reason in step(lambda: getattr(land, "waiting_reports", lambda *a, **k: [])(
+            repo, session=sid, cwd=cwd)) or []:
+        landed.append("{} is waiting: {}".format(item, reason))
+    told = notes.setdefault("told_handoffs", {})
+    for h in step(lambda: land.handoffs(repo)) or []:
+        if h.get("reason") and told.get(h["item"]) != h.get("tried"):
+            told[h["item"]] = h.get("tried")
+            said.append("Edits handed over from Cowork ({}) did not land:\n{}\nFix them where they are, in "
+                        "main's checkout; the end of the next turn tries again with them.".format(
+                            h["item"], h["reason"]))
+    for item, reason in step(lambda: land.held_reports(repo, session=sid, cwd=cwd)) or []:
+        said.append("lockmaster could not land {} at the end of a turn:\n{}\nFix it in its worktree; it "
+                    "lands at the end of the next turn. Nothing on main changed.".format(item, reason))
+    if sid:
+        notes["last_stop"] = time.time()
+        write_notes(repo, sid, notes)
+        reminder = step(lambda: checkout_reminder(land, repo, sid, src))
+        if reminder:
+            said.append(reminder)
+    if not foreground:
+        args = ["sync", "--pickup", "--cwd", cwd] + (["--session", sid] if sid else [])
+        step(lambda: detach(src, args, cwd))
+    result = {}
+    if landed:
+        result["systemMessage"] = "lockmaster: " + "; ".join(landed)
+    if said:
+        if hook.get("stop_hook_active"):
+            # Already continuing because of a Stop hook: say it, never block twice in a row.
+            result["systemMessage"] = "\n\n".join(([result["systemMessage"]] if landed else []) + said)
+        else:
+            result["decision"] = "block"
+            result["reason"] = "\n\n".join(said)
+    return result or None
+
+
+def checkout_reminder(land, repo, sid, src):
+    """Once per set of files: the session's own edits in main's checkout that are not on main."""
+    notes = read_notes(repo, sid)
+    if not notes["edits"]:
+        return None
+    left = [p for p in land._checkout_dirty(repo, notes["edits"]) if p in notes["edits"]]
+    if not left:
+        return None
+    key = hashlib.sha256("\0".join(sorted(left)).encode()).hexdigest()[:16]
+    if notes.get("told") == key:
+        return None
+    notes["told"] = key
+    write_notes(repo, sid, notes)
+    return ("This session edited {} in main's checkout and it is not on main. Land it now: "
+            "`{} save -m \"<what changed and why>\" {}`".format(", ".join(left), command(src), " ".join(left)))
+
+
+def end(sid, hook):
+    src = find_src()
+    if src is None:
+        return None
+    cwd = hook.get("cwd") or str(ROOT)
+    args = ["sync", "--final", "--cwd", cwd] + (["--session", sid] if sid else [])
+    detach(src, args, cwd)
+    return None
+
+
+def main(argv):
+    mode = argv[0] if argv else ""
+    fn = {"start": start, "edit": edit, "stop": stop, "end": end}.get(mode)
+    if fn is None:
+        print("usage: auto-land.py start|edit|stop|end", file=sys.stderr)
+        return 0
+    hook = {}
+    if not sys.stdin.isatty():
+        try:
+            hook = json.loads(sys.stdin.read() or "{}")
+        except ValueError:
+            hook = {}
+    sid = hook.get("session_id") or os.environ.get("CLAUDE_SESSION_ID", "")
+    try:
+        result = fn(sid, hook)
+    except Exception as e:  # noqa: BLE001 — never fail the session over a landing
+        print("auto-land.py {}: {}".format(mode, e), file=sys.stderr)
+        return 0
+    if result:
+        print(json.dumps(result))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))