@ssheleg/agent-sync 1.2.2

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

@@ -0,0 +1,99 @@
+# Claude Code hooks
+
+**Read this when** installing, debugging or removing the enforcement hooks.
+
+## The limit, first
+
+**Hooks exist only in Claude Code.** On Cursor, Codex and the other agents the
+skills CLI serves there is no `PreToolUse`, so nothing blocks a guarded edit. On
+those agents the same checks run as a self-check written into the skill body, and
+the run is recorded on the board as `ungated`.
+
+Never describe a project as protected when its agents run outside Claude Code. The
+board's `gated` / `ungated` column exists precisely so that an operator can tell an
+enforced run from a promised one.
+
+## Contract
+
+Verified against the Claude Code hooks reference, 2026-07-29.
+
+A `PreToolUse` hook blocks a call in either of two ways:
+
+- **exit 2**, with the reason on **stderr** (stdout is ignored); or
+- **exit 0** with this on stdout:
+
+```json
+{"hookSpecificOutput":{"hookEventName":"PreToolUse",
+ "permissionDecision":"deny",
+ "permissionDecisionReason":"agent-sync: docs/DECISIONS.md is held by run r-7f3a91"}}
+```
+
+Any other exit code is a non-blocking error: execution continues and stderr is shown
+in the transcript. So **a crashing guard fails open** — write the guard to exit 2 on
+its own internal errors, or it silently stops guarding.
+
+The hook receives JSON on stdin with `session_id`, `prompt_id`, `transcript_path`,
+`cwd`, `permission_mode`, `hook_event_name`, `tool_name`, `tool_input` and
+`tool_use_id`.
+
+## Installed hooks
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      { "matcher": "startup|resume",
+        "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh" }] }
+    ],
+    "PreToolUse": [
+      { "matcher": "Edit|Write|MultiEdit",
+        "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" }] }
+    ],
+    "PostToolUse": [
+      { "matcher": "*",
+        "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/renew.sh" }] }
+    ],
+    "SessionEnd": [
+      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-end.sh" }] }
+    ]
+  }
+}
+```
+
+| Hook | Job |
+|---|---|
+| `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 |
+
+## Performance
+
+`renew.sh` runs after **every** tool call. It must be a no-op in the common case:
+it reads one timestamp file and returns. It touches the network at most once per
+`renewIntervalSeconds` (default 300 s). If it ever becomes slower than that, the
+throttle is broken — fix the throttle rather than removing the hook.
+
+## Debugging
+
+| Symptom | Cause |
+|---|---|
+| 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 |
+| 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:
+
+```bash
+echo '{"tool_name":"Edit","tool_input":{"file_path":"docs/DECISIONS.md"},"cwd":"'"$PWD"'"}' \
+  | "$CLAUDE_PLUGIN_ROOT/hooks/guard.sh"; echo "exit=$?"
+```
+
+## Removing them
+
+Delete the `hooks` block from the project's `.claude/settings.json`. The skill keeps
+working — every guard is also available as a command, and the board simply records
+runs as `ungated` from then on.

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

@@ -0,0 +1,145 @@
+# Lease and id-reservation protocol
+
+**Read this when** changing acquisition, expiry, stealing, or id allocation — or
+when two agents disagree about who holds something.
+
+Two different mechanisms, and confusing them is how this went wrong twice:
+
+> **A lease is decided by an atomic operation** — `O_EXCL` on one filesystem, or a pushed
+> git ref across machines. **An id reservation is decided by replaying the log**, where
+> allocation is positional and every reader computes the same answer.
+
+The log never decides a lease. It records one, so other agents can see it.
+
+## Line grammar
+
+One event per line, appended, never edited. Exactly this shape:
+
+```
+- `2026-07-29T10:42:13Z` `op=acquire` `key=ASC-072` `run=r-7f3a91` `ttl=2700` `repo=account-session-connect` `sha=9bba6d2`
+```
+
+Parsed by:
+
+```
+^[-*+] `(?P<ts>[^`]+)`(?P<pairs>(?: `[a-z_]+=[^`]*`)+)$
+```
+
+**Emit `- `; accept `-`, `*` or `+`.** The bullet is deliberately liberal because a
+knowledge base normalises markdown on the way in — Outline rewrites `- ` to `* ` —
+so a parser anchored to the character you wrote rejects every line the server hands
+back. Observed live, and it presented as a lost race rather than a parse failure.
+
+Required on every line: `op`, `key`, `run`. `op` is one of
+`acquire` · `release` · `renew` · `base` · `reserve` · `release_id` · `signal` · `journal`.
+
+Unparseable lines are **counted and reported**, never guessed at. Anything
+entry-shaped (`^[-*+] \``) that fails the full pattern counts as unparseable; blank
+lines, prose and the generated marker are skipped without counting.
+
+**Do not put a narrower pre-filter in front of the pattern.** A `continue` that
+tests for the exact bullet you emitted skips malformed lines *before* they can be
+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.
+
+## 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
+```
+
+**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.
+
+### Why not the knowledge base
+
+Two earlier designs were measured and rejected. **One shared append-only document** loses
+writes: twelve concurrent appends, twelve reported successes, three lines present — so a
+lease decided on it can be held by two runs, each with proof. **One document per writer**
+loses nothing (12/12) but cannot decide: without compare-and-swap nothing knows whether a
+contender is still writing, and eight parallel processes each read only their own shard —
+**eight winners for one key**. A longer settle window reached five, never one.
+
+`O_EXCL` answers what the store cannot: twelve processes, one winner, eleven losers naming
+the same holder. Full history in `CHANGELOG.md` (1.0.0).
+
+### Cross-machine: `leaseBackend: "git"`
+
+A lock file is exclusive between processes on **one filesystem**; two machines have two.
+For cross-machine exclusion the lease is a commit pushed to
+`refs/agent-sync/leases/<key>`, and the remote's non-fast-forward rejection **is** a
+compare-and-swap — verified against a hosted remote, then proven with eight parallel
+processes: one winner, seven losers naming it. Expired leases are stolen with
+`--force-with-lease` against the exact object seen, so a steal cannot clobber a holder who
+renewed in between.
+
+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`.
+
+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.
+
+**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.
+
+## Releasing
+
+`release` on every path, including failure. An abandoned lease is indistinguishable
+from active work until its TTL runs out, and during that window the task looks
+taken. Report the failure and release; do not hold the lease "in case".
+
+## Id reservation
+
+Reading a "next free id" line from a file is not reserving it. Allocation is
+**positional over the log**, so no agent has to trust another's arithmetic.
+
+A register is opened once:
+
+```
+- `…` `op=base` `key=DEC` `value=0216` `run=r-bootstrap`
+```
+
+Then, replaying in order and maintaining a free list:
+
+- `op=release_id key=DEC value=NNNN` pushes `NNNN` onto the 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.
+
+**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
+closes is reported by the board as a **leak** — never reclaimed automatically,
+because a half-written decision on a branch is not the same thing as an unused
+number, and silently handing it out again would produce two documents with one id.
+
+## The lease is not the claim
+
+| 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 |
+
+`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
+registry is the collision a lease exists to prevent — is engineered out rather than
+accepted: one row, one cell, refused on ambiguity, atomic, and reversible from stored
+state. See `roadmap.md`.
+
+Do not add a third place that records ownership — a project with two claim vocabularies
+has, in practice, none.

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

@@ -0,0 +1,76 @@
+# Binding to task-pipeline
+
+**Read this when** wiring `pipeline.json`, or adding a stage hook.
+
+`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.
+
+## 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 |
+| **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 |
+| **5 Dev** | `renew` (automatic), `journal` | Also the owner of the submodule-commit → parent-gitlink bump. Nobody else has both repos in hand |
+| **6 Tests** | `journal` | The suite result is evidence, and evidence belongs in the run |
+| **7 Lint + deploy** | `journal` per gate | — |
+| **8 Post-deploy** | `journal` | — |
+| **9 Docs + wiki** | `signal` per dependency flip, then `board` | The main write point. The pipeline already updates docs here; the board is regenerated from what it wrote |
+| **10 Acceptance** | `release` every lease, write the claim tag through | A run that ends without releasing looks alive until its TTL expires |
+
+## pipeline.json
+
+`task-pipeline`'s `pipeline.schema.json` already permits this; nothing is forked.
+Add `agent-sync` to `skills[]` on the six stages that call it:
+
+```json
+{
+  "stages": [
+    { "id": "0",  "title": "Intake grill",  "skills": ["task-pipeline:grill", "agent-sync"],
+      "gate": { "type": "manual", "check": "brief committed and lease held" } },
+    { "id": "3",  "title": "Spec",          "skills": ["task-pipeline:spec", "agent-sync"],
+      "gate": { "type": "auto",   "check": "every id in the spec was reserved" } },
+    { "id": "4",  "title": "Plan",          "skills": ["task-pipeline:planning", "agent-sync"],
+      "gate": { "type": "auto",   "check": "no two parallel tasks write one file" } },
+    { "id": "5",  "title": "Dev",           "skills": ["task-pipeline:build", "agent-sync"],
+      "gate": { "type": "auto",   "check": "lease live and submodule pointers current" } },
+    { "id": "9",  "title": "Docs + wiki",   "skills": ["task-pipeline:artifacts", "agent-sync"],
+      "gate": { "type": "auto",   "check": "board regenerated and no mirror drift" } },
+    { "id": "10", "title": "Acceptance",    "skills": ["task-pipeline:acceptance", "agent-sync"],
+      "gate": { "type": "auto",   "check": "every lease released and every claim tag written through" } }
+  ]
+}
+```
+
+Stages 1, 2, 6, 7 and 8 keep their own `skills[]`; `agent-sync` only journals there,
+which needs no wiring.
+
+## Preflight
+
+`task-pipeline` is required. When it is absent, print the install line and **stop** —
+do not improvise a substitute flow, because without those stages there is nothing to
+bind to and the result is ad-hoc work wearing a pipeline's vocabulary.
+
+```bash
+npx sshlg-skills install
+```
+
+That installer also brings `super-ux` (its stage-3 UX track is required for
+user-facing work) and `make-skill`, and it prunes the duplicate plain-copy shadow in
+`~/.claude/skills/` that otherwise serves a stale skill over the installed plugin.
+
+## Gate expressions
+
+Each `check` above is verified by the coordinator, not by prose:
+
+| 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 |
+| 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/references/roadmap.md

@@ -0,0 +1,103 @@
+# Working the roadmap: claims, closing, re-planning
+
+**Read this when** configuring `claimTags`, taking or releasing a task, closing one, or
+re-planning work that is already on a board.
+
+The roadmap is where a project says *what is being done and by whom*. With several
+agents it is also the file most likely to be written by two of them at once, which is why
+it is guarded — and why the tool touches it as narrowly as it possibly can.
+
+## The two records, and why both exist
+
+| Record | Says | Lives | Lifetime |
+|---|---|---|---|
+| **Lease** | who holds this task *this minute* | the lease backend | expires by TTL |
+| **Claim tag** | who *owns* this task | the roadmap, in git | until released or done |
+
+A lease without a claim tag is invisible to anyone reading the repository. A claim tag
+without a lease is a name that never expires — the stale `[Backend]` that blocks a task
+for a week because someone's session died. **Both, or neither.**
+
+`acquire` writes the tag through; `release` restores exactly what was there. You do not
+write it by hand, and you should not: an editor rewriting a shared registry is the
+collision the lease exists to prevent.
+
+## How the write is made safe
+
+The roadmap is a shared registry, so the edit is deliberately the smallest one possible:
+
+1. **One row.** The tool finds the *single* markdown table row containing the task id as
+   a whole word. **Zero rows → nothing happens. Two or more → it refuses and says so.**
+   It never guesses which row you meant.
+2. **One cell.** Only the configured cell of that row changes. Everything else on the
+   line — links, notes, other columns — is untouched, byte for byte.
+3. **Reversible.** The previous cell text is stored in `.agent-sync/claims.json` and
+   restored verbatim on release. Not a default, not a guess: what was actually there.
+4. **Atomic.** Written to a temporary file and moved into place, so a crash mid-write
+   cannot leave the register half-edited.
+
+After `acquire` then `release`, `git diff` on the roadmap is **empty**. If it is not,
+that is a bug, not a convention.
+
+## Configuring it
+
+```json
+"claimTags": {
+  "docs/WORKSTREAMS.md":     { "mode": "cell", "cell": 2,  "held": "{prev} · claimed {holder}" },
+  "apps/*/docs/ROADMAP.md":  { "mode": "cell", "cell": -1, "held": "{prev} (claimed: {holder})" }
+}
+```
+
+- `cell` is **0-based** over the row's cells. `-1` is the last cell, `-2` the one before
+  it. Getting this wrong writes the claim into the wrong column and looks like it worked —
+  check the result of your first `acquire` against the file before trusting the mapping.
+- `held` is a template. `{prev}` is the cell's current text, `{holder}` the run id.
+  Keeping `{prev}` is what makes `todo` become `todo (claimed: r-x)` rather than losing
+  the status.
+- A pattern may cover many files (`apps/*/docs/ROADMAP.md`); each is searched
+  independently, and a file with no matching row is simply skipped.
+
+`check` validates that every pattern matches a real file and that the cell exists.
+
+## Closing a task
+
+Closing is **not** the same as releasing, and the tool does not do it for you.
+
+```
+release <KEY>    → the claim is removed; the row returns to what it said before
+```
+
+That is the right behaviour when you stop working. **Closing** means the row's status
+becomes `done` — a statement about the work, not about who was holding it, and one only
+you can make. Do it as part of the same change that lands the work:
+
+1. `record` what you actually built, with the decision id and the files;
+2. edit the row's status to `done` yourself — you hold the lease, so the guard allows it;
+3. `release` the lease;
+4. `reconcile`, then `board`.
+
+The tool refuses to write `done` on your behalf for the same reason it refuses to guess a
+row: a status that a machine sets is a status nobody checked.
+
+## Re-planning
+
+New tasks, split tasks, re-ordered phases — all of it is an ordinary guarded edit:
+
+- **Take a lease on the board itself** before restructuring it. Use the direction or
+  board id as the key (`WS-9`), not a task id, so the lease says what it means.
+- **Reserve every new id** with `reserve` before writing it. Re-planning is exactly when
+  several agents mint ids at once, and reading a *next free id* line is not reserving it.
+- **A task that moves keeps its id.** Ids are stable; renumbering breaks every reference
+  in every other document and in the as-built record.
+- **Record the re-plan as a decision** if it changes scope. A board that quietly grew a
+  phase is a scope change nobody agreed to.
+
+## When the claim cannot be written
+
+If `acquire` prints nothing about the claim, no row matched — the task id is not on the
+board, or not in a table row. That is worth noticing rather than ignoring: it usually
+means the key you leased is not the key the board uses.
+
+If it prints *refusing to guess which one*, two rows carry the id. Fix the board or
+narrow the pattern; do not work around it by editing by hand, because the next agent's
+lease will hit the same ambiguity.

package/plugins/agent-sync/skills/agent-sync/references/two-sources.md

@@ -0,0 +1,131 @@
+# Two documentation sources, and the duty to reconcile them
+
+**Read this when** starting a task, finishing one, or deciding where a piece of
+documentation belongs.
+
+## They answer different questions
+
+| Source | Answers | Written | Authority over |
+|---|---|---|---|
+| **Git docs** (`docs/`, ADRs, specs, contracts) | *How it should be* | before the code, often without it | intent, design, scope, decisions |
+| **The coordination plane** (`70 As-built`) | *How it actually is* | from what agents really wrote | the record of what was built, by whom, at which commit |
+
+Neither is a copy of the other and neither outranks the other, because neither is
+answering the other's question. A spec that describes an unbuilt thing is not wrong —
+it is intent. An as-built record that contradicts the spec is not wrong either — it is
+what happened.
+
+**The gap between them is the finding.** It is drift between plan and reality, and
+surfacing it is the whole point. A system where the two can never disagree has simply
+hidden the disagreement.
+
+This is why the as-built record does **not** violate a single-source-of-truth rule:
+there is no second home for one fact, there are two facts. What would violate it is
+copying a decision's *body* into the cloud and editing it there.
+
+## The duty, both ends of a task
+
+**Before starting** — during the pipeline's docs-study stage:
+
+```bash
+python3 "$SKILL_DIR/scripts/agent_sync.py" reconcile
+```
+
+Read the git documents for the area you are about to touch **and** the as-built
+record for it. Then resolve every divergence one of three ways:
+
+1. the git document is stale → fix it, or record why it stands;
+2. the as-built record is wrong or incomplete → correct it with `record`;
+3. they genuinely disagree and the disagreement is real → that is a decision to make,
+   not a discrepancy to paper over. Raise it before you write code against either.
+
+Starting work on top of an unresolved divergence means building against a document
+that describes a system that does not exist.
+
+**After finishing** — during the pipeline's docs stage:
+
+```bash
+python3 "$SKILL_DIR/scripts/agent_sync.py" record "what you actually built" --decision DEC-0216 --files a.py,b.ts
+python3 "$SKILL_DIR/scripts/agent_sync.py" reconcile
+```
+
+Update **both** sides in the same change: the git documents that state intent, and the
+as-built record of what landed. Then run the check again. A task that updated only one
+side has left the next agent a divergence to discover the hard way.
+
+## What `reconcile` decides, and what it refuses to
+
+It is mechanical, and it says so in its own output. It finds:
+
+- an as-built entry whose commit is **not in this repository's history** — recorded
+  from a branch that never landed, or from another repo;
+- an id written in a register **after the baseline** with no as-built record — decided
+  since adoption, and nothing reports it was built;
+- an as-built entry citing an id that **exists in no register** — built against
+  something never written down.
+
+It does **not** judge whether the built thing matches what the document describes.
+That is a reading, not a diff. The tool points at where to look and refuses to imply
+it checked the substance.
+
+## The baseline — why the check is a ratchet
+
+A project adopting this on day one has every prior decision unrecorded. A check that
+reports all of them reports nothing: it is noise, and noise is what gets a gate
+switched off.
+
+```bash
+python3 "$SKILL_DIR/scripts/agent_sync.py" reconcile --set-baseline
+```
+
+Run once per project. Ids at or below the baseline become a **backlog** — counted,
+visible, allowed only to shrink. Ids after it must carry an as-built record or the
+check fails. This is the same shape as a well-behaved lint ratchet, and for the same
+reason: a gate that fails on history is a gate nobody keeps.
+
+## Where a piece of documentation belongs
+
+| It is… | Home |
+|---|---|
+| a decision about what to build | git — the decision register |
+| a contract, schema, spec | git |
+| user-facing behaviour | git |
+| "this is what I implemented, here is the commit" | the as-built record |
+| "the implementation diverged from the spec, here is why" | **both** — as-built for the fact, git for the decision |
+| who is doing what right now | the claims log — ephemeral, never git |
+
+When in doubt: if it must survive the tool being uninstalled, it goes in git.
+
+## Lifetime, and why nothing is deleted
+
+| Information | Home | Lifetime |
+|---|---|---|
+| Decisions, specs, contracts, user-facing behaviour | git | permanent, append-only register |
+| What was actually built, with its commit | as-built log | permanent, append-only |
+| Cross-repo dependency state | signal log | permanent, append-only |
+| Who holds a task right now | claims log | expires by TTL |
+| Per-run narrative | that run's journal | permanent |
+| The board, the repo page, the setup snapshot | generated | replaced on every regeneration |
+
+**No log entry is ever edited or deleted.** The logs are replayed in order to decide who
+holds what and which id was allocated, so removing a line silently rewrites a conclusion
+every other agent has already acted on. Correct by **appending**:
+
+- a lease is **released**, never removed;
+- a reserved id you did not use is returned with `release-id`, which appends;
+- a wrong as-built entry is superseded by a later, correct one, and both stay visible —
+  the history of what was believed is itself worth keeping.
+
+Generated pages are the exception, and a narrow one: they are rewritten wholesale, and a
+page whose first line has lost its `agent-sync:generated` marker is **refused** rather
+than overwritten, because a human took it over.
+
+**Growth.** These logs are small — one line per event — so rotation is not urgent. When a
+log does need trimming, archive the whole document and start a fresh one with a `base`
+line carrying the current allocation state. Never delete lines from a live log to shrink
+it: replay would then produce a different answer than it did yesterday.
+
+**Removing the tool.** Everything durable is already in git. Delete `.agent-sync/`, the
+config and the env file; the knowledge-base pages can be kept as a record or archived.
+Nothing in the repository depends on the tool being installed, which is the property that
+makes adopting it reversible.