@ssheleg/agent-sync 1.4.3 → 1.7.0

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.4.3"
+  version: "1.7.0"
   author: ssheleg
 ---
 
@@ -43,8 +43,8 @@ coordination plane, where `status` shows it to every agent without anyone fetchi
 branch. Committed to a branch, a claim is invisible until the merge and turns the shared
 roadmap into a file two branches both edit. Land work with `merge`: conflicts computed by
 `git merge-tree` **before anything is touched**, named and refused if any, the merge
-recorded in `docs/MERGES.md` (recent days in full, older compacted on write), the lease
-released. `merges` tells the next agent what landed while it was away. **Read
+recorded in `docs/MERGES.md` (recent days in full, older compacted on write), the `--key`
+lease released. `merges` tells the next agent what landed while it was away. **Read
 `references/branching.md`** before merging.
 
 **3. Hooks exist only in Claude Code.** Elsewhere nothing blocks a guarded edit: run
@@ -97,10 +97,8 @@ python3 "$SKILL_DIR/scripts/agent_sync.py" adopt
 Confirm the registers and guarded files with the operator first: a register pointed at the
 wrong file makes every later check confidently wrong, and a guarded list that misses a
 shared file leaves the one place collisions happen unprotected. In a submodule it declares
-no registers: decisions belong to the parent repository.
-
-Then: `init` → paste the approved config → `reconcile --set-baseline` → `setup` →
-commit the snapshot and link it from the project's agent instructions.
+no registers: decisions belong to the parent repository. Then take the chain above from
+`init`.
 
 ## First command in a project: `init`
 
@@ -147,7 +145,8 @@ python3 "$SKILL_DIR/scripts/agent_sync.py" status
 ```
 
 Idempotent. Inspects, repairs what is missing, prints a status block, names exactly
-ONE next action.
+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.
 
 **Read the two awareness sections it prints — they are the point, not decoration.**
 
@@ -191,7 +190,7 @@ npx sshlg-skills install
 | `whoami` | Print this run's id and its held leases |
 | `setup` | Write the generated snapshot of how **this** project is wired, for agents to read |
 | `adopt` | Inspect an existing project and **propose** a config — writes nothing |
-| `merge` | Land this branch: conflicts checked **before** anything is touched, merge log written, lease released. `--key`, `--summary`, `--dry-run`, `--push` |
+| `merge` | Land this branch: local target fast-forwarded, conflicts checked **before** anything is touched, merge log written, the `--key` lease released. `--summary`, `--dry-run`, `--push` |
 | `merges` | What landed while you were on your branch. `--all` includes the compacted tail |
 | `check` | Validate the whole setup end to end. Non-zero when it is not healthy |
 | `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 |
@@ -214,10 +213,8 @@ shared.
 
 The third matters because a plain shell command has no session id and a hook does. So
 `SessionStart` stamps `.agent-sync/sessions/<CLI pid>` with the session it knows, and a later
-command finds itself by walking its own process ancestry to a stamped pid — exact, and
-deliberately not command-line parsing: the throwaway shell every tool call runs in carries
-claude paths in its argv, so every heuristic aimed at the binary matched it instead. Stamps
-are removed when their process is gone.
+command finds itself by walking its own process ancestry to a stamped pid. Why that and not
+command-line parsing: `references/earned-rules.md`.
 
 When none of the four can be established the run says so — *"this identity is shared with any other
 session in this checkout"* — rather than presenting a shared entry as separation.
@@ -246,8 +243,11 @@ The config lists registry files several agents write. Before editing one:
 python3 "$SKILL_DIR/scripts/agent_sync.py" guard docs/DECISIONS.md
 ```
 
-Exit 2 means another run holds it. Do not edit anyway, and do not "just fix one line" —
-a clobbered decision looks exactly like a decision.
+**Exit 2 is about *this run*: it holds no lease** — not that somebody else holds that
+file. One lease covers every guarded file; hold one or write none. A denial names the
+other run **and its key**, because "r-x holds a lease" beside a path gets repeated as
+"r-x holds this file". Do not edit anyway, and do not "just fix one line" — a clobbered
+decision looks exactly like a decision.
 
 Claude Code's `PreToolUse` hook runs this for you. Elsewhere nothing does.
 
@@ -260,9 +260,9 @@ both use it.
 python3 "$SKILL_DIR/scripts/agent_sync.py" reserve DEC   # → DEC-0216
 ```
 
-Allocation is positional over the log, so every agent computes the same answer. Reserve
-and not write it to git? `release-id` it — otherwise the number is a hole the board
-reports as a leak, and nobody can tell a hole from work on a branch.
+Allocation is positional over the **merged** log — every shard, never just this run's —
+so every agent computes the same answer. Reserved and not written to git? `release-id`
+it, or the number is a hole the board reports as a leak.
 
 ## Nothing in a log is ever edited or deleted
 
@@ -304,7 +304,7 @@ which side a document belongs on.
 This skill supplies stages; it does not define them. Stage names are
 `task-pipeline`'s own.
 
-Four of the eleven stages carry a rule the others do not, and each is about ordering:
+Five of the eleven stages carry a rule the others do not, and each is about ordering:
 **0** `acquire` before the brief is committed; **1** `reconcile` and resolve every
 divergence before writing code; **3** `reserve` every id before it reaches git; **9**
 `record`, `signal`, `reconcile`, `board` — the main write point. **10** ends the run:
@@ -368,12 +368,6 @@ The mirror is a **rendering** of git, stamped with the source commit. It has no
 authority. When its stamp and `HEAD` disagree, the board gate fails — that is
 drift, not a formatting problem.
 
-## Two rules, and the failures that taught them
-
-Identity comes before coordination: a lease is only a lease if two agents get two identities. A
-submodule commit is unfinished until its parent points at it. Both:
-[`references/earned-rules.md`](references/earned-rules.md).
-
 ## Non-negotiables
 
 - Append, read back, then act. Never rewrite a coordination document.
@@ -399,6 +393,7 @@ Each file is loaded on its own trigger, not by default.
 | `references/two-sources.md` | before the first reconcile, or when deciding where a document belongs |
 | `references/roadmap.md` | configuring `claimTags`, taking or closing a task, or re-planning a board |
 | `references/branching.md` | starting work that will produce commits, merging a branch, or asking what landed while you were away |
+| `references/earned-rules.md` | asking why identity resolves the way it does, or why `finish` exists |
 
 If this copy arrived without `references/`, fetch them from
 `https://raw.githubusercontent.com/ssheleg/agent-sync/main/plugins/agent-sync/skills/agent-sync/references/<file>`.

package/plugins/agent-sync/skills/agent-sync/references/branching.md

@@ -45,8 +45,15 @@ In order, and every check before anything is touched:
 
 1. **Refuses a detached HEAD, the integration branch itself, and a dirty tree.** A merge
    cannot tell uncommitted work from the branch's own commits.
-2. **Fetches the integration branch** and reports how far it moved since the branch
-   started — the number that predicts how stale the work is.
+2. **Fetches the integration branch and fast-forwards the local one to it**, so the
+   preflight and the merge share a base, then reports how far it moved since the branch
+   started. Until 1.6.0 they did not share one: conflicts and the diff were measured
+   against `origin/<target>` while the merge went into a local `<target>` nothing
+   advanced — so `merge` printed the staleness it had just measured, printed `✓ merged`,
+   wrote the log entry and released the lease, and the push was rejected. The work had not
+   landed, the log said it had, and the task was free for somebody else. A local branch
+   that has *diverged* (commits on both sides) cannot be fast-forwarded and is refused
+   with both counts.
 3. **Computes conflicts with `git merge-tree`**, in memory. A merge that starts and then
    aborts leaves the operator in a repository they did not ask for. On conflict it names
    the files, changes nothing, and exits non-zero: resolve in your own branch, where the
@@ -55,8 +62,14 @@ In order, and every check before anything is touched:
    the same files, they merge into what is about to land.
 5. Merges `--no-ff`, so the branch stays visible in history.
 6. **Writes the merge log** and commits it.
-7. **Releases every lease this run holds.** A run that ends holding one blocks the next
-   agent for the whole TTL.
+7. **Releases the lease named by `--key`.** Only that one: releasing every lease the run
+   holds is a different statement from the one this step makes, and it quietly frees work
+   that has not landed. Without `--key` there is nothing to name, so it releases what the
+   run holds and says so. A run that ends holding a lease blocks the next agent for the
+   whole TTL — so release, but release what you landed.
+
+The remote is `origin`, the conventional home of the integration branch. `leaseRemote` is a
+different setting for a different job: where the lease refs live.
 
 `--dry-run` stops after step 4. `--push` pushes the integration branch afterwards;
 without it, `finish` is the next call — it checks every repository, not just this one.

package/plugins/agent-sync/skills/agent-sync/references/earned-rules.md

@@ -13,6 +13,15 @@ belonged to somebody else, and `release` would have taken it. The resolution ord
 `AGENT_SYNC_RUN_ID` · `CLAUDE_SESSION_ID` · the session that started this shell · shared, and where
 none can be established the run says so instead of presenting a shared entry as separation.
 
+The third position is the one that needs explaining, because the obvious implementation of it is
+wrong. A plain shell command carries no session id; a hook does. So `SessionStart` stamps
+`.agent-sync/sessions/<CLI pid>` with the session it knows, and any later command finds itself by
+walking its own **process ancestry** to a stamped pid, removing stamps whose process is gone. It is
+deliberately not command-line parsing: the throwaway shell every tool call runs in carries claude
+paths in its own `argv`, so every heuristic aimed at spotting the CLI binary matched that shell
+instead — and matching the wrong ancestor hands two sessions one identity, which is the failure
+above.
+
 **Work in a submodule is not finished until its parent says so.** A parent records each submodule as
 a pointer to one commit, and moving the submodule does not move the pointer. The work is committed,
 pushed, green in CI and marked done in its own roadmap — and a clone of the parent gets the commit

package/plugins/agent-sync/skills/agent-sync/references/hooks.md

@@ -46,7 +46,7 @@ The hook receives JSON on stdin with `session_id`, `prompt_id`, `transcript_path
         "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh" }] }
     ],
     "PreToolUse": [
-      { "matcher": "Edit|Write|MultiEdit",
+      { "matcher": "Edit|Write|MultiEdit|NotebookEdit",
         "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/guard.sh" }] },
       { "matcher": "Bash", "if": "Bash(git commit *)",
         "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/guard.sh" }] }
@@ -66,8 +66,8 @@ The hook receives JSON on stdin with `session_id`, `prompt_id`, `transcript_path
 |---|---|
 | `session-start.sh` | Register the run, print the board summary and the one next action |
 | `guard.sh` | Deny an edit to a `guardedFiles[]` path, or a commit staging one, without a live lease |
-| `renew.sh` | Renew the lease, throttled to `renewIntervalSeconds` — a no-op most calls |
-| `session-end.sh` | Release every lease, flush the journal, close the run |
+| `renew.sh` | Renew the lease — moves the timestamp expiry is computed from, throttled to `renewIntervalSeconds`, a no-op most calls |
+| `session-end.sh` | Release every lease this run holds. That is all it does — it writes no journal entry and closes nothing else |
 
 ## Performance
 
@@ -82,7 +82,7 @@ throttle is broken — fix the throttle rather than removing the hook.
 |---|---|
 | Guarded edits go through | The guard crashed. Any exit code other than 2 is non-blocking. Run it by hand with a sample stdin payload |
 | Everything is denied | No config, or no lease. `status` says which |
-| Session start is slow | The backend is unreachable; it should time out at 5 s and degrade, not hang |
+| Session start is slow | The backend is unreachable. Each hook is capped twice — `run_limited 10` inside the script, and the `timeout` in `hooks.json` (15–20 s) — so it degrades rather than hanging |
 | Renew floods the log | The throttle file is not being written — check its path is writable |
 
 Run the guard directly to see what it decides:

package/plugins/agent-sync/skills/agent-sync/references/lease-protocol.md

@@ -42,20 +42,37 @@ tests for the exact bullet you emitted skips malformed lines *before* they can b
 counted, so the ratio reads 0% while nothing parses — the guard and the counter both
 go quiet at once. This is not hypothetical; it is how the bug above stayed invisible.
 
-**An unreadable log is not a lost race.** When more than 2% of a log fails to parse,
-`acquire` **raises** instead of reporting `lost`, and the board gate fails. Reporting
-a lost race would name a holder who does not exist and send the caller looking for
-them.
+**An unreadable log is not a lost race.** Past 2% unparseable, **every command that
+replays a log refuses it** — the read itself fails, so `status`, `board`, `check`,
+`reconcile` and `reserve` stop and name the ratio instead of acting on a partial
+history. Replaying it would report holders who do not exist and silence where the real
+ones are, and both of those look exactly like an answer.
+
+`acquire` is not in that list, and the reason is the design: the lease is decided by the
+lock file or the git ref, never by the log, so a corrupt log cannot make a lease look
+lost. Until 1.6.0 the threshold was a constant nothing read — declared, quoted in three
+documents, and implemented nowhere except a warning line on the board that returned zero.
 
 ## Acquiring — the third design, and the first that is true
 
 ```
-1. reap     if .agent-sync/leases/<K>.lock exists and is expired, remove it
-2. create   os.open(lock, O_CREAT | O_EXCL) — this is the decision, and it is atomic
-3. lost     FileExistsError -> read the holder out of the file and report it
-4. won      write {run, ts, ttl, repo}; publish op=acquire to the plane for visibility
+1. free     os.open(lock, O_CREAT | O_EXCL) — this is the decision, and it is atomic
+2. held     live holder -> report it; this run -> already ours
+3. expired  take the steal section, re-read expiry inside it, then reap and create
+4. lost     FileExistsError, or the section is held -> read the holder and report it
+5. won      write {run, ts, ttl, repo}; publish op=acquire to the plane for visibility
 ```
 
+**Step 3 is one critical section, not two calls.** `unlink` followed by `O_EXCL create`
+leaves a gap, and a second stealer that has already read the lock as expired removes the
+lock the first one just created — both then hold what each believes is exclusive. Twelve
+racing processes never showed it; a 300 ms delay injected between the two calls produced
+two winners out of two, and in production that delay is an ordinary scheduler hiccup. So
+`<K>.lock.steal` is created with `O_EXCL`, the expiry is re-read **inside** it (the holder
+may have renewed, or another stealer may have finished), and it carries its own 30-second
+abandonment grace — without one, a crash between two filesystem calls would cost the key
+until somebody deleted a file nobody documents.
+
 **Publishing is not the decision.** A failure to reach the knowledge base costs
 visibility, never correctness: the lock is already held. So the append is wrapped and
 its failure reported, not raised.
@@ -86,16 +103,29 @@ The tool reports which guarantee is in force; it never implies the stronger one.
 
 ## Expiry and stealing
 
-A lock is expired when `now > ts + ttl` for the timestamp inside it, refreshed by
-`renew`.
+A lock is expired when `now > ts + ttl` for the timestamp inside it.
+
+**`renew` moves that timestamp, in the plane that arbitrates the lease** — it rewrites the
+lock file in `local` mode, and re-pushes the ref with `--force-with-lease` against the
+exact object it read in `git` mode. The `op=renew` line it also appends to the record plane
+is visibility, not renewal.
+
+That distinction is the whole of the bug fixed in 1.5.3: `renew` wrote *only* the record
+line. The lock's `ts` was written once, by `acquire`, so a run holding a lease lost it at
+TTL while still working — its own guard began denying it, and another run acquired the task
+it was in the middle of. Nothing reported it, because from the record plane's side the
+renewals were arriving exactly as scheduled. **A renewal that does not move the timestamp
+the expiry is computed from is not a renewal**, however faithfully it is logged.
 
 Default `ttl` is 2700 s (45 minutes). `renew` is emitted at most once per
 `renewIntervalSeconds` (default 300 s) — by the `PostToolUse` hook in Claude Code,
-and by the agent itself everywhere else.
+and by the agent itself everywhere else. A `renew` for a key this run does not hold
+refreshes nothing and says so.
 
-**Stealing an expired lease is the ordinary `acquire` path.** There is no force flag:
-the reap step removes an expired lock and the create proceeds. The steal is visible on
-the plane with both run ids, so an operator can see that it happened and when.
+**Stealing an expired lease is the ordinary `acquire` path.** There is no force flag: the
+steal section above removes an expired lock and creates the new one, as one operation. The
+steal is visible on the plane with both run ids, so an operator can see that it happened
+and when.
 
 ## Releasing
 
@@ -120,7 +150,14 @@ Then, replaying in order and maintaining a free list:
 - `op=reserve key=DEC` takes the free-list head if it is non-empty; otherwise it
   takes `base + (count of prior reserves not served from the free list)`.
 
-Every reader computes the same assignment for every reserve line, including its own.
+Every reader computes the same assignment for every reserve line, including its own —
+**and "the log" means every shard merged, never the one this run writes.** Reading only
+its own document is how `reserve` handed three runs `DEC-0007` three times (fixed in
+1.5.3): each replayed a log containing only its own lines, each seeded its own `base`
+from the register, and each was correct about a history nobody else shared. The failure
+is the same one that disqualified per-writer documents as a *lease* store, arriving in
+the allocator — so a `base` now only ever moves allocation **forward**, and two runs
+opening a register in the same minute cannot restart each other's count.
 
 **An id you reserved and did not write to git must be released** with
 `release_id`. An id that is reserved, unreleased and absent from git after its run
@@ -133,7 +170,7 @@ number, and silently handing it out again would produce two documents with one i
 | Fact | Home | Lifetime |
 |---|---|---|
 | Who holds this task **right now** | the lease log | ephemeral, TTL |
-| Who **owns** this task | the git claim tag (`[name]`, `todo (claimed: <role>)`) | durable |
+| Who **owns** this task | the git claim tag — `todo (claimed: r-7f3a91)`, the template from `claimTags.held` | durable |
 
 `acquire` writes the git tag through and `release` restores exactly what was there. The
 objection that once demoted this to a check — an unattended process rewriting a shared

package/plugins/agent-sync/skills/agent-sync/references/pipeline-binding.md

@@ -5,12 +5,29 @@
 `agent-sync` supplies stages; it does not define them. The stage names below are
 `task-pipeline`'s own — do not rename, renumber or fork them.
 
+## The numbers, once
+
+<!-- agent-sync:stages rules=0,1,3,9,10 wired=0,1,3,4,5,9,10 -->
+
+Two different questions, and answering them in one list is why three documents once gave
+three answers:
+
+- **Stages carrying a rule — 0, 1, 3, 9, 10.** Something must happen there or the run is
+  wrong, and each rule is about ordering. Quoted in `SKILL.md`.
+- **Stages wired into `pipeline.json` — 0, 1, 3, 4, 5, 9, 10.** The list above plus the two
+  where the journal has teeth (file ownership, submodule pointers). Quoted in the README.
+
+`SKILL.md` said "four of the eleven stages" and then listed five; the README named a third
+set; and this file called stage 1 *"nothing shared to coordinate"* — the stage `reconcile`
+belongs to. The marker above is the source, and the validator fails when a surface stops
+agreeing with it.
+
 ## Where it plugs in
 
 | Stage | Calls | Why there and not elsewhere |
 |---|---|---|
 | **0 Intake grill** | `status`, then `acquire <KEY>` | The cloud KB and the board join the harvest's source ledger. The lease is taken **before the brief is committed**, or two agents write two briefs for one task |
-| **1 Docs study** | — | External docs; nothing shared to coordinate |
+| **1 Docs study** | `reconcile`, then resolve every divergence | The git documents say how it *should* be, the as-built record how it *is*. Building on an unresolved divergence is writing code against a system that does not exist — and this is the last stage where that costs nothing |
 | **2 Brainstorm + decompose** | `journal` | Also warns when a live run holds an overlapping key — cheapest moment to find the overlap |
 | **3 Spec** | `reserve <REG>` per id | Ids must be reserved *before* they are written to git. Reading "next free id" is not reserving it |
 | **4 Plan** | `journal` with the plan's file ownership | Parallel groups that write one file are a merge conflict scheduled for later |
@@ -33,6 +50,9 @@ clause to each of those stages' existing `gate.check`:
     { "id": 0,  "state": "intake",      "name": "Intake grill",
       "skills": ["task-pipeline:grill", "agent-sync"],
       "gate": { "type": "manual", "check": "<the stage's own criteria> AND the lease for this task is held before the brief is committed" } },
+    { "id": 1,  "state": "docs-study",  "name": "Docs study",
+      "skills": ["task-pipeline:knowledge", "agent-sync"],
+      "gate": { "type": "manual", "check": "<the stage's own criteria> AND `reconcile` ran and every divergence it named is resolved or recorded as standing" } },
     { "id": 3,  "state": "spec",        "name": "Spec",
       "skills": ["task-pipeline:spec", "agent-sync"],
       "gate": { "type": "manual", "check": "<the stage's own criteria> AND every id the spec writes was reserved first" } },
@@ -65,7 +85,7 @@ that copied it silently dropped the stage's real gate: stage 9 lost the propagat
 sweep and the documentation gate, stage 10 lost the ladder walk and the evidence
 rule.
 
-Stages 1, 2, 6, 7 and 8 keep their own `skills[]`; `agent-sync` only journals there,
+Stages 2, 6, 7 and 8 keep their own `skills[]`; `agent-sync` only journals there,
 which needs no wiring.
 
 ## What must be guarded