agy-squad 0.0.0-stage → 0.1.1

package/.agents/skills/pr-review/references/pr-review-standard.md

@@ -0,0 +1,163 @@
+# Agy-Squad PR Review Standard
+
+Version: 1.4.0
+Status: Active repository workflow standard (enforced by `.agents/skills/pr-review/SKILL.md` and `.agents/skills/self-diagnosis/SKILL.md`)
+Established: 2026-11-08
+
+## Purpose and authority
+
+A review must make its coverage, reasoning, findings, and evidence inspectable by category. Passing tests, a polished change document, and a previous approval are inputs; none establishes that the implementation satisfies its architecture.
+
+Use this standard for a PR review. Implementation status updates are separate from that review.
+
+Changes to this standard require a version bump, a rationale, and a PR that identifies which review requirements change. A reviewer cannot silently omit or weaken a category. This is a repository workflow contract, not a claim that GitHub branch protection or an automated merge gate has been installed.
+
+## 1. Pin the review
+
+Record:
+
+- Repository, PR URL, review date, reviewer, standard version, base SHA, and head SHA (plus any uncommitted working-tree delta).
+- Append-only **Session Provenance** table (`Session # | Operator Conversation ID | Parent Session | Date | Base..Head + Working-Tree State | Skill / Topology Invoked`) so parent, resumed, and branched review or `/self-diagnosis` sessions and their exact `HEAD` state are distinguishable at the top of the report.
+- Exact commit or tree executed by each cited CI run. Distinguish a PR head from GitHub's generated merge commit.
+- Changed-file inventory from the base/head comparison, plus unchanged dependencies examined.
+- Evidence actually available: repository sources, normative design records (`docs/plans/LEDGER.md`, `docs/plans/wsl-cli-verification.md`, base commit `ee10ebc`), prior review, transcript, local reproduction, and CI logs. State when an attachment or environment was unavailable.
+- Scope and exclusions. Fetching a file is not the same as reviewing it.
+
+A new head invalidates claims about changed behavior until the delta and affected categories are re-reviewed. Retain the previous review and record which findings carry forward.
+
+## 2. Review architecture before runtime
+
+For every behavior change, trace:
+
+design thesis / invariant -> current architecture decision -> public contract -> implementation -> verification.
+
+Read the normative design records (`docs/plans/LEDGER.md`, `docs/plans/wsl-cli-verification.md`, and historical commit `ee10ebc`) when assessing preservation or modification of project invariants. Separate historical design records, normative current contracts, as-built descriptions, and external evidence. Existing implementation does not automatically override a higher-priority contract.
+
+When modernization relies on a current ecosystem norm, cite a primary source, its version or date, the exact capability, the demonstrated gap, and why closing that gap benefits Agy-Squad. Unsupported generalizations such as "modern agents expect this" are not evidence.
+
+For each intentional departure from a contract, require a recorded decision, compatibility implications, and acceptance criteria before recommending runtime changes. Do not resolve a mismatch by silently rewriting documentation to match code.
+
+## 3. Required categories
+
+Each category has its own coverage statement, independently triaged P1/P2/P3 finding lists, verification gaps, and verdict.
+
+| ID | Category | Required review questions |
+| --- | --- | --- |
+| ARCH | Architecture and contracts | Are boundaries, guarantees, ownership, compatibility, and resource limits explicit? Does implementation satisfy the selected decisions? |
+| DOC | Documentation and change records | Do active docs agree with normative contracts and actual behavior? Are historical records distinguished? Are completion and benchmark claims supported? |
+| SKILL | Skills and agent instructions | Are referenced APIs, enums, fields, commands, and guarantees real and current? Do instructions guide correct implementation and review? |
+| MCP | MCP schemas and public API | Do discovery schemas, runtime acceptance, errors, defaults, nullability, bounds, and documented responses agree? |
+| RUN | Core runtime, parsing, and validation | Are inputs untrusted, failures deterministic, workspace/descriptor containment enforced, and stage compilation/reporting accurate? |
+| SVC | Services, orchestration, and audit semantics | Are retries, lineage, request identity, recovery, and shared entry points consistent with the contracts? |
+| DB | Database, migrations, replay, and concurrency | When SQL/database persistence exists, are reads/writes transactionally coherent and migrations verified? When only filesystem state exists (`scratch/agy-squad/`), is state persistence covered under `RUN`/`SVC` and `DB` marked `Not applicable`? |
+| SCRIPT | Scripts, evaluation, and developer tooling | Do scripts fail on unexpected results? Are exceptions scenario-specific? Are measurement claims limited to what was measured? |
+| TEST | Tests and CI | Do tests prove the guarantees, including adversarial cases? What ran, where, against which revision, and what remains unverified? |
+| DEP | Dependencies, packaging, and configuration | Are installation paths, lockfiles, supported versions, configuration names, and startup assumptions coherent? |
+
+Map every changed file to one primary category. Cross-reference affected categories without counting the same defect twice. Split a category into named subsections when necessary; additions cannot replace the required categories. A documentation file defining architecture can belong primarily to ARCH.
+
+"No findings" is permitted. A finding quota is prohibited.
+
+## 4. Required category record
+
+For each category include:
+
+1. **Scope:** changed files and relevant unchanged dependencies examined.
+2. **Coverage:** complete, partial, or not reviewed; specify what remains.
+3. **P1 — high priority:** independently triaged blocking findings, or an explicit empty/unassessed statement.
+4. **P2 — medium priority:** independently triaged actionable findings, or an explicit empty/unassessed statement.
+5. **P3 — low priority:** independently triaged advisory findings, or an explicit empty/unassessed statement.
+6. **Verification:** tests inspected, tests executed, CI evidence inspected, and missing proof.
+7. **Verdict:** changes required, no findings within reviewed scope, incomplete, or not applicable with a reason.
+
+Every category must contain all three triage headings, even when a bucket is empty. For reviewed scope, write "None identified within reviewed scope"; for unreviewed scope, write "Not assessed." Do not equate an empty bucket with complete coverage. Order findings by severity within their owning category. Classify each finding from its impact and trigger; do not copy priority from a previous review automatically.
+
+Verification gaps and unresolved questions remain separate from the P1/P2/P3 finding buckets unless evidence establishes a concrete defect. Record priority changes with a reason and preserve finding IDs. An exceptional P0 emergency is escalated explicitly in addition to the required three buckets.
+
+A category with findings and partial coverage records both facts. "Not applicable" means the category has no relevant change or dependency, not that it was skipped.
+
+## 5. Required finding record
+
+Enforce a strict **`1 ID = 1 Row / Record`** and **zero lead/bundle compression or silent omission** rule: assign one stable ID per independently remediable problem (e.g., `MCP-001`) and preserve IDs across revisions. Because `node bin/agy-squad.mjs prune` (via `mcp/handoffs.mjs`) removes specialist reports and `diagnose.mjs --teardown` removes `scratch/agy-squad/squad-<id>/lead/report.md` (`L41`), the `docs/reviews/` report is the sole surviving record; compressing findings into multi-defect umbrella IDs (`R5-HARDEN-P3-1`, `R5-OPT-P3-1`), range-compressed IDs (`TEST-2..4`), or multi-ID combined rows (`A & B`), or silently omitting deferred/residual items, is prohibited because it prevents distinguishing solved defects from hidden ones. Only duplicate reports of the exact same underlying defect are merged into one canonical ID (cross-referencing the duplicate report alias in parentheses per Section 3).
+
+**Report readability & backtick discipline:** Keep review reports scannable in plain prose and Markdown tables. Reserve inline backticks strictly for exact code identifiers, file paths (`path#L10-L20`), CLI flags, and commands—never wrap plain numbers (`0`, `1`, `42`), English statuses/disposition labels (Closed, Open, Changes required, PASS), or multi-sentence quotations inside inline backticks or fenced code blocks inside prose or table cells. Use fenced code blocks sparingly for multi-line command invocations or exact diff hunks only.
+
+Every surfaced `P0`–`P3` item must carry one explicit canonical status: `Open (Pre-Remediation)`, `Closed`, `Residual (Open)`, `Closed (Post-Remediation)`, `Deferred / Won't Fix`, or `Closed (By Design)` (with `Informational` permitted for non-defect observations in Section 8). Section 8 is the mandatory sink for all `Residual (Open)` / `Closed (Post-Remediation)`, `Deferred / Won't Fix`, and `Closed (By Design)` / `Informational` items—never bury them inside a `Closed` row's prose or omit them.
+
+Tiered record density (instead of row compression):
+
+- **`P0` / `P1` / `P2` defects** require all 10 fields below, written as concise 1-line entries without repeating multi-paragraph prose across sections:
+  - **Title, priority, status.**
+  - **Contract provenance:** exact invariant, architecture decision (`docs/plans/LEDGER.md`), public contract, or evidenced external norm.
+  - **Source evidence:** immutable commit-pinned file links and relevant line ranges, plus the affected symbol.
+  - **Trigger:** concrete input, state, interleaving, or document instruction that exposes the issue.
+  - **Expected / actual:** explain the mismatch and distinguish observed execution from source-derived inference.
+  - **Impact:** concrete consequence and affected scope.
+  - **Required remediation:** precise behavior to restore, compatibility constraints, and affected contract surfaces.
+  - **Acceptance evidence:** regression case and assertions; use source reconciliation for low-impact prose changes where a test would add no value.
+  - **Root cause / related IDs:** connect cross-layer defects without duplicating the finding.
+  - **Closure:** fix commit, evidence at that revision, reviewer recheck, and residual limitations.
+- **`P3` advisories and optimizations** use a compact **1-row-per-ID** structured table schema (`ID | Wave/Session | Cat | Status | Source | Defect / Proposal | Disposition / Fix | Verification & Bundle SHA`), preserving 100% per-finding granularity without prose bloat.
+
+Priorities:
+
+- P0: immediate critical failure requiring emergency handling.
+- P1: high-impact correctness, data loss, security, or reliability failure.
+- P2: actionable correctness or contract problem that should be fixed.
+- P3: lower-impact issue or improvement; identify whether it is advisory.
+
+A verification gap alone is not proof of a production defect. Label it as a gap. Do not inflate severity or finding counts to fill categories.
+
+## 6. Evidence rules
+
+- Separate source inspection, attempted reproduction, local execution, and inspected CI logs.
+- Give reproduction steps even when execution is unavailable; label the expected failure as source-derived.
+- Test names, comments, string-presence assertions, and a green summary do not prove the named guarantee. Inspect what is asserted.
+- Never inherit a previous review's verdict. Revalidate its findings and explicitly accept, revise, or reject them.
+- Identify assumptions, unresolved questions, and unverified external claims.
+- Do not claim that a transcript, attachment, or design record was read unless its contents were accessible and examined.
+
+Agy-Squad-specific verification:
+
+- **Schema & Stdio Framing:** exercise documented omitted/null/valid/invalid values through `request.jsonrpc === "2.0"` validation, actual `tools/list` schemas (`mcp/index.js`), and the `dispatch_squad` (`mcp/dispatch.mjs`) and `squad_planner` (`mcp/planner.mjs`) runtime boundaries, including positive-integer `AGY_MAX_STDIO_PAYLOAD_BYTES` and the 10MB stdio frame limit.
+- **Workspace & Descriptor Containment:** verify workspace-internal symlink resolution (`fs.realpathSync` + `O_NOFOLLOW`, `O_NONBLOCK`, and `/proc/self/fd/${fd}` regular-file verification) for manifests in `mcp/dispatch.mjs`; strict symlink rejection (`O_NOFOLLOW`, `O_NONBLOCK`, symlink directory rejection, and `/proc/self/fd/${fd}` verification) for reports and bundles in `mcp/handoffs.mjs`.
+- **Subagent Capability, Model Provenance & Input Guards:** verify built-in `TypeName` rejection (`research`, `browser`, `image-generator`; default `"self"`), manifest `workspace === "inherit"` in `invoke_subagent` and `squad_planner` (with `/swarm` copy isolation via top-level `workspaceIsolation`), honest `modelProvenance` disclosure vs. `/swarm` pinning, `scopeFiles` path normalization and writable overlap warnings, and camelCase/PascalCase conflict rejection (`mcp/briefs.mjs`, `mcp/planner.mjs`).
+- **Pointer-Over-Wire Handoffs & Bundling:** verify single-line `<= 500` UTF-8 byte `READY`/`PARTIAL`/`NO_REPORT` receipt grammar, custom `reportRoot` alignment in `inspectReports`/`bundleReports`, atomic `publish()` link/rename semantics, strict single-line verdicts (`mcp/verdicts.mjs`), `integrityAudit` binding, and `bundle`/`verify`/`prune` SHA-256 verification (`mcp/handoffs.mjs`).
+- **External MCP & Governance CLI:** distinguish an in-process adapter call from a real stdio subprocess and CLI execution (`node bin/agy-squad.mjs plan|dispatch|fingerprint|inspect|bundle|verify|prune|verdict`).
+
+Run checks appropriate to the change. A documentation-only review-standard change does not require rerunning the product suite.
+
+## 7. Verdict and closure
+
+Keep coverage and merge disposition separate.
+
+- Request changes when blocking correctness or contract findings remain.
+- Mark the review incomplete when a material category is unreviewed; this can coexist with request changes.
+- Recommend approval only after all material categories are covered, blocking findings are resolved and rechecked, and required verification has evidence.
+- Never calculate approval from a pass percentage, number of findings, test count, or absence of findings in an unreviewed category.
+
+Re-review each fix in its primary category and all affected categories. A fix commit is not closure by itself. Every closed finding needs the relevant evidence and reviewer recheck.
+
+## 8. Required report structure
+
+1. Review metadata, Session Provenance table, and evidence limits.
+2. File-to-category inventory and coverage matrix.
+3. Architecture-to-implementation trace.
+4. Ten category sections, each with separate P1, P2, and P3 finding lists, verification gaps, and its own verdict.
+5. Cross-category root causes and rationale for remediation order.
+6. Verification record and remaining gaps.
+7. Overall disposition and finding closure table.
+8. **Post-Remediation Residuals & Deferred Dispositions** (mandatory): atomic 1-ID-per-row table (`ID | Wave/Session | Cat | Status | Source | Defect / Proposal | Disposition / Fix | Verification & Bundle SHA`) recording every advisory surfaced during re-verification (`Residual (Open)` -> `Closed (Post-Remediation)`), `Deferred / Won't Fix` item, and `Closed (By Design)` / `Informational` item—never buried inside a `Closed` row's prose cell. Record `None (0 open residuals, 0 deferred items)` when empty.
+9. **`/self-diagnosis` Cohort & Bundle Ledger** (mandatory whenever `/self-diagnosis` cohorts are dispatched against the target branch/PR): one canonical **Cohort Provenance** table (`Wave | Session ID | Stage | Subagent IDs | Pre-Fix Bundle SHA | Re-Verify Bundle SHA | Teardown`) plus one atomic 1-ID-per-row **Wave Finding Ledger**, keeping `docs/reviews/` to one clean file per PR review cycle rather than bespoke per-wave sections or proliferating files.
+
+Keep local review reports under `docs/reviews/`. Cite the reviewed base and head, category coverage, findings, evidence and verdict in the PR. Identify the previous review when recording a follow-up.
+
+## Change history
+
+| Version | Date | Change |
+| --- | --- | --- |
+| 1.4.0 | 2026-11-14 | Enforce mandatory Sections `1–8` and cross-section ID-status consistency in `validateTargetReviewLedger`; surface open P0–P2 ledger blockers explicitly; require `Evidence Digest: <64-hex>` binding (`agy-squad digest`), multi-auditor `integrityAudits[]` consensus, persisted bundle `auditPolicy`, atomic pre-delete teardown preflight, and documented single- vs multi-squad audit slots (`squad-integrity_auditor` vs `squad-integrity_auditor-<id>`). |
+| 1.3.0 | 2026-11-08 | Enforce `1 ID = 1 Row` (ban umbrella/range IDs) and 6-status enum, add tiered record density for `P3` tables, require Section 1 Session Provenance and mandatory Section 8 (`Post-Remediation Residuals & Deferred Dispositions`), and standardize Section 9 (`/self-diagnosis` Cohort & Bundle Ledger). |
+| 1.2.0 | 2026-11-08 | Adapt standard to Agy-Squad with 5 WSL runtime verification boundaries, durable review ledger coupling with `/self-diagnosis`, and distinct version bump per Section 0. |
+| 1.1.0 | 2026-10-20 | Require explicit P1/P2/P3 triage inside every category, including empty versus unassessed buckets; preserve separate verification gaps. |
+| 1.0.0 | 2026-10-20 | Establish category-separated review, provenance, explicit coverage, evidence distinctions, and finding closure. |

package/.agents/skills/self-diagnosis/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: self-diagnosis
+description: >-
+  [Task Spec — Agy-Squad self-audit & optimization; pair with swarm-governance on
+  /swarm] Use when the user asks to self-diagnose, troubleshoot, audit, or
+  optimize Agy-Squad or its workspace skills (.agents/skills/). Uses
+  diagnose.mjs, squad_planner (or dispatch_squad for invoke_subagent), the
+  bin/agy-squad.mjs Pointer-Over-Wire pipeline, and the Agy-Squad PR Review
+  Standard v1.4.0.
+---
+
+# Agy-Squad Self-Diagnosis & Optimization Skill
+
+Self-diagnose, audit, and optimize `Agy-Squad` and its workspace skills (including [`pr-review`](../pr-review/SKILL.md), [`full-review`](../full-review/SKILL.md), and [`swarm-governance`](../swarm-governance/SKILL.md)). This skill is a **Task Spec** for repository and harness self-audits; when run on `/swarm` or multi-agent teams, compose it with [`swarm-governance`](../swarm-governance/SKILL.md) (which owns `/swarm` launch, `open_board`, `swarm_wait`, pointer receipts, and closure).
+
+It dogfoods `Agy-Squad`'s `/swarm` planner (`mcp/planner.mjs` via `squad_planner` / `node bin/agy-squad.mjs plan`), `invoke_subagent` compiler (`mcp/dispatch.mjs` via `dispatch_squad` / `node bin/agy-squad.mjs dispatch`), Pointer-Over-Wire CLI (`node bin/agy-squad.mjs`), and [Agy-Squad PR Review Standard v1.4.0](../pr-review/references/pr-review-standard.md). Consult [Optimization & Review Rubric](./references/optimization-and-review-rubric.md) for budgets, [Execution & Teardown Reference](./references/execution-and-teardown.md) for uncondensed multi-squad and `--teardown` edge cases, and [Core workflows](../../../docs/core-workflows.md) for the 3-scope retention contract.
+
+---
+
+## Invariants
+
+1. **Zero-Subagent Local Profiler (`L7`):** [`diagnose.mjs`](./scripts/diagnose.mjs) launches zero agents; pass `--allow-active-cohort` while `scratch/agy-squad/squad-*` cohorts are active.
+2. **Self-Contained Instruction Standard:** Never use unanchored abbreviations or unexpanded section codes in briefs; state exact paths, constraints, and deliverable formats explicitly.
+3. **Non-Negotiable Pre-Remediation & Pre-Teardown Gate (`docs/reviews/`):** Before editing code or running `--teardown`, record every distinct defect/proposal `1-to-1` (`1 ID = 1 Row`, zero umbrella compression or silent drops) in `docs/reviews/<target-review-slug>.md` per [pr-review-standard.md](../pr-review/references/pr-review-standard.md) (Section 1 Session Provenance, Section 9 Cohort Provenance & Wave Finding Ledger, Section 8 residuals/deferred/closed items, plain-text readability rules without decorative backticks on numbers or English statuses).
+4. **Three-Scope Teardown Isolation (`Scope 2` vs `Scope 3`, `L41`):** `Scope 2` (`bin/agy-squad.mjs prune [--keep-reports]`) manages loose specialist reports under verified SHA-256 bundles; `Scope 3` (`diagnose.mjs --teardown ... --ledger <slug>.md`) refuses deletion until `lead/report.sources.json` verifies and the target ledger has `mtime >= bundle mtime` (unless `--force` is passed). See [Scope 3 refusal & partial cleanup rules](./references/execution-and-teardown.md#pre-teardown-refusal-conditions-and-partial-cleanup).
+5. **Same-Cohort Re-Verification & Runtime Closure:** Keep existing `/swarm` workers (`swarm_wait` / `post_message`) or `invoke_subagent` children (`send_message`) alive to re-verify remediation fixes in place; spawn fresh cohorts only for independent new audits. Kill workers only after `0` open blockers remain, ledger rows close, and teardown finishes, then complete the 4-check closure gate (`manage_subagents`, `manage_task`, `swarm status` including `monitor`, child OS processes; see [Roles & skill workflows](../../../docs/roles-and-workflows.md#self-diagnosis)).
+6. **Empirical Measurement & Architecture Trace:** Verify `design thesis / invariant (L1-L7, L21, L29-L31, L40-L43) -> public contract -> implementation -> verification` before altering runtime or skill code, record exact UTF-8 byte deltas, token estimates, and timings from `diagnose.mjs`, and confirm `npm test` passes after final edits.
+
+---
+
+## Workflow
+
+### Step 0: Pre-Flight Intake Interview (Neutral Alignment Gate)
+Ask once before compiling manifests or launching workers whenever any choice below is unspecified (skip questions already answered; defer `/swarm` launch, `open_board`, and `swarm_wait` rules to [`swarm-governance`](../swarm-governance/SKILL.md#step-0-pre-flight-intake-ask-when-unspecified)):
+1. **Execution Mode, Topology & Isolation (neutral, no default bias):**
+   - `/swarm` via `squad_planner` (`diagnose.mjs --print-plan [--topology flat|layered | --flat]`): **Flat Specialist Swarm** (6 read-only specialists -> coordinator) or **Layered Squad Swarm** (3 leads -> 6 specialists), plus `workspaceIsolation` (`inherit` for read-only audits vs `share`/`branch` for writers) and model (coordinator default unless user specifies otherwise).
+   - `invoke_subagent` fallback via `diagnose.mjs --print-dispatch <target>` (`all_l1`, `all_specialists`, or one squad; MCP `dispatch_squad` accepts `all_l1`, `<squadId>`, or `integrity_auditor[:<target>]`, whereas `all_specialists` is `diagnose.mjs` only).
+   - **Local Profiler Only:** run `diagnose.mjs` locally with zero agents launched.
+2. **Retention & Teardown (`Scope 2` vs `Scope 3`):** Keep loose reports via `prune --keep-reports` or prune after SHA-256 bundling (`Scope 2`); run `--teardown` after updating `docs/reviews/<target-review-slug>.md` or defer cleanup across active waves (`Scope 3`).
+3. **Integrity Audit Gate:** Independent Integrity Auditor enabled (`audit-<id>` on `/swarm` or `integrity_auditor[:<target>]` slot) enforcing `Integrity Verdict: CLEAN` before acceptance, vs working-squad synthesis only (`--allow-unaudited`).
+
+---
+
+### Step 1: Run the Automated Profiler (`L7`-Safe)
+Run `node .agents/skills/self-diagnosis/scripts/diagnose.mjs [--ledger docs/reviews/<slug>.md] --markdown`:
+1. **Skill & Doc Health (`SKILL`, `DOC`):** Validates frontmatter, entry budgets (`<= 10,240 B` / `<= 250` lines for `SKILL.md`; warns above `12,288 B` / `300` lines; `<= 70%` entry share when `> 8 KB`), relative links, `zensical.toml` `nav` & `docs/assets/*.svg`, closure checklists, and `v1.4.0` ledgers (`1 ID = 1 Row`, no retired symbol drift).
+2. **Planner, Dispatch & Pointer-Over-Wire Canary (`RUN`, `SVC`, `MCP`):** Compiles [`self-diagnosis-manifest.json`](./resources/self-diagnosis-manifest.json) for both tools, checks disjoint write scopes (skipping `readOnly: true`), and tests `fingerprint -> inspect -> bundle -> verify -> integrity -> prune` in temp storage.
+3. **Byte & Token Telemetry (`SKILL`, `RUN`):** Reports brief sizes, UTF-8/token overhead, and specialist timing regressions across `dispatch_squad`, `squad_planner`, handoff bundling, and MCP stdio checks.
+4. **Workspace Hygiene (`SVC`):** Detects orphaned `scratch/agy-squad/squad-*` cohorts against `--allow-active-cohort` and `--ledger`.
+
+---
+
+### Step 2: Execute Cohort, Verify Bundles & Tear Down
+Plan cohorts per [Planning & Dispatch Commands](./references/execution-and-teardown.md#planning-and-dispatch-commands) (working squads in [`self-diagnosis-manifest.json`](./resources/self-diagnosis-manifest.json): `skill_and_pr_review_audit`, `runtime_and_contract_diagnosis`, and `token_and_execution_optimization`; omit `squadId` on `/swarm` to compile all three, and follow [`swarm-governance`](../swarm-governance/SKILL.md#stage-1-plan-launch--park) for launch and UI lifecycle):
+
+1. **Bundle per Squad (`Scope 2`):** Assemble `<bundle-record.json>` from `--print-plan` `bundleRecordTemplates` plus `fingerprint` digests, run `digest` before `audit-*` signs `CLEAN`, and run `verdict`, `verdict --integrity`, `inspect`, `bundle`, `verify`, and `prune [--keep-reports]` for every working squad per [Multi-Squad Bundling & Prune](./references/execution-and-teardown.md#multi-squad-bundling-and-scope-2-prune).
+2. **Transcribe Ledger (`docs/reviews/`):** Record every distinct defect and proposal `1-to-1` (`1 ID = 1 Row`) into `docs/reviews/<target-review-slug>.md` before editing code or running teardown.
+3. **Atomic Teardown (`L41`, `Scope 3`), Remediation & Closure:** After the target ledger has `mtime >= bundle mtime`, run `diagnose.mjs --teardown` per [Scope 3 Atomic Teardown](./references/execution-and-teardown.md#scope-3-atomic-teardown-and-failure-modes), re-verify remediation fixes with the **same** specialists/workers, kill agents (`swarm{action: "kill"}` / `manage_subagents`), and complete the 4-check closure gate.
+
+---
+
+### Step 3: Triage & Verify Optimizations with `pr-review`
+Activate [`pr-review`](../pr-review/SKILL.md) with rubric thresholds from Sections 2–3 of [Optimization & Review Rubric](./references/optimization-and-review-rubric.md), trace invariants first, and prove exact before/after metrics and `npm test` pass after final edits.

package/.agents/skills/self-diagnosis/references/execution-and-teardown.md

@@ -0,0 +1,71 @@
+# Self-Diagnosis Execution, Bundling & Teardown Reference
+
+Uncondensed execution examples, multi-squad bundling workflows, and Scope 2 / Scope 3 `--teardown` edge cases for [`.agents/skills/self-diagnosis/SKILL.md`](../SKILL.md).
+
+## Planning and Dispatch Commands
+
+Run [`scripts/diagnose.mjs`](../scripts/diagnose.mjs) from the repository root (`node .agents/skills/self-diagnosis/scripts/diagnose.mjs`):
+
+```bash
+# 1. Zero-subagent local profiler (add --allow-active-cohort when scratch/agy-squad/squad-* is in flight):
+node .agents/skills/self-diagnosis/scripts/diagnose.mjs --markdown
+node .agents/skills/self-diagnosis/scripts/diagnose.mjs --ledger docs/reviews/<slug>.md --markdown
+
+# 2. Primary /swarm cohort plan (squad_planner): omit squadId to plan all 3 working squads, or pass --topology flat|layered:
+node .agents/skills/self-diagnosis/scripts/diagnose.mjs \
+  --print-plan [squadId] [--topology flat|layered | --flat] [--mode swarm|subagent] [--workspace-isolation inherit|share|branch]
+
+# 3. Fallback invoke_subagent stage compiler (all_l1, all_specialists, or single squadId):
+node .agents/skills/self-diagnosis/scripts/diagnose.mjs \
+  --print-dispatch <all_l1|all_specialists|squadId> --parent-id <parent-conversation-id>
+```
+
+- **Note on `all_specialists`:** `all_specialists` is supported only by `diagnose.mjs --print-dispatch`; MCP `dispatch_squad` accepts `all_l1`, a single `<squadId>`, or `integrity_auditor[:<target>]`.
+- **Self-diagnosis working squads (`self-diagnosis-manifest.json`, `readOnly: true` specialists):**
+  - `skill_and_pr_review_audit`: 2 specialists covering `SKILL`, `DOC`, `ARCH`, `SCRIPT`.
+  - `runtime_and_contract_diagnosis`: 2 specialists covering `MCP`, `RUN`, `SVC`, `SCRIPT`, `TEST`, `DEP`.
+  - `token_and_execution_optimization`: 2 specialists covering `RUN`, `SKILL`, `SVC`, `ARCH`.
+
+## Multi-Squad Bundling and Scope 2 Prune
+
+When running all three squads in Layered mode (or any multi-squad plan), each working squad owns its own report directory (`scratch/agy-squad/squad-<squadId>/`), its own flat integrity auditor (`audit-<squadId>` -> `scratch/agy-squad/squad-integrity_auditor-<squadId>/specialist-1/report.md`), and its own `<bundle-record.json>`:
+
+```bash
+# Per working squad (<id> = skill_and_pr_review_audit | runtime_and_contract_diagnosis | token_and_execution_optimization, or self_diagnosis in flat mode):
+node bin/agy-squad.mjs verdict scratch/agy-squad/squad-<id>/lead/report.md
+node bin/agy-squad.mjs fingerprint <verified-file...>
+node bin/agy-squad.mjs digest <bundle-record-<id>.json>
+node bin/agy-squad.mjs verdict --integrity scratch/agy-squad/squad-integrity_auditor[-<id>]/specialist-1/report.md
+node bin/agy-squad.mjs inspect <bundle-record-<id>.json>
+node bin/agy-squad.mjs bundle <bundle-record-<id>.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]
+```
+
+- **Scope 2 (`prune`) vs. Scope 3 (`--teardown`):** `prune` removes only verified loose `specialist-<N>/report.md` files (preserving `lead/report.md` and `lead/report.sources.json`) unless `--keep-reports` is passed. `Scope 3` (`--teardown`) removes the entire `scratch/agy-squad/squad-*` cohort tree after durable ledger verification.
+
+## Scope 3 Atomic Teardown and Failure Modes
+
+Run `--teardown` **only after** every distinct finding from the cohort is transcribed `1-to-1` (`1 ID = 1 Row`) into `docs/reviews/<target-review-slug>.md`:
+
+```bash
+# Tear down one verified squad (optional --accept <sha256> pins expected bundle digest):
+node .agents/skills/self-diagnosis/scripts/diagnose.mjs \
+  --teardown <squadId> [--accept <64-hex-sha256>] --ledger docs/reviews/<target-review-slug>.md
+
+# Tear down all completed self-diagnosis squads and accompanying integrity_auditor* directories:
+node .agents/skills/self-diagnosis/scripts/diagnose.mjs \
+  --teardown all --ledger docs/reviews/<target-review-slug>.md
+
+# Override refusal only when discarding an aborted or superseded diagnostic cohort:
+node .agents/skills/self-diagnosis/scripts/diagnose.mjs \
+  --teardown all --ledger docs/reviews/<target-review-slug>.md --force
+```
+
+### Pre-Teardown Refusal Conditions and Partial Cleanup
+
+1. **Unbundled evidence refusal:** If `scratch/agy-squad/squad-<id>/lead/report.sources.json` is missing or fails `verifyBundle()`, `--teardown` exits `1` (`unbundled evidence`) and deletes nothing unless `--force` is passed.
+2. **Stale ledger refusal (`mtime < bundle mtime`):** If the target `docs/reviews/<target-review-slug>.md` has not been modified at or after the bundle's creation timestamp (or fails v1.4.0 ledger schema validation), `--teardown` exits `1` without deleting `scratch/`.
+3. **Finding-ID coverage check:** Scoped teardown verifies that findings referenced in the verified bundle/reports appear in the target ledger before removing evidence.
+4. **Scoped vs. `all` teardown with auditors:** Single-squad `--teardown <squadId>` removes `squad-<squadId>`; `--teardown all` deletes working squad directories and removes verified bundle artifacts only alongside valid ledger gates—never call `--teardown` before saving the durable ledger or running same-cohort remediation re-checks.
+5. **Partial permission failure during cleanup:** Check command exit codes and `ls scratch/` afterwards; if a partial deletion failure leaves orphaned files after fixing permissions, re-run `--teardown` (or `prune` for `Scope 2`) to finish cleaning empty `scratch/agy-squad/` and `scratch/` directories.

package/.agents/skills/self-diagnosis/references/optimization-and-review-rubric.md

@@ -0,0 +1,61 @@
+# Agy-Squad Self-Diagnosis, PR-Review & Optimization Rubric
+
+This reference pairs the `self-diagnosis` skill with the [Agy-Squad PR Review Standard v1.4.0](../../pr-review/references/pr-review-standard.md) ([`pr-review` skill](../../pr-review/SKILL.md)). Use it to classify self-diagnosis findings, verify skill and runtime invariants, and evaluate token and execution optimizations.
+
+---
+
+## 1. Coupling `self-diagnosis` with `pr-review` (Standard v1.4.0)
+
+Every self-diagnosis pass evaluates `Agy-Squad` and its skills (`.agents/skills/self-diagnosis/`, `.agents/skills/pr-review/`) using the `pr-review` v1.4.0 trace chain:
+
+`design thesis / invariant -> current architecture decision (LEDGER.md) -> public contract -> implementation -> verification`
+
+Map every diagnosed defect or optimization opportunity to **one primary category** from the 10 mandatory `pr-review` categories (cross-referencing related categories without double-counting):
+
+| Category | Self-Diagnosis & Optimization Focus |
+| --- | --- |
+| `ARCH` | `L1`–`L43` ledger alignment, host-enforced vs. receipt-verified boundaries, workspace containment, and cohort topology. |
+| `DOC` | `README.md`, `docs/tools.md`, `docs/plans/LEDGER.md`, and `docs/reviews/` parity with runtime behavior and benchmark/trial evidence. |
+| `SKILL` | `.agents/skills/*/SKILL.md` frontmatter (`name`, `description`), relative link integrity, progressive disclosure ratio (`SKILL.md` vs. `references/` and `scripts/`), and accuracy of referenced tools/flags. |
+| `MCP` | `mcp/index.js` JSON-RPC 2.0 compliance, positive integer `AGY_MAX_STDIO_PAYLOAD_BYTES` limits, and `dispatch_squad` / `squad_planner` schema compactness. |
+| `RUN` | `mcp/dispatch.mjs`, `mcp/briefs.mjs`, and `mcp/planner.mjs` symlink/fd checks, `TypeName: "self"` + rejected built-ins (`research`, `browser`, `image-generator`), `modelProvenance`, and scope overlap checks. |
+| `SVC` | `mcp/handoffs.mjs`, `mcp/verdicts.mjs`, and `bin/agy-squad.mjs` receipt reconciliation, custom `reportRoot` handling, `readSynthesis` PASS verdict, `integrityAudit` binding, atomic bundle replacement, and `--teardown`. |
+| `DB` | Verify absence of unreviewed database state (file-backed atomic bundle persistence is audited under `SVC`). |
+| `SCRIPT` | `bin/agy-squad.mjs` (`plan`, `dispatch`, `fingerprint`, `inspect`, `bundle`, `verify`, `prune`, `verdict`) and `.agents/skills/self-diagnosis/scripts/diagnose.mjs` deterministic exit codes and argument validation (`mcp/handoffs.mjs` is the internal library module, not a CLI). |
+| `TEST` | `tests/test-*.mjs` assertion strength, adversarial coverage, two-process concurrency, and supervised live subagent verification. |
+| `DEP` | `package.json`, `zensical.toml`, `.gitignore`, and `.github/workflows/*.yml` coherence. |
+
+---
+
+## 2. Quantitative Optimization Budgets & Thresholds
+
+`scripts/diagnose.mjs` measures the following budgets and flags violations or optimization opportunities:
+
+| Metric | Target Budget | Warning / Optimization Threshold | Triage When Exceeded |
+| --- | --- | --- | --- |
+| **`SKILL.md` Entry Size (Progressive Disclosure)** | $\le 250$ lines and $\le 10,240$ UTF-8 bytes ($\approx 2,500$ tokens) per `SKILL.md` | $> 300$ lines or $> 12,288$ UTF-8 bytes, or $> 70\%$ of total skill text inlined in `SKILL.md` when total skill size $> 8\text{ KiB}$ | `P2` (if instructions conflict/truncate) or `P3` Advisory (`SKILL`) — extract bulky tables/examples into `references/` or `scripts/`. |
+| **Compiled Specialist Brief Overhead** | $\le 1,600$ UTF-8 bytes ($\approx 400$ tokens) of fixed template text in `buildSubagentSpec` | $> 1,800$ UTF-8 bytes of fixed template text | `P3` Advisory (`RUN` / `SKILL`) — tighten `mcp/briefs.mjs` prompt lines without dropping required handoff rules. |
+| **Compiled Lead Brief Overhead** | $\le 3,100$ UTF-8 bytes ($\approx 775$ tokens) of fixed template text (including `superviseCohort`) | $> 3,300$ UTF-8 bytes of fixed template text | `P3` Advisory (`RUN` / `SKILL`). |
+| **MCP `tools/list` Schema Response** | $\le 3,072$ UTF-8 bytes (`dispatch_squad` + `squad_planner`) | $> 4,096$ UTF-8 bytes (`MCP-BUDGET-SCHEMA`) | `P3` Advisory (`MCP`) — tighten schema descriptions in `mcp/index.js`. |
+| **Pointer-Over-Wire Receipt Headroom** | `READY <slot> — ` prefix $\le 150$ UTF-8 bytes, leaving $\ge 350$ bytes of the `500`-byte `messageLimit` for the observation | Prefix $> 160$ UTF-8 bytes | `P2` (`SVC` / `RUN`) — shorten `squadId` or slot path encoding. |
+| **Sibling Specialist `scopeFiles` Overlap** | $0\%$ overlapping files across specialists in the same squad | $> 25\%$ overlapping `scopeFiles` within one squad | `P2` (for concurrent writers) or `P3` Advisory (for readers) — partition `scopeFiles` cleanly across specialists or use `/swarm` `workspace: "share"`. |
+| **Stage Compilation & Planner Latency (`handleDispatchSquad` / `planSquadCohort`)** | $< 10\text{ ms}$ per call on local SSD/WSL | $> 25\text{ ms}$ per call | `P3` Advisory (`RUN`) — inspect redundant `realpathSync` / manifest re-reads. |
+| **Handoff & Bundle Pipeline Latency (`inspect` + `bundle` + `verify` + `prune`)** | $< 20\text{ ms}$ for a 2-specialist cohort | $> 50\text{ ms}$ for a 2-specialist cohort | `P3` Advisory (`SVC`) — inspect redundant file opens in `verifyFiles` / `verifyBundle`. |
+
+---
+
+## 3. Failure-to-Category Triage Matrix
+
+| Diagnostic Check | Failure Symptom | Primary Category & Priority | Root Cause & Remediation |
+| --- | --- | --- | --- |
+| **Skill Frontmatter & Links** | Missing `name` / `description` YAML frontmatter or broken relative link (`[...](./path)`) in `.agents/skills/*/SKILL.md` | `SKILL` (**P1** if broken script/manifest link; **P2** if broken doc link) | Fix frontmatter or restore the missing target file under `.agents/skills/<skill>/`. |
+| **Skill Tool/API Drift** | Skill instructs use of retired Phase 1/2 symbols (`subagent_brief`, `spawnPacingMs`, `agy-squad run`, `terminal.py`, `run-state.mjs`, `AGY_SQUAD_RUN_DIR`, `AGY_SQUAD_SESSION`, `.mcp-ready`, `managed manifest`, `adversarial_l1`, `adversarial_flat`, `adversarial_review`, `node mcp/handoffs.mjs`, `integrity-auditor`) as active | `SKILL` (**P2**) | Update skill instructions to use `squad_planner` (`manifestPath`, inline `manifest`, or `task`), `dispatch_squad` (subagent mode only), `integrity_auditor[:<target>]` / `audit-<id>`, and `node bin/agy-squad.mjs` exclusively. |
+| **Report Readability & Formatting** | Review reports wrap plain numbers, English statuses, or multi-sentence quotes inside inline backticks or fenced code boxes in tables/prose | `DOC` / `SKILL` (**P3**) | Keep inline backticks strictly for code identifiers, paths, flags, and commands per `pr-review-standard.md` Section 5. |
+| **Preset Capability Check** | Specialist compiled with `TypeName: "research"` or `Workspace !== "inherit"` | `RUN` (**P1**) | Ensure `buildSubagentSpec` in `mcp/briefs.mjs` defaults `TypeName` to `"self"`, rejects `"research"`, and requires `Workspace === "inherit"`. |
+| **Synthesis Verdict Gate** | `bundleReports` or `verifyBundle` accepts a `lead/report.md` containing `FAIL`, `BLOCKED`, or no `PASS` token | `SVC` (**P1**) | Ensure `readSynthesis` in `mcp/handoffs.mjs` validates line-anchored `PASS` and rejects `FAIL` / `BLOCKED` across both `bundleReports` and `verifyBundle`. |
+| **Receipt Reconciliation** | Handoff rejected for `> 500` UTF-8 bytes, multiline text, wrong sender, or wrong slot | `SVC` (**P2**) | Ensure child sends single-line `READY <assigned-slot> — <observation>` within `500` UTF-8 bytes (`Buffer.byteLength`). |
+| **MCP Framing & Planner Boundary** | Oversized stdio payload allowed past `AGY_MAX_STDIO_PAYLOAD_BYTES`, negative byte limit accepted, or `squad_planner` omits `modelProvenance` / `provenanceScaffold` | `MCP` (**P1** / **P2**) | Verify positive integer `AGY_MAX_STDIO_PAYLOAD_BYTES` guard in `mcp/index.js` and `planSquadCohort` invariants in `mcp/planner.mjs`. |
+| **Durable Target PR Review Ledger Gate & `v1.4.0` Schema (`docs/reviews/`)** | Missing target ledger, starting code edits or `--teardown` before updating `docs/reviews/<target-review-slug>.md`, missing Sections `1–8` (`Session Provenance`, `Post-Remediation Residuals & Deferred Dispositions`, cross-section ID-status conflicts) or Section 9 (`/self-diagnosis` Cohort & Bundle Ledger), open P0–P2 ledger blockers, or umbrella IDs (`DOC-LEDGER-MISSING`, `DOC-LEDGER-SCHEMA`, `DOC-LEDGER-OPEN-BLOCKERS`) | `DOC` / `SVC` (**P1** if missing/stale pre-teardown; **P2** if schema/umbrella/open-blocker violation; **P3** `DOC-LEDGER-RESIDUALS-OPEN` while Section 8 `Residual (Open)` rows await fix) | Update `docs/reviews/<target-review-slug>.md` in place before remediation or `--teardown` with consistent `v1.4.0` Sections `1–8` (+ Section 9 for `/self-diagnosis` cohorts). |
+| **Self-Diagnosis Directory Teardown (`L41`)** | Lingering `scratch/agy-squad/squad-<id>` or `self-diag-canary-*` directories left in workspace after verification (`SVC-TEARDOWN-*`) | `SVC` (**P2** post-cohort; **P3** advisory when `--allow-active-cohort` is passed mid-cohort) | Run `node .agents/skills/self-diagnosis/scripts/diagnose.mjs --teardown [all | <squadId> [--accept <sha256>]] [--ledger docs/reviews/<slug>.md]` after updating the target `docs/reviews/` ledger to atomically verify bundles and remove self-diagnosis directories and empty `scratch/agy-squad` / `scratch` parent directories. |
+| **Cohort Agent Freshness vs. Remediation Check** | Reusing an old pass's subagent `conversationId` for an unrelated pass (`invoke_subagent` required), or spawning a brand-new squad when the operator requested verifying remediations on the active squad's exact findings (`send_message` required) | `SVC` (**P2**) | Launch fresh subagents (`invoke_subagent`) for new independent passes; message the **same** cohort (`send_message`) after `prune`/`--teardown` when verifying that their exact reported findings were remediated. |
+| **Post-Cohort Subagent Termination** | Completed subagents left lingering in `idle` state in the session table after final bundle verification and `--teardown` | `SVC` (**P2**) | Call `manage_subagents(Action='kill', ConversationIds=[...])` for all spawned subagents once the cohort's final verification (including any same-squad remediation check) and `--teardown` complete. |

package/.agents/skills/self-diagnosis/resources/comparative-research-manifest.json

@@ -0,0 +1,42 @@
+{
+  "squads": {
+    "harness_comparative_audit": {
+      "lead": {
+        "role": "Harness Comparative Architecture Lead",
+        "objective": "Synthesize findings from both research specialists into docs/plans/comparative-harness-architecture-retest.md, score all harnesses objectively against the 5-Axis Rubric, enforce the Squad Lead Patrol Gate against sycophancy, and verify citations.",
+        "scopeFiles": [
+          "docs/concepts.md",
+          "docs/core-workflows.md",
+          "benchmarks/teamwork-vs-squad/README.md",
+          "docs/plans/comparative-harness-architecture-retest.md"
+        ],
+        "instructions": "Wait for READY receipts from specialist-1 and specialist-2. Enforce the Squad Lead Patrol Gate: inspect specialist reports and tool traces via rtk read. Verify that specialists executed search_web and cited primary sources without parametric guessing or flattering bias. Synthesize the unified scoring matrix and comparative dossier in your lead report at your assigned slot and write the complete deliverable to docs/plans/comparative-harness-architecture-retest.md. Send a <=500B READY receipt to parent.",
+        "expectedDeliverable": "Synthesis report with Content Verdict: PASS | FAIL | BLOCKED, objective 5-Axis Rubric scores, and docs/plans/comparative-harness-architecture-retest.md."
+      },
+      "specialists": [
+        {
+          "role": "General Workflow & Graph Harness Specialist",
+          "objective": "Empirically audit MetaGPT (SOP-driven), CrewAI (role-playing), AutoGen / Swarm (conversational broadcast), and LangGraph (statechart DAGs). Contrast their IPC token footprints, state machines, and scratch handling against Agy-Squad's Pointer-Over-Wire model.",
+          "scopeFiles": [
+            "mcp/briefs.mjs",
+            "mcp/dispatch.mjs",
+            "docs/concepts.md"
+          ],
+          "instructions": "Execute search_web to audit external architecture documentation and papers for MetaGPT, CrewAI, AutoGen, and LangGraph. Profile token transmission overhead per turn compared to Agy-Squad's 500-byte receipt ceiling. Do not rely on parametric memory or internal flattery. Write your detailed markdown report with citations to your specialist slot.",
+          "expectedDeliverable": "Markdown evidence report with comparative matrix, protocol sequence diagrams, and 5-axis ratings for the 4 general workflow harnesses."
+        },
+        {
+          "role": "Autonomous Coding & SWE Harness Specialist",
+          "objective": "Empirically audit Devin/Sol (sandboxed SWE workspace), Claude Code / SWE-agent (interactive command execution), and Google Antigravity Native /teamwork. Compare their evidence retention, sandbox boundaries, and context compaction against Agy-Squad.",
+          "scopeFiles": [
+            "bin/agy-squad.mjs",
+            "mcp/planner.mjs",
+            "benchmarks/teamwork-vs-squad/README.md"
+          ],
+          "instructions": "Execute search_web and inspect benchmark files to audit Devin/SWE-agent execution patterns and Antigravity native /teamwork. Measure context consumption under heavy test runs and compare with Agy-Squad's swarm planning and L41 teardown. Do not rely on parametric memory or internal flattery. Write your detailed markdown report with citations to your specialist slot.",
+          "expectedDeliverable": "Markdown evidence report with comparative matrix, blast-radius analysis, and 5-axis ratings for the 3 coding agent harnesses."
+        }
+      ]
+    }
+  }
+}

package/.agents/skills/self-diagnosis/resources/self-diagnosis-manifest.json

@@ -0,0 +1,144 @@
+{
+  "squads": {
+    "skill_and_pr_review_audit": {
+      "lead": {
+        "role": "Skill & PR-Review Standard Lead",
+        "readOnly": true,
+        "objective": "Apply the Agy-Squad PR Review Standard v1.4.0 (.agents/skills/pr-review/SKILL.md) to audit .agents/skills/self-diagnosis and .agents/skills/pr-review for contract accuracy, progressive disclosure, and token efficiency.",
+        "scopeFiles": [
+          ".agents/skills/self-diagnosis/SKILL.md",
+          ".agents/skills/self-diagnosis/scripts/diagnose.mjs",
+          ".agents/skills/pr-review/SKILL.md",
+          "docs/tools.md"
+        ],
+        "instructions": "For subagent fallback, compile via 'diagnose.mjs --print-dispatch skill_and_pr_review_audit --parent-id <id>'. On /swarm, wait via swarm_wait for READY receipts, inspect specialist reports with rtk read, write verified synthesis ('Content Verdict: PASS', FAIL, or BLOCKED) preserving 1-ID-per-finding granularity (never compress or omit distinct P0-P3/optimization/residual items before prune), verify planner-assigned flat audit-* reports 'Integrity Verdict: CLEAN', run 'node bin/agy-squad.mjs' (fingerprint, inspect, bundle, verify, prune), and post <=500B READY.",
+        "expectedDeliverable": "Synthesis report with Content Verdict: PASS | FAIL | BLOCKED, SKILL/DOC/ARCH/SCRIPT triage, and verified SHA-256 hashes."
+      },
+      "specialists": [
+        {
+          "role": "Self-Diagnosis Skill & Progressive Disclosure Auditor",
+          "readOnly": true,
+          "objective": "Audit .agents/skills/self-diagnosis/SKILL.md, scripts/diagnose.mjs, resources/self-diagnosis-manifest.json, and references/optimization-and-review-rubric.md using pr-review SKILL/DOC/SCRIPT criteria: verify frontmatter, relative links, CLI flags, progressive disclosure ratio (SKILL.md vs references/), and propose concrete token or runtime optimizations.",
+          "scopeFiles": [
+            ".agents/skills/self-diagnosis/SKILL.md",
+            ".agents/skills/self-diagnosis/scripts/diagnose.mjs",
+            ".agents/skills/self-diagnosis/resources/self-diagnosis-manifest.json",
+            ".agents/skills/self-diagnosis/references/optimization-and-review-rubric.md"
+          ],
+          "instructions": "Use rtk read via run_command to inspect your scopeFiles (never call read_file; pass --allow-active-cohort when running diagnose.mjs while sibling cohorts are active, and never run --teardown mid-cohort).",
+          "expectedDeliverable": "Markdown evidence report with SKILL/DOC/SCRIPT P1/P2/P3 triage, progressive disclosure byte counts, concrete optimization proposals, and exact line references."
+        },
+        {
+          "role": "PR-Review Skill & Contract Alignment Auditor",
+          "readOnly": true,
+          "objective": "Cross-check .agents/skills/pr-review/SKILL.md and references/pr-review-standard.md against current Agy-Squad runtime contracts (mcp/index.js, mcp/dispatch.mjs, mcp/briefs.mjs, mcp/handoffs.mjs, docs/plans/LEDGER.md, docs/tools.md) and identify any stale guidance or token/prompt optimization opportunities.",
+          "scopeFiles": [
+            ".agents/skills/pr-review/SKILL.md",
+            ".agents/skills/pr-review/references/pr-review-standard.md",
+            "docs/plans/LEDGER.md",
+            "docs/tools.md"
+          ],
+          "instructions": "Use rtk read via run_command to inspect your scopeFiles (never call read_file).",
+          "expectedDeliverable": "Markdown evidence report with SKILL/ARCH/DOC P1/P2/P3 triage, contract provenance checks, and concrete optimization recommendations."
+        }
+      ]
+    },
+    "runtime_and_contract_diagnosis": {
+      "lead": {
+        "role": "Runtime & Contract Diagnostics Lead",
+        "readOnly": true,
+        "objective": "Execute a pr-review v1.4.0 audit across MCP, RUN, SVC, SCRIPT, TEST, and DEP categories to detect unhandled edge cases, boundary gaps, or state-cleanup defects in Agy-Squad.",
+        "scopeFiles": [
+          "mcp/index.js",
+          "mcp/dispatch.mjs",
+          "mcp/briefs.mjs",
+          "mcp/handoffs.mjs",
+          "mcp/planner.mjs",
+          "bin/agy-squad.mjs"
+        ],
+        "instructions": "For subagent fallback, compile via 'diagnose.mjs --print-dispatch runtime_and_contract_diagnosis --parent-id <id>'. On /swarm, wait via swarm_wait for READY receipts, inspect specialist reports with rtk read, write verified synthesis ('Content Verdict: PASS', FAIL, or BLOCKED) preserving 1-ID-per-finding granularity (never compress or omit distinct P0-P3/optimization/residual items before prune), verify planner-assigned flat audit-* reports 'Integrity Verdict: CLEAN', run 'node bin/agy-squad.mjs' (fingerprint, inspect, bundle, verify, prune), and post <=500B READY.",
+        "expectedDeliverable": "Synthesis report with Content Verdict: PASS | FAIL | BLOCKED summarizing MCP/RUN/SVC/SCRIPT/TEST/DEP findings."
+      },
+      "specialists": [
+        {
+          "role": "MCP, Dispatch, Planner & Handoff Boundary Inspector",
+          "readOnly": true,
+          "objective": "Audit mcp/index.js, mcp/dispatch.mjs, mcp/briefs.mjs, mcp/handoffs.mjs, mcp/verdicts.mjs, and mcp/planner.mjs under pr-review MCP, RUN, and SVC criteria: verify input validation, symlink/fd containment, TypeName/Workspace invariants, <= 500 byte receipt grammar, model provenance caveats, and readSynthesis verdict enforcement.",
+          "scopeFiles": [
+            "mcp/index.js",
+            "mcp/dispatch.mjs",
+            "mcp/briefs.mjs",
+            "mcp/handoffs.mjs",
+            "mcp/verdicts.mjs",
+            "mcp/planner.mjs"
+          ],
+          "instructions": "Use rtk read via run_command to inspect your scopeFiles (never call read_file).",
+          "expectedDeliverable": "Markdown evidence report with MCP/RUN/SVC P1/P2/P3 triage and reproduction or test coverage evidence."
+        },
+        {
+          "role": "Governance CLI, Bundler & Test Coverage Inspector",
+          "readOnly": true,
+          "objective": "Audit bin/agy-squad.mjs and tests/ under pr-review SCRIPT, TEST, and DEP criteria: verify CLI argument validation, --allow-unaudited override behavior, bundle integrity verification, and adversarial test assertions.",
+          "scopeFiles": [
+            "bin/agy-squad.mjs",
+            "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"
+          ],
+          "instructions": "Use rtk read via run_command to inspect your scopeFiles (never call read_file).",
+          "expectedDeliverable": "Markdown evidence report with SCRIPT/TEST/DEP P1/P2/P3 triage and verification gap analysis."
+        }
+      ]
+    },
+    "token_and_execution_optimization": {
+      "lead": {
+        "role": "Token & Execution Optimization Lead",
+        "readOnly": true,
+        "objective": "Profile and optimize Agy-Squad's context footprint, compiled brief byte budgets, squad manifest topology, and filesystem/IPC hot paths without weakening L1-L43 guarantees.",
+        "scopeFiles": [
+          "mcp/briefs.mjs",
+          "mcp/dispatch.mjs",
+          "mcp/handoffs.mjs",
+          "mcp/planner.mjs",
+          "mcp/index.js",
+          "bin/agy-squad.mjs",
+          ".agents/skills/self-diagnosis/SKILL.md",
+          ".agents/skills/pr-review/SKILL.md"
+        ],
+        "instructions": "For subagent fallback, compile via 'diagnose.mjs --print-dispatch token_and_execution_optimization --parent-id <id>'. On /swarm, wait via swarm_wait for READY receipts, inspect specialist reports with rtk read, write verified synthesis ('Content Verdict: PASS', FAIL, or BLOCKED) preserving 1-ID-per-finding granularity (never compress or omit distinct P0-P3/optimization/residual items before prune), verify planner-assigned flat audit-* reports 'Integrity Verdict: CLEAN', run 'node bin/agy-squad.mjs' (fingerprint, inspect, bundle, verify, prune), and post <=500B READY.",
+        "expectedDeliverable": "Synthesis report with Content Verdict: PASS | FAIL | BLOCKED, ranked optimizations, and measured byte/latency deltas."
+      },
+      "specialists": [
+        {
+          "role": "Prompt, Schema & Skill Token Optimizer",
+          "readOnly": true,
+          "objective": "Measure UTF-8 byte and token budgets across mcp/briefs.mjs (superviseCohort, superviseIntegrityCohort, compiled lead/specialist prompts), mcp/index.js (tools/list schema), and .agents/skills/*/SKILL.md; identify concrete wording or progressive-disclosure optimizations that reduce context overhead while preserving all contract invariants.",
+          "scopeFiles": [
+            "mcp/briefs.mjs",
+            "mcp/index.js",
+            ".agents/skills/self-diagnosis/SKILL.md",
+            ".agents/skills/pr-review/SKILL.md"
+          ],
+          "instructions": "Use rtk read via run_command to inspect your scopeFiles (never call read_file).",
+          "expectedDeliverable": "Markdown evidence report with exact byte/token measurements and concrete before/after optimization proposals."
+        },
+        {
+          "role": "I/O, Concurrency & Cohort Topology Optimizer",
+          "readOnly": true,
+          "objective": "Inspect mcp/dispatch.mjs, mcp/planner.mjs, mcp/handoffs.mjs, and bin/agy-squad.mjs for redundant filesystem syscalls (realpathSync, openSync, statSync), cohort fan-out bottlenecks, and scopeFiles overlap; propose measurable runtime optimizations.",
+          "scopeFiles": [
+            "mcp/dispatch.mjs",
+            "mcp/planner.mjs",
+            "mcp/handoffs.mjs",
+            "bin/agy-squad.mjs"
+          ],
+          "instructions": "Use rtk read via run_command to inspect your scopeFiles (never call read_file).",
+          "expectedDeliverable": "Markdown evidence report with syscall/latency analysis and ranked runtime optimization proposals."
+        }
+      ]
+    }
+  }
+}