diff --git a/AGENTS.md b/AGENTS.md index 2de74de..396ecab 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,8 +13,9 @@ loop around `kraken.py next-action` — **no deltas either**. ## Your operating contract — read these, then follow them 1. [`PROTOCOL.md`](PROTOCOL.md) — the normative wire contract (`kraken-protocol/9`): the - label state machine, the hidden `` markers, the claim algorithm, - delivery, and the authorization boundaries. Agent-agnostic already. + state record and the label state machine it projects, the hidden + `` markers, the claim algorithm, delivery, and the authorization + boundaries. Agent-agnostic already. 2. [`skills/unleash/SKILL.md`](skills/unleash/SKILL.md) — how a worker *executes* that contract. **Read it in full and follow it.** Every transition runs through the bundled [`skills/unleash/kraken.py`](skills/unleash/kraken.py) — the **same** program the diff --git a/PROTOCOL.md b/PROTOCOL.md index d7a9a3f..2c0e38b 100644 --- a/PROTOCOL.md +++ b/PROTOCOL.md @@ -107,7 +107,7 @@ issue timeline is the log. | Label | State | Suggested color | | --- | --- | --- | -| `kraken-task` | queued (when no other state label is present) | `1D76DB` blue | +| `kraken-task` | queue membership (§1), not a state — a task wearing no other state label *shows* as queued | `1D76DB` blue | | `in-progress` | claimed by a worker and being executed | `FBCA04` yellow | | `needs-decision` | blocked on the operator's decision | `D93F0B` red | | `awaiting-merge` | delivered, waiting for review + merge | `0E8A16` green | @@ -610,7 +610,12 @@ therefore no version handshake between the two sides. The verdict of a transition is an exit status, never text (§5.3). Matching the reference implementation's codes — `0` success, `10` lost CAS or lost lease, `11` not clear, `20` transport failure (state unknown) — is RECOMMENDED, so a driver -written against one conforming worker can drive another. +written against one conforming worker can drive another. Those four cover every +transition this contract defines; a code outside them can only come from an +ergonomic above it (below), and a driver MUST NOT read one as a transition +verdict. The reference implementation's are `3` (nothing startable) and `13` (the +repo has no such `project:` label), both reported by the claim loop and the +envelope rather than by any transition. An implementation MAY offer ergonomics above the wire contract, which are **not** part of it and which a conforming worker may ignore entirely: the reference implementation diff --git a/README.md b/README.md index a5cd725..8f29d54 100644 --- a/README.md +++ b/README.md @@ -362,6 +362,18 @@ delivered, the result with the acceptance check executed, and the close: A kraken task issue timeline: claim comment, assumptions, draft PR link, result comment, and close + + +## FAQ + +
+Doesn't this already exist — Copilot, Claude cloud agents, CI? + +Partly, and for a single GitHub repo with no local services those are simpler — +say so and use them. Kraken's edge is the prepared environment, GitLab/private +work repos, and a fan-out of named, audited workers. The honest side-by-side can +be found below. + ## Why not just use X? | Alternative | Coordination primitive | Infra required | Agent-agnostic | Prefer it when | @@ -412,16 +424,6 @@ when** your automation is CI-shaped and a disposable runner is the correct environment; prefer Kraken when the environment is the point and you want no lock to a single runner or vendor. -## FAQ - -
-Doesn't this already exist — Copilot, Claude cloud agents, CI? - -Partly, and for a single GitHub repo with no local services those are simpler — -say so and use them. Kraken's edge is the prepared environment, GitLab/private -work repos, and a fan-out of named, audited workers. The honest side-by-side is -[Why not just use X?](#why-not-just-use-x) above. -
diff --git a/skills/unleash/DELIVERY.md b/skills/unleash/DELIVERY.md index 2eddec3..66b1c8a 100644 --- a/skills/unleash/DELIVERY.md +++ b/skills/unleash/DELIVERY.md @@ -10,8 +10,8 @@ task's **notes** say otherwise, every task ends as a pushed branch and a draft P ## The branch **First, check whether this task already has one.** A task can come back to the queue -after it was delivered — I bounce a review by commenting the feedback and removing -`awaiting-merge`, and the task requeues with its whole thread. The `brief.body` and the +after it was delivered — I bounce a review by commenting the feedback, and that comment +alone requeues the task with its whole thread. The `brief.body` and the issue thread will show the earlier delivery and its PR. When they do, **continue on that branch and update that PR**: opening a second branch and a second draft PR for one task splits the review and leaves an orphan PR behind. diff --git a/skills/unleash/SKILL.md b/skills/unleash/SKILL.md index 7113dc0..9c48913 100644 --- a/skills/unleash/SKILL.md +++ b/skills/unleash/SKILL.md @@ -204,8 +204,10 @@ instead. - Invoking this skill is my durable authorization to: (a) manage issues **in the coordination repo** — labels and comments, never closing or reopening a task ("done" is *delivered for review*; closing is mine or the merge's) — - and your own claim ref under `refs/kraken/claims/`: create, renew and delete your own - lease, and take over one that has expired; + and the refs under `refs/kraken/`: your own claim ref under `refs/kraken/claims/` + (create, renew and delete your own lease, and take over one that has expired), and the + state record under `refs/kraken/state/` for the task you hold, which every transition + that ends your turn writes; (b) in the task's work repo, **deliver as [`DELIVERY.md`](DELIVERY.md) describes**: create work branches, commit to them with the attribution trailers, push them, and open draft PRs.