flockwork 0.1.0__py3-none-any.whl

flockwork-0.1.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: flockwork
+Version: 0.1.0
+Summary: A worker swarm whose entire coordination substrate is git itself.
+Author: jlam
+License: Apache-2.0
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# flockwork — the swarm that runs like clockwork
+
+**flockwork** is a worker swarm whose **entire coordination substrate is
+git itself**: no server, no database, no queue daemon — a shared origin's
+refs under `refs/swarm/` carry task briefs, claims, returns, and
+verdicts, and every guarantee (exactly-once work, honest outcomes,
+bounded retries) reduces to a git property you can verify with
+`ls-remote` and `cat-file`. This repo doubles as its own substrate
+(**D-INREPO**): the machinery lives in `l2/inrepo.py`, and workers
+coordinate through refs on the project's own origin. (The code, CLI, and
+repo internals keep the working name `swarmo` — same product.)
+
+> **New to swarms, git refs, or both?** `docs/00-ORIENTATION.md` is the
+> zero-context orientation: the project in 15 sentences, how the pieces
+> relate, which doc to open for which job, what a verdict means, and a
+> full glossary.
+
+Run it yourself in five minutes: `QUICKSTART.md` (scratch board, zero
+model spend).
+
+## The refs model (one diagram)
+
+```
+  origin  (any git remote — a bare repo; e.g. a local bare repo under /tmp)
+  ├── refs/heads/main                      the product: landed fixes
+  └── refs/swarm/*                         the coordination lane
+      ├── specs/<task>      the brief      operator seeds it (root commit,
+      │                                    body carries the task + `verify:` line)
+      ├── claims/<task>     the lease      create-once CAS push — exactly one
+      │                                    worker wins; duplicates are rejected
+      ├── tasks/<task>      the return     points at the fix, on main's lineage
+      ├── verdicts/<task>   the outcome    root commit: task/attempt/fixed/host/rc
+      └── archive/<kind>/<task>@<att>      dead attempts, preserved (never deleted)
+```
+
+Claim and verdict commits are ROOT commits, so their objects never
+leak into consumer clones or fetches; the whole lane is evictable with
+a one-transaction namespace delete.
+
+## The five verbs
+
+1. **seed** — the operator declares a task: `python3 l2/inrepo.py seed
+   spec.json` pushes `refs/swarm/specs/<task>` carrying the brief; a
+   `verify:` line in the brief is the task's oracle.
+2. **claim** — a worker leases a task: a create-once CAS push
+   (`push --force-with-lease=<ref>:`) to `refs/swarm/claims/<task>`.
+   Git itself rejects the second claim — exactly-once is not a lock
+   file, it is the ref database.
+3. **work** — the claim winner clones the origin, dispatches the brief
+   to the model, and the `verify:` line (or host pytest) judges the
+   tree. A pass lands the fix on main and points the return ref at it;
+   a fail touches nothing but the verdict.
+4. **verdict** — the attempt closes as a root commit at
+   `refs/swarm/verdicts/<task>`: `fixed: true|false`, host, dispatch
+   and oracle exit codes. The refs alone must separate environmental
+   deaths from honest merit failures.
+5. **evict** — `sweep`/`reconcile` archive dead attempts to
+   `refs/swarm/archive/<kind>/<task>@<att>` and free the live refs in
+   one atomic transaction, so the task re-enters the queue; eviction
+   is bounded (one heir per death, then a final honest `fixed:false`).
+
+## The honesty laws (what keeps the lane truthful)
+
+Claim and verdict commits are ROOT commits so their objects never leak
+into consumer fetches, and eviction is a one-transaction namespace
+delete. Four honesty laws keep the lane truthful. **Claim-loss
+honesty:** a failed claim is classified — a lost race (`! [rejected]
+(stale info)`) is healthy contention to re-scan, a structurally broken
+origin is reported — and bounded by `SWARM_WORKER_MAX_FAILS` so a sick
+host exits instead of spinning. **Law-freshness gate:** each worker
+refuses to claim when its running `l2/inrepo.py` blob differs from
+origin main's published copy, so stale code never writes to the
+substrate. **Environmental honesty:** a dispatch death (timeout, or
+failure with an empty tree) is never recorded as a fix — the attempt is
+archived and requeued to one heir, then closed with a final honest
+`fixed:false`. **Main-push honesty:** a fix is a fix only if its commit
+actually lands on main, else the task requeues under the same bounded
+machinery — and a change that fails its oracle never lands at all: a
+merit failure publishes only its final honest verdict, never to main.
+
+**No-default-origin law:** there is **no** default `SWARM_ORIGIN`. Every
+origin resolution is explicit-arg > `SWARM_ORIGIN` at call time > the
+import-time `ORIGIN` > a typed `OriginUnsetError` naming the fix. A
+write or read leg with no origin anywhere refuses *before* any git/ssh
+contact, so a forgotten config can never push into a production board.
+
+`python3 l2/inrepo.py audit` is the board's health instrument
+(`h1_pass`: every live claim has a matching return + verdict);
+`reconcile` is the TTL backstop for stale claims; `correction-graph`
+reconstructs the multi-model attempt graph from refs alone.
+
+## Observability (opt-in, zero wire change)
+
+- `FLOCKWORK_METRICS=1` turns on a JSONL observer over the lane's own
+  results; `python3 -m l2.metrics [files]` summarizes counts,
+  reject-rate, and claim→verdict latency. `--dora` adds the DORA five
+  over the same stream.
+- `FLOCKWORK_KEEP_TREE=1` preserves a merit-failed attempt's tree so a
+  failure is auditable.
+
+## Layout
+
+```
+l2/inrepo.py      the lane law: seed/claim/work/verdict/evict + review/gate + audit
+l2/metrics.py     the opt-in JSONL observer + DORA judge
+l2/gates.py       the verdict-count gate (n-of-m reviewer agreement)
+l2/refschema.py   minimal required-field schemas; loud typed refusals
+tests/            the suite (hermetic: scratch boards, no network, no default origin)
+demo/             the scripted end-to-end (owner_test.sh) + the raw CAS demo
+docs/             00-ORIENTATION (start here), GATES, SCRATCH-BOARDS
+```
+
+## License
+
+Apache-2.0. See `LICENSE`.

flockwork-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+flockwork-0.1.0.dist-info/licenses/LICENSE,sha256=noRx8qE5pk5Hg2SX-f9BIaaL8Vq5qDK5zb6r8ray45g,8615
+l2/__init__.py,sha256=hgSLVWfzYABuapdnJBmIriwZFcIsoUB_JtBd0WdBcOQ,208
+l2/gates.py,sha256=-MbcD-NiN9L4eTZIH5dkGY-rcbGd1UZoMRjqyYFR_jQ,12716
+l2/inrepo.py,sha256=z3mwX3-Ru2y-PM_biw-TD9H8aTD04CL5D-rPvhe3jZo,88863
+l2/metrics.py,sha256=ahxnPqeyeeC49s5vh2jXV4wY6x4mBbdk6rUrd-EuwUs,14515
+l2/refschema.py,sha256=2CcMygaT26R6jUahChVrDFBx5IO5JAOkLzToq0LR2mw,4653
+flockwork-0.1.0.dist-info/METADATA,sha256=r0pLhbaIY2ycQFheY-3OfmRoqTT-TjFycyFJQbZkf64,6448
+flockwork-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+flockwork-0.1.0.dist-info/entry_points.txt,sha256=FjyoKj09jziAHjdNwW9mzuvr21v-ME12lvHX9LNxLqM,45
+flockwork-0.1.0.dist-info/top_level.txt,sha256=Wa1GMFfGQKaWYK7qyOSbr7jav5_aJkEpJloKgx66FUg,3
+flockwork-0.1.0.dist-info/RECORD,,

flockwork-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

flockwork-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+flockwork = l2.inrepo:main

flockwork-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,162 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by the
+      copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the legal entity that controls or is
+      controlled by such Legal Entity and any entities that control or are
+      controlled by such Legal Entity, or are under common control with such Legal
+      Entity. For the purposes of this definition, "control" means (i) the power,
+      direct or indirect, to cause the direction or management of such Legal
+      Entity, whether by contract or otherwise, or (ii) ownership of fifty percent
+      (50%) or more of the outstanding shares, or (iii) beneficial ownership.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received for inclusion in
+      the Work by the copyright owner or other entity authorized to grant
+      such rights on behalf of the copyright owner.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the
+      Work, where such license applies to patent claims infringed by
+      the Work or any Contribution incorporated in the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the
+      Licensor, except as required for reasonable and customary use in
+      describing the origin of the Work and reproducing the
+      inclusion of the Work in derivative works.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise, unless
+      required by applicable law (such as deliberate and gross
+      negligence) or agreed to in writing, shall any Contributor be liable
+      to You for damages, including any direct, indirect, special, incidental,
+      or consequential damages of any character arising from the use of or
+      inability to use the Work (or any other breach of this License), even
+      if advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing the
+      Work or Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other liability
+      obligations and/or rights consistent with this License. However, in
+      accepting such obligations, You act on Your own behalf, on Your sole
+      responsibility, not on behalf of any Contributor.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. Don't include
+      the brackets!  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included in the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 jlam
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

flockwork-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+l2

l2/__init__.py

@@ -0,0 +1,5 @@
+"""flockwork lane — the git-refs coordination substrate.
+
+The CLI lives in l2/inrepo.py; the opt-in observer in l2/metrics.py;
+the verdict-count gate in l2/gates.py; the ref schemas in l2/refschema.py.
+"""

l2/gates.py

@@ -0,0 +1,325 @@
+#!/usr/bin/env python3
+"""flockwork verdict-count gate — n-of-m independent verdicts flip an
+integration ref (docs/GATES.md; INT-081 bridge, INT-085b pilot 1).
+
+Design landed through flockwork itself (pilot wave A); this module is
+its implementation. Self-contained on purpose: stdlib only, its own
+git plumbing, no l2 imports — the gate must be liftable to any lane
+without carrying the wire's law file (the lawgate lone-law lesson).
+
+Substrate laws it reuses, never redefines:
+  - create-once CAS: `git push --force-with-lease=<ref>:` (empty lease
+    base) — the ref database decides races, exactly like claim_detail.
+  - the @-law: per-instance refs are `<base>/<task>@<instance>` (the
+    heirs_count archive shape); the subpath form is illegal beside a
+    live leaf ref (git D/F conflict).
+  - JSON-event prints: one json.dumps line per operation, like the kit.
+
+Verdict body schema (docs/GATES.md §2 — the schema IS the instruction;
+a body failing any check is not a verdict and is never counted):
+
+    review-verdict
+    task: <task>
+    reviewer: <reviewer>
+    outcome: agree|veto
+    evidence: <a git ref the reviewer examined>
+
+The gate reads n/m from the task's spec body (`n: <int>` / `m: <int>`
+lines), counts valid reviewer verdicts under
+refs/swarm/verdicts/<task>@*, and fires iff count(agree)==n AND
+count(veto)==0 AND every counted verdict's evidence ref resolves. The
+flip writes refs/swarm/integrated/<task> create-once; an existing flip
+makes any later gate run an honest idempotent no-op.
+"""
+import json
+import os
+import subprocess
+import sys
+
+try:
+    import refschema
+except ImportError:  # loaded by path (tests, drivers): resolve the sibling
+    try:
+        sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+        import refschema
+    except ImportError:
+        # staged alone (the lawgate lone-law lesson): the gate keeps its
+        # own inline §2 checks below — same refusals, no module typing.
+        refschema = None
+
+LAW = "docs/GATES.md"
+
+
+def sh(cmd, cwd=None, inp=None, timeout=120):
+    return subprocess.run(cmd, cwd=cwd, input=inp, capture_output=True,
+                          text=True, timeout=timeout)
+
+
+def ok(r):
+    return r.returncode == 0
+
+
+def git(*args, cwd=None, inp=None):
+    return sh(["git", *args], cwd=cwd, inp=inp)
+
+
+class OriginUnsetError(RuntimeError):
+    """No origin to talk to: no explicit orig and SWARM_ORIGIN unset.
+    A config error, never a silent write (WQ-093, 2026-10-03). Kept
+    name/shape-identical to l2/inrepo.py's — this module is
+    deliberately self-contained (no l2 imports), so the two classes
+    are textual twins by law, not by import."""
+
+
+def origin():
+    """The gate's board: explicit orig > SWARM_ORIGIN. The old default
+    (the literal remote name "origin" — whatever the cwd clone points
+    at) was a silent write target of the same footgun family as
+    inrepo's production default; there is no default now."""
+    o = os.environ.get("SWARM_ORIGIN")
+    if not o:
+        raise OriginUnsetError(
+            "no origin: export SWARM_ORIGIN=<board-url> (or pass "
+            "orig=) — there is no default origin (WQ-093, 2026-10-03: "
+            "the old 'origin' remote-name default pushed gate writes "
+            "to whatever the cwd clone points at)"
+        )
+    return o
+
+
+def emit(event):
+    print(json.dumps(event), flush=True)
+    return event
+
+
+def commit_tree(*args, cwd=None):
+    """Empty-tree commit carrying a body; its sha is pushable from cwd
+    (the object store lives in the repo the process runs in — the
+    test_claim_loss lesson)."""
+    t = git("hash-object", "-t", "tree", "/dev/null", cwd=cwd)
+    if not ok(t):
+        raise RuntimeError(f"tree: {t.stderr.strip()[:120]}")
+    c = git("commit-tree", t.stdout.strip(), "-m", "\n".join(args),
+            cwd=cwd)
+    if not ok(c):
+        raise RuntimeError(f"commit-tree: {c.stderr.strip()[:120]}")
+    return c.stdout.strip()
+
+
+def push_sha_ref(sha, ref, orig, cwd=None):
+    """Create-once CAS push. Returns (pushed, rejected, stderr)."""
+    r = git("push", orig, f"--force-with-lease={ref}:", f"{sha}:{ref}",
+            cwd=cwd)
+    return ok(r), not ok(r), (r.stderr or "")
+
+
+def ref_exists(orig, ref):
+    r = git("ls-remote", "--exit-code", orig, ref)
+    return ok(r)
+
+
+# --------------------------------------------------------------- verdicts
+
+
+def _check_name(kind, name):
+    """Refname safety: '@' is the archive-marker separator (an @-named
+    instance would collide with the @-law parse), '/' would make the
+    instance a path (and a task a namespace)."""
+    if not name or "@" in name or "/" in name:
+        return f"{kind} name must be nonempty and free of '@' and '/': {name!r}"
+    return None
+
+
+def parse_review_verdict(body, task, reviewer):
+    """docs/GATES.md §2 schema check. Returns (fields, error). The
+    schema's definition of record is l2/refschema.py (the schema IS the
+    instruction, WQ-054); this delegation keeps one implementation, the
+    inline body below is the staged-alone fallback."""
+    if refschema is not None:
+        fields, errs = refschema.validate_review_verdict(body, task,
+                                                         reviewer)
+        return fields, ("; ".join(errs) if errs else None)
+    lines = body.strip().splitlines()
+    if not lines or lines[0].strip() != "review-verdict":
+        return None, "not a review-verdict object"
+    fields = {}
+    for ln in lines[1:]:
+        if ": " in ln:
+            k, v = ln.split(": ", 1)
+            fields[k.strip()] = v.strip()
+    if fields.get("task") != task:
+        return None, "task field mismatch"
+    if fields.get("reviewer") != reviewer:
+        return None, "reviewer field mismatch"
+    if fields.get("outcome") not in ("agree", "veto"):
+        return None, "outcome not agree|veto"
+    if not fields.get("evidence"):
+        return None, "evidence missing"
+    return fields, None
+
+
+def review_verdict(task, reviewer, outcome, evidence, orig=None, cwd=None):
+    """Create-once reviewer verdict at refs/swarm/verdicts/<task>@<reviewer>."""
+    orig = orig or origin()
+    err = _check_name("task", task) or _check_name("reviewer", reviewer)
+    if err:
+        return emit({"event": "review_verdict", "task": task,
+                     "reviewer": reviewer, "pushed": False,
+                     "refused": True, "reason": err})
+    if outcome not in ("agree", "veto"):
+        return emit({"event": "review_verdict", "task": task,
+                     "reviewer": reviewer, "pushed": False,
+                     "refused": True,
+                     "reason": "outcome must be agree|veto"})
+    ref = f"refs/swarm/verdicts/{task}@{reviewer}"
+    body = (f"review-verdict\ntask: {task}\nreviewer: {reviewer}\n"
+            f"outcome: {outcome}\nevidence: {evidence}\n")
+    sha = commit_tree(body, cwd=cwd)
+    pushed, rejected, stderr = push_sha_ref(sha, ref, orig, cwd=cwd)
+    return emit({
+        "event": "review_verdict", "task": task, "reviewer": reviewer,
+        "outcome": outcome, "ref": ref, "sha": sha[:12],
+        "pushed": pushed, "rejected": rejected and not pushed,
+        "reason": None if pushed else stderr.strip()[:200],
+    })
+
+
+# -------------------------------------------------------------------- gate
+
+
+def _spec_nm(orig, task):
+    """n and m from the spec body's `n: <int>` / `m: <int>` lines."""
+    fr = git("fetch", "-q", orig, f"refs/swarm/specs/{task}")
+    if not ok(fr):
+        raise RuntimeError(f"spec fetch: {fr.stderr.strip()[:160]}")
+    body = git("log", "-1", "--format=%B", "FETCH_HEAD").stdout
+    n = m = None
+    for ln in body.splitlines():
+        s = ln.strip()
+        if s.startswith("n:"):
+            n = int(s[2:].strip())
+        elif s.startswith("m:"):
+            m = int(s[2:].strip())
+    if n is None or m is None:
+        raise RuntimeError(f"spec {task} carries no n:/m: lines")
+    return n, m
+
+
+def _reviewer_refs(orig, task):
+    r = git("ls-remote", orig, f"refs/swarm/verdicts/{task}@*")
+    if not ok(r):
+        raise RuntimeError(f"board read: {r.stderr.strip()[:160]}")
+    out = []
+    for ln in r.stdout.splitlines():
+        if ln.strip():
+            sha, ref = ln.split()
+            out.append((ref, sha))
+    return out
+
+
+def _read_ref_body(orig, sha_or_ref):
+    """Commit message body of a sha (the house verdict-read: %B, never
+    raw cat-file — the commit header is not the schema)."""
+    r = git("log", "-1", "--format=%B", sha_or_ref)
+    return r.stdout if ok(r) else None
+
+
+def verdicts(orig, task):
+    """Parsed reviewer verdicts for task: (reviewer, outcome, evidence,
+    invalid_reason or None, sha). Applies the full §2 schema."""
+    out = []
+    for ref, sha in _reviewer_refs(orig, task):
+        reviewer = ref.rsplit("@", 1)[1]
+        body = _read_ref_body(orig, sha)
+        fields, err = (None, f"unreadable object {sha[:12]}")
+        if body is not None:
+            fields, err = parse_review_verdict(body, task, reviewer)
+        if fields is None:
+            out.append((reviewer, None, None, err, sha))
+        else:
+            out.append((reviewer, fields["outcome"], fields["evidence"],
+                        None, sha))
+    return out
+
+
+def flip(task, agreed, evidence=None, n=None, m=None, orig=None, cwd=None):
+    """Create-once CAS flip of refs/swarm/integrated/<task>. Returns the
+    push result dict (property 4's referee). evidence/n/m resolve from
+    the board when not given (first agreeing verdict's evidence ref;
+    the spec's n:/m: lines)."""
+    orig = orig or origin()
+    if n is None or m is None:
+        n, m = _spec_nm(orig, task)
+    if evidence is None:
+        vs = verdicts(orig, task)
+        agree = [v for v in vs if v[1] == "agree"]
+        if not agree:
+            raise RuntimeError("flip with no agreeing verdict to cite")
+        evidence = agree[0][2]
+    ref = f"refs/swarm/integrated/{task}"
+    body = (f"integrated\ntask: {task}\nn: {n}\nm: {m}\n"
+            f"agreed: {' '.join(agreed)}\nevidence: {evidence}\n")
+    sha = commit_tree(body, cwd=cwd)
+    pushed, rejected, stderr = push_sha_ref(sha, ref, orig, cwd=cwd)
+    return {"event": "flip", "task": task, "ref": ref, "sha": sha[:12],
+            "pushed": pushed,
+            "rejected": rejected and not pushed,
+            "reason": None if pushed else stderr.strip()[:200]}
+
+
+def gate(task, orig=None, cwd=None):
+    """The gate: count, check evidence, fire iff agree==n and veto==0.
+    Idempotent: an existing integration ref is an honest no-op."""
+    orig = orig or origin()
+    intref = f"refs/swarm/integrated/{task}"
+    if ref_exists(orig, intref):
+        return emit({"event": "gate", "task": task,
+                     "already_integrated": True, "fired": False,
+                     "flipped": False})
+    n, m = _spec_nm(orig, task)
+    vs = verdicts(orig, task)
+    agree = [v for v in vs if v[1] == "agree"]
+    veto = [v for v in vs if v[1] == "veto"]
+    invalid = [v for v in vs if v[1] is None]
+    missing = [v for v in agree + veto
+               if not ref_exists(orig, v[2])]
+    fired = len(agree) == n and len(veto) == 0 and not missing
+    ev = {"event": "gate", "task": task, "n": n, "m": m,
+          "agree": len(agree), "veto": len(veto),
+          "invalid": len(invalid), "evidence_missing": len(missing),
+          "fired": fired, "flipped": False,
+          "already_integrated": False}
+    if invalid:
+        # the typed schema refusals, loud in the event (WQ-054): a body
+        # that is not a verdict is never counted, and the field it is
+        # missing is named. Absent entirely on a clean count — a
+        # well-formed board's event gains no keys.
+        ev["invalid_reasons"] = sorted({v[3] for v in invalid if v[3]})
+    if fired:
+        evidence = agree[0][2]
+        res = flip(task, [v[0] for v in agree], evidence, n, m,
+                   orig=orig, cwd=cwd)
+        ev["flipped"] = res["pushed"]
+        ev["flip"] = res
+    return emit(ev)
+
+
+# --------------------------------------------------------------------- CLI
+
+
+def main(argv):
+    if len(argv) >= 2 and argv[0] == "review":
+        task, reviewer, outcome = argv[1], argv[2], argv[3]
+        evidence = argv[4] if len(argv) > 4 else f"refs/swarm/tasks/{task}"
+        ev = review_verdict(task, reviewer, outcome, evidence)
+        return 0 if ev["pushed"] else 1
+    if len(argv) >= 2 and argv[0] == "gate":
+        ev = gate(argv[1])
+        return 0 if (ev["fired"] or ev["already_integrated"]) else 1
+    print(f"usage: {sys.argv[0]} review <task> <reviewer> <agree|veto> "
+          f"[evidence-ref] | gate <task>", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))