@ssheleg/agent-sync 1.2.4 → 1.3.3

package/CHANGELOG.md

@@ -3,6 +3,129 @@
 All notable changes to this project are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 1.3.3 — 2026-07-29
+
+### Fixed
+- **The git lease backend could not take a lease on any machine without a git
+  identity.** Acquiring writes a lease object with `git commit-tree`, which
+  refuses when `user.email` is unset and cannot be auto-detected — CI runners,
+  containers, a freshly provisioned box. So the backend that advertises
+  *exclusive across machines* failed on precisely the machines least likely to
+  have a personal git config, with `could not create the lease object` and no
+  further detail. The lease object is plumbing, not authorship: it now carries a
+  fixed `agent-sync <agent-sync@localhost>` identity passed inline, so it never
+  depends on ambient config.
+- The same failure now reports git's own last line instead of swallowing it. The
+  bug survived six red CI runs because the message named a possible cause and
+  showed no evidence.
+
+## 1.3.2 — 2026-07-29
+
+Open-source hygiene — the repo is public and ships in the `sshlg-skills` bundle,
+so the files a first-time contributor looks for now exist.
+
+### Added
+- `CODE_OF_CONDUCT.md`, issue forms and a pull-request template. The forms ask
+  the question that actually matters for this project: **how many agents were
+  running, against what checkout** — a coordination bug reported without the
+  concurrency shape is not reproducible.
+- The PR checklist requires a negative self-test with any new validator guard —
+  plant the defect, watch the check fail, then trust the green.
+- README points at the code of conduct and at the family bundle.
+
+## 1.3.1 — 2026-07-29
+
+### The git lease was invisible to everything that reads a lease — fixed
+
+Found in production, blocking real work three times in one session. In `git` lease mode `acquire`
+won the lease by pushing `refs/agent-sync/leases/<key>` and stopped there, while `held()` — the one
+function behind `whoami`, `status` and the **PreToolUse guard** — read `.agent-sync/leases/*.lock`,
+which nothing in that path ever wrote. The result was the exact inversion of the tool's purpose:
+`acquire` printed *won*, `whoami` printed *holds: nothing*, and the guard **denied the run that held
+the lease**. Every guarded register was unwritable under the mode this tool recommends, and the only
+way past it was to bypass the guard — which is the behaviour the guard exists to prevent.
+
+The git ref remains the authority; it is what makes exclusion hold across machines. What was missing
+is that the winner now leaves a local note, so the local question — *does this run hold that key?* —
+is answered locally instead of putting a network round-trip in front of every Edit. `release`
+already removed that note, which is why only one half of the loop was ever written.
+
+**Why it shipped:** the lease-visibility assertion existed only for the local mode. `test/validate.py`
+now runs acquire → `whoami` → `guard` → release against **both** modes; against 1.3.0 it fails with
+the two symptoms above, which is the point of adding it.
+
+## 1.3.1 — 2026-07-29
+
+### Ignoring the state directory does nothing once git is tracking it
+
+Found in the project this plugin was built for: `.agent-sync/` was gitignored **and committed**,
+because the files went in before the rule existed. Consequences, all of them silent:
+
+- every tool call rewrites `last-renew`, so all three repositories were permanently dirty and no
+  run could ever report itself finished
+- `run-id` is the checkout's **agent identity**. Committed, it reaches every clone — two machines
+  would then coordinate as one run, which is the failure 1.3.0 fixed at the other end
+
+`init` now untracks the directory when it finds it tracked, and `check` reports it as a problem
+rather than passing a project whose state is versioned. Probed: a repository with a committed
+`.agent-sync/run-id` fails `check` with the exact removal command, and passes once it is untracked.
+
+## 1.3.0 — 2026-07-29
+
+### Two agents in one checkout were one identity — fixed
+
+Found in production, in the case this plugin exists for: **two Claude sessions working the same
+checkout shared a single run id**, so the lease could not separate them. A hook runs with
+`CLAUDE_SESSION_ID` in its environment and a plain shell command does not, and the marker file held
+one id per checkout — so the second session adopted whatever the first had stamped. Both acquired
+as one run, both were guarded as one run, and `release` would take a lease the caller never
+acquired. The failure is silent: `whoami` reports a lease, and it is somebody else's.
+
+- the marker is now a **map** keyed by session, and migrates the old single-value file into it
+- a plain shell has no session id, so the `SessionStart` hook stamps
+  `.agent-sync/sessions/<CLI pid>` with the session it *does* know, and later commands find
+  themselves by walking their own ancestry. Exact, and no command-line parsing: the throwaway
+  shell every tool call runs in carries claude paths in its argv and defeated every heuristic
+  aimed at the CLI binary
+- stale stamps are removed when their process is gone, so the directory cannot grow
+- where identity still cannot be established, the run says so rather than presenting a shared
+  entry as separation
+
+### `scaffold --full` — the architecture that keeps documentation linked, not merely present
+
+`scaffold` seeded a decision register and an agent protocol. That is enough to be coordinated and
+not enough to stay coherent: the things that rot are the links between documents, and nothing was
+seeding the pieces that hold them — a question register that resolves into decisions, an index
+nobody has to scan the register to use, one place for facts about two repositories, one definition
+per entity with a checkable address, **and a gate**, because each of those decays silently.
+
+`--full` adds `OPEN_QUESTIONS.md`, `INDEX.md`, `DEPENDENCIES.md`, `DATA_MODEL.md` (with the entity
+register and the one-definition rule) and `scripts/check-docs.sh`, which fails on: an id cited and
+never defined, a next-free-ID line that is not next, a relative link to a file that does not exist,
+a `#anchor` that does not exist in the file it points at, and a decision with no index row. All
+five probed against planted defects.
+
+**A fresh scaffold passes its own gate.** The first version did not — it counted the template block
+and the allocation line as real ids — and a project that starts red teaches everyone that the gate
+is noise.
+
+### `finish` — the gate expressions this plugin declares, executed
+
+`references/pipeline-binding.md` has always listed *submodule pointers current* and *every lease
+released* as gate expressions "verified by the coordinator, not by prose". Nothing ran them:
+`check` validates the **setup** — config, registers, credentials, snapshot — and never looks at the
+state of the repositories.
+
+`finish` answers the other question, *is the work finished*:
+
+- every submodule's recorded gitlink equals its HEAD. This is the failure it exists for and it is
+  invisible from either side alone: the submodule is pushed, its CI is green, its roadmap says
+  done, and a clone of the parent has the commit before the work
+- every repository — parent included — is clean and pushed, with a detached submodule accepted
+  only when its commit exists on some remote branch
+- no lease left held, because a run that ends holding one blocks the next agent for the whole TTL
+- `--gates` also runs the project's own declared gate commands
+
 ## 1.2.4 — 2026-07-29
 
 ### Fixed — the tool misreported its own version, and disagreed with itself about the lease

package/README.md

@@ -389,8 +389,13 @@ agent loads on their own trigger rather than by default:
 | [`two-sources.md`](plugins/agent-sync/skills/agent-sync/references/two-sources.md) | before the first reconcile, or when deciding where a document belongs |
 | [`roadmap.md`](plugins/agent-sync/skills/agent-sync/references/roadmap.md) | configuring `claimTags`, taking or closing a task, or re-planning a board |
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) and [CHANGELOG.md](CHANGELOG.md). Security
-reports: [SECURITY.md](SECURITY.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [CHANGELOG.md](CHANGELOG.md). Everyone
+taking part is expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+Security reports: [SECURITY.md](SECURITY.md).
+
+`agent-sync` also ships in the [sshlg-skills](https://github.com/ssheleg/sshlg-skills)
+bundle, which installs the whole family for Claude Code, Cursor, Codex and 70+
+other agents with one command.
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ssheleg/agent-sync",
-  "version": "1.2.4",
-  "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.",
+  "version": "1.3.3",
+  "description": "Let concurrent coding agents share one project without colliding — 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,6 +1,6 @@
 {
   "name": "agent-sync",
-  "version": "1.2.4",
+  "version": "1.3.3",
   "description": "Coordination layer for multi-agent repositories — 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": "appvillis-com"

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]"
+argument-hint: "[init|status|claim <KEY>|release <KEY>|reserve <REG>|board|finish]"
 ---
 
 Invoke the `agent-sync` skill.
@@ -14,3 +14,7 @@ instance URL) or local files. Never guess that answer.
 
 If the project is already initialised, report status and name exactly one next
 action.
+
+With `finish`, run the end-of-work check instead: every repository clean, pushed and pointed at,
+and no lease left held. In a project of git submodules that is the one failure nobody sees — the
+submodule is pushed and the parent still points at the commit before the work.

package/plugins/agent-sync/hooks/session-start.sh

@@ -4,5 +4,24 @@ set -uo pipefail
 . "${CLAUDE_PLUGIN_ROOT}/hooks/_lib.sh"
 S="$AGENT_SYNC_PY"
 agent_sync_configured || exit 0
+
+# Stamp who this session is, keyed by the process every command in it descends from.
+# A hook has CLAUDE_SESSION_ID in its environment and a plain shell command does not, so without
+# this a second session in the same checkout adopts the first one's identity: both acquire and
+# release as one run, and the lease stops separating the exact case it exists for. $PPID here is
+# the CLI process, which is the one ancestor every later command shares.
+if [ -n "${CLAUDE_SESSION_ID:-}" ]; then
+  d="$(git rev-parse --show-toplevel 2>/dev/null)/.agent-sync/sessions"
+  if mkdir -p "$d" 2>/dev/null; then
+    printf '%s' "$CLAUDE_SESSION_ID" > "$d/$PPID" 2>/dev/null || true
+    # forget the stamps of processes that are gone, so the directory cannot grow without bound
+    for f in "$d"/*; do
+      b="$(basename "$f")"
+      case "$b" in *[!0-9]*) continue ;; esac
+      kill -0 "$b" 2>/dev/null || rm -f "$f"
+    done
+  fi
+fi
+
 run_limited 10 python3 "$S" status 2>&1 || true
 exit 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.2.4"
+  version: "1.3.3"
   author: appvillis-com
 ---
 
@@ -191,11 +191,34 @@ npx sshlg-skills install
 | `adopt` | Inspect an existing project and **propose** a config — writes nothing |
 | `scaffold` | Create the missing documentation architecture. Never overwrites |
 | `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 |
+| `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
 `.claude/agent-sync.json` from the project root and needs no arguments beyond those
 listed.
 
+## One identity per session, and how it is decided
+
+A lease is only a lease if two agents get two identities. Ordering matters here and both ends have
+bitten: deriving the id from `CLAUDE_SESSION_ID` alone gave **one session two identities** — it
+acquired as one and was denied by its own guard as the other — and keeping one id per checkout gave
+**two sessions one identity**, which is worse. The second is silent: both sessions acquire, both are
+guarded, and `release` takes a lease the caller never had.
+
+The order is: `AGENT_SYNC_RUN_ID` · `CLAUDE_SESSION_ID` · **the session that started this shell** ·
+shared.
+
+The third is the one that matters, because a plain shell command has no session id and a hook does.
+So `SessionStart` stamps `.agent-sync/sessions/<the CLI's pid>` with the session it knows, and a
+later command finds itself by walking its own process ancestry to a pid that appears there. It is
+exact, and it deliberately does **not** parse command lines: the throwaway shell every tool call
+runs in carries claude paths in its own argv, so every heuristic aimed at the CLI binary matched it
+instead. Stamps are removed when their process is gone.
+
+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.
+
 ## Claiming — the shape that matters
 
 ```

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

@@ -64,13 +64,17 @@ user-facing work) and `make-skill`, and it prunes the duplicate plain-copy shado
 
 ## Gate expressions
 
-Each `check` above is verified by the coordinator, not by prose:
+Each `check` above is verified by the coordinator, not by prose — and since 1.3.0 the repository
+half of that verification is a command rather than a promise: **`agent_sync.py finish`** runs the
+pointer, cleanliness, pushed-ness and lease checks, and `finish --gates` adds the project's own
+declared gates. Until then this table described work nothing performed.
 
 | Check | How it is decided |
 |---|---|
 | lease held | replay the log; holder == this run |
 | every id reserved | every `DEC-`/`OQ-`/`DEP-`-shaped token new in the diff has a `reserve` line in this run |
 | no two parallel tasks write one file | intersect the file lists journaled at stage 4 |
-| submodule pointers current | `git submodule status` reports no `+` prefix |
+| submodule pointers current | `git submodule status` reports no `+` prefix — `finish` |
+| every repository pushed | no commits ahead of upstream anywhere, parent included — `finish` |
 | board regenerated, no drift | each mirror stamp equals `git rev-parse HEAD` for its source |
 | every lease released | replay the log; this run holds nothing |

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

@@ -32,7 +32,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
-VERSION = "1.2.4"
+VERSION = "1.3.3"
 
 CONFIG_PATH = Path(".claude/agent-sync.json")
 ENV_FILE = Path(".env.agent-sync")
@@ -208,46 +208,103 @@ def load_config(root: Path) -> dict[str, Any]:
         raise Fail(f".claude/agent-sync.json is not valid JSON: {exc}") from exc
 
 
-def run_id(root: Path) -> str:
-    """One identity per session, whichever way the tool is invoked.
+def _session_key() -> tuple[str, str]:
+    """Who is asking — and how confidently.
+
+    Returns `(key, how)`. `how` is reported to the user, because the three answers are not
+    equally strong and an identity nobody can question is how two agents end up as one.
 
-    This is load-bearing. A hook runs with CLAUDE_SESSION_ID in its environment and a
-    plain shell command usually does not, so deriving the id from that variable gave
-    one session two identities: the agent acquired a lease as one and was then denied
-    by its own guard as the other. The gate blocked the lease holder.
+    The hard case is real and was found in production: **two Claude sessions in the same
+    checkout.** A hook runs with `CLAUDE_SESSION_ID` in its environment; a plain shell command
+    does not. With a single marker file per checkout, the second session adopts whatever the
+    first stamped — so both acquire, release and are guarded as one run. The lease then fails to
+    separate exactly the case it exists for, silently, and one agent can release the other's
+    lease mid-work.
 
-    The marker file is therefore authoritative for the checkout, with the session name
-    recorded beside it. A genuinely different session rotates it; a run that merely
-    *learns* its session name adopts it instead of rotating — otherwise the first shell
-    command in a fresh checkout would fork the identity all over again.
+    The process tree is what a plain shell still has. Every Claude session runs under its own
+    `claude` process, so the nearest such ancestor identifies the session even when the
+    environment does not. A pid can be recycled, so it is paired with that process's start time.
     """
     override = os.environ.get("AGENT_SYNC_RUN_ID")
     if override:
-        return "r-" + re.sub(r"[^a-z0-9]", "", override.lower())[:12]
+        return "env:" + override, "AGENT_SYNC_RUN_ID"
 
     session = os.environ.get("CLAUDE_SESSION_ID") or ""
-    marker = root / STATE_DIR / "run-id"
+    if session:
+        return "session:" + session, "CLAUDE_SESSION_ID"
+
+    # No session id in this environment — a plain shell command has none. What it does have is
+    # an ancestor process that the SessionStart hook ran under, and that hook DID have the id.
+    # So the hook stamps `<state>/sessions/<its own parent pid>` with the session, and this walk
+    # looks for an ancestor that appears there. That is exact: no command-line parsing, which was
+    # tried and failed — the throwaway shell this very command runs in carries claude paths in
+    # its argv and matched every heuristic aimed at the CLI.
+    try:
+        root = project_root()
+        sessions = root / STATE_DIR / "sessions"
+        pid = os.getpid()
+        for _ in range(10):
+            marker = sessions / str(pid)
+            if marker.exists():
+                return "session:" + marker.read_text().strip(), "the session that started this shell"
+            out = subprocess.run(["ps", "-o", "ppid=", "-p", str(pid)],
+                                 capture_output=True, text=True, timeout=5)
+            ppid = out.stdout.strip()
+            if not ppid or ppid in ("0", "1", str(pid)):
+                break
+            pid = int(ppid)
+    except (OSError, ValueError, subprocess.SubprocessError):
+        pass
+
+    return "", "nothing — this identity is shared with any other session in this checkout"
+
+
+def run_id(root: Path) -> str:
+    """One identity per session, whichever way the tool is invoked.
+
+    Load-bearing in both directions. Deriving the id from `CLAUDE_SESSION_ID` alone gave one
+    session two identities — the agent acquired a lease as one and was denied by its own guard as
+    the other. Keeping a single id per checkout gave two sessions one identity, which is worse:
+    the guard let each of them write the other's guarded files and `release` took a lease its run
+    never acquired.
 
-    stored: dict[str, str] = {}
+    So the marker is a **map**, keyed by whatever `_session_key()` could establish. A key that
+    cannot be established falls back to the shared entry — the old behaviour, kept because it is
+    better than minting a fresh identity on every shell command, and reported as weak rather than
+    presented as separation.
+    """
+    key, _how = _session_key()
+    if key.startswith("env:"):
+        return "r-" + re.sub(r"[^a-z0-9]", "", key[4:].lower())[:12]
+
+    marker = root / STATE_DIR / "run-id"
+    data: dict[str, Any] = {}
     if marker.exists():
         raw = marker.read_text().strip()
         try:
-            stored = json.loads(raw)
+            parsed = json.loads(raw)
         except json.JSONDecodeError:
-            stored = {"run": raw, "session": ""}   # legacy plain-text marker
-
-    if stored.get("run"):
-        known = stored.get("session", "")
-        if not session or known == session:
-            return stored["run"]
-        if not known:
-            marker.write_text(json.dumps({"run": stored["run"], "session": session}))
-            return stored["run"]
-
-    rid = ("r-" + re.sub(r"[^a-z0-9]", "", session.lower())[:12]) if session else \
-          "r-%06x%s" % (random.getrandbits(24), format(int(time.time()) & 0xFFF, "03x"))
+            parsed = {"run": raw, "session": ""}
+        if isinstance(parsed, dict) and "runs" in parsed:
+            data = parsed
+        elif isinstance(parsed, dict) and parsed.get("run"):
+            # migrate the single-value marker: it belonged to whichever session stamped it
+            legacy_key = ("session:" + parsed["session"]) if parsed.get("session") else "shared"
+            data = {"runs": {legacy_key: {"run": parsed["run"], "seen": now_iso()}}}
+    data.setdefault("runs", {})
+
+    entry = data["runs"].get(key or "shared")
+    if entry and entry.get("run"):
+        entry["seen"] = now_iso()
+        rid = entry["run"]
+    else:
+        session = os.environ.get("CLAUDE_SESSION_ID") or ""
+        rid = ("r-" + re.sub(r"[^a-z0-9]", "", session.lower())[:12]) if session else \
+              "r-%06x%s" % (random.getrandbits(24), format(int(time.time()) & 0xFFF, "03x"))
+        data["runs"][key or "shared"] = {"run": rid, "seen": now_iso()}
+
     marker.parent.mkdir(parents=True, exist_ok=True)
-    marker.write_text(json.dumps({"run": rid, "session": session}))
+    marker.write_text(json.dumps(data, indent=1))
     return rid
 
 
@@ -718,6 +775,27 @@ class Sync:
         except (json.JSONDecodeError, ValueError):
             return sha, {}
 
+    def _note_local(self, key: str, payload: str) -> None:
+        """Record locally that THIS run won THIS key here.
+
+        The git ref is the authority and stays so — it is what makes the lease exclusive across
+        machines. But `held()`, `whoami`, `status` and the PreToolUse guard all ask a *local*
+        question: does this run hold that key? Answering it by reading the remote would put a
+        network round-trip in front of every single Edit. So the winner leaves a note, and
+        `release()` — which already removes it — closes the loop.
+
+        Without this the guard denied the run that held the lease: `acquire` wrote a ref, `held()`
+        read a directory nothing had written, and every guarded file became unwritable in git mode.
+        """
+        lock = self._local_lock(key)
+        try:
+            fd = os.open(str(lock), os.O_CREAT | os.O_TRUNC | os.O_WRONLY, 0o600)
+            with os.fdopen(fd, "w") as fh:
+                fh.write(payload)
+        except OSError as exc:
+            # Never fatal: the lease is already won on the remote, which is the part that matters.
+            print(f"note: lease won but not noted locally ({exc})", file=sys.stderr)
+
     def _git_acquire(self, key: str) -> tuple[bool, str | None]:
         """Push a ref that must not already exist. The remote's non-fast-forward rule
         IS the compare-and-swap — verified against a hosted remote, not assumed."""
@@ -725,6 +803,7 @@ class Sync:
         held_sha, held = self._git_read_lease(key)
         if held:
             if held.get("run") == self.rid:
+                self._note_local(key, json.dumps(held))
                 self._touch_renew()
                 return True, self.rid
             alive = time.time() <= parse_iso(held.get("ts", "")) + int(held.get("ttl", self.ttl))
@@ -734,10 +813,20 @@ class Sync:
         payload = json.dumps({"run": self.rid, "ts": now_iso(), "ttl": self.ttl,
                               "repo": repo_name(), "host": os.uname().nodename})
         empty_tree = git("hash-object", "-t", "tree", "/dev/null")
-        commit = subprocess.run(["git", "commit-tree", empty_tree], input=payload,
-                                capture_output=True, text=True).stdout.strip()
+        # A lease object is plumbing, not authorship, so it must not depend on the
+        # machine having a git identity. Without these `-c` flags `commit-tree`
+        # refuses wherever user.email is unset and cannot be auto-detected — CI
+        # runners, containers, a freshly provisioned box — and the lease backend
+        # silently becomes unusable on exactly the machines that need it most.
+        made = subprocess.run(
+            ["git", "-c", "user.name=agent-sync", "-c", "user.email=agent-sync@localhost",
+             "commit-tree", empty_tree],
+            input=payload, capture_output=True, text=True)
+        commit = made.stdout.strip()
         if not commit:
-            raise Fail("could not create the lease object — is this a git repository?")
+            detail = (made.stderr or "").strip().splitlines()
+            why = detail[-1] if detail else "no output from git commit-tree"
+            raise Fail(f"could not create the lease object — is this a git repository? ({why})")
 
         args = ["git", "push", remote, f"{commit}:{ref}"]
         if held_sha:                       # stealing an expired lease, and only that
@@ -747,6 +836,7 @@ class Sync:
             # Rejected: somebody won between our read and our push. Ask who.
             _s, now_held = self._git_read_lease(key)
             return False, now_held.get("run") or "another run"
+        self._note_local(key, payload)
         self._touch_renew()
         return True, self.rid
 
@@ -1698,6 +1788,7 @@ def cmd_init(args: argparse.Namespace) -> int:
 
     ensure_gitignored(root, str(ENV_FILE))
     ensure_gitignored(root, f"{STATE_DIR}/")
+    ensure_untracked(root, f"{STATE_DIR}/")
 
     print()
     if backend == "outline":
@@ -1753,6 +1844,25 @@ def ensure_gitignored(root: Path, entry: str) -> None:
     print(f"✓ added {entry} to .gitignore")
 
 
+def ensure_untracked(root: Path, entry: str) -> None:
+    """Ignoring a path does nothing once git is already tracking it.
+
+    Found in a real project: the state directory had been committed before the ignore rule
+    existed, so `git status` reported it modified after **every** tool call — the repository was
+    permanently dirty and no run could report itself finished. `run-id` is the worse half: it is
+    this checkout's agent identity, and committed it reaches every clone, so two machines
+    coordinate as one run.
+    """
+    tracked = git("ls-files", "--", entry.rstrip("/"), cwd=root)
+    if not tracked:
+        return
+    if git("rm", "-r", "--cached", "-q", "--", entry.rstrip("/"), cwd=root) is None:
+        return
+    n = len(tracked.split("\n"))
+    print(f"✓ untracked {n} committed file(s) under {entry} — commit that removal; "
+          "ignoring a tracked path has no effect")
+
+
 # --------------------------------------------------------------------------- status
 
 def cmd_status(_args: argparse.Namespace) -> int:
@@ -2075,6 +2185,149 @@ def cmd_adopt(_args: argparse.Namespace) -> int:
     return 0
 
 
+OPEN_QUESTIONS_SEED = """# Open questions
+
+**One job: what is not decided yet, and what settling it would unblock.**
+
+**Next free ID:** `OQ-0001`
+
+A question here is answered by a decision, never by a conversation: when it is settled, its row
+becomes `Resolved→DEC-####` and the reasoning goes in that decision. A question with no owner and
+no consequence is not an open question — it is a note, and it belongs somewhere else.
+
+| ID | Question | Area | Status | Affects |
+|---|---|---|---|---|
+"""
+
+INDEX_SEED = """# Index — one row per decision
+
+**One job: find the decision without reading the register.** Generated by hand and gated: a
+decision with no row here fails the docs gate, because a register nobody can scan is a register
+nobody reads.
+
+**It quotes no counts and no rule.** A restated rule is a second source with a decay rate; this
+file holds titles and status only.
+
+| ID | Title | Status |
+|---|---|---|
+"""
+
+DEPENDENCIES_SEED = """# Dependencies — the only place a fact about two repositories lives
+
+**One job: name what one repository needs from another, who produces it, and who is waiting.**
+
+A row carries **both sides**. A dependency with no producer task is a dependency nobody is going to
+build, and the block it causes is invisible from either side alone — the consumer says *blocked on
+DEP-003*, and DEP-003 names nobody.
+
+**No status rollup.** Each row names the producer's task; the current answer is read at its source,
+never copied here where it drifts.
+
+| ID | What is needed | Producer | Consumer | State | Notes |
+|---|---|---|---|---|---|
+"""
+
+DATA_MODEL_SEED = """# Data model — one definition per thing
+
+**One job: every entity defined once, with an address, so nothing is described twice and differently.**
+
+Two layers, and the distinction is not cosmetic:
+
+- **Conceptual entity** — what the thing *is* in the product, its identity, its relationships, and
+  the rules that travel with it. Here.
+- **Physical table** — columns, types, nullability, indexes. In the owning service's own schema
+  document.
+
+A physical table **must name the conceptual entity it implements**; one that names none is a
+finding, because that is where two services drift without either being wrong. The reverse is a
+finding too: an entity with no table anywhere is a thing everyone agreed on and nobody built.
+
+Every entity heading carries an explicit anchor — `## <a id="thing"></a>Thing` — so a mention
+elsewhere links to the definition rather than to the top of this file. An explicit id is checkable
+at both ends; an auto-generated slug changes the moment somebody rewords a heading, and every
+inbound link breaks silently.
+
+## <a id="entity_register"></a>Entity register
+
+| Entity | Address | Physical table in | Introduced by |
+|---|---|---|---|
+"""
+
+CHECK_DOCS_SEED = r'''#!/usr/bin/env bash
+# The documentation gate. Seeded by agent-sync; extend it, do not replace it.
+#
+# It exists because linked documentation rots quietly: a decision cites a document that never
+# mentions it, a link points at a file that moved, an id is minted twice, an index row is missing.
+# None of those break anything visibly, and all of them cost the next reader an hour.
+set -uo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"; cd "$ROOT" || exit 1
+fail=0; err() { printf 'FAIL: %s\n' "$1"; fail=1; }
+DOCS="${DOCS_DIR:-docs}"; [ -d "$DOCS" ] || DOCS="."
+md=$(find "$DOCS" -name '*.md' 2>/dev/null; ls ./*.md 2>/dev/null)
+
+# 1. every id that is cited is defined somewhere
+for reg in DEC OQ DEP; do
+  file=$(grep -rl "Next free ID:\*\* \`$reg-" $md 2>/dev/null | head -1)
+  [ -z "$file" ] && continue
+  # A definition is a heading or a table row in the register itself. The template block and the
+  # allocation line are neither, and a gate that counts them fails a project on the day it is
+  # created — which teaches everyone that the gate is noise.
+  body=$(sed -n '/^```/,/^```/!p' "$file" | grep -v "Next free ID")
+  defined=$(echo "$body" | grep -ohE "^#+ $reg-[0-9]{3,4}|^\| \[?$reg-[0-9]{3,4}" | grep -oE "$reg-[0-9]{3,4}" | sort -u)
+  cited=$(cat $md | sed -n '/^```/,/^```/!p' | grep -v "Next free ID" | grep -ohE "\b$reg-[0-9]{3,4}\b" | sort -u)
+  missing=$(comm -13 <(echo "$defined") <(echo "$cited"))
+  [ -n "$missing" ] && err "$reg cited but never defined: $(echo $missing | tr '\n' ' ')"
+  # 2. the next-free-ID line is the next one, or two agents mint the same number
+  next=$(grep -oE "Next free ID:\*\* \`$reg-[0-9]{3,4}" "$file" | grep -oE '[0-9]{3,4}$')
+  max=$(echo "$defined" | grep -oE '[0-9]{3,4}$' | sort -n | tail -1)
+  if [ -n "$next" ] && [ -n "$max" ] && [ "$((10#$next))" -le "$((10#$max))" ]; then
+    err "$reg next free id is $next but $reg-$max exists"
+  fi
+done
+
+# 3. every relative link resolves
+while IFS= read -r hit; do
+  src="${hit%%:*}"; link="${hit#*:}"
+  tgt="$(cd "$(dirname "$src")" && cd "$(dirname "$link")" 2>/dev/null && pwd)/$(basename "$link")"
+  [ -e "$tgt" ] || err "$src → $link does not exist"
+done < <(grep -rhoE '\]\(\.{1,2}/[A-Za-z0-9_./-]+\.md' $md 2>/dev/null | sed 's/](//' | sort -u | while read -r l; do grep -rl -- "]($l" $md | head -1 | sed "s|$|:$l|"; done)
+
+# 4. every #anchor a link points at exists in the file it points at
+python3 - "$ROOT" <<'PYEOF' || fail=1
+import os, re, sys
+root = sys.argv[1]; bad = 0; cache = {}
+def ids(path):
+    if path not in cache:
+        try: t = open(path, errors="replace").read()
+        except OSError: cache[path] = None; return None
+        cache[path] = set(re.findall(r'<a id="([^"]+)"', t))
+    return cache[path]
+for dp, _, fns in os.walk(root):
+    if any(p in dp for p in (".git", "node_modules")): continue
+    for fn in fns:
+        if not fn.endswith(".md"): continue
+        src = os.path.join(dp, fn)
+        for rel, frag in re.findall(r'\]\((\.{1,2}/[A-Za-z0-9_./-]+\.md)#([A-Za-z0-9_-]+)\)',
+                                    open(src, errors="replace").read()):
+            tgt = os.path.normpath(os.path.join(dp, rel)); have = ids(tgt)
+            if have is not None and frag not in have:
+                print("FAIL: %s -> %s#%s (no such anchor)" % (os.path.relpath(src, root), rel, frag)); bad = 1
+sys.exit(bad)
+PYEOF
+
+# 5. every decision has an index row
+idx=$(ls "$DOCS/INDEX.md" 2>/dev/null || true)
+dec=$(ls "$DOCS/DECISIONS.md" 2>/dev/null || true)
+if [ -n "$idx" ] && [ -n "$dec" ]; then
+  for d in $(sed -n '/^```/,/^```/!p' "$dec" | grep -ohE '^#+ DEC-[0-9]{3,4}' | grep -oE 'DEC-[0-9]{3,4}'); do
+    grep -q "$d" "$idx" || err "$d has no INDEX row"
+  done
+fi
+
+[ "$fail" -eq 0 ] && printf 'OK: documentation consistent.\n'
+exit "$fail"
+'''
+
 DECISIONS_SEED = """# Decisions
 
 Every settled decision about this project, append-only. A decision is any answer that
@@ -2160,6 +2413,19 @@ def cmd_scaffold(args: argparse.Namespace) -> int:
 
     seed(docs / "DECISIONS.md", DECISIONS_SEED)
     seed(root / "AGENTS.md", AGENTS_SEED.format(snapshot=snapshot))
+    if args.full:
+        # The rest of the architecture that keeps documentation LINKED rather than merely present:
+        # a question register that resolves into decisions, an index nobody has to scan the
+        # register to use, a place for facts about two repositories, one definition per entity —
+        # and the gate, because every one of those rots silently without a check that fails.
+        seed(docs / "OPEN_QUESTIONS.md", OPEN_QUESTIONS_SEED)
+        seed(docs / "INDEX.md", INDEX_SEED)
+        seed(docs / "DEPENDENCIES.md", DEPENDENCIES_SEED)
+        seed(docs / "DATA_MODEL.md", DATA_MODEL_SEED)
+        gate = root / "scripts" / "check-docs.sh"
+        seed(gate, CHECK_DOCS_SEED)
+        if gate.exists():
+            gate.chmod(0o755)
 
     for c in created:
         print(f"  + {c}")
@@ -2175,6 +2441,124 @@ def cmd_scaffold(args: argparse.Namespace) -> int:
     return 0
 
 
+def _repo_state(path: Path, label: str, ignore: str) -> list[str]:
+    """Is this repository clean, and is its work anywhere but here?
+
+    Both halves matter and only one of them is obvious. Uncommitted work is visible to whoever
+    is sitting in front of it; work committed and never pushed is invisible to everyone else
+    while looking finished to its author — the roadmap says done, the test suite is green, and
+    nobody else can fetch a line of it.
+    """
+    problems: list[str] = []
+    porcelain = git("status", "--porcelain", cwd=path)
+    dirty = [ln for ln in porcelain.split("\n")
+             if ln.strip() and not re.search(ignore, ln.split()[-1] if ln.split() else "")]
+    if dirty:
+        problems.append(f"{label} has uncommitted work: " + ", ".join(d.split()[-1] for d in dirty[:6]))
+    upstream = git("rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}", cwd=path)
+    branch = git("rev-parse", "--abbrev-ref", "HEAD", cwd=path)
+    if upstream:
+        ahead = git("rev-list", "--count", f"{upstream}..HEAD", cwd=path) or "0"
+        if ahead != "0":
+            problems.append(f"{label} is {ahead} commit(s) ahead of {upstream} — pushed nowhere")
+    elif branch == "HEAD":
+        # A submodule sits at a detached pointer by design; what matters is that the commit exists
+        # somewhere others can fetch from.
+        if not git("branch", "-r", "--contains", "HEAD", cwd=path):
+            problems.append(f"{label} is at a commit on no remote branch — nobody else can fetch it")
+    else:
+        problems.append(f"{label} ({branch}) tracks no remote — its work cannot be seen by anyone")
+    return problems
+
+
+def cmd_finish(args: argparse.Namespace) -> int:
+    """The gate expressions this plugin's pipeline binding declares, actually executed.
+
+    `check` answers *is this project wired correctly*. This answers *is the work finished*, and
+    they are different questions with different failure modes. The one it exists for is silent by
+    construction: a project of git submodules records each submodule's commit as a pointer in its
+    parent, and moving the submodule does not move the pointer. So the submodule is pushed, its CI
+    is green, its roadmap says `done` — and anyone who clones the parent gets the commit before the
+    work. Nothing in either repository looks wrong on its own; the disagreement only exists between
+    them, which is why nothing had been checking it.
+    """
+    s = Sync()
+    root = project_root()
+    ok: list[str] = []
+    problems: list[str] = []
+    ignore = r"\.agent-sync/"
+
+    print(f"run {s.rid} · {'gated' if s.gated else 'ungated'}\n")
+
+    # 1. the parent, then every submodule: clean, pushed, and pointed at
+    p = _repo_state(root, root.name, ignore)
+    problems.extend(p)
+    if not p:
+        ok.append(f"{root.name} clean and pushed")
+
+    for line in (git("submodule", "status") or "").split("\n"):
+        if not line.strip():
+            continue
+        prefix, rest = line[0], line[1:].split()
+        sub = rest[1] if len(rest) > 1 else "?"
+        if prefix == "+":
+            recorded = (git("ls-tree", "HEAD", sub) or "").split()
+            problems.append(
+                f"{sub} — the parent points at {recorded[2][:8] if len(recorded) > 2 else '?'}, "
+                f"the submodule is at {rest[0][:8]}. The bump commit is missing")
+        elif prefix == "-":
+            problems.append(f"{sub} is not checked out — a gate run here skips everything it owns")
+        elif prefix == "U":
+            problems.append(f"{sub} has merge conflicts")
+        else:
+            ok.append(f"{sub} pointer current")
+        subp = root / sub
+        if subp.is_dir():
+            sp = _repo_state(subp, sub, ignore)
+            problems.extend(sp)
+            if not sp and prefix == " ":
+                ok.append(f"{sub} clean and pushed")
+
+    # 2. leases. A run that ends holding one blocks the next agent for the whole TTL, and the
+    #    holder is a run id nobody can ask about once its session is gone.
+    held = s.held()
+    if held:
+        problems.append("this run still holds " + ", ".join(held) + " — release before you finish")
+    else:
+        ok.append("no lease left held")
+
+    # 3. the declared gates, on request. They are the project's own commands and can be slow, so
+    #    running them is opt-in — but a `finish` that never ran them is a claim, not a check.
+    if args.gates:
+        for cmd in s.cfg.get("gates", []):
+            try:
+                r = subprocess.run(cmd, shell=True, cwd=str(root), capture_output=True,
+                                   text=True, timeout=600)
+            except (OSError, subprocess.SubprocessError) as exc:
+                problems.append(f"gate `{cmd}` could not run: {exc}")
+                continue
+            if r.returncode == 0:
+                ok.append(f"gate `{cmd}`")
+            else:
+                tail = [ln for ln in (r.stdout + r.stderr).split("\n") if ln.strip()][-3:]
+                problems.append(f"gate `{cmd}` failed: " + " / ".join(tail))
+
+    for line in ok:
+        print(f"  \u2713 {line}")
+    for line in problems:
+        print(f"  \u2717 {line}")
+    print()
+    if problems:
+        print(f"{len(problems)} problem(s) — this work is not finished. The usual one is a "
+              "submodule commit with no parent bump:")
+        print('    git -C <submodule> push && git add <submodule> && '
+              'git commit -m "chore: bump <name> submodule — <why>"')
+        return 1
+    print(f"finished cleanly ({len(ok)} checks passed) — every repository is clean, pushed, "
+          "and pointed at.")
+    return 0
+
+
 def cmd_check(_args: argparse.Namespace) -> int:
     """Validate the whole setup, end to end, and refuse to call a broken one healthy.
 
@@ -2360,6 +2744,16 @@ def cmd_check(_args: argparse.Namespace) -> int:
         except Fail:
             pass
 
+    tracked_state = git("ls-files", "--", STATE_DIR)
+    if tracked_state:
+        problems.append(
+            f"{STATE_DIR}/ is tracked by git ({len(tracked_state.split(chr(10)))} file(s)) — it is "
+            "generated state, the repository is dirty after every tool call, and a committed "
+            "run-id hands this checkout's identity to every clone. "
+            f"Run: git rm -r --cached {STATE_DIR} && commit")
+    else:
+        ok.append(f"{STATE_DIR}/ is not tracked")
+
     for line in ok:
         print(f"  ✓ {line}")
     for line in warn:
@@ -2418,8 +2812,13 @@ def build_parser() -> argparse.ArgumentParser:
     sub.add_parser("setup", help="write the generated snapshot of how this project is wired").set_defaults(fn=cmd_setup)
     sub.add_parser("adopt", help="inspect an existing project and propose a config (writes nothing)").set_defaults(fn=cmd_adopt)
     sub.add_parser("check", help="validate the whole setup; non-zero if it is not healthy").set_defaults(fn=cmd_check)
+    fi = sub.add_parser("finish", help="is the work finished — every repo clean, pushed and pointed at; no lease held")
+    fi.add_argument("--gates", action="store_true", help="also run the project's declared gate commands")
+    fi.set_defaults(fn=cmd_finish)
     sc = sub.add_parser("scaffold", help="create the missing documentation architecture (never overwrites)")
     sc.add_argument("--docs-dir", action="store_true", help="put the register under docs/ even if it does not exist yet")
+    sc.add_argument("--full", action="store_true",
+                    help="also seed OPEN_QUESTIONS, INDEX, DEPENDENCIES, DATA_MODEL and the docs gate")
     sc.set_defaults(fn=cmd_scaffold)
     bd = sub.add_parser("board", help="regenerate the read-only board")
     bd.add_argument("--mirror", action="store_true",