@ssheleg/agent-sync 1.3.5 → 1.4.0

package/CHANGELOG.md

@@ -3,6 +3,121 @@
 All notable changes to this project are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 1.4.0 — 2026-07-30
+
+### Work happens on a branch, and the integration branch stays somebody else's stable base
+
+Two agents renamed this repository the same minute yesterday, both committing straight to
+`main`. The second push was rejected — after the work was already duplicated. Nothing in
+the tool said where work should happen, so both did the obvious thing.
+
+- **`acquire` writes the claim through only on the integration branch.** On any other
+  branch it says so and writes nothing: a claim committed to a branch is invisible to
+  every other agent until the merge, and it turns the shared roadmap into a file two
+  branches both edit — a conflict on the one file that exists to prevent collisions. The
+  holder lives in the coordination plane, where `status` already shows it to everyone
+  without anyone fetching a branch.
+- **`integrationBranch`** in the config, or the repository's own default branch when unset.
+  Asked of the repository, never assumed.
+
+### `merge` — land a branch, with every check before anything is touched
+
+`merge` refuses a detached HEAD, the integration branch itself and a dirty tree; fetches
+the target and reports how far it moved; computes conflicts with **`git merge-tree`, in
+memory**; lists every other run's live lease; merges `--no-ff`; records the merge; and
+releases every lease this run holds. On conflict it names the files, changes nothing and
+exits non-zero — a merge that starts and aborts leaves the operator in a repository they
+did not ask for, and a resolution nobody reviewed does not belong on the integration
+branch. `--dry-run` stops after the checks, `--push` pushes afterwards.
+
+### `merges` — what landed while you were on your branch
+
+A merge log at `docs/MERGES.md` (`mergeLog.file`), written by `merge`. It answers what
+`git log` cannot without reading every commit and what a changelog only covers once
+released: *what landed while I was away, and was any of it near my work.*
+
+**Compaction happens on write.** Entries inside `mergeLog.retentionDays` (7) keep their
+detail; older ones fold to one line each on the next merge. No cron, no second command,
+and no log that grows until people stop reading it — which is the same as not having one.
+
+### Added
+- `test/validate.py` exercises both rules against throwaway repositories: `acquire` on a
+  feature branch must leave the roadmap untouched **and** say where the claim lives, while
+  on the integration branch it must still write through; a conflicting `merge` must exit
+  non-zero, name the conflicting file, leave the checkout on the original branch with a
+  clean tree, and write **no** log entry for a merge that did not happen. Both have
+  self-test fixtures that remove the guard and confirm the check goes red.
+- `references/branching.md`, and the doctrine in the skill body.
+
+## 1.3.9 — 2026-07-30
+
+### Changed
+- `license: MIT` added to the `marketplace.json` plugin entry. The front matter
+  already declared it — this repo was the only one in the family that did — but
+  the plugin listing, which is what a user reads before installing, did not.
+
+
+## 1.3.8 — 2026-07-30
+
+The 1.3.6 move was performed twice, by two agents in this repository within the same
+minute, and neither held a lease on it. Both renames were correct and nearly identical —
+the duplicated effort is the cost, and this project exists to make it visible. This
+release carries the two things only one of them had, and it is the release that moves the
+npm package page: 1.3.6 and 1.3.7 were tagged and never published.
+
+### Changed
+- **`LICENSE` and the README footer read `ssheleg`.** The rename moved every address and
+  every manifest identity, and left the copyright line naming the previous owner — the one
+  statement in this repository with legal weight.
+
+### Added
+- **`test/validate.py` fails a half-finished rename.** It derives the canonical slug from
+  `package.json` and rejects any other owner of this repository name anywhere in the tree:
+  in a URL, in a `github:` install argument, in a `marketplace add` line, or as a bare
+  quoted slug. That last shape is what the installers actually clone, and the first draft
+  of the check missed it — `bin/agent-sync.js` and `install.sh` both passed while still
+  pointing at the old owner. Verified red against the pre-rename tree; the self-test
+  fixture assembles its slug from parts, because written whole it makes the validator the
+  file that fails the check.
+
+## 1.3.7 — 2026-07-30
+
+### Fixed
+- **The 1.3.6 note below claimed `raw.githubusercontent.com` does not follow a
+  repository transfer. It does** — the old owner's raw path returns 200 with the
+  current file, no redirect involved, because GitHub resolves a transferred
+  repository by identity on every surface (git, web and raw alike). Measured
+  after the move, which is what the claim should have been before it was
+  written. The paragraph is corrected in place so no install ships the wrong
+  fact; the reason to update the URLs is unchanged and stated accurately there.
+
+
+## 1.3.6 — 2026-07-30
+
+### Changed
+
+The repository moved from `appvillis-com/agent-sync` to **`ssheleg/agent-sync`**,
+joining the rest of the family under one owner. GitHub keeps serving the old path
+on every surface, so nothing breaks today — but that only holds while the
+`appvillis-com` name is never re-registered, and a reference that depends on
+somebody else not taking a name is worth one commit to remove.
+
+- **Install paths** — `install.sh`, `bin/agent-sync.js` (the `npx github:…`
+  fallback), and the README's npx and `claude plugin marketplace add` commands.
+- **Identity** — `package.json` (homepage, repository, bugs, author),
+  `.claude-plugin/marketplace.json` (owner, homepage, repository, plugin author),
+  `plugins/agent-sync/.claude-plugin/plugin.json`, and the `author` in the skill's
+  front matter: `appvillis-com` → `ssheleg`.
+- **Raw URLs** — `agent-sync.schema.json` `$id`, the `$schema` in
+  `agent-sync.example.json`, and the reference-loading fallback URL in `SKILL.md`.
+  A `$id` is an identifier as much as a location, so it should name the repository
+  that actually holds the schema.
+- Cursor rule, code of conduct and the security-advisory link in the issue-template
+  config.
+
+The changelog entries below and `docs/superpowers/specs/` keep the old path on
+purpose: they record where this was published at the time.
+
 ## 1.3.5 — 2026-07-29
 
 ### The two rules this plugin enforces are now stated, with the failures that taught them

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Appvillis
+Copyright (c) 2026 ssheleg
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,6 +1,6 @@
 # agent-sync
 
-[![CI](https://github.com/appvillis-com/agent-sync/actions/workflows/validate.yml/badge.svg)](https://github.com/appvillis-com/agent-sync/actions/workflows/validate.yml)
+[![CI](https://github.com/ssheleg/agent-sync/actions/workflows/validate.yml/badge.svg)](https://github.com/ssheleg/agent-sync/actions/workflows/validate.yml)
 [![npm](https://img.shields.io/npm/v/%40ssheleg%2Fagent-sync)](https://www.npmjs.com/package/@ssheleg/agent-sync)
 [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
@@ -112,7 +112,7 @@ Restart Claude Code after installing, so it picks the plugin up.
 Track `main` from GitHub instead of the npm release:
 
 ```bash
-npx github:appvillis-com/agent-sync install
+npx github:ssheleg/agent-sync install
 ```
 
 Claude Code only, no skills CLI:
@@ -130,7 +130,7 @@ npx @ssheleg/agent-sync install --agent cursor,codex
 Or add the plugin by hand — the full `<name>@<name>` form is required:
 
 ```bash
-claude plugin marketplace add appvillis-com/agent-sync && claude plugin install agent-sync@agent-sync
+claude plugin marketplace add ssheleg/agent-sync && claude plugin install agent-sync@agent-sync
 ```
 
 </details>
@@ -247,16 +247,53 @@ python3 "$SKILL_DIR/scripts/agent_sync.py" <command>
 | `guard <path>` | May this run write that path? Exit 0 = yes, 2 = no |
 | `board` | Regenerate the read-only board and the mirror from git |
 | `whoami` | Print this run's id and its held leases |
+| `merge` | Land this branch on the integration branch: conflicts checked first, merge log written, lease released |
+| `merges` | What landed while you were on your branch |
 
 The shape that matters:
 
 ```
-acquire → do the work → release
+acquire → work on a branch → merge
 ```
 
-Never skip `release`, including when the work failed. An abandoned lease blocks the task
-until its TTL expires, and the next agent cannot tell "in progress" from "crashed an hour
-ago". A lease is a promise to come back.
+Never skip the last step, including when the work failed. An abandoned lease blocks the
+task until its TTL expires, and the next agent cannot tell "in progress" from "crashed an
+hour ago". A lease is a promise to come back. `merge` releases for you; without a branch,
+`release` by hand.
+
+### Work on a branch, land it with `merge`
+
+The integration branch is somebody else's stable base, so nothing about work in flight is
+committed there. `acquire` writes the claim through to the roadmap **only** on the
+integration branch; on any other branch it says so and keeps the holder in the coordination
+plane, where `status` already shows it to every agent — no one has to fetch your branch to
+see who has what, and the shared roadmap does not become the file every branch edits.
+
+```bash
+python3 "$SKILL_DIR/scripts/agent_sync.py" merge --key ASC-072 --summary "what landed"
+```
+
+Conflicts are computed with `git merge-tree` **before anything is touched** — on conflict
+it names the files, changes nothing and exits non-zero, so a resolution nobody reviewed
+never reaches the integration branch. Then it merges `--no-ff`, records the merge, and
+releases every lease this run holds. `--dry-run` stops after the checks; `--push` pushes
+afterwards.
+
+**The merge log** — `docs/MERGES.md`, configurable via `mergeLog` — answers the question an
+agent coming back from a branch cannot answer from `git log` alone: *what landed while I
+was away, and was any of it near my work.* Entries inside `retentionDays` (7) keep their
+detail; older ones are folded to one line each **on the next write**, so the file stays
+readable without a cron job.
+
+```bash
+python3 "$SKILL_DIR/scripts/agent_sync.py" merges          # recent detail
+python3 "$SKILL_DIR/scripts/agent_sync.py" merges --all    # plus the compacted tail
+```
+
+This is the flow for agents sharing one repository. A project that reviews through pull
+requests keeps doing that — `merge` is then the wrong command, and `finish` is still the
+right one. Full doctrine:
+[`references/branching.md`](plugins/agent-sync/skills/agent-sync/references/branching.md).
 
 **The lease is not the claim.** The lease says who holds the task *now* and expires; the
 durable claim is the tag in git (`[name]`, `todo (claimed: <role>)`). `acquire` writes
@@ -279,6 +316,8 @@ that tag through and `release` clears it, so one fact keeps one home.
 | `claimTags` | file → the durable claim tag `acquire`/`release` writes through |
 | `gates` | commands the pipeline stages run as gates |
 | `mirror` | which git files are rendered into the read-only mirror |
+| `integrationBranch` | where work lands and the only branch a claim is written on (default: the repo's own) |
+| `mergeLog` | `file` and `retentionDays` for the merge log (default `docs/MERGES.md`, 7) |
 
 `.env.agent-sync` — gitignored, mode 600:
 
@@ -405,6 +444,7 @@ 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 |
 | [`earned-rules.md`](plugins/agent-sync/skills/agent-sync/references/earned-rules.md) | why identity is resolved the way it is, and why `finish` exists — the two failures that produced both |
 | [`roadmap.md`](plugins/agent-sync/skills/agent-sync/references/roadmap.md) | configuring `claimTags`, taking or closing a task, or re-planning a board |
+| [`branching.md`](plugins/agent-sync/skills/agent-sync/references/branching.md) | starting work that will produce commits, merging a branch, or asking what landed while you were away |
 
 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).
@@ -416,4 +456,4 @@ other agents with one command.
 
 ## License
 
-MIT © Appvillis
+MIT © ssheleg

package/agent-sync.example.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://raw.githubusercontent.com/appvillis-com/agent-sync/main/agent-sync.schema.json",
+  "$schema": "https://raw.githubusercontent.com/ssheleg/agent-sync/main/agent-sync.schema.json",
   "backend": "outline",
   "leaseTtlSeconds": 2700,
   "renewIntervalSeconds": 300,
@@ -36,5 +36,10 @@
       "docs/ROADMAP.md"
     ]
   },
-  "leaseBackend": "git"
+  "leaseBackend": "git",
+  "integrationBranch": "main",
+  "mergeLog": {
+    "file": "docs/MERGES.md",
+    "retentionDays": 7
+  }
 }

package/agent-sync.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://raw.githubusercontent.com/appvillis-com/agent-sync/main/agent-sync.schema.json",
+  "$id": "https://raw.githubusercontent.com/ssheleg/agent-sync/main/agent-sync.schema.json",
   "title": "agent-sync project configuration",
   "description": "Shape only. Identity (instance URL, token, container id) lives in .env.agent-sync and is never committed.",
   "type": "object",
@@ -139,6 +139,26 @@
       "minimum": 0,
       "default": 3.0,
       "description": "Unused by the git and local backends; retained for adapters that must wait for writes to become visible."
+    },
+    "integrationBranch": {
+      "type": "string",
+      "description": "The branch work lands on. Claims are written through only there; on any other branch the holder lives in the coordination plane until `merge`. Default: the repository's own default branch."
+    },
+    "mergeLog": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The record of what landed on the integration branch, written by `merge`.",
+      "properties": {
+        "file": {
+          "type": "string",
+          "description": "Path to the log, relative to the repository root. Default docs/MERGES.md."
+        },
+        "retentionDays": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "How many days keep full detail; older entries are compacted to one line on the next write. Default 7."
+        }
+      }
     }
   }
 }

package/bin/agent-sync.js

@@ -15,7 +15,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
-const REPO = 'appvillis-com/agent-sync';
+const REPO = 'ssheleg/agent-sync';
 const NAME = 'agent-sync';
 const SHADOW = path.join(os.homedir(), '.claude', 'skills', NAME);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/agent-sync",
-  "version": "1.3.5",
+  "version": "1.4.0",
   "description": "Let concurrent coding agents share one project without colliding \u2014 leases with TTL, race-free id reservation, a run journal and a generated board, over a pluggable knowledge cloud.",
   "bin": {
     "agent-sync": "bin/agent-sync.js"
@@ -30,15 +30,15 @@
     "knowledge-base",
     "task-pipeline"
   ],
-  "homepage": "https://github.com/appvillis-com/agent-sync",
+  "homepage": "https://github.com/ssheleg/agent-sync",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/appvillis-com/agent-sync.git"
+    "url": "git+https://github.com/ssheleg/agent-sync.git"
   },
   "bugs": {
-    "url": "https://github.com/appvillis-com/agent-sync/issues"
+    "url": "https://github.com/ssheleg/agent-sync/issues"
   },
-  "author": "appvillis-com",
+  "author": "ssheleg",
   "license": "MIT",
   "engines": {
     "node": ">=18"

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

@@ -1,12 +1,12 @@
 {
   "name": "agent-sync",
-  "version": "1.3.5",
+  "version": "1.4.0",
   "description": "Coordination layer for multi-agent repositories \u2014 leases with TTL, race-free ID reservation, a run journal, a cross-repo signal feed and a generated board, over a pluggable knowledge cloud.",
   "author": {
-    "name": "appvillis-com"
+    "name": "ssheleg"
   },
-  "homepage": "https://github.com/appvillis-com/agent-sync",
-  "repository": "https://github.com/appvillis-com/agent-sync",
+  "homepage": "https://github.com/ssheleg/agent-sync",
+  "repository": "https://github.com/ssheleg/agent-sync",
   "license": "MIT",
   "keywords": [
     "multi-agent",

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

@@ -4,8 +4,8 @@ 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.3.5"
-  author: appvillis-com
+  version: "1.4.0"
+  author: ssheleg
 ---
 
 # agent-sync — one project, many agents, no collisions
@@ -37,6 +37,16 @@ what was there — one row, one cell, refused on ambiguity, `git diff` empty aft
 round-trip. **Read `references/roadmap.md`** before configuring `claimTags` or closing a
 task; closing is a statement about the work and stays yours.
 
+**Work on a branch; the integration branch is somebody else's stable base.** `acquire`
+writes the claim through **only** there; on any other branch the holder stays in the
+coordination plane, where `status` shows it to every agent without anyone fetching your
+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
+`references/branching.md`** before merging.
+
 **3. Hooks exist only in Claude Code.** Elsewhere nothing blocks a guarded edit: run
 `guard` yourself and record the run as `ungated`. Do not describe a project as protected
 when it is not.
@@ -60,16 +70,12 @@ setup     → generate the snapshot that describes this project's wiring
 check     → validate the whole thing; non-zero if it is not healthy
 ```
 
-**`check` is what makes the skill self-sufficient.** It refuses to call a setup healthy
-on any of: a register file that does not exist or whose allocation pattern matches
-nothing; a guard glob that matches no file (a rule that protects nothing); a claim-tag
-pattern with nothing to look for; a gate command whose script is missing; a mirror source
-that is not there; missing or empty credentials; a `.gitignore` that does not cover the
-env file — or the env file being **tracked by git**, which is the one unrecoverable
-mistake here; a missing, hand-edited or stale snapshot; **a snapshot no agent instruction
-file links**, because agents that cannot find it will infer the pipeline instead; and a
-register with no as-built baseline. Every one of those failed for real during this tool's
-own adoption.
+**`check` is what makes the skill self-sufficient.** It refuses to call a setup healthy on
+a rule that protects nothing (a register, guard glob, claim pattern, gate or mirror source
+pointing at what is not there), on missing credentials, on an env file **tracked by git** —
+the one unrecoverable mistake here — on a stale or unlinked snapshot, and on a register
+with no baseline. It names each one; every one failed for real during this tool's own
+adoption.
 
 Run `check` after adopting, after changing the config, and in CI.
 
@@ -88,11 +94,10 @@ then proposes a config. It writes nothing.
 python3 "$SKILL_DIR/scripts/agent_sync.py" adopt
 ```
 
-Confirm the registers and guarded files with the operator before writing them. 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 actually happen
-unprotected. In a submodule it declares no registers at all: decisions belong to the
-parent repository.
+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.
@@ -157,12 +162,9 @@ ONE next action.
 An agent that skips this block will re-derive work someone else is doing and act on a
 dependency state that changed an hour ago.
 
-What else `status` decides for you:
-
-- No credentials in the environment → degraded mode, reported, and it continues.
-  Missing credentials are not an error, they are a smaller mode.
-- `task-pipeline` absent → it prints the install line and stops. Do not improvise a
-  substitute flow; without those stages there is nothing to bind to.
+What else `status` decides: no credentials → degraded mode, reported, and it continues (a
+smaller mode, not an error); `task-pipeline` absent → it prints the install line and stops.
+Do not improvise a substitute flow — without those stages there is nothing to bind to.
 
 ```bash
 npx sshlg-skills install
@@ -189,7 +191,8 @@ 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 |
-| `scaffold` | Create the missing documentation architecture. Never overwrites |
+| `merge` | Land this branch: conflicts checked **before** anything is touched, merge log written, lease released. `--key`, `--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 |
 | `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 |
@@ -209,12 +212,12 @@ 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.
+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.
 
 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.
@@ -278,14 +281,13 @@ answer different questions. **The gap between them is the finding**, not a defec
 
 The duty runs at both ends of every task:
 
-- **Before starting** (docs-study stage) — `reconcile`, then read both sides for the
-  area you are about to touch. Resolve each divergence: the git doc is stale, or the
-  as-built record is wrong, or they genuinely disagree and that is a decision to make.
-  Building on an unresolved divergence means writing code against a system that does
-  not exist.
-- **After finishing** (docs stage) — `record` what you actually built, update the git
-  documents that state intent, then `reconcile` again. A task that updated one side
-  has left the next agent a divergence to find the hard way.
+- **Before starting** (docs-study stage) — `reconcile`, then read both sides for the area
+  you are about to touch, and resolve each divergence: the git doc is stale, the as-built
+  record is wrong, or they genuinely disagree and that is a decision. Building on an
+  unresolved divergence is writing code against a system that does not exist.
+- **After finishing** (docs stage) — `record` what you built, update the git documents
+  that state intent, then `reconcile` again. A task that updated one side leaves the next
+  agent a divergence to find the hard way.
 
 `reconcile` is mechanical and says so: it compares ids, commits and presence, and refuses
 to judge whether the built thing matches the document. That reading is yours.
@@ -302,17 +304,12 @@ which side a document belongs on.
 This skill supplies stages; it does not define them. Stage names are
 `task-pipeline`'s own.
 
-| Stage | What to do here |
-|---|---|
-| 0 Intake grill | Add the cloud KB and the board to the harvest's source ledger; `acquire` **before** the brief is committed |
-| 1 Docs study | `reconcile` — study git docs **and** the as-built record, resolve every divergence before writing code |
-| 2 Brainstorm | `journal`; warn if a live run holds an overlapping key |
-| 3 Spec | `reserve` every id before writing it to git |
-| 4 Plan | Register file ownership for the plan's parallel groups |
-| 5 Dev | Lease renews itself; own the submodule-commit → parent-gitlink bump |
-| 6 Tests · 7 Lint · 8 Post-deploy | `journal` each gate result |
-| 9 Docs + wiki | The main write point — `record` what was built, update the git docs, `signal` the dependency flips, `reconcile` again, then `board` |
-| 10 Acceptance | `release` every lease, write the durable claim tag through to done |
+Four 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:
+`merge` if the work is on a branch, otherwise `release` every lease by hand. Full table
+with the reasoning per stage: `references/pipeline-binding.md`.
 
 **Read `references/pipeline-binding.md` when wiring `pipeline.json`** — it holds the
 `skills[]` entries and the gate expressions.
@@ -401,6 +398,7 @@ Each file is loaded on its own trigger, not by default.
 | `references/hooks.md` | installing, debugging or removing the Claude Code hooks |
 | `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 |
 
 If this copy arrived without `references/`, fetch them from
-`https://raw.githubusercontent.com/appvillis-com/agent-sync/main/plugins/agent-sync/skills/agent-sync/references/<file>`.
+`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

@@ -0,0 +1,108 @@
+# Branch discipline, merging, and the merge log
+
+**Read this when** starting work that will produce commits, merging a branch, or deciding
+where a claim should be written.
+
+## The rule
+
+> **Work happens on a branch. The integration branch is somebody else's stable base.**
+> Nothing about work in flight is committed there — the holder lives in the coordination
+> plane until the work lands.
+
+Three failures make this a rule rather than a preference, and all three happened here:
+
+| What breaks | Why |
+|---|---|
+| Two agents edit the roadmap to mark a claim | The one file that exists to prevent collisions becomes the file every branch touches, so every merge conflicts on it |
+| A claim committed to a branch tells nobody | It is invisible on the integration branch until the merge — exactly when it stops being useful |
+| Two agents commit straight to the integration branch | The second push is rejected, the work is already duplicated, and the repository has two versions of one change |
+
+## Where a claim lives
+
+`acquire` writes the claim through to the roadmap **only when the run is on the
+integration branch**. On any other branch it says so and writes nothing:
+
+```
+claim for `ASC-072` left in the coordination plane — this run is on 'feature/x',
+not main. `status` shows the holder to every agent; `merge` records the outcome.
+```
+
+That is not a downgrade. The plane is where the claim is *more* visible: `status` lists
+every other run's live holdings, from any checkout and any repository, and neither agent
+has to fetch the other's branch to see it. Git keeps what must survive — the merge, and
+the log entry naming it.
+
+The integration branch is `integrationBranch` in the config, or the repository's own
+default branch when that is unset. It is asked of the repository, never assumed.
+
+## Landing the work
+
+```bash
+python3 "$SKILL_DIR/scripts/agent_sync.py" merge --key ASC-072 --summary "what landed"
+```
+
+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.
+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
+   resolution is reviewable, and run it again.
+4. **Lists every other run's live lease.** Their work is not in this diff; if it touches
+   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.
+
+`--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.
+
+## The merge log
+
+`docs/MERGES.md` by default, `mergeLog.file` to move it, `mergeLog.retentionDays` to
+change the window (7 days).
+
+It answers one question an agent returning from a branch cannot answer from git alone
+without reading every commit: **what landed while I was away, and was any of it near my
+work.** `git log` has the same facts and none of the summary; a changelog has the summary
+and only for released work.
+
+```markdown
+### 2026-07-30T16:42:11Z · `ASC-072` · feature/rename → main · `ec414cd`
+- run: r-4f9c2
+- files: 8 (8 files changed, 120 insertions(+), 31 deletions(-))
+- conflicts: none
+- summary: every address moved to the new owner
+
+## Compacted
+
+- 2026-07-21 · `ASC-060` · fix/lease-visibility → main · `9817f19` · the guard denied the holder
+```
+
+**Compaction happens on write.** Every `merge` re-reads the file, keeps entries inside the
+window in full, and folds everything older into one line each under `## Compacted`. No
+cron, no second command, and no log that grows until people stop reading it — which is the
+same as not having one.
+
+Read it at the start of a task:
+
+```bash
+python3 "$SKILL_DIR/scripts/agent_sync.py" merges           # recent detail
+python3 "$SKILL_DIR/scripts/agent_sync.py" merges --all     # including the compacted tail
+python3 "$SKILL_DIR/scripts/agent_sync.py" merges --compact # force the pass now
+```
+
+## What this does not do
+
+- **No pull request.** This is the flow for agents that share one repository and merge
+  their own work. A project that reviews through pull requests keeps doing that; `merge`
+  is then the wrong command, and `finish` is still the right one.
+- **It does not make a branch safe to skip a lease.** Two agents on two branches editing
+  one file still collide — later, at merge time, with more work already spent. `acquire`
+  first; the branch is where the work goes, not what decides who does it.
+- **It does not rebase for you.** A conflicting merge is refused with the file list; the
+  resolution belongs in the branch, in a commit somebody can read.

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

@@ -19,7 +19,7 @@
 | **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 |
+| **10 Acceptance** | `merge` when the work is on a branch — it records the merge and releases; otherwise `release` every lease and write the claim tag through | A run that ends without releasing looks alive until its TTL expires |
 
 ## pipeline.json
 

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

@@ -32,12 +32,15 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
-VERSION = "1.3.5"
+VERSION = "1.4.0"
 
 CONFIG_PATH = Path(".claude/agent-sync.json")
 ENV_FILE = Path(".env.agent-sync")
 STATE_DIR = Path(".agent-sync")
 GENERATED_MARKER = "<!-- agent-sync:generated"
+MERGE_LOG_MARKER = "<!-- agent-sync:merge-log -->"
+DEFAULT_MERGE_LOG = "docs/MERGES.md"
+DEFAULT_MERGE_RETENTION = 7
 
 # What a won lease is actually worth, in one place. Six surfaces used to phrase this
 # independently and two of them named the knowledge base as the authority — a role it
@@ -119,6 +122,53 @@ def head_sha() -> str:
     return git("rev-parse", "--short", "HEAD") or "unknown"
 
 
+def current_branch() -> str:
+    return git("rev-parse", "--abbrev-ref", "HEAD") or ""
+
+
+def default_branch() -> str:
+    """The branch everything integrates into. Asked of the repository, never assumed."""
+    ref = git("symbolic-ref", "--quiet", "refs/remotes/origin/HEAD")
+    if ref:
+        return ref.rsplit("/", 1)[-1]
+    for cand in ("main", "master"):
+        if git("rev-parse", "--verify", "--quiet", cand):
+            return cand
+    return "main"
+
+
+def merge_conflicts(target: str, branch: str) -> list[str]:
+    """Files that would conflict, decided WITHOUT touching the working tree.
+
+    A merge that starts and then aborts still leaves the operator in a repository they
+    did not expect. `git merge-tree` answers the same question in memory. Modern git
+    (2.38+) takes --write-tree and reports conflicted paths; older git prints a diff
+    where a conflict shows up as marker lines, so both forms are read here.
+    """
+    r = subprocess.run(["git", "merge-tree", "--write-tree", "--name-only", target, branch],
+                       capture_output=True, text=True)
+    if r.returncode == 0:
+        return []
+    if r.returncode == 1:
+        # Layout: tree oid, the conflicted paths, a blank line, then git's own prose
+        # ("Auto-merging …", "CONFLICT (content) …"). Only the paths are the answer;
+        # printing the prose as if it were a filename makes the report untrustworthy.
+        paths: list[str] = []
+        for line in r.stdout.splitlines()[1:]:
+            if not line.strip():
+                break
+            paths.append(line)
+        return paths
+
+    base = git("merge-base", target, branch)
+    if not base:
+        return ["(cannot determine a merge base — unrelated histories)"]
+    old = subprocess.run(["git", "merge-tree", base, target, branch],
+                         capture_output=True, text=True)
+    return ["(conflicting hunks — this git is too old to name the files)"] \
+        if "<<<<<<<" in old.stdout else []
+
+
 def repo_name() -> str:
     url = git("config", "--get", "remote.origin.url")
     if url:
@@ -1170,6 +1220,98 @@ class Sync:
             raw = raw[:-1]
         return raw[1:].split("|")
 
+    # -- branch discipline -------------------------------------------------
+
+    @property
+    def integration_branch(self) -> str:
+        """Where work lands. Configured, or asked of the repository — never assumed."""
+        return self.cfg.get("integrationBranch") or default_branch()
+
+    @property
+    def on_integration_branch(self) -> bool:
+        return current_branch() == self.integration_branch
+
+    def merge_log(self) -> tuple[Path, int]:
+        spec = self.cfg.get("mergeLog") or {}
+        return (self.root / (spec.get("file") or DEFAULT_MERGE_LOG),
+                int(spec.get("retentionDays") or DEFAULT_MERGE_RETENTION))
+
+    def merge_log_append(self, entry: dict[str, str] | None = None) -> Path:
+        """Append one merge, then compact anything past the retention window.
+
+        Two audiences, one file. An agent that just arrived needs the last few days in
+        enough detail to know what changed under it; nobody needs that detail from three
+        weeks ago, and a log that only grows stops being read — which is the same as not
+        having one. Compaction happens on write, so it needs no cron and no second command.
+        """
+        path, retention = self.merge_log()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        detailed, compacted = self._read_merge_log(path)
+
+        if entry is not None:
+            detailed.insert(0, entry)
+        cutoff = time.time() - retention * 86400
+        keep, aged = [], []
+        for e in detailed:
+            (keep if parse_iso(e.get("ts", "")) >= cutoff else aged).append(e)
+        compacted = [self._one_line(e) for e in aged] + compacted
+
+        path.write_text(self._render_merge_log(keep, compacted, retention))
+        return path
+
+    @staticmethod
+    def _one_line(e: dict[str, str]) -> str:
+        return (f"- {e.get('ts', '')[:10]} · `{e.get('key', '—')}` · {e.get('branch', '?')} → "
+                f"{e.get('target', '?')} · `{e.get('sha', '?')}` · {e.get('summary', '')}".rstrip())
+
+    @staticmethod
+    def _read_merge_log(path: Path) -> tuple[list[dict[str, str]], list[str]]:
+        if not path.exists():
+            return [], []
+        text = path.read_text()
+        body, _, tail = text.partition("\n## Compacted\n")
+        compacted = [l for l in tail.splitlines() if l.startswith("- ")]
+        entries: list[dict[str, str]] = []
+        for block in body.split("\n### ")[1:]:
+            lines = block.splitlines()
+            head = lines[0]
+            e = {"ts": "", "key": "—", "branch": "?", "target": "?", "sha": "?",
+                 "run": "?", "files": "?", "conflicts": "none", "summary": ""}
+            parts = [p.strip() for p in head.split("·")]
+            if parts:
+                e["ts"] = parts[0]
+            if len(parts) > 1:
+                e["key"] = parts[1].strip("`")
+            if len(parts) > 2 and "→" in parts[2]:
+                e["branch"], _, e["target"] = (x.strip() for x in parts[2].partition("→"))
+            if len(parts) > 3:
+                e["sha"] = parts[3].strip("`")
+            for l in lines[1:]:
+                for field in ("run", "files", "conflicts", "summary"):
+                    if l.startswith(f"- {field}: "):
+                        e[field] = l.split(": ", 1)[1]
+            entries.append(e)
+        return entries, compacted
+
+    @staticmethod
+    def _render_merge_log(entries: list[dict[str, str]], compacted: list[str],
+                          retention: int) -> str:
+        out = [MERGE_LOG_MARKER, "", "# Merge log", "",
+               f"Written by `agent_sync.py merge`. Entries newer than {retention} days keep "
+               "their detail; older ones are compacted to one line each on the next write. "
+               "Read it before starting work: it is the shortest answer to *what landed while "
+               "I was on my branch*.", ""]
+        for e in entries:
+            out += [f"### {e['ts']} · `{e['key']}` · {e['branch']} → {e['target']} · `{e['sha']}`",
+                    f"- run: {e['run']}",
+                    f"- files: {e['files']}",
+                    f"- conflicts: {e['conflicts']}",
+                    f"- summary: {e['summary']}", ""]
+        # The placeholder deliberately does not start with "- ": the reader counts list
+        # items, and an empty log that reports one compacted entry is a lie about history.
+        out += ["## Compacted", ""] + (compacted or ["_nothing older than the window yet_"])
+        return "\n".join(out) + "\n"
+
     def write_claim(self, key: str, holder: str | None) -> list[str]:
         """Write the claim through to git, or restore it. Surgical and reversible.
 
@@ -1178,6 +1320,17 @@ class Sync:
         exists to prevent. The previous cell text is stored in the lock file, so release
         restores what was there rather than an assumed default.
         """
+        # A claim is a statement about the integration branch, so it is only written
+        # there. Committed on a feature branch it is invisible to everyone until the
+        # merge — and it turns the shared roadmap into a file two branches both edit,
+        # which is a merge conflict on the one file that exists to prevent collisions.
+        # While the work is on a branch the holder lives in the coordination plane,
+        # where `status` and the board already read it.
+        if holder is not None and not self.on_integration_branch:
+            return [f"claim for `{key}` left in the coordination plane — this run is on "
+                    f"'{current_branch()}', not {self.integration_branch}. `status` shows the "
+                    f"holder to every agent; `merge` records the outcome."]
+
         notes: list[str] = []
         for path, spec in self._claim_targets(key):
             if spec.get("mode") != "cell":
@@ -1855,6 +2008,7 @@ def default_config(backend: str) -> dict[str, Any]:
         "claimTags": {},
         "gates": [],
         "mirror": {"enabled": False, "sources": []},
+        "mergeLog": {"file": DEFAULT_MERGE_LOG, "retentionDays": DEFAULT_MERGE_RETENTION},
     }
 
 
@@ -2829,6 +2983,120 @@ def cmd_whoami(_args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_merge(args: argparse.Namespace) -> int:
+    """Land a branch on the integration branch, and leave a record of what landed.
+
+    Every check here runs *before* anything is touched, because a merge that starts and
+    then aborts leaves the operator somewhere they did not ask to be. The conflict answer
+    comes from `git merge-tree`, which computes it in memory.
+    """
+    s = Sync()
+    branch = current_branch()
+    target = args.into or s.integration_branch
+
+    if not branch or branch == "HEAD":
+        raise Fail("detached HEAD — check out the branch you want to merge")
+    if branch == target:
+        raise Fail(f"already on {target} — there is no branch to merge. Work happens on a "
+                   f"branch so the integration branch stays somebody else's stable base")
+    dirty = [l for l in (git("status", "--porcelain") or "").splitlines()
+             if l and STATE_DIR.name not in l]
+    if dirty:
+        raise Fail(f"working tree is not clean ({len(dirty)} path(s)) — commit or stash first; "
+                   "a merge cannot tell your uncommitted work from the branch's")
+
+    git("fetch", "--quiet", "origin", target)
+    upstream = f"origin/{target}" if git("rev-parse", "--verify", "--quiet", f"origin/{target}") else target
+    behind = git("rev-list", "--count", f"{branch}..{upstream}")
+    changed = [l for l in (git("diff", "--name-only", f"{upstream}...{branch}") or "").splitlines() if l]
+    stat = git("diff", "--shortstat", f"{upstream}...{branch}") or "no changes"
+
+    print(f"{branch} → {target}")
+    print(f"  files changed  : {len(changed)}  ({stat.strip()})")
+    print(f"  {target} moved  : {behind or '0'} commit(s) since this branch started")
+
+    conflicts = merge_conflicts(upstream, branch)
+    if conflicts:
+        print("\n✗ this merge conflicts. Nothing was touched.")
+        for c in conflicts[:20]:
+            print(f"    · {c}")
+        print(f"\nNEXT: rebase or merge {target} into {branch} in your own branch, resolve there,")
+        print("  then run this again. The integration branch never carries a resolution nobody reviewed.")
+        return 1
+    print("  conflicts      : none")
+
+    others = {k: v for k, v in s.all_holders().items() if v != s.rid}
+    if others:
+        print("\n  other runs hold leases right now:")
+        for k, v in sorted(others.items()):
+            print(f"    · {v} holds {k}")
+        print("  Their work is not in this diff. If it touches the same files, they merge into "
+              "what you are about to land.")
+
+    if args.dry_run:
+        print("\n(dry run — nothing merged)")
+        return 0
+
+    if git("checkout", target) == "" and current_branch() != target:
+        raise Fail(f"could not check out {target}")
+    msg = args.message or f"Merge {branch}" + (f" — {args.key}" if args.key else "")
+    r = subprocess.run(["git", "merge", "--no-ff", "-m", msg, branch],
+                       capture_output=True, text=True)
+    if r.returncode != 0:
+        subprocess.run(["git", "merge", "--abort"], capture_output=True)
+        git("checkout", branch)
+        raise Fail(f"merge failed and was aborted; you are back on {branch}\n"
+                   f"  {(r.stderr or r.stdout).strip().splitlines()[-1] if (r.stderr or r.stdout).strip() else ''}")
+    sha = head_sha()
+    print(f"\n✓ merged as {sha}")
+
+    path = s.merge_log_append({
+        "ts": now_iso(), "key": args.key or "—", "branch": branch, "target": target,
+        "sha": sha, "run": s.rid, "files": f"{len(changed)} ({stat.strip()})",
+        "conflicts": "none", "summary": args.summary or "(no summary given)",
+    })
+    rel_log = path.relative_to(s.root)
+    git("add", str(rel_log))
+    subprocess.run(["git", "commit", "--quiet", "-m",
+                    f"docs(merges): record {branch} → {target}"], capture_output=True)
+    print(f"✓ recorded in {rel_log}")
+
+    for key in (s.held() or []):
+        s.release(key)
+        print(f"✓ released {key}")
+
+    if args.push:
+        out = subprocess.run(["git", "push", "origin", target], capture_output=True, text=True)
+        print(f"✓ pushed {target}" if out.returncode == 0
+              else f"✗ push failed: {(out.stderr or '').strip().splitlines()[-1:]}")
+    else:
+        print(f"\nNEXT: push {target}, or run `finish` to check every repository first.")
+    return 0
+
+
+def cmd_merges(args: argparse.Namespace) -> int:
+    """What landed while you were on your branch."""
+    s = Sync()
+    path, retention = s.merge_log()
+    if not path.exists():
+        print(f"no merge log yet at {path.relative_to(s.root)} — `merge` writes one")
+        return 0
+    if args.compact:
+        s.merge_log_append()          # same pass the writer runs, without a new entry
+        print("compacted anything past the retention window")
+    entries, compacted = s._read_merge_log(path)
+    print(f"{path.relative_to(s.root)} — {len(entries)} detailed (last {retention} days), "
+          f"{len(compacted)} compacted\n")
+    for e in (entries if args.all else entries[:args.limit]):
+        print(f"{e['ts']} · {e['key']} · {e['branch']} → {e['target']} · {e['sha']}")
+        print(f"    {e['summary']}")
+    if args.all and compacted:
+        print("\nolder:")
+        for line in compacted[:args.limit if not args.all else len(compacted)]:
+            print(f"  {line[2:]}")
+    return 0
+
+
 def build_parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(prog="agent_sync.py", description=__doc__.splitlines()[0])
     p.add_argument("--version", action="version", version=VERSION)
@@ -2849,6 +3117,19 @@ def build_parser() -> argparse.ArgumentParser:
     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)
+    mg = sub.add_parser("merge", help="land this branch on the integration branch, and record it")
+    mg.add_argument("--into", help="integration branch (default: config, else the repo's own)")
+    mg.add_argument("--key", help="the task id this branch delivered")
+    mg.add_argument("--summary", help="one line for the merge log — what landed")
+    mg.add_argument("--message", help="merge commit message")
+    mg.add_argument("--push", action="store_true", help="push the integration branch afterwards")
+    mg.add_argument("--dry-run", action="store_true", help="check conflicts and stop")
+    mg.set_defaults(fn=cmd_merge)
+    ml = sub.add_parser("merges", help="what landed while you were on your branch")
+    ml.add_argument("--all", action="store_true", help="include the compacted tail")
+    ml.add_argument("--limit", type=int, default=10, help="how many detailed entries to print")
+    ml.add_argument("--compact", action="store_true", help="run the compaction pass now")
+    ml.set_defaults(fn=cmd_merges)
     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",