@ssheleg/agent-sync 1.4.1 → 1.4.3

package/CHANGELOG.md

@@ -3,6 +3,43 @@
 All notable changes to this project are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 1.4.3 — 2026-08-03
+
+### Fixed
+
+- **The `pipeline.json` example did not validate against the schema it cited.** It
+  claimed `task-pipeline`'s `pipeline.schema.json` permitted it while carrying a
+  string `id`, a `title` where the schema says `name`, and no `state` at all — which
+  is required. Anyone who copied it got a config `task-pipeline` rejects. The example
+  is now checked against that schema.
+- **Gate texts stated only this plugin's half.** Each `check` read as if it replaced
+  the stage's own criteria, so a host that copied the block silently dropped them —
+  stage 9 lost the propagation sweep and the documentation gate, stage 10 lost the
+  ladder walk and the evidence rule. Every `check` is now written as
+  *`<the stage's own criteria>` **AND** agent-sync's clause*.
+- **Stage 9 pointed at the wrong doctrine.** `task-pipeline:artifacts` is the
+  artifact-layout reference; that stage runs on `task-pipeline:documentation` and
+  `task-pipeline:gates` since the documentation track landed.
+- **`guardedFiles` did not cover what the pipeline now creates.** `docs/DOCMAP.md`
+  holds a project's registers, propagation matrix and ratchet floors, and
+  `docs/superpowers/retro.md` is capped at ten standing instructions — so a
+  concurrent write there drops a lesson instead of conflicting visibly. Both are
+  guarded, with the reasoning in `references/pipeline-binding.md` because the config
+  schema keeps `agent-sync.json` to known keys.
+
+## 1.4.2 — 2026-07-30
+
+### Changed
+- **The README's hook section now opens with what it actually is:** the only part
+  of this plugin that executes code on your machine, four bash scripts with 15-20s
+  timeouts, run by Claude Code on named events, with a pointer to `SECURITY.md`
+  for every path the install touches. The facts were already in `SECURITY.md`; the
+  README described the hooks' behavior without ever framing them as the security
+  surface a reader should check first.
+
+### Added
+- **`displayName`** ("Agent Sync") in both manifests.
+
 ## 1.4.1 — 2026-07-30
 
 ### Fixed

package/README.md

@@ -361,8 +361,15 @@ Adding one: read
 
 ## Enforcement hooks
 
-Installed with the Claude Code plugin. Every hook exits immediately in projects without
-`.claude/agent-sync.json`, so installing globally changes nothing elsewhere.
+**This is the only part of the plugin that executes code on your machine.** Everything
+else — the skill, its references — is text an agent reads. Four bash scripts, bundled in
+the plugin and run by Claude Code on the events below, each with a timeout (15–20s) so a
+hung script cannot stall a session. Read them before installing: they are short, and
+[`SECURITY.md`](SECURITY.md) lists every path the install touches and why.
+
+Every hook exits immediately in projects without `.claude/agent-sync.json`, so installing
+globally changes nothing elsewhere. The `PreToolUse` guard can **deny** a tool call and
+never grants one that would otherwise be denied.
 
 | Hook | Runs | Effect |
 |---|---|---|
@@ -454,6 +461,13 @@ Security reports: [SECURITY.md](SECURITY.md).
 bundle, which installs the whole family for Claude Code, Cursor, Codex and 70+
 other agents with one command.
 
+## Author
+
+Built by ssheleg — [sshlg.me](https://sshlg.me)
+
+- X / Twitter — [@sshlg93](https://x.com/sshlg93)
+- Telegram — [@sshlg](https://t.me/sshlg)
+
 ## License
 
 MIT © ssheleg

package/agent-sync.example.json

@@ -17,7 +17,9 @@
   "guardedFiles": [
     "docs/DECISIONS.md",
     "docs/OPEN_QUESTIONS.md",
-    "docs/ROADMAP.md"
+    "docs/ROADMAP.md",
+    "docs/DOCMAP.md",
+    "docs/superpowers/retro.md"
   ],
   "claimTags": {
     "docs/ROADMAP.md": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/agent-sync",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "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"
@@ -38,7 +38,10 @@
   "bugs": {
     "url": "https://github.com/ssheleg/agent-sync/issues"
   },
-  "author": "ssheleg",
+  "author": {
+    "name": "ssheleg",
+    "url": "https://x.com/sshlg93"
+  },
   "license": "MIT",
   "engines": {
     "node": ">=18"

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

@@ -1,9 +1,11 @@
 {
   "name": "agent-sync",
-  "version": "1.4.1",
+  "displayName": "Agent Sync",
+  "version": "1.4.3",
   "description": "Coordination layer for multi-agent repositories \u2014 leases with TTL, race-free ID reservation, a run journal, a cross-repo signal feed and a generated board, over a pluggable knowledge cloud.",
   "author": {
-    "name": "ssheleg"
+    "name": "ssheleg",
+    "url": "https://x.com/sshlg93"
   },
   "homepage": "https://github.com/ssheleg/agent-sync",
   "repository": "https://github.com/ssheleg/agent-sync",

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

@@ -4,7 +4,7 @@ description: "Use when several coding agents work one repository at the same tim
 compatibility: "Requires the task-pipeline skill for its stages (npx sshlg-skills install). Needs python3 3.9+ (stdlib only, HTTP included - nothing to pip install) and bash for the hooks. The knowledge backend is configured per project; with none configured it degrades to git-file leases. Enforcement hooks are Claude Code only - on other agents the same checks run as a self-check."
 license: MIT
 metadata:
-  version: "1.4.1"
+  version: "1.4.3"
   author: ssheleg
 ---
 

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

@@ -24,30 +24,65 @@
 ## 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:
+Add `agent-sync` to `skills[]` on the six stages that call it, and append its
+clause to each of those stages' existing `gate.check`:
 
 ```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" } }
+    { "id": 0,  "state": "intake",      "name": "Intake grill",
+      "skills": ["task-pipeline:grill", "agent-sync"],
+      "gate": { "type": "manual", "check": "<the stage's own criteria> AND the lease for this task is held before the brief is committed" } },
+    { "id": 3,  "state": "spec",        "name": "Spec",
+      "skills": ["task-pipeline:spec", "agent-sync"],
+      "gate": { "type": "manual", "check": "<the stage's own criteria> AND every id the spec writes was reserved first" } },
+    { "id": 4,  "state": "plan",        "name": "Plan",
+      "skills": ["task-pipeline:planning", "agent-sync"],
+      "gate": { "type": "auto",   "check": "<the stage's own criteria> AND no two parallel tasks write one file" } },
+    { "id": 5,  "state": "dev",         "name": "Dev",
+      "skills": ["task-pipeline:build", "agent-sync"],
+      "gate": { "type": "auto",   "check": "<the stage's own criteria> AND the lease is live and submodule pointers are current" } },
+    { "id": 9,  "state": "docs-wiki",   "name": "Docs + wiki",
+      "skills": ["task-pipeline:documentation", "task-pipeline:gates", "agent-sync"],
+      "gate": { "type": "auto",   "check": "<the stage's own criteria — the propagation sweep and a green documentation gate with its ratchets printed> AND the board is regenerated with no mirror drift" } },
+    { "id": 10, "state": "acceptance",  "name": "Acceptance",
+      "skills": ["task-pipeline:acceptance", "agent-sync"],
+      "gate": { "type": "manual", "check": "<the stage's own criteria> AND every lease is released and every claim tag written through" } }
   ]
 }
 ```
 
+**Three things in that JSON are contract, not style.** `state` is **required** by
+`pipeline.schema.json`, `id` is an **integer**, and the human label is `name` — not
+`title`. This example carried `"id": "0"` with a `title` and no `state` until
+2026-08-03, while claiming the schema permitted it; anyone who copied it got a config
+`task-pipeline` rejects.
+
+**And the gate text EXTENDS, never replaces.** Each `check` above is
+*`<the stage's own criteria>` **AND** agent-sync's clause* — written out that way on
+purpose. An earlier version of this file stated only agent-sync's half, so a host
+that copied it silently dropped the stage's real gate: stage 9 lost the propagation
+sweep and the documentation gate, stage 10 lost the ladder walk and the evidence
+rule.
+
 Stages 1, 2, 6, 7 and 8 keep their own `skills[]`; `agent-sync` only journals there,
 which needs no wiring.
 
+## What must be guarded
+
+`guardedFiles` is every shared file two agents could write in the same minute — and
+since the pipeline's documentation track it is longer than the registers:
+
+| File | Why it is shared state |
+|---|---|
+| the decision register (`docs/DECISIONS.md` or `docs/adr/`) | append-only; a concurrent write loses an entry |
+| `docs/OPEN_QUESTIONS.md`, `docs/ROADMAP.md` | the same |
+| **`docs/DOCMAP.md`** | seeded into every project the pipeline touches; holds the registers, the propagation matrix and the ratchet floors. Losing it loses the map |
+| **`docs/superpowers/retro.md`** | capped at ten standing instructions, so a concurrent write silently **drops a lesson** instead of conflicting visibly |
+
+The schema keeps `agent-sync.json` to known keys, which is why this reasoning lives
+here and not as a comment in the config.
+
 ## Preflight
 
 `task-pipeline` is required. When it is absent, print the install line and **stop** —

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.4.1"
+VERSION = "1.4.3"
 
 CONFIG_PATH = Path(".claude/agent-sync.json")
 ENV_FILE = Path(".env.agent-sync")