@ssheleg/agent-sync 1.7.0 → 1.7.1

package/CHANGELOG.md

@@ -1,3 +1,68 @@
+## 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.7.1",
   "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.7.1",
   "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.7.1"
   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/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.7.1"
 
 CONFIG_PATH = Path(".claude/agent-sync.json")
 ENV_FILE = Path(".env.agent-sync")
@@ -2094,19 +2094,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 +2899,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 +3122,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():