agy-squad 0.0.0-stage → 0.1.1

package/.agents/skills/swarm-governance/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: swarm-governance
+description: >-
+  [Execution Modifier — pairs with /pr-review, /full-review, or /self-diagnosis on /swarm]
+  Apply Agy-Squad governance, role separation, Pointer-Over-Wire reporting, and
+  SHA-256 proof bundling on top of Antigravity native /swarm execution.
+---
+
+# Agy-Squad Swarm Governance (Native `/swarm` Execution Modifier)
+
+Governs Antigravity native `/swarm` orchestration (`swarm`, `post_message`, `read_board`, `swarm_wait`, `swarm_monitor`) alongside any **Task Spec** ([`pr-review`](../pr-review/SKILL.md), [`full-review`](../full-review/SKILL.md), or [`self-diagnosis`](../self-diagnosis/SKILL.md)). For the canonical cross-skill role graph, scaling rules, and `Spike S5` hook boundary, consult [Core workflows](../../../docs/core-workflows.md) and [Roles & skill workflows](../../../docs/roles-and-workflows.md#swarm-governance).
+
+---
+
+## Invariants
+
+1. **Tool & Surface Boundaries:** Plan `/swarm` cohorts via `squad_planner` (MCP) or `node bin/agy-squad.mjs plan` (omit `squadId` to compile all squads; never pass `all_l1`). Use `dispatch_squad` / `agy-squad dispatch` only for `invoke_subagent` fallback (`executionMode: "subagent"`). Never run `mcp/handoffs.mjs` as a CLI (it is an internal JS library), and never invoke retired `agy-squad run` (`L17`). See [planner & dispatch commands](./references/intake-and-planning.md#planner-and-dispatch-commands) and [model caveats](./references/intake-and-planning.md#model-pinning-and-subagent-caveats) (including `invoke_subagent` `inherit|flash_lite|flash|pro` limits and [tools contract](../../../docs/tools.md#manifest-structure-rules) `24`-char names, `500` B pointers, `10 MiB` stdio cap, and no hardcoded worker count ceiling).
+2. **Strict Role Separation & Canonical Audit Slots:** Never merge content acceptance with integrity auditing:
+   - **Working Lead / Coordinator** (`<squad>-lead` layered, or coordinator flat): verifies deliverables and tests, owns strict single-line `Content Verdict: PASS | FAIL | BLOCKED`.
+   - **Integrity Auditor** (`audit-<id>` -> `scratch/agy-squad/squad-integrity_auditor/specialist-1/report.md` single-squad; `audit-<id>` -> `scratch/agy-squad/squad-integrity_auditor-<id>/specialist-1/report.md` multi-squad): independent flat peer verifying tool traces and `Evidence Digest`, owns `Target Squad: <id>` and strict `Integrity Verdict: CLEAN | INTEGRITY VIOLATION`. Reject hedged verdicts (`CONDITIONAL PASS`, `PASS with Advisories`). See [role separation & slots](./references/bundling-and-wire-format.md#canonical-auditor-slots-and-verdicts).
+3. **Pointer-Over-Wire & `L6` Transcript Isolation:** Workers write full Markdown reports to assigned `scratch/` slots (collecting from `share`/`branch` copies before normal bundling or `kill`) and post **zero mid-flight chatter** — only one single-line `< 500` UTF-8 byte pointer (`@lead READY <path> — <observation>`, `@lead PARTIAL <path> — <observation and blocker>`, or `@lead NO_REPORT — <reason>`) to prevent quadratic board token bloat. Record raw board posts verbatim (including `@lead`) in `handoffs[].message` for `agy-squad inspect`. Note this convention is detected post-hoc, not board-enforced. Never copy `.system_generated/` transcripts into `scratch/` (`L6`). See [Pointer-Over-Wire convention](./references/bundling-and-wire-format.md#pointer-over-wire-convention) and [large-swarm reference](./references/large-swarms.md#shared-board-on2-broadcast-and-zero-mid-flight-chatter).
+4. **`open_board`, `swarm_wait`, Immediate Kill & Quota Recovery:** Emit `open_board` (`[Open the Swarm UI](sidecar://swarm/swarm_board/)` or `?tab=graph` for the `@mention` graph) **only on active `/swarm` launch turns and in-flight user updates** — **never emit `open_board` after all swarm workers are killed**. Do not call `swarm_wait` silently on the launch turn so the Swarm UI pill renders immediately; **warn explicitly** that ending the launch turn without `swarm_wait` displays `"waiting for my reply"` / `"waiting for user reply"` in Antigravity until a worker message (`@coordinator`) or scheduled watchdog wakes the coordinator. Use `swarm_wait` on subsequent intermediate quiet turns. **User-directed kill override:** Whenever the user explicitly asks to kill or stop workers, execute `swarm{action: "kill"}` immediately without delaying for worktree collection or bundling; for quota exhaustion on active `waiting` workers, switch models in place via `swarm{action: "model"}` rather than `kill` + `add`. See [UI turn lifecycle](./references/intake-and-planning.md#swarm-ui-and-turn-lifecycle) and [large-swarm reference](./references/large-swarms.md#immediate-user-directed-kill-vs-normal-shutdown).
+5. **Cryptographic File-Integrity Boundary:** `bundle` and `verify` enforce `requireIntegrityAudit: true` by default and attest SHA-256 digests of coordinator-assembled inputs (`verifiedFiles`, reports, `Evidence Digest`), not host authorship or unverified claim truth. Never ask LLMs to copy-paste 64-hex hashes; see [bundle schema & CLI](./references/bundling-and-wire-format.md#bundle-record-schema-and-cli).
+
+---
+
+## Workflow
+
+### Step 0: Pre-Flight Intake (Ask When Unspecified)
+Ask once via `ask_question` before compiling plans whenever any of these four settings are unspecified (see [Step 0 templates](./references/intake-and-planning.md#step-0-intake-question-templates)):
+1. **Topology (neutral, no default bias):** `Flat` (specialists -> coordinator) vs `Layered` (specialists -> domain squad leads -> coordinator).
+2. **Workspace Isolation (`workspaceIsolation`):** `inherit` (shared workspace for read-only or disjoint `scopeFiles`) vs `share` (shared-storage copy) vs `branch` (isolated clone).
+3. **Evidence Retention (`Scope 2` / `Scope 3`):** Keep loose specialist reports (`--keep-reports` on `prune` / defer `--teardown`) vs prune/tear down after verified bundling.
+4. **Model:** Defaults to the **coordinator's active model** (`model` / `--model` omitted) unless the user specifies another model ID (`swarm{action: "models"}` + `knownModels` allowlist).
+
+### Stage 1: Plan, Launch & Park
+1. Run `squad_planner` (or `node bin/agy-squad.mjs plan` per [planner commands](./references/intake-and-planning.md#planner-and-dispatch-commands)); check `swarm{action: "models"}` first if pinning non-default model IDs.
+2. Spawn workers via `swarm{action: "add"}`, record roster names and IDs in `provenanceScaffold`, and verify running models via `swarm{action: "status"}`.
+3. End the launch turn with `open_board` on its own line (`no swarm_wait` on launch; `"waiting for my reply"` clears on worker wakeup). On subsequent quiet turns while active, park via `swarm_wait`.
+
+### Stage 2: Content Gate & Flat Integrity Audit
+1. Collect any `share`/`branch` report slots into the coordinator workspace, verify worker claims against primary files and test output, and write `lead/report.md` (`Content Verdict: ...`).
+2. Run `node bin/agy-squad.mjs fingerprint` and `digest` (`Evidence Digest: <64-hex>`). With `Agy-Context-Saver >= 2.0.1`, `squad_planner` stamps `[agy-transcript-access: allow]` on `audit-<id>` and `<squad>-lead` briefs (and `[agy-transcript-access: deny]` on leaf specialists) so `audit-<id>` can directly run single-pass batch `agy-context transcript query --id <id> --summary` / `read --id <id> --last-turns 10` (or verify a coordinator-extracted `scratch/agy-squad/transcript-index-<id>.md` fallback; never raw logs) before emitting `Target Squad: <id>` and strict `Integrity Verdict: CLEAN | INTEGRITY VIOLATION` (re-execution alone cannot satisfy `CLEAN`). See [transcript index protocol](./references/bundling-and-wire-format.md#coordinator-extracted-transcript-index-native-swarm-fallback).
+
+### Stage 3: Bundle, Multi-Cycle Continuation, or Final Close
+1. Run the 7-step CLI gate (`verdict`, `fingerprint`, `digest`, `verdict --integrity`, `bundle`, `verify`, `prune [--keep-reports]`) per working squad against `<bundle-record.json>` (multi-squad runs audit each `audit-<squadId>` and bundle each squad independently) per [bundle schema & CLI](./references/bundling-and-wire-format.md#bundle-record-schema-and-cli).
+2. **Remediation / multi-cycle swarms:** For follow-up fixes or re-verification on the same codebase, keep waiting `/swarm` workers idle and wake them with `post_message` (pass `occupiedWorkerNames` to `squad_planner` if spawning extra workers onto the active board; start a fresh conversation between major waves for a clean UI board).
+3. **Final shutdown:** Unless the user requested an immediate kill (which executes `swarm{action: "kill"}` at once), finish normal `share`/`branch` teardown per the [pre-kill checklist](./references/large-swarms.md#pre-kill-checklist-for-share-and-branch-worktrees), post `[done] <summary>`, kill workers with `swarm{action: "kill"}`, complete Section 5 below, and do **not** emit `open_board`.
+
+---
+
+## 5. Runtime Closure Checklist (Pre-Handoff Gate)
+
+`bundle`/`verify` check disk SHA-256 digests only; before ending any session, verify all four live runtime checks:
+
+1. `swarm{action: "status"}`: every worker **including `monitor`** (exact monitor roster name in status, killed via `swarm{action: "kill", name: "monitor"}` after `[done]`) reports `state: "killed"`.
+2. `manage_subagents(Action='list')`: `0 active subagent(s): []`.
+3. `manage_task(Action='list')`: `No background tasks are currently running.` (catches lingering `swarm_monitor` daemon crons).
+4. Child commands: any worker-launched builds, servers, or watchers exited cleanly.

package/.agents/skills/swarm-governance/references/bundling-and-wire-format.md

@@ -0,0 +1,88 @@
+# Swarm Governance: Pointer-Over-Wire, Role Separation & Bundling Schema
+
+Reference details for [`.agents/skills/swarm-governance/SKILL.md`](../SKILL.md). Preserves complete wire-format examples, role-separation constraints, and SHA-256 verification schemas without inflating `SKILL.md` entry context.
+
+## Pointer-Over-Wire Convention
+
+Posting 50 KB Markdown reports directly to the `/swarm` board forces every waiting worker to ingest them on subsequent turns, causing quadratic token bloat.
+
+1. **Write workspace report slots:** Instruct each `/swarm` worker to write its full Markdown report to its workspace-relative scratch slot (for example, `scratch/agy-squad/squad-<id>/specialist-N/report.md`, or inside its `share`/`branch` copy before coordinator collection).
+2. **Post a single-line pointer (`<= 500` UTF-8 bytes):** Have the worker post one single-line pointer to the board (no embedded newlines; leaves headroom for `@<24-char-name> ` prefix):
+   - `@lead READY <report-path> — <1-line concrete observation>`
+   - `@lead PARTIAL <report-path> — <observation and blocker>`
+   - `@lead NO_REPORT — <reason>`
+3. **Record raw posts verbatim in `<bundle-record.json>`:** When populating `handoffs[].message` for `inspectHandoffs` (`node bin/agy-squad.mjs inspect <record.json>`), copy the exact raw board post verbatim (including any leading `@lead ` mention prefix — `mcp/handoffs.mjs` parses leading `@mention` tokens natively while rejecting mismatches against the sender's assigned slot).
+
+> [!NOTE]
+> Pointer-Over-Wire on the `/swarm` board is a governance convention, not runtime-enforced by the board tool itself: workers can post arbitrary text, and `agy-squad inspect` detects deviations after the fact rather than blocking them at send time.
+
+## Canonical Auditor Slots and Verdicts
+
+Never conflate content acceptance with integrity auditing:
+
+| Role | Native `/swarm` Member | Strict Verdict Format | Responsibility & Constraints |
+| :--- | :--- | :--- | :--- |
+| **Working Lead / Coordinator** | `<squad>-lead` (layered) or coordinator (flat) | `Content Verdict: PASS` \| `FAIL` \| `BLOCKED` | Reviews specialist deliverables, inspects cited files and executed tests, and owns final technical acceptance (`lead/report.md`). Never self-certifies execution integrity. |
+| **Integrity Auditor** | `audit-<id>` (flat peer) | `Integrity Verdict: CLEAN` \| `INTEGRITY VIOLATION` | Independent flat peer auditing tool traces (`agy-context transcript query --id <id> --summary` / `agy-context transcript read --id <id> --last-turns 10` with `[agy-transcript-access: allow]`, or coordinator-extracted sanitized transcript index in `scratch/`), primary evidence, absence of sycophancy or guessing, and SHA-256 `Evidence Digest`. Never treats workspace re-execution alone as sufficient for `CLEAN` (fails closed with `INTEGRITY VIOLATION` if traces are unavailable). Must declare `Target Squad: <id>`. Cannot waive defects or issue content `PASS`. |
+
+- **Strict single-line enforcement (`mcp/verdicts.mjs`):** Reject hedged, inline-wrapped, or contradictory verdicts (`PASS with Advisories`, `CONDITIONAL PASS`, `PASS / FAIL`). Note: `Verdict:` without `Content ` is accepted only as a legacy alias on lead reports; prefer `Content Verdict:`.
+- **Canonical flat auditor slots:**
+  - Single-squad manifests (flat or layered): `audit-<id>` -> `scratch/agy-squad/squad-integrity_auditor/specialist-1/report.md`
+  - Multi-squad manifests (flat or layered): `audit-<id>` -> `scratch/agy-squad/squad-integrity_auditor-<id>/specialist-1/report.md`
+  - Always keep `audit-*` as flat peers so an auditor is never subordinated inside a working lead's squad tree.
+
+### Coordinator-Extracted Transcript Index (Native `/swarm` Fallback)
+
+On Antigravity native `/swarm`, `Agy-Context-Saver` (`>= 2.0.1`) `PreToolUse` hooks block direct `.system_generated/` shell reads while enforcing 5-tier transcript access governance (`[agy-transcript-access: allow]` on `audit-<id>` and `<squad>-lead`, `[agy-transcript-access: deny]` on leaf specialists). `audit-<id>` can directly run single-pass batch `agy-context transcript query --id <id> --summary` / `agy-context transcript read --id <id> --last-turns 10` on recorded `provenanceScaffold` IDs. When child `conversationId` UUIDs are not mapped or direct CLI access is restricted, extract a sanitized coordinator transcript index before waking `audit-<id>`:
+
+1. Query every working lead and specialist `conversationId` from `provenanceScaffold` once from the coordinator (`agy-context transcript query --id <uuid> --roles assistant --include-tools --limit 50` plus `step` checks on any `status: "ERROR"` step; avoid relying solely on `--roles error`, which matches `"Error"` substrings inside normal source reads).
+2. Write a concise, sanitized summary table (executed commands, read targets, errors encountered — never raw `.system_generated/` JSONL lines) to `scratch/agy-squad/transcript-index-<id>.md` and include that path in `<bundle-record.json>` or the board wakeup to `@audit-<id>`.
+3. `audit-<id>` cross-checks the `agy-context transcript` output or sanitized trace index against `verifiedFiles` SHA-256s, `Evidence Digest`, and direct workspace re-execution; if neither `agy-context transcript` nor a coordinator-extracted index covers material worker claims, `audit-<id>` must fail closed and emit `Integrity Verdict: INTEGRITY VIOLATION` (never `CLEAN`).
+
+## Bundle Record Schema and CLI
+
+**What a bundle attests, and what it does not:** `bundle` and `verify` bind SHA-256 digests of the verified workspace files, worker reports, and integrity-audit reports to a `<bundle-record.json>`, and `verify` fails if any input or report changes afterward. The coordinator assembles `assignments`, `handoffs`, and `sender` (`workerName` in `/swarm`) from the board. Treat a verified bundle (`lead/report.sources.json`) as cryptographic **file-integrity evidence** for a coordinator-assembled record — **not** as host attestation of worker authorship or truth of unverified claims.
+
+Run all commands from the shared workspace root via `node bin/agy-squad.mjs` (`requireIntegrityAudit: true` by default; `mcp/handoffs.mjs` hashes inputs and audit reports programmatically — never ask LLMs to copy-paste 64-hex SHA-256 digests):
+
+```bash
+node bin/agy-squad.mjs verdict scratch/agy-squad/squad-<id>/lead/report.md
+node bin/agy-squad.mjs fingerprint <verified-file-1> <verified-file-2>
+node bin/agy-squad.mjs digest <bundle-record.json>
+node bin/agy-squad.mjs verdict --integrity scratch/agy-squad/squad-integrity_auditor[-<id>]/specialist-1/report.md
+node bin/agy-squad.mjs bundle <bundle-record.json>
+node bin/agy-squad.mjs verify scratch/agy-squad/squad-<id>/lead/report.sources.json
+node bin/agy-squad.mjs prune scratch/agy-squad/squad-<id>/lead/report.sources.json <accepted-sha256> [--keep-reports]
+```
+
+### `<bundle-record.json>` Schema & Concrete Wire-Format Example
+
+Start from `squad_planner`'s pre-populated `bundleRecordTemplates.<squadId>`, fill `verifiedFiles` from `node bin/agy-squad.mjs fingerprint ...`, and record exact worker `assignments` + verbatim board `handoffs`:
+
+```json
+{
+  "squadId": "storage",
+  "workspace": "/home/paragon-ux/Antigravity/Agy-Squad",
+  "verdict": "PASS",
+  "requireIntegrityAudit": true,
+  "verifiedFiles": {
+    "src/storage.js": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+  },
+  "assignments": [
+    {
+      "conversationId": "storage-wal-reviewer",
+      "report": "scratch/agy-squad/squad-storage/specialist-1/report.md"
+    }
+  ],
+  "handoffs": [
+    {
+      "sender": "storage-wal-reviewer",
+      "message": "@lead READY scratch/agy-squad/squad-storage/specialist-1/report.md — src/storage.js:42 fsync guard verified (npm test exit 0)"
+    }
+  ]
+}
+```
+
+- Pass `--allow-unaudited` to `bundle` only when explicitly opting out of `requireIntegrityAudit: true` (persists `auditPolicy: "unaudited-explicit"` inside v2 `lead/report.sources.json`).
+- Pass `--replace` or `--predecessor <sha256>` to `bundle` when overwriting an existing `lead/report.sources.json` from a prior run.
+- Omit `--keep-reports` on `prune` to unlink verified loose `specialist-<N>/report.md` files (re-verifying inode identity and SHA-256), or pass `--keep-reports` when preserving loose scratch files per Step 0.

package/.agents/skills/swarm-governance/references/intake-and-planning.md

@@ -0,0 +1,120 @@
+# Swarm Governance: Step 0 Intake, Planning Commands & Turn Lifecycle
+
+Reference details for [`.agents/skills/swarm-governance/SKILL.md`](../SKILL.md). Links use section anchors so [`SKILL.md`](../SKILL.md) remains concise while preserving full CLI flags, model caveats, and UI lifecycle rules.
+
+## Step 0 Intake Question Templates
+
+When launching `/swarm` and any of the four execution choices below are unspecified by the user or Task Spec, ask once via `ask_question` without biasing `Flat` vs. `Layered` topology (`squad_planner` sets `topology.defaultBias: "none (ask user if unspecified)"`):
+
+```json
+{
+  "questions": [
+    {
+      "question": "Which swarm topology should coordinate this run?",
+      "is_multi_select": false,
+      "options": [
+        "Flat — specialists report directly to the swarm coordinator (fewer coordination hops)",
+        "Layered — domain squad leads review specialists before reporting to the coordinator (isolates multi-domain syntheses)"
+      ]
+    },
+    {
+      "question": "Which workspaceIsolation mode should workers use?",
+      "is_multi_select": false,
+      "options": [
+        "inherit — shared coordinator workspace (use for read-only audits or strictly disjoint scopeFiles)",
+        "share — isolated per-worker working copy sharing repository storage (use for concurrent edits)",
+        "branch — isolated clone per worker (use when independent git history/branches are required)"
+      ]
+    },
+    {
+      "question": "Which evidence retention policy should apply after verification?",
+      "is_multi_select": false,
+      "options": [
+        "Keep loose specialist reports (`--keep-reports` on prune / defer `--teardown` during active waves)",
+        "Prune loose specialist reports after SHA-256 bundle + verify succeed (and `--teardown` after ledger update)"
+      ]
+    },
+    {
+      "question": "Which model should spawned workers use?",
+      "is_multi_select": false,
+      "options": [
+        "(Recommended) Coordinator default — omit `model` / `--model` so workers inherit the active session model",
+        "Custom explicit model ID — inspect `swarm{action: \"models\"}` first and pin the chosen ID"
+      ]
+    }
+  ]
+}
+```
+
+## Planner and Dispatch Commands
+
+`Agy-Squad` can be invoked either over MCP (`squad_planner` / `dispatch_squad` — pass `workspace: "<repo-root>"` when running from a global plugin install so relative `manifestPath` resolves to the active repository) or from the workspace root via `node bin/agy-squad.mjs` (legacy `agy-squad run` and the standalone `node mcp/handoffs.mjs` CLI are retired; `mcp/handoffs.mjs` is an internal JS library only).
+
+### Manifest & Task Planning (`squad_planner` / `agy-squad plan`)
+
+```bash
+# Plan all working squads from a manifest, inheriting coordinator default model:
+node bin/agy-squad.mjs plan \
+  --manifest .agents/skills/self-diagnosis/resources/self-diagnosis-manifest.json \
+  --topology flat \
+  --workspace-isolation inherit
+
+# Plan from a manifest while pinning an explicit user-requested model ID:
+node bin/agy-squad.mjs plan \
+  --manifest .agents/skills/self-diagnosis/resources/self-diagnosis-manifest.json \
+  --model gemini-4-hydrogen-high \
+  --known-model gemini-4-hydrogen-high
+
+# Plan a freeform task with repeatable custom roles, scopes, and shared worktrees:
+node bin/agy-squad.mjs plan \
+  --mode swarm \
+  --scope src/app.js --scope docs/tools.md \
+  --role "Implementer" --role "Reviewer" \
+  --workspace-isolation share \
+  "Verify Phase 2 runtime fixes and update documentation."
+
+# Add a follow-up wave onto an already-active /swarm board without name collisions:
+node bin/agy-squad.mjs plan \
+  --manifest docs/custom-manifest.json \
+  --occupied-worker storage-lead --occupied-worker audit-storage \
+  --report-root scratch/agy-squad-wave2
+```
+
+- **Multi-squad vs. single-squad:** Omit `squadId` (`--squad`) to compile all non-audit squads in the manifest; never pass `all_l1` to `squad_planner` or `agy-squad plan`.
+- **Custom per-worker roles, scopes, models, and `readOnly`:** Inline `task` shares one `scopeFiles` list across `--role` titles and compiles a flat `task_squad`. For distinct per-worker `scopeFiles`, custom `objective`/`instructions`, per-worker `model`, `readOnly: true` overlap exemptions, or domain `lead`s, use `manifest` (inline) or `--manifest <path>`. Never pass `roles` or `scopeFiles` alongside `manifest` or `manifestPath`.
+- **Hard planner/wire caps ([docs/tools.md](../../../../docs/tools.md#manifest-structure-rules)):** There is no hardcoded cap on squad count or workers per squad, but code enforces `MAX_SWARM_NAME_LENGTH = 24` chars (deduplicated with `-2`, `-3`, ...), `squad-<encodeURIComponent(id)>` directory names `<= 255` UTF-8 bytes, `reportPath()` headroom so `READY <path> — ` plus `SWARM_MENTION_RESERVE_BYTES = 26` stays under `500` UTF-8 bytes, and `10 MiB` (`AGY_MAX_STDIO_PAYLOAD_BYTES`) on MCP stdio.
+
+### `invoke_subagent` Fallback (`dispatch_squad` / `agy-squad dispatch`)
+
+Use `dispatch_squad` (MCP) or `node bin/agy-squad.mjs dispatch` only when explicitly targeting `invoke_subagent` (`executionMode: "subagent"`):
+
+```bash
+node bin/agy-squad.mjs dispatch --squad all_l1 --manifest task-01-manifest.json
+node bin/agy-squad.mjs dispatch --squad storage --manifest task-01-manifest.json
+node bin/agy-squad.mjs dispatch --squad integrity_auditor:storage --manifest task-01-manifest.json
+```
+
+## Model Pinning and Subagent Caveats
+
+- **Under `executionMode: "swarm"` (default):** `squad_planner` emits `swarmAdd` payloads. When pinning an explicit non-default model (`model` / `--model`), call `swarm{action: "models"}` upfront (or pass `knownModels` / `--known-model`) so typos fail before spawn, then run `swarm{action: "status"}` immediately after `swarm{action: "add"}` to verify each running worker's actual model ID. When inheriting the coordinator default, omit `model` / `--model`.
+- **Under `executionMode: "subagent"`:** `invoke_subagent` accepts only the four aliases `inherit`, `flash_lite`, `flash`, or `pro`. Any exact model ID other than those four aliases falls back to `inherit`, and `modelProvenance` warns that neither `agy-context transcript read` nor `manage_subagents` exposes resolved per-child model IDs.
+- **L6 transcript isolation (`provenanceScaffold`):** Record parent-known worker roster names, report slots, and native `conversationId`s in `provenanceScaffold` and pass them to the flat integrity auditor (`audit-<id>`). **Never** copy raw `.system_generated/` transcripts into `scratch/` or lead/leaf directories (`L6`); compiled briefs stamp `[agy-transcript-access: allow]` on leads/auditors and `[agy-transcript-access: deny]` on leaf specialists so auditors use single-pass `agy-context transcript query --id <id> --summary` / `agy-context transcript read --id <id> --last-turns 10` or `read_board` / `swarm{action: "status"}`.
+
+## Swarm UI and Turn Lifecycle
+
+1. **Active Launch Turn (`open_board`, no `swarm_wait`):**
+   - Right after spawning workers via `swarm{action: "add"}` and confirming models via `swarm{action: "status"}`, end the launch turn with the live board link from `open_board` on its own line:
+     - Standard board view: `[Open the Swarm UI](sidecar://swarm/swarm_board/)`
+     - Mention graph view: `[Open Swarm Graph](sidecar://swarm/swarm_board/?tab=graph)` (use `?tab=graph` when inspecting or explaining the `@mention` routing graph)
+   - **Do not** call `swarm_wait` silently on the launch turn; ending the turn renders the Swarm UI pill immediately for the user.
+   - **Explicit UI warning:** Ending the turn without calling `swarm_wait` causes Antigravity to show `"waiting for my reply"` / `"waiting for user reply"` until a worker post (`@coordinator`) or scheduled watchdog wakes the coordinator. Mention or account for this behavior cleanly rather than waiting passively for user input.
+2. **In-Flight Quiet Turns (`swarm_wait`):**
+   - On intermediate quiet turns while waiting for active workers, park via `swarm_wait` (`since` = highest board `seq` seen) instead of emitting repeated user turns or polling `read_board`.
+   - Emit `open_board` only on active launch turns or active in-flight user status updates while workers are running or waiting.
+3. **Multi-Cycle & Remediation Swarms (Stage 3 Continuation):**
+   - When fixing findings or running a second verification wave against the same codebase, **keep waiting `/swarm` workers idle** and wake the same specialists via `post_message` so they re-verify deltas with preserved context.
+   - If adding extra cohorts onto an already-active board, pass existing roster names via `occupiedWorkerNames` (`--occupied-worker`) to prevent 24-character name collisions.
+   - Because Antigravity keeps one append-only board (`board: "local"`) per conversation (and `channel` is host-gated), close the finished swarm and start a **fresh conversation** between major waves when you want a clean Swarm UI board.
+4. **Final Shutdown (`kill` + No `open_board`):**
+   - If the user asks to stop or kill workers, call `swarm{action: "kill"}` immediately without delaying for bundling or worktree collection.
+   - Otherwise, on normal coordinator completion (after verified bundles are saved and any `share`/`branch` worktree slots/diffs are collected), post `[done] <summary>`, kill workers **including `monitor`** via `swarm{action: "kill"}`, run the 4-check runtime closure checklist, and **never emit `open_board` after all swarm workers are killed**.

package/.agents/skills/swarm-governance/references/large-swarms.md

@@ -0,0 +1,39 @@
+# Large-Swarm Scaling, Worktree Collection, and Recovery
+
+Standalone reference for running larger `/swarm` cohorts (`8+` workers, concurrent code editors, or multi-squad waves) under [`.agents/skills/swarm-governance/SKILL.md`](../SKILL.md).
+
+## Immediate User-Directed Kill vs. Normal Shutdown
+
+- **User-directed kill (highest priority):** Whenever the user explicitly asks to kill, stop, cancel, or abort workers, invoke `swarm{action: "kill"}` (including `monitor`) immediately in that turn. Never delay or block a user-requested stop on copying `share`/`branch` files, merging diffs, auditing, or bundling. Preserve any already-collected partial reports if present, and note clearly that uncollected edits inside terminated `share`/`branch` worktrees are discarded upon `kill`.
+- **Normal coordinator completion:** When the coordinator (rather than an explicit user stop request) is closing a completed `share` or `branch` run, follow the 4-step pre-kill collection checklist below before calling `kill`.
+
+## Pre-Kill Checklist for `share` and `branch` Worktrees
+
+`swarm{action: "kill"}` permanently deletes worker `share` and `branch` copies along with any unmerged code edits or uncollected `report.md` slots inside them. During normal completion of a `share` or `branch` swarm (for example, 10–20 concurrent workers), complete all four steps **in order** before calling `kill`:
+
+1. **Copy report slots:** Copy every `scratch/agy-squad/squad-<id>/specialist-<N>/report.md` (and any `lead/report.md`) from each worker's `share` or `branch` copy back into the matching path in the coordinator workspace.
+2. **Collect and merge code diffs:** Inspect and cherry-pick, patch, or merge any verified worker code modifications into the coordinator workspace before terminating workers.
+3. **Verify and bundle:** From the coordinator workspace, run `node bin/agy-squad.mjs fingerprint`, `digest`, flat `audit-<id>`, `bundle`, and `verify`, confirming `report.sources.json` validates against the final collected files.
+4. **Kill workers only after bundle verification:** Call `swarm{action: "kill"}` on specialists, leads, auditors, and `monitor` only after `verify` passes (or after saving partial evidence on an early coordinator abort).
+
+## Shared Board `O(N^2)` Broadcast and Zero Mid-Flight Chatter
+
+Antigravity attaches one persistent append-only board (`board: "local"`) per conversation and omits `channel` partitioning when the host `swarm` schema exposes only `status`, `models`, `add`, `model`, `kill`, and `title`. Above `~8` workers, mid-flight status updates (`"still checking X"`) or coordinator acknowledgments are replicated into every active member's context on subsequent wakeups (`O(N^2)` token growth):
+
+- Instruct every worker explicitly in its brief/assignment to post **zero mid-flight status chatter** on the board and emit **only one final `<= 500` UTF-8 byte Pointer-Over-Wire line** (`@lead READY <path> — <observation>`, `@lead PARTIAL <path> — <observation and blocker>`, or `@lead NO_REPORT — <reason>`).
+- Keep coordinator acknowledgments off the board unless waking a worker for clarification or a follow-up cycle.
+- Start a **fresh Antigravity conversation** between major waves if the persistent board accumulates enough retired workers or messages to slow down the Swarm UI pane.
+
+## Name Truncation, `474` B Path Budget, and Multi-Squad Bundling Loop
+
+- **24-character worker name truncation (`mcp/planner.mjs`):** `MAX_SWARM_NAME_LENGTH = 24` lowercases `[a-z0-9-]+` slugs and truncates long worker names. Similar role titles (such as `frontend-security-reviewer` and `frontend-session-reviewer`) or long `squadId` values truncate to 24 chars and collide, causing `allocateWorkerName` to append `-2`, `-3`, ... suffixes. Keep `squadId` short, give roles distinct leading words, and pass existing roster names via `occupiedWorkerNames` across sequential `squad_planner` calls on the same board.
+- **`474`-byte report path budget (`mcp/handoffs.mjs`):** `reportPath()` reserves `SWARM_MENTION_RESERVE_BYTES = 26` bytes (`@<24-char-name> `) inside the `500`-byte `messageLimit`, leaving `< 474` UTF-8 bytes for `READY <reportRoot>/squad-<encodeURIComponent(id)>/<slot>/report.md — `. Deep custom `reportRoot` paths paired with long `squadId` strings throw at compile time—keep both short.
+- **Multi-squad audit and bundle loop:** Multi-squad manifests spawn **one flat `audit-<squadId>` per working squad**, writing to `scratch/agy-squad/squad-integrity_auditor-<squadId>/specialist-1/report.md`. Because `squad_planner` emits one entry per squad under `bundleRecordTemplates.<squadId>`, execute `fingerprint` -> `digest` -> `audit-<squadId>` -> `bundle` -> `verify` **independently per working squad** using separate `<bundle-record.json>` files rather than merging multiple squads into a single bundle record.
+
+## Host Model Quota Exhaustion Recovery
+
+When a large swarm pinned to one model hits host quota or capacity limits mid-run, **never `kill` the worker and `add` a fresh replacement** (which wipes its conversation context and destroys uncommitted `share`/`branch` changes):
+
+1. Inspect available fallback models and quotas with `swarm{action: "models"}`.
+2. Wait until the affected worker reaches `state: "waiting"`.
+3. Reassign its model in place using `swarm{action: "model", name: "<worker-name>", model: "<fallback-model-id>"}`—the worker preserves its conversation history and isolated copy and resumes its unfinished work on the new model.

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to `Agy-Squad` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.1] - 2026-11-15
+
+### Fixed
+- **MCP Workspace Resolution (`mcp/index.js`, `mcp/dispatch.mjs`, `mcp/planner.mjs`, `docs/tools.md`)**: Added optional `workspace` parameter on both `dispatch_squad` and `squad_planner`, forwarded explicit `workspace` overrides in `all_l1` lead delegation instructions, captured client `initialize` workspace roots (`workspaceFolders`/`rootUri`/`rootPath` with resilient URI fallback), supported absolute `manifestPath` inside symlinked workspaces, trimmed `manifestPath`/`AGY_SQUAD_WORKSPACE` consistently, and surfaced actionable `ENOENT` diagnostics (`workspace:`, `manifestPath:`, and `Pass 'workspace'` / `AGY_SQUAD_WORKSPACE` hints) even on missing default manifests when the MCP server starts outside the active repository root.
+- **Bounded File-Read Guidance (`mcp/briefs.mjs`, `mcp/planner.mjs`)**: Added concise `rtk read` / `rtk grep` / bounded `<= 150`-line `read_file` (`StartLine`/`EndLine`) instructions across compiled working specialist, squad lead, and auto-synthesized `integrity_auditor` (`audit-<id>`) prompts while removing duplicated auditor text and staying inside prompt byte budgets (`1702 B <= 1800 B` specialist, `2881 B <= 3300 B` lead, `3075 B <= 4096 B` `tools/list`).
+- **Release Preflight & Package Checks (`scripts/release-preflight.mjs`, `tests/verify-package.mjs`, `tests/test-server.mjs`)**: Added `mcp/dispatch.mjs`, `self-diagnosis` runtime files, `verify:package` script checks, `./` + `!` negation handling in `files`, `LICENSE` + nested scratch/log tarball guards, isolated `AGY_SQUAD_WORKSPACE` in MCP server tests, and bumped catch version fallbacks to `0.1.1`.
+
+### Documentation
+- **Matched-`High` Benchmark Retest (`benchmarks/teamwork-vs-squad/`, `docs/benchmarks.md`, `docs/index.md`, `docs/getting-started.md`, `docs/core-workflows.md`, `README.md`, `package.json`, `zensical.toml`)**: Recorded the November 15, 2026 `Gemini 4 Hydrogen (High)` matched-effort comparison (`6m 30s` / `390s` vs. `22m 41s` / `1,361s`, `178` vs. `655` combined steps, `336.8 KB` vs. `801.8 KB` combined raw transcripts, `1,629 B` vs. `18,322 B` parent wakeup bytes, `21` vs. `16` defects, and `audit-ab-audit` `CLEAN` verdict vs. `/teamwork` Sentinel-fabricated snippets passing `Victory Auditor`) alongside the historical November 8, 2026 Phase 1 baseline, extended `verify-benchmark.mjs` to validate per-row KB sums, `N1`–`N6` rubric mappings, digest/SHA-256 provenance, and flat `/swarm` planning, scoped platform support to Linux and WSL2, and standardized GitHub Pages URL casing (`https://paragon-ux.github.io/Agy-Squad/`).
+
+## [0.1.0] - 2026-11-15
+
+### Added
+- **Zero-Clone CLI & Plugin Installer (`scripts/install-register.mjs`, `bin/agy-squad.mjs`, `plugin.json`)**: Added `npx --package=agy-squad agy-squad setup` (`status`, `uninstall`, `--check`, `--restore-backups`) to install the native Antigravity plugin (`~/.gemini/config/plugins/agy-squad`), link `.agents/skills`, register the `agy-squad` MCP server in `~/.gemini/config/mcp_config.json`, and provision `agy-squad` CLI shims in `~/.gemini/antigravity/bin/`.
+- **`squad_planner` & Native `/swarm` Cohort Compiler (`mcp/planner.mjs`, `bin/agy-squad.mjs`)**: Compiles flat (`1–3` workers) and layered (`4+` workers with Squad Leads) `/swarm` cohorts with disjoint file-scope validation, 24-character roster-name enforcement, model pinning (`knownModels`), `provenanceScaffold`, and flat `audit-<id>` integrity auditor slots.
+- **First-Line Transcript Access Directives (`mcp/briefs.mjs`)**: Stamps `[agy-transcript-access: allow]` on Squad Lead and Independent Integrity Auditor briefs/prompts and `[agy-transcript-access: deny]` on leaf Specialist briefs/prompts for zero-config isolation with `Agy-Context-Saver >= 2.0.1`.
+- **Pointer-Over-Wire & SHA-256 Proof Pipeline (`mcp/handoffs.mjs`, `mcp/verdicts.mjs`, `bin/agy-squad.mjs`)**: Implements `fingerprint`, `inspect`, `digest`, `verdict`, `bundle`, `verify`, and `prune` commands producing tamper-evident `.sources.json` sidecars with canonical `Evidence Digest` verification.
+- **PR Review Standard `v1.4.0` & Governance Skills (`.agents/skills/`)**: Ships `pr-review`, `full-review`, `self-diagnosis` (`diagnose.mjs`), and `swarm-governance` skills with 10 mandatory review categories (`ARCH`, `DOC`, `SKILL`, `MCP`, `RUN`, `SVC`, `DB`, `SCRIPT`, `TEST`, `DEP`), 1-ID-per-row finding tables, and runtime closure checklists.
+- **Release Preflight & Trusted Publishing Workflow (`scripts/release-preflight.mjs`, `.github/workflows/release-tag.yml`)**: Added automated release preflight verification and GitHub Actions OIDC Trusted Publishing to npm.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 paragon-ux
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# Agy-Squad
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/agy-squad.svg)](https://www.npmjs.com/package/agy-squad)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-Zensical-purple.svg)](https://paragon-ux.github.io/Agy-Squad/)
+[![Tests](https://img.shields.io/badge/tests-100%25%20passing-brightgreen.svg)](https://github.com/paragon-ux/Agy-Squad/actions)
+
+`Agy-Squad` is a multi-agent `/swarm` planner, code-review harness, and SHA-256 proof bundler (`agy-squad`) for **Google Antigravity** (`agy`) on Linux and WSL2 (`Node.js >= 22`, zero external npm dependencies). It pairs with [Agy-Context-Saver](https://github.com/paragon-ux/Agy-Context-Saver) (`>= 2.0.1`) to assign non-overlapping file scopes, keep board handoffs under `500` bytes, audit worker tool traces, and verify every report with SHA-256 digests.
+
+![Agy-Squad, Antigravity, and Agy-Context-Saver architecture](docs/assets/architecture-overview.svg)
+
+The repository ships four components:
+
+- **Cohort planner & MCP server ([`mcp/planner.mjs`](mcp/planner.mjs), [`mcp/dispatch.mjs`](mcp/dispatch.mjs), [`mcp/index.js`](mcp/index.js)):** Compiles flat (`1–3` workers) and layered (`4+` workers with Squad Leads) `/swarm` cohorts via `squad_planner` (or `dispatch_squad` for `invoke_subagent`), enforcing disjoint writable file scopes, 24-character roster names, explicit model pinning, and first-line `[agy-transcript-access: allow|deny]` directives.
+- **Verification & proof CLI ([`bin/agy-squad.mjs`](bin/agy-squad.mjs), [`mcp/handoffs.mjs`](mcp/handoffs.mjs), [`mcp/verdicts.mjs`](mcp/verdicts.mjs)):** Fingerprints verified source files, reconciles `<= 500` byte `Pointer-Over-Wire` board receipts, computes canonical `Evidence Digest` hashes for independent integrity auditors (`audit-<id>`), and writes tamper-evident `.sources.json` bundles (`plan`, `dispatch`, `fingerprint`, `inspect`, `digest`, `verdict`, `bundle`, `verify`, `prune`).
+- **Review & governance skills ([`.agents/skills/`](.agents/skills/)):** Installs [`pr-review`](.agents/skills/pr-review/SKILL.md) (branch/PR diffs), [`full-review`](.agents/skills/full-review/SKILL.md) (non-diff triage and direction decisions), and [`swarm-governance`](.agents/skills/swarm-governance/SKILL.md) (role separation, proof bundling, and 4-check runtime closure) using the 10-category [PR Review Standard v1.4.0](.agents/skills/pr-review/references/pr-review-standard.md).
+- **Zero-subagent harness profiler ([`self-diagnosis`](.agents/skills/self-diagnosis/SKILL.md), [`diagnose.mjs`](.agents/skills/self-diagnosis/scripts/diagnose.mjs)):** Audits skill token budgets, prompt template byte ceilings (`<= 1800 B` specialist, `<= 3300 B` lead), review ledger invariants, and package boundaries in `< 200 ms` with zero model cost.
+
+## Quickstart
+
+![Six-step swarm lifecycle and dual-verdict gate](docs/assets/swarm-lifecycle.svg)
+
+### Prerequisites
+
+- **Node.js:** `>= 22.0.0` (Linux or WSL2 on Windows)
+- **Google Antigravity:** Antigravity 2.0+ (Desktop IDE or `agy` CLI with `/swarm` / `invoke_subagent`)
+- **Agy-Context-Saver:** `>= 2.0.1` with **RTK (`>= 1.1.0`)** (`npx --package=agy-context-saver agy-context setup`)
+
+### Install and verify
+
+```bash
+# Install via npx (registers plugin, skills, MCP server, and agy-squad CLI shim)
+npx --package=agy-squad agy-squad setup
+
+# Or from a local checkout
+npm run setup
+
+# Check plugin, skills, MCP registration, and CLI shim status
+agy-squad status
+```
+
+To remove the plugin link, MCP server entry, and CLI shims:
+
+```bash
+agy-squad uninstall
+# Or restore pre-install .bak configuration files:
+agy-squad uninstall --restore-backups
+```
+
+### Plan, audit, and bundle a cohort
+
+```bash
+# Plan a layered /swarm cohort from a manifest or freeform task
+agy-squad plan --manifest .agents/skills/self-diagnosis/resources/self-diagnosis-manifest.json \
+  --topology layered --mode swarm
+
+# Parse strict content and integrity verdicts
+agy-squad verdict scratch/agy-squad/squad-<id>/lead/report.md
+agy-squad verdict --integrity scratch/agy-squad/squad-integrity_auditor-<id>/specialist-1/report.md
+
+# Compute canonical Evidence Digest, write .sources.json proof bundle, and verify SHA-256 hashes
+agy-squad fingerprint src/app.js docs/tools.md
+agy-squad inspect scratch/agy-squad/<id>-record.json
+agy-squad digest scratch/agy-squad/<id>-record.json
+agy-squad bundle scratch/agy-squad/<id>-record.json --replace
+agy-squad verify scratch/agy-squad/squad-<id>/lead/report.sources.json
+```
+
+## CLI, MCP, and skills summary
+
+| Surface | Purpose | Common usage |
+| :--- | :--- | :--- |
+| `agy-squad setup` / `status` / `uninstall` | Install, audit, or remove plugin link, skills, MCP entry, and CLI shim | `agy-squad setup` / `agy-squad status` / `agy-squad setup --check` |
+| `agy-squad plan` / `squad_planner` (MCP) | Compile flat or layered `/swarm` cohorts with scope checks and `provenanceScaffold` | `agy-squad plan --manifest <path> [--topology flat\|layered]` |
+| `agy-squad dispatch` / `dispatch_squad` (MCP) | Compile `invoke_subagent` payloads (`all_l1`, `<squadId>`, `integrity_auditor[:<id>]`) | `agy-squad dispatch --squad <id> --manifest <path>` |
+| `agy-squad fingerprint` / `inspect` / `digest` | Hash verified files, check `< 500 B` `READY` receipts, and compute `Evidence Digest` | `agy-squad digest scratch/agy-squad/<id>-record.json` |
+| `agy-squad verdict` / `bundle` / `verify` / `prune` | Parse `PASS` / `CLEAN` verdicts, write `.sources.json` proofs, and prune loose reports | `agy-squad bundle <record.json> --replace` / `agy-squad verify <sources.json>` |
+| `/pr-review` & `/full-review` (`v1.4.0`) | 10-category commit-pinned diff review (`pr-review`) or non-diff triage (`full-review`) | Pair with `/swarm-governance` on `/swarm` |
+| `/self-diagnosis` (`diagnose.mjs`) | Zero-subagent profiler checking skill token budgets, prompt sizes, and review ledgers | `node .agents/skills/self-diagnosis/scripts/diagnose.mjs --markdown` |
+
+## Benchmark summary vs. Antigravity `/teamwork`
+
+In a matched-effort sequential audit (`Gemini 4 Hydrogen (High)` on all parents and workers, November 15, 2026) against the six-defect event-relay fixture ([`benchmarks/teamwork-vs-squad/`](benchmarks/teamwork-vs-squad/README.md)) using native `/swarm` + `Agy-Context-Saver 2.0.1` (`rtk 1.1.0`), both arms caught all six planted defect categories (`6 / 6`):
+
+| Metric (Parent + All Workers End-to-End) | Agy-Squad + Agy-Context-Saver (`flat /swarm`) | Antigravity `/teamwork` (`[skip-interview]`) | Difference |
+| :--- | :--- | :--- | :--- |
+| Planted defect categories caught | `6 / 6` (`21` defects: `10 P1`, `11 P2`) | `6 / 6` (`16` defects: `8 P1`, `8 P2`) | Equal recall; Arm 1 found 5 more defects |
+| Total sessions (parent + child workers) | `4` (`1` coordinator + `3` workers) | `9` (`1` parent + `8` subagents) | `2.25x` fewer sessions (`3` vs `8` children) |
+| Wall-clock runtime | `6m 30s` (`390s`) | `22m 41s` (`1,361s`) | `3.49x` faster (`71.3%` less time) |
+| Combined transcript steps | `178` (`88` parent + `90` workers) | `655` (`19` parent + `636` subagents) | `3.68x` fewer steps (`72.8%` reduction) |
+| Combined assistant turns | `49` (`25` parent + `24` workers) | `319` (`8` parent + `311` subagents) | `6.51x` fewer turns (`84.6%` reduction) |
+| Combined tool calls | `117` (`57` parent + `60` workers) | `311` (`6` parent + `305` subagents) | `2.66x` fewer tool calls (`62.4%` reduction) |
+| Combined raw transcript size | `336.8 KB` (`183.6 KB` workers) | `801.8 KB` (`773.7 KB` subagents) | `58.0%` smaller overall (`76.3%` child-only) |
+| Parent inbox wakeup bytes | `1,629 B` (`5` notices; `647 B` handoffs) | `18,322 B` (`4` wakeups) | `91.1%` fewer parent wakeup bytes (`11.2x`) |
+| Independent proof & quality outcome | SHA-256 bundle (`ad876bd4...` Digest) + `audit-ab-audit` `CLEAN` | `Victory Auditor` approved Sentinel-fabricated snippets; caught by parent (`Steps 11–17`) | Cryptographic proof vs. unverified QA |
+| Scratch files left after run | `4` proof/report files (`72.3 KB`, gitignored) | `33` files (`183.7 KB` in `.agents/teamwork/`) | `29` fewer scratch files |
+
+See [Benchmarks](docs/benchmarks.md) for the per-agent breakdown of the November 15 matched-`High` retest and the historical November 8 Phase 1 baseline (`6m 15s` vs. `26m 19s`, `148.2 KB` vs. `817.4 KB` subagent-only).
+
+## Documentation
+
+Full documentation is hosted at [paragon-ux.github.io/Agy-Squad](https://paragon-ux.github.io/Agy-Squad/) (built with Zensical) and in [`docs/`](docs/):
+
+- [Overview](docs/index.md)
+- [Getting started](docs/getting-started.md)
+- [Core workflows: orchestrate, self-diagnose, review, and tear down](docs/core-workflows.md)
+- [Roles, skill workflows, and runtime closure checklist](docs/roles-and-workflows.md)
+- [Concepts and terminology](docs/concepts.md)
+- [Manifest and tool contract](docs/tools.md)
+- [Stopping agents and child processes](docs/stopping-agents.md)
+- [Benchmarks vs. Antigravity Teamwork](docs/benchmarks.md)
+- [WSL CLI verification and live trial](docs/plans/wsl-cli-verification.md)
+- [Architecture decision ledger](docs/plans/LEDGER.md)
+- [Native enforcement ledger](docs/plans/native-enforcement-ledger.md)
+
+## Development
+
+Run `node scripts/release-preflight.mjs`, `npm test`, and `npm run verify:package` with Node.js `>= 22`. Runs all 10 test suites (`tests/test-verdicts-and-pivot.mjs`, `tests/test-dispatch.mjs`, `tests/test-planner.mjs`, `tests/test-handoffs.mjs`, `tests/test-run.mjs`, `tests/test-server.mjs`, `tests/test-comparative-dossier.mjs`, `tests/test-lifecycle-installer.mjs`, `benchmarks/teamwork-vs-squad/verify-benchmark.mjs`, and `tests/verify-package.mjs`) in isolated temporary directories without mutating your live `~/.gemini` configuration.
+
+## License
+
+MIT License. Copyright (c) 2026 paragon-ux.