@ssheleg/agent-sync 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -1,3 +1,142 @@
+## v1.8.0
+
+**The board, cleared.** Nine rows opened by the two audits of 2026-08-10, closed with a check, a
+measurement or a written decision — because a backlog nobody empties is a list of things everyone
+has agreed to stop seeing.
+
+### The two scenarios that were only ever driven by hand are now gated
+
+Two agents contending for one task, and the guard across every shape a write arrives in, were
+verified by executing them and had no check that fails on its own — the exact state in which the
+first audit found six shipped defects. `check_two_agents_cannot_share_one_task` drives the full
+sequence from two identities: the second run loses, is told who holds it, sees the holding in
+`status`, is denied the guarded registry, cannot release a lease it does not hold, and the holder
+can. `check_guard_covers_every_write_shape` drives nine payloads through the real hook — `Edit`,
+`Write`, `NotebookEdit`, an unguarded file, `git commit`, `git -C <dir> commit`,
+`cd <dir> && git commit`, `git log --grep=commit`, and malformed input — with and without the lease.
+
+Planting the first defect took two mutations, not one, and that is worth recording: breaking only
+`acquire`'s expiry check still refuses the steal, because `_steal_expired` re-reads the expiry
+**inside** the critical section. The exclusion has two independent layers. The single-point fixture
+was MISSED, which is how that was discovered.
+
+### `check_merge_releases_only_its_key`
+
+`merge --key` must release that lease and leave the others held. It was verified by reading the
+code, and every defect the first audit found was in something verified by reading.
+
+### `status` on a large repository: 3.2 s → 0.5 s
+
+`check` resolved guarded and claim-tag patterns by walking the whole tree **once per pattern** —
+five patterns over a 20 000-file repository is five full walks, measured at 3.2 s for a single
+`status`, which is a `SessionStart` hook. It now walks once, and uses git's own index where there is
+one, so `.gitignore` is honoured for free. Same output, six times faster.
+
+### `check_commands_work_without_the_family_installed`
+
+Runs the commands with `HOME` redirected at an empty directory — the state of every CI runner, and
+where the task-pipeline ordering defect was obvious while this development machine could not see it.
+The check proves its own isolation on a healthy project before asserting on a broken one, because a
+probe that cannot fail is not a probe.
+
+### The self-test: 6 min → 2.8 min
+
+Each fixture now runs as its own process, eight at a time. It was a loop that reassigned module
+globals and called `main()` in-band, once per fixture; at 32 fixtures it had already blown a
+ten-minute command budget, and a suite people stop running is a suite that does not exist. The
+subprocess also removes the global-state reset that made parallelism impossible.
+
+### Decisions recorded rather than deferred again
+
+**`settleSeconds` stays.** It is the adapter contract's extension point for a store whose writes are
+not immediately readable; removing it would fail every config that carries one to buy nothing.
+Written into `references/adapter-contract.md`, where the next reader will look.
+
+**Blockers stay gone.** The concept needs a writer, a reader and a place on the board before the
+word earns a document.
+
+**Guard latency is fine:** 130–220 ms per guarded edit with no run id in the environment, against a
+`PreToolUse` budget of 20 s. Measured, recorded, no change.
+
+### Also
+
+`actions/checkout@v5`, `actions/setup-node@v5`, `actions/setup-python@v6` — the v4 pins were being
+forced onto Node 24 by the runner and annotated every release.
+
+`merge` also gained a preflight it was missing. A merge commit is authorship, so it needs a real
+git identity — unlike a lease object, which is plumbing and is written with a synthetic one on
+purpose. Without one the merge started, git refused at the commit, and the abort path ran: it
+recovers, and it is still not what a command whose whole doctrine is *every check before anything
+is touched* promises. Found by CI, because a runner has no global `.gitconfig` and this machine
+does — the same blind spot, twice in one day.
+
+The validator now runs 44 checks and plants and catches 37 distinct defects.
+
+## v1.7.1
+
+**A second audit, along a different axis: not whether the tool keeps its promises, but whether an
+agent reading this skill can follow it and get a correct result.** The scenarios were executed, not
+imagined — cold start, the whole adoption chain, the per-task cycle, two agents contending for one
+task, every hook with a realistic payload, and the edges (no git repository, uninitialised project,
+absolute paths, `git -C <dir> commit`). The coordination core came through clean. What did not was
+everything the agent *reads*.
+
+### The documents the tool generates were two versions behind the doctrine it teaches
+
+`setup` writes the snapshot every agent is told to read first — *"it states how documentation and
+coordination work here"* — and `scaffold` seeds `AGENTS.md`. Neither mentioned a branch or `merge`
+even once. Both prescribed a cycle ending in `release`, and the snapshot stated *"the claim tag in
+git is written through"* as an unconditional fact, which has been false on any branch since 1.4.0 —
+the branch being where the doctrine says the work belongs.
+
+So an agent doing exactly what the skill instructs — trust the generated snapshot — got the
+workflow from two releases ago. Regenerating did not help: the generator was what was stale. Both
+now carry the branch rule, `merge --key`, and this project's integration branch by name.
+
+`AGENTS.md` stopped restating the cycle altogether. It is seeded once and **never overwritten**, so
+a copy of the protocol there is frozen on the day the project was created while the tool moves on —
+and every project scaffolded before today would have kept the old one forever. It now points at the
+snapshot, which is regenerable and which `check` fails on when it goes stale. One fact, one home.
+
+### `check` blessed a project an agent cannot work in
+
+A configuration declaring `idRegisters` on a backend whose `reserve` always raises passed as
+`setup healthy`. `check`'s own promise is that it refuses a rule pointing at what is not there, and
+a register nobody can allocate from is exactly that — while the snapshot it generates instructs
+every agent to run `agent_sync.py reserve DEC`, which cannot succeed there. It is now a problem,
+named with both ways out.
+
+### The slash command offered a verb the CLI does not have
+
+`argument-hint` advertised `claim <KEY>` and the README showed `/agent-sync claim ASC-072`. The
+command is `acquire`; `claim` is an `invalid choice`. First thing an agent reads, first thing it
+types.
+
+### `$SKILL_DIR` was used in every example and defined nowhere
+
+Six invocations tell the agent to run `python3 "$SKILL_DIR/scripts/agent_sync.py"`, and the only
+explanation was the prose *"this skill's own directory"*. Nothing gave a value. The Cursor rule
+names a concrete path; the skill body now names both — `${CLAUDE_PLUGIN_ROOT}/skills/agent-sync`
+and `~/.agents/skills/agent-sync`.
+
+### What the audit found working
+
+Worth recording, because a report that only lists faults says nothing about the rest: two agents
+contending for one task behave correctly end to end — the second loses, sees who holds it and in
+which repository, is denied the guarded file, and cannot release a lease it does not hold. The
+guard denies `Edit`, `Write`, `NotebookEdit` and absolute paths, and blocks `git commit`,
+`git -C <dir> commit` and `cd <dir> && git commit` when a guarded file is staged, while letting
+`git log --grep=commit` and malformed JSON through. `SessionStart` stamps the identity and prints
+the awareness block; `SessionEnd` releases. The adoption chain works with and without a pre-existing
+`docs/`. An uninitialised project and a non-git directory both answer with the next action and a
+non-zero exit.
+
+### New checks
+
+`check_every_advertised_verb_exists`, `check_generated_docs_carry_current_doctrine`,
+`check_registers_need_a_backend_that_can_reserve`, `check_skill_gives_a_resolvable_script_path` —
+with four more self-test fixtures. The validator now plants and catches 32 distinct defects.
+
 ## v1.7.0
 
 **Observability, honest degradation, and the removal of things that were never load-bearing.**

package/README.md

@@ -225,8 +225,9 @@ action:
 
 ## Everyday use
 
-In an agent session you use the slash command (`/agent-sync claim ASC-072`); the same
-commands run directly against the coordinator script, which is what the hooks and CI do:
+In an agent session you use the slash command (`/agent-sync acquire ASC-072` — the verb is
+`acquire`, the same one the CLI takes); the same commands run directly against the
+coordinator script, which is what the hooks and CI do:
 
 ```bash
 python3 "$SKILL_DIR/scripts/agent_sync.py" <command>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/agent-sync",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Let concurrent coding agents share one project without colliding \u2014 leases with TTL, race-free id reservation, a run journal and a generated board, over a pluggable knowledge cloud.",
   "bin": {
     "agent-sync": "bin/agent-sync.js"

package/plugins/agent-sync/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-sync",
   "displayName": "Agent Sync",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Coordination layer for multi-agent repositories \u2014 leases with TTL, race-free ID reservation, a run journal, a cross-repo signal feed and a generated board, over a pluggable knowledge cloud.",
   "author": {
     "name": "ssheleg",

package/plugins/agent-sync/commands/agent-sync.md

@@ -1,6 +1,6 @@
 ---
-description: Coordinate concurrent agents — initialise the shared knowledge store, check status, claim a task, reserve an id, or regenerate the board.
-argument-hint: "[init|status|claim <KEY>|release <KEY>|reserve <REG>|board|finish]"
+description: Coordinate concurrent agents — initialise the shared knowledge store, check status, take a task, reserve an id, or regenerate the board.
+argument-hint: "[init|status|check|acquire <KEY>|release <KEY>|reserve <REG>|board|merge|finish]"
 ---
 
 Invoke the `agent-sync` skill.

package/plugins/agent-sync/skills/agent-sync/SKILL.md

@@ -4,7 +4,7 @@ description: "Use when several coding agents work one repository at the same tim
 compatibility: "Requires the task-pipeline skill for its stages (npx sshlg-skills install). Needs python3 3.9+ (stdlib only, HTTP included - nothing to pip install) and bash for the hooks. The knowledge backend is configured per project; with none configured it degrades to git-file leases. Enforcement hooks are Claude Code only - on other agents the same checks run as a self-check."
 license: MIT
 metadata:
-  version: "1.7.0"
+  version: "1.8.0"
   author: ssheleg
 ---
 
@@ -113,10 +113,9 @@ storage question gets asked and answered, once, and written down.
    - or local files (`fs`) — no credentials, and no visibility to an agent on another
      machine: no shared awareness, no cross-repo signals, no shared board.
 
-   The lease is decided separately by `leaseBackend` — `git` for cross-machine exclusion,
-   `local` otherwise — and **`gated` follows that choice, never the record plane**. `fs`
-   with a local lock is still real exclusion between the agents on this machine; `outline`
-   with a local lock is *not* exclusion across them. Report the one you actually have.
+   The lease is decided separately by `leaseBackend` (trap 2), and **`gated` follows that
+   choice, never the record plane**. Report the guarantee you actually have, not the
+   stronger one the record plane suggests.
 2. **If cloud: the instance URL.** The URL is configuration, not a secret, so you
    may write it. The **token is not** — you never ask for it in chat, never read it
    back, and never place it yourself.
@@ -144,9 +143,9 @@ the file is their step, and the design depends on it staying theirs.
 python3 "$SKILL_DIR/scripts/agent_sync.py" status
 ```
 
-Idempotent. Inspects, repairs what is missing, prints a status block, names exactly
-ONE next action — and carries `check`'s verdict, so the command every session runs and
-the command that validates the setup cannot give two answers about one project.
+Idempotent. Inspects, repairs, reports, names exactly ONE next action — and carries
+`check`'s verdict, so the command every session runs and the one that validates the
+setup cannot give two answers about one project.
 
 **Read the two awareness sections it prints — they are the point, not decoration.**
 
@@ -196,7 +195,9 @@ npx sshlg-skills install
 | `scaffold [--full]` | Create only what is missing, never a line over anything that exists. `--full` also seeds the question register, the index, the dependency board, the data model with its entity register, and the docs gate |
 | `finish [--gates]` | Is the **work** finished — every repository clean, pushed and pointed at, no lease left held. `check` answers whether the project is wired correctly; this answers whether you are done |
 
-`$SKILL_DIR` is this skill's own directory. Every command reads
+`$SKILL_DIR` is this skill's own directory: `${CLAUDE_PLUGIN_ROOT}/skills/agent-sync`
+under the Claude Code plugin, `~/.agents/skills/agent-sync` elsewhere. Resolve it once
+per session and reuse it — do not guess a path. Every command reads
 `.claude/agent-sync.json` from the project root and needs no arguments beyond those
 listed.
 
@@ -321,16 +322,10 @@ Two files, and the split between them is the whole security model.
 **`.claude/agent-sync.json`** — *shape*, committed: which backend, TTLs, which files
 are guarded, which registers exist, which gates to run.
 
-**`.env.agent-sync`** — *identity*, created by `init`, mode 600, gitignored:
-
-```
-AGENT_SYNC_BACKEND=outline
-AGENT_SYNC_OUTLINE_URL=https://<instance>
-AGENT_SYNC_OUTLINE_TOKEN=          # the operator fills this line, nobody else
-AGENT_SYNC_OUTLINE_COLLECTION=     # printed by `bootstrap`
-```
-
-Load it before running agents:
+**`.env.agent-sync`** — *identity*, written by `init` with the keys already in it, mode
+600, gitignored. The operator fills the token line and nobody else; `bootstrap` prints
+the collection id to paste beside it. Found here, or in a superproject, or wherever
+`AGENT_SYNC_ENV` points — `check` prints which. Load it before running agents:
 
 ```bash
 set -a && . ./.env.agent-sync && set +a

package/plugins/agent-sync/skills/agent-sync/references/adapter-contract.md

@@ -1,3 +1,11 @@
+> **`settleSeconds` is this contract's extension point, and nothing shipped reads it.**
+> It exists for an adapter whose writes are not immediately visible to a subsequent read —
+> a store with an asynchronous index, where a reader must wait before replaying. Neither
+> `outline` nor `fs` needs it, so `check` says plainly that setting it does nothing here.
+> It is kept rather than removed because deleting it would make every config carrying one
+> fail validation to buy nothing, and because an adapter that needs it has nowhere else to
+> ask. If you add a backend that waits, this is the knob; if you do not, ignore it.
+
 # Adapter contract
 
 **Read this when** adding a knowledge backend, auditing one, or deciding whether a

package/plugins/agent-sync/skills/agent-sync/scripts/agent_sync.py

@@ -33,7 +33,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
-VERSION = "1.7.0"
+VERSION = "1.8.0"
 
 CONFIG_PATH = Path(".claude/agent-sync.json")
 ENV_FILE = Path(".env.agent-sync")
@@ -231,18 +231,41 @@ def matches_glob(rel: str, pattern: str) -> bool:
     return bool(rx.match(rel.replace(os.sep, "/")))
 
 
-def glob_files(root: Path, pattern: str) -> list[Path]:
-    """Every existing file the pattern covers, by the same rule the guard applies."""
+def _tracked_files(root: Path) -> list[str]:
+    """Every candidate path in the repository, walked ONCE.
+
+    `glob_files` used to walk the whole tree per pattern, and `check` calls it for every
+    guarded pattern and every claim-tag pattern — five patterns over a 20 000-file
+    repository is five full walks. Measured at ~3 s for a single `status`, which since
+    1.7.0 runs `check`, and `status` is a `SessionStart` hook. Git's own index is used
+    where it exists, because it already excludes everything `.gitignore` does; the walk
+    is the fallback for files not yet tracked.
+    """
+    listed = git("ls-files", "--cached", "--others", "--exclude-standard", cwd=root)
+    if listed:
+        return listed.split("\n")
     skip = {".git", "node_modules", STATE_DIR.name}
-    out: list[Path] = []
+    out: list[str] = []
     for path in root.rglob("*"):
-        if skip & set(path.relative_to(root).parts):
+        rel = path.relative_to(root)
+        if skip & set(rel.parts):
             continue
-        if path.is_file() and matches_glob(str(path.relative_to(root)), pattern):
-            out.append(path)
+        if path.is_file():
+            out.append(str(rel))
     return out
 
 
+def glob_files(root: Path, pattern: str) -> list[Path]:
+    """Every existing file the pattern covers, by the same rule the guard applies."""
+    return [root / rel for rel in _tracked_files(root) if matches_glob(rel, pattern)]
+
+
+def glob_files_many(root: Path, patterns: list[str]) -> dict[str, list[Path]]:
+    """The same answer for several patterns, from one walk."""
+    files = _tracked_files(root)
+    return {p: [root / rel for rel in files if matches_glob(rel, p)] for p in patterns}
+
+
 # --------------------------------------------------------------------------- config
 
 def find_env_file(root: Path) -> Path | None:
@@ -2094,19 +2117,29 @@ class Sync:
             "## The cycle, per task",
             "",
             "```",
-            "status      → who else is working, and what changed while you were away",
+            "merges      → what landed while you were away",
+            "status      → who else is working, and what changed since you last looked",
             "reconcile   → resolve every divergence BEFORE writing code",
-            "acquire ID  → take the lease; the claim tag in git is written through",
+            "branch      → work happens on one; the integration branch is somebody",
+            "              else's stable base",
+            "acquire ID  → take the lease. On the integration branch the claim tag is",
+            "              written through to git; on any other branch the holder stays",
+            "              in the coordination plane, where `status` shows it to everyone",
             "   … work …",
             "record      → what you ACTUALLY built, with the decision id and files",
             "   … update the git documents in the same change …",
             "reconcile   → check both sides again",
             "board       → regenerate the shared view",
-            "release ID  → on every path, including failure",
+            "merge --key → land the branch: conflicts checked first, the merge recorded,",
+            "              that lease released. Without a branch, `release ID` by hand",
+            "              — on every path, including failure",
             "```",
             "",
+            f"This project's integration branch is `{self.integration_branch}`.",
+            "",
             "Full doctrine ships with the skill: `references/two-sources.md`,",
-            "`references/lease-protocol.md`, `references/pipeline-binding.md`.",
+            "`references/lease-protocol.md`, `references/branching.md`,",
+            "`references/roadmap.md`, `references/pipeline-binding.md`.",
         ]
         return "\n".join(L) + "\n"
 
@@ -2889,31 +2922,24 @@ annotate the old entry's status line. The body of the old entry stays as history
 
 AGENTS_SEED = """# AGENTS.md — working protocol
 
-**Read [`{snapshot}`]({snapshot}) first.** It is generated from the live configuration and
-states how documentation and coordination work here: which registers exist, which files
-need a lease, which gates run, what is written where, and what is never deleted.
-
-## Before you write anything
-
-Several agents may work this repository at once.
+**Read [`{snapshot}`]({snapshot}) first, and follow the cycle it states.** That file is
+generated from the live configuration: which registers exist, which files need a lease,
+which gates run, what is written where, what is never deleted, and the order to do it in.
 
-1. `agent-sync status` — who else is working, and what changed while you were away.
-2. `agent-sync reconcile` — the git documents say how it *should* be, the as-built record
-   says how it *is*. Resolve every divergence **before** writing code.
-3. `agent-sync acquire <TASK-ID>` — the guarded registers refuse an unleased write.
-4. Reserve any new id with `agent-sync reserve <REGISTER>` before writing it.
+This file deliberately does **not** restate that cycle. It is seeded once and never
+overwritten, so a copy of the protocol here would be frozen on the day the project was
+created while the tool moved on — and the two would disagree in front of an agent with no
+way to tell which is current. One fact, one home; the home is the generated snapshot,
+because it can be regenerated and `agent-sync check` fails when it goes stale.
 
-## When you finish
+## The three that are true in every project
 
-1. `agent-sync record` — what you actually built, with the decision id and the files.
-2. Update the git documents in the **same** change.
-3. `agent-sync reconcile` again, then `agent-sync board`.
-4. `agent-sync release <TASK-ID>` — on every path, including failure.
-
-## The one rule that matters most
-
-**No decision lives only in chat.** Record it in the decision register, propagate it to
-every document it affects, and commit referencing the id.
+1. **Several agents may work this repository at once.** `agent-sync status` before you
+   start: who holds what, and what changed since you last looked.
+2. **Work on a branch, and land it with `agent-sync merge`.** The integration branch is
+   somebody else's stable base — nothing about work in flight is committed there.
+3. **No decision lives only in chat.** Record it in the decision register, propagate it to
+   every document it affects, and commit referencing the id.
 """
 
 
@@ -3119,8 +3145,21 @@ def check_setup(root: Path) -> tuple[list[str], list[str], list[str]]:
     for k in sorted(set(cfg) - CONFIG_KEYS):
         problems.append(f"config key '{k}' is not in the schema — it will be ignored")
 
-    # Registers must exist AND their allocation pattern must actually match.
+    # Registers must exist, their allocation pattern must match — and the backend must be
+    # able to hand an id out at all. A register declared on a plane whose `reserve` always
+    # raises is a rule that protects nothing, which is the exact thing `check` promises to
+    # refuse: the generated snapshot then instructs every agent to run `reserve <REG>`, and
+    # the command cannot succeed in that project.
     regs = cfg.get("idRegisters") or {}
+    if regs:
+        backend = os.environ.get("AGENT_SYNC_BACKEND") or cfg.get("backend") or "fs"
+        probe = make_adapter(cfg, root)
+        if not probe.is_lease_authority:
+            problems.append(
+                f"{len(regs)} id register(s) declared, but backend '{probe.name}' cannot "
+                f"reserve ids (atomicAppend is false){' — the configured backend is ' + backend + ' and it is not reachable, so runs degrade to fs' if backend != probe.name else ''}. "
+                "`reserve` fails every time here; either configure a backend that can "
+                "allocate, or remove the registers and allocate them in the parent repository")
     for reg, spec in sorted(regs.items()):
         f = root / spec.get("file", "")
         if not f.exists():
@@ -3139,9 +3178,11 @@ def check_setup(root: Path) -> tuple[list[str], list[str], list[str]]:
             ok.append(f"register {reg} allocates from {spec['file']} ({reg}-{m.group(1)})")
 
     # A guard glob that matches nothing protects nothing. Resolved by the same function
-    # the guard itself applies, so the two commands cannot disagree about one pattern.
+    # the guard itself applies, so the two commands cannot disagree about one pattern —
+    # and from one walk of the repository, not one per pattern.
+    guard_hits = glob_files_many(root, list(cfg.get("guardedFiles") or []))
     for pattern in (cfg.get("guardedFiles") or []):
-        hits = glob_files(root, pattern)
+        hits = guard_hits.get(pattern) or []
         if not hits:
             problems.append(f"guarded pattern '{pattern}' matches no file — it guards nothing")
     if cfg.get("guardedFiles"):
@@ -3149,8 +3190,9 @@ def check_setup(root: Path) -> tuple[list[str], list[str], list[str]]:
     else:
         warn.append("no guarded files — nothing requires a lease in this repository")
 
+    claim_hits = glob_files_many(root, list(cfg.get("claimTags") or {}))
     for pattern, spec in (cfg.get("claimTags") or {}).items():
-        files = glob_files(root, pattern)
+        files = claim_hits.get(pattern) or []
         if not files:
             problems.append(f"claimTags pattern '{pattern}' matches no file")
             continue
@@ -3381,6 +3423,21 @@ def cmd_merge(args: argparse.Namespace) -> int:
         raise Fail(f"working tree is not clean ({len(dirty)} path(s)) — commit or stash first; "
                    "a merge cannot tell your uncommitted work from the branch's")
 
+    # A merge commit is authorship, so it needs a real identity — unlike a lease object,
+    # which is plumbing and is written with a synthetic one on purpose. Checked HERE
+    # because everything in this command is checked before anything is touched: without
+    # it the merge starts, git refuses at the commit, and the abort path runs. That is
+    # recoverable and it is still not what this command promises. It is also the ordinary
+    # state of a CI runner and a fresh container, which is where it was found.
+    ident = subprocess.run(["git", "var", "GIT_COMMITTER_IDENT"],
+                           capture_output=True, text=True)
+    if ident.returncode != 0:
+        why = (ident.stderr or "").strip().splitlines()
+        raise Fail("git has no committer identity here, so the merge commit cannot be "
+                   "written. Set one and run this again — nothing was touched:\n"
+                   "  git config user.name '<you>' && git config user.email '<you@example>'"
+                   + (f"\n  ({why[-1]})" if why else ""))
+
     git("fetch", "--quiet", "origin", target)
     upstream = f"origin/{target}" if git("rev-parse", "--verify", "--quiet", f"origin/{target}") else target