agy-squad 0.0.0-stage → 0.1.1

package/.agents/skills/full-review/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: full-review
+description: >-
+  [Task Spec — non-diff triage, evidence bundles & Direction decisions; pair with
+  swarm-governance on /swarm] Use when the user asks for a full review, triage,
+  diagnosis, or direction recommendation on Agy-Squad using repository state or
+  supplied evidence (transcripts, logs, CI output, review ledgers, diffs),
+  including work that is not a pull request. Applies the Agy-Squad PR Review
+  Standard v1.4.0 with cited, commit-pinned evidence and 1-ID-per-row findings.
+---
+
+# Agy-Squad Full Review Skill (Standard v1.4.0)
+
+Review a repository target, change, or evidence bundle and answer the question the user asked. This skill is a **Task Spec** for non-diff reviews, evidence triage, and direction decisions (distinct from `pr-review` for branch/PR diffs and `self-diagnosis` for automated harness self-audits). When executed as a team or `/swarm`, compose it with the `swarm-governance` **Execution Modifier** and choose `squad_planner` (`node bin/agy-squad.mjs plan`) for `/swarm` or `dispatch_squad` (`node bin/agy-squad.mjs dispatch`) for `invoke_subagent`.
+
+The governing report contract is [Agy-Squad PR Review Standard v1.4.0](../pr-review/references/pr-review-standard.md); see [Roles & skill workflows](../../../docs/roles-and-workflows.md#full-review) for the composition matrix, MCP/CLI surface map, and 4-check runtime closure gate. Passing tests, docs, prior approvals, and transcripts are inputs, not proof of architecture or claimed verification.
+
+## Use this skill when
+
+- The user asks for a review, audit, triage, or root cause of Agy-Squad, a commit range, subsystem, skill, or document beyond a single PR diff.
+- The user supplies non-diff evidence (transcripts, logs, CI runs, ledgers, benchmarks) or asks a direction question (merge/rework, keep/close, option selection, sequencing).
+- A PR review needs multi-artifact evidence or a Direction decision section.
+
+For a standard PR/branch diff without non-diff direction framing, prefer `pr-review`. Keep diagnosis separate from unauthorized code edits.
+
+## Invariants (Non-negotiables)
+
+1. **Read the standard first.** Its ten categories, category records, finding schema, status enums, evidence rules, and report structure are mandatory; this skill adds non-PR intake and Direction decisions.
+2. **Pin target and evidence.** Record revisions, SHA-256 hashes, dirty state, access status, and unexamined scope.
+3. **Architecture before runtime.** Trace `design thesis / invariant -> architecture decision -> public contract -> implementation -> verification` before judging behavior; record contract mismatches as findings.
+4. **All ten categories, all three triage buckets.** Every category (`ARCH`, `DOC`, `SKILL`, `MCP`, `RUN`, `SVC`, `DB`, `SCRIPT`, `TEST`, `DEP`) records scope, coverage, P1, P2, P3, verification, and verdict (`Not applicable` or `None identified within reviewed scope` or `Not assessed` — never silent skips).
+5. **`1 ID = 1 Row`.** One stable ID per independently remediable defect (no umbrella ranges or silent drops). One canonical status per row; `Informational` applies only to non-defects in Section 8.
+6. **Cite exact locators and label evidence.** Cite commit-pinned line ranges, transcript steps/timestamps, exact commands + exit codes, or dated URLs. Separate observed execution from `Source-derived inference`.
+7. **Do not inherit prior verdicts or waive findings from pass counts.** Revalidate prior items explicitly (accept, revise, or reject).
+8. **Separate content acceptance from integrity audit.** Content reviewer/lead owns `PASS`/`FAIL`/`BLOCKED` (or `APPROVE`/`REQUEST_CHANGES`); an independent auditor (`audit-<id>` on `/swarm` or `integrity_auditor[:<target>]` via slot) owns `CLEAN`/`INTEGRITY VIOLATION` and cannot waive content defects. Lead re-reviews after `CLEAN`. See [review roles](references/review-roles.md).
+9. **Enforce report readability.** Reserve inline backticks for code identifiers, file paths, flags, CLI commands, and verdict enums. Write plain numbers, counts, English statuses, labels, and quoted sentences as clean prose (no backtick-pill clutter).
+
+### Citation contract
+
+- **Code:** commit-pinned `path#Lx-Ly` with `HEAD`/tree pinned in Section 1.
+- **Transcript:** manifest SHA-256 hash, `step N @ ISO timestamp`, and verbatim quote.
+- **Command:** working directory, exact command, exit code, and observed output excerpt.
+- **External source:** title, URL, version/date, access date; label inference as `Source-derived inference`.
+- **Prior review:** prior report + finding ID + explicit status (`accepted`, `revised`, or `rejected`).
+
+## Workflow
+
+### Step 0 — Frame the request and execution mode
+
+1. State the decision/review question in one sentence, name the target type (`PR/branch`, `working tree`, `commit range`, `repository/subsystem`, `evidence bundle`, `direction question`, or `incident/regression`), and pin minimum evidence per [references/evidence-intake.md](references/evidence-intake.md).
+2. Check ambiguity once upfront without asking for facts already visible in git/evidence:
+   - If stacked on an unmerged PR base, confirm base branch and merge order.
+   - If running on `/swarm`, delegate Step 0 intake (neutral `Flat` vs `Layered` topology, `workspaceIsolation`, retention, coordinator-default model), `open_board` (`?tab=graph`), `swarm_wait`, pointer receipts, multi-cycle continuation, and shutdown to [`swarm-governance`](../swarm-governance/SKILL.md#step-0-pre-flight-intake-ask-when-unspecified) and [swarm intake & UI lifecycle](../swarm-governance/references/intake-and-planning.md#step-0-intake-question-templates).
+
+### Step 1 — Pin the review
+
+Populate Section 1 of [references/report-template.md](references/report-template.md): repository, target, base, date, reviewer, standard version, executed trees, **Session Provenance** table, **Evidence manifest**, artifact inventory, and explicit scope/exclusions. For a new `HEAD`, invalidate affected prior conclusions and state which prior findings carry forward.
+
+### Step 2 — Ingest evidence in batches
+
+Index large transcripts/logs once and read targeted windows (never poll step-by-step):
+1. Record size, SHA-256 hash, format, and entry count.
+2. Extract skeleton first (user turns, final messages, tool names/failures, step/time index).
+3. Inspect targeted windows around decision points, reversals, constraints, verdicts, and quoted claims.
+4. Separate user assertions, model claims, tool outputs, and external claims; log skipped or truncated ranges.
+
+See [references/evidence-intake.md](references/evidence-intake.md) for batch extraction and hashing commands.
+
+### Step 3 — Trace architecture before runtime
+
+Trace `design thesis / invariant -> architecture decision -> public contract -> implementation -> verification` using normative records (`docs/plans/LEDGER.md`, `docs/plans/wsl-cli-verification.md`, commit `ee10ebc`). Distinguish historical design records from active contracts and note compatibility impacts of intentional changes.
+
+### Step 4 — Review the ten categories & record findings
+
+Map each artifact to one primary category and cross-reference secondary impacts without double-counting. Record concise 10-field blocks for `P0`/`P1`/`P2` and `1 ID = 1 Row` table entries for `P3` per [pr-review-standard.md](../pr-review/references/pr-review-standard.md). Use Section 8 (`Post-Remediation Residuals & Deferred Dispositions`) as the mandatory sink for residuals, deferred proposals, by-design closures, and informational items. A zero-finding ("No findings") result is valid; finding quotas are prohibited.
+
+### Step 5 — Answer direction questions (when requested)
+
+Add a **Direction decision** subsection to Section 7 containing:
+1. One-sentence **Decision question**.
+2. Cited **Constraints** (hard constraints vs preferences).
+3. **Options** (including status quo and a minimal/do-less option) with preserved invariants, costs, dependencies, reversibility, blast radius, and pros/cons evidence.
+4. **Recommendation** with load-bearing evidence, **Falsifiers**, ordered **Immediate next actions** (each with an acceptance test), and **What not to do**.
+
+Keep coverage and disposition separate: do not recommend merging while material categories are unreviewed or P1/P2 blockers stay open.
+
+### Step 6 — Write, recheck, and close
+
+Save under `docs/reviews/<review-slug>.md` using [references/report-template.md](references/report-template.md) (omit Section 9 unless `/self-diagnosis` cohorts ran; write `None (0 open residuals, 0 deferred items)` if Section 8 is empty). Recheck fixes against primary and cross-referenced categories at the fixed revision—a fix commit alone is not closure. Before delivering, verify all checks in [references/report-template.md](references/report-template.md#quality-gates).

package/.agents/skills/full-review/references/evidence-intake.md

@@ -0,0 +1,146 @@
+# Evidence intake for full reviews
+
+This reference supports Step 1 and Step 2 of [../SKILL.md](../SKILL.md). It is a procedure, not a substitute for the [PR Review Standard v1.4.0](../../pr-review/references/pr-review-standard.md).
+
+## 0. Target types and minimum evidence
+
+| Target type | Baseline to pin | Minimum evidence |
+| --- | --- | --- |
+| Pull request / branch | merge-base and head SHA | diff, changed-file inventory, CI commit, prior review ledger |
+| Working tree | `HEAD` plus dirty delta | tracked diff, untracked inventory, commands run |
+| Commit range | base..head | changed files, affected contracts, tests |
+| Whole repository or subsystem | one pinned SHA | inventory, dependencies, normative records |
+| Evidence bundle | artifact hashes and locators | transcript/log/CI plus the claims they are meant to prove |
+| Direction question | pinned state plus decision constraints | options, prior decisions, evidence for and against each option |
+| Incident / regression | last known good..bad | reproduction, logs, timeline, blast radius |
+
+## 1. Build the evidence manifest first
+
+Every artifact that will be cited gets an `EID`, a locator, a content hash or size, a class, an access status, and an examined scope. The manifest is part of the report, not private scratch work.
+
+| Field | Meaning |
+| --- | --- |
+| `EID` | Stable ID such as `E01`; findings cite it. |
+| `Artifact` | File name, transcript, CI run, URL, or command output. |
+| `Locator` | Path, URL, commit, step range, or line range. |
+| `SHA-256 / size` | Content identity; use the hash when available, size plus date otherwise. |
+| `Class` | Repository source, normative design record, user-provided evidence, local execution, CI log, external source, or prior review. |
+| `Access` | `Examined`, `Partially examined`, `Unavailable`, or `Not examined`. |
+| `Examined` | Exact sections, steps, lines, or queries actually read. |
+
+Rules:
+
+- A hash proves identity, not truth. It does not prove that the content was read or that its claims are correct.
+- State when an attachment, environment, CI run, or external source was unavailable. Do not fill the gap with inference.
+- Keep user-provided evidence separate from repository evidence. A transcript is a record of claims, not an authoritative design record.
+- If the evidence is large, record the index you built and the windows you read. Do not imply full coverage from targeted reads.
+
+## 2. Pin revisions and working state
+
+For a Git target, record at minimum:
+
+```bash
+git rev-parse HEAD
+git rev-parse <base>
+git status --porcelain
+git diff --stat <base>..HEAD
+git diff --name-status <base>..HEAD
+```
+
+For a working-tree review, also capture the tracked diff and the untracked inventory. For a PR, record the PR URL, base branch, head branch, head SHA, mergeability, and the exact commit each CI run executed. Distinguish the PR head from GitHub's generated merge commit.
+
+For local execution, record the runtime and environment, not just the command:
+
+```text
+cwd: <path>
+runtime: <node/python version, OS, sandbox mode>
+command: <exact command>
+exit: <code>
+output: <relevant excerpt, with truncation marked>
+```
+
+## 3. Transcript protocol (batch, never poll)
+
+A typical JSONL transcript has one object per step with fields such as `step_index`, `source`, `type`, `status`, `created_at`, `content`, `thinking`, and `tool_calls`. Do not assume that schema; inspect the first and last records and the key distribution.
+
+### 3.1 Index once
+
+Use one batch pass to produce:
+
+- total records, byte size, hash, first and last timestamps;
+- counts by `type` and `source`;
+- every user turn with step and timestamp;
+- every assistant message with non-empty `content`, with length and a short prefix;
+- tool call counts by name and error counts;
+- a step/time index around quoted evidence.
+
+A compact Node recipe for user-supplied or exported JSONL files (for internal Antigravity `.system_generated/` transcripts, shell reads are hook-blocked under `L6`; call `query_transcript` / `read_transcript` in one batch pass from the coordinator session if `/swarm` workers lack those MCP tools):
+
+```bash
+node -e '
+const fs = require("node:fs");
+const p = process.argv[1];
+const rows = fs.readFileSync(p, "utf8").trim().split(/\r?\n/).map(JSON.parse);
+const counts = {};
+for (const r of rows) counts[r.type] = (counts[r.type] ?? 0) + 1;
+console.log(JSON.stringify({ rows: rows.length, counts }, null, 2));
+for (const r of rows) {
+  if (r.type === "USER_INPUT") console.log(`USER step=${r.step_index} at=${r.created_at}\n${String(r.content ?? "").slice(0, 500)}\n`);
+}
+' transcript_full.jsonl
+```
+
+Add a second pass for assistant messages and tool calls only when the index shows they matter. Never call a transcript-reading tool once per step; that is the quadratic pattern this protocol exists to prevent.
+
+### 3.2 Read targeted windows
+
+For each key step, read a bounded window (for example ±3 steps) and record:
+
+- the exact user request or model claim, quoted;
+- whether it is a user assertion, a model claim, a tool result, or an external-source claim;
+- the tool command and result if the claim depends on execution;
+- the timestamp and step;
+- what the surrounding window does not establish.
+
+### 3.3 Separate the four evidence layers
+
+| Layer | What it proves | What it does not prove |
+| --- | --- | --- |
+| User statement | The user's requirement, verdict, or constraint | That the claim is factually correct |
+| Model statement | What the model asserted or proposed | That the assertion was executed or verified |
+| Tool result | What the tool returned in that run | That the run was representative or complete |
+| Repository source | What the code or document currently says | That it behaves that way at runtime |
+
+Do not cite a model's summary of a transcript as if it were the transcript. Quote the underlying step or tool result.
+
+## 4. Logs, CI, and command output
+
+- Record the exact revision, job, command, and environment.
+- Distinguish a passing summary from the assertions that were executed. A green suite that never exercises the named guarantee is not evidence for that guarantee.
+- A failure caused by the review environment (missing OS feature, sandbox denial, unavailable service) is an environment limitation, not a product defect. State it as such and do not count it against the target.
+- If a test cannot run, give the reproduction steps and label the expected result as source-derived. Do not claim it passed or failed.
+
+## 5. Citation formats
+
+| Evidence | Format |
+| --- | --- |
+| Code at a commit | `https://github.com/paragon-ux/Agy-Squad/blob/<sha>/path#Lx-Ly` |
+| Local code | `path#Lx-Ly` with the SHA pinned in Section 1 |
+| Transcript | `transcript_full.jsonl step 1375 @ 2026-11-10T06:29:55Z` plus a short quote |
+| Command | `cwd`, command, exit code, output excerpt |
+| CI | workflow, job, revision, URL, conclusion, and the asserted check |
+| External | title, URL, version/date, access date |
+| Prior review | report path, finding ID, and the prior revision |
+
+Mark `Observed` for execution you performed or output you inspected, and `Source-derived inference` for conclusions drawn from code or documents without execution. Never blur the two.
+
+## 6. Intake failure modes to avoid
+
+- Reading the first and last transcript entries and calling it a review.
+- Polling a transcript one or two steps at a time and inflating the token cost.
+- Treating a model's self-report ("I ran the tests", "I searched the web") as execution evidence.
+- Treating a green test summary as proof of the guarantee the test names.
+- Treating a hash as proof of correctness rather than identity.
+- Citing a file you fetched but did not read, or a section you read but did not understand.
+- Letting a prior review's verdict stand without revalidating its findings.
+- Hiding unavailable evidence inside a confident narrative.

package/.agents/skills/full-review/references/report-template.md

@@ -0,0 +1,216 @@
+# Full review report template
+
+Copy this skeleton into `docs/reviews/<review-slug>.md` and replace every `<...>` placeholder. Delete no mandatory section; use Not applicable with a reason where a section does not apply, and None identified within reviewed scope or Not assessed inside each triage bucket as the standard requires.
+
+**Formatting & Readability:** Keep reports scannable in plain prose and Markdown tables. Reserve backticks strictly for exact code identifiers, file paths, CLI flags, and commands—never wrap plain numbers, statuses (Closed, Open, PASS), or quoted sentences inside inline backticks or fenced code blocks inside table cells.
+
+---
+
+# <Review title>
+
+**Governing Standard:** Agy-Squad PR Review Standard `v1.4.0` ([`pr-review-standard.md`](../../pr-review/references/pr-review-standard.md))
+**Review type:** `<PR / branch / working tree / subsystem / evidence bundle / direction decision>`
+**Review date:** `<YYYY-MM-DD>`
+**Reviewer:** `<name / agent>`
+**Standard version:** `1.4.0`
+
+## 1. Review metadata, Session Provenance, and evidence limits
+
+### 1.1 Target
+
+| Field | Value |
+| --- | --- |
+| Repository | `paragon-ux/Agy-Squad` |
+| Target | `<PR URL / branch / commit / working tree / evidence bundle>` |
+| Comparison base | `<base SHA / tag / none>` |
+| Head / tree | `<head SHA / tree>` |
+| Working-tree state | `<clean / dirty delta / untracked files>` |
+| CI revision | `<exact commit / run URL>` |
+| Prior review | `<path and finding IDs, or None>` |
+
+### 1.2 Session Provenance
+
+| Session # | Operator Conversation ID | Parent Session | Date | Base..Head + Working-Tree State | Skill / Topology Invoked |
+| --- | --- | --- | --- | --- | --- |
+| `<n>` | `<id or Unavailable>` | `<parent or None>` | `<YYYY-MM-DD>` | `<base..head + state>` | `<skill / single-agent / cohort>` |
+
+### 1.3 Evidence manifest
+
+| EID | Artifact | Locator | SHA-256 / size | Class | Access | Examined |
+| --- | --- | --- | --- | --- | --- | --- |
+| `E01` | `<file/transcript/CI>` | `<path/URL/step>` | `<hash/size>` | `<class>` | `<Examined / Partial / Unavailable>` | `<lines/steps>` |
+
+### 1.4 Evidence limits
+
+- `<Unavailable or partial evidence, with reason>`
+- `<Environment limitations, e.g. WSL unavailable, sandbox denial>`
+- `<Claims that remain source-derived rather than observed>`
+
+## 2. File/artifact-to-category inventory and coverage matrix
+
+| Artifact | Change / role | Primary category | Cross-references | Coverage |
+| --- | --- | --- | --- | --- |
+| `<path>` | `<added/modified/unchanged>` | `<ARCH...DEP>` | `<categories>` | `<Complete/Partial/Not reviewed>` |
+
+| Category | Scope covered | Coverage | Verdict |
+| --- | --- | --- | --- |
+| `ARCH` | `<files/evidence>` | `<Complete/Partial/Not reviewed>` | `<Changes required / No findings / Incomplete / Not applicable>` |
+| `DOC` | | | |
+| `SKILL` | | | |
+| `MCP` | | | |
+| `RUN` | | | |
+| `SVC` | | | |
+| `DB` | | | |
+| `SCRIPT` | | | |
+| `TEST` | | | |
+| `DEP` | | | |
+
+## 3. Architecture-to-implementation trace
+
+For each behavior or claim:
+
+`design thesis / invariant -> architecture decision -> public contract -> implementation -> verification`
+
+| Claim | Normative source | Architecture decision | Public contract | Implementation | Verification | Result |
+| --- | --- | --- | --- | --- | --- | --- |
+| `<claim>` | `<LEDGER ID / standard / user requirement>` | `<decision>` | `<schema/docs>` | `<code>` | `<test/run/evidence>` | `<satisfied / mismatch / unverified>` |
+
+Narrative: `<what the trace establishes and what it does not>`
+
+## 4. Category reviews
+
+### 4.1 `ARCH` — Architecture and contracts
+
+- **Scope:** `<changed and unchanged artifacts examined>`
+- **Coverage:** `<Complete / Partial / Not reviewed; what remains>`
+- **P1 — high priority:** `<finding IDs or None identified within reviewed scope / Not assessed>`
+- **P2 — medium priority:** `<finding IDs or ...>`
+- **P3 — low priority:** `<finding IDs or ...>`
+- **Verification:** `<tests inspected/executed, CI, missing proof>`
+- **Verdict:** `<Changes required / No findings within reviewed scope / Incomplete / Not applicable>`
+
+Repeat this seven-item record for `DOC`, `SKILL`, `MCP`, `RUN`, `SVC`, `DB`, `SCRIPT`, `TEST`, and `DEP`.
+
+### 4.12 Integrity audit record (when an integrity audit is used)
+
+- **Role contract:** see [review roles](review-roles.md).
+- **Auditor / independence:** `<who, parent, independence from the reviewed work>`
+- **Verdict enum:** `CLEAN` / `INTEGRITY VIOLATION`
+- **Coverage:** `<transcripts and step ranges, tool traces, artifacts, evidence classes; what was not covered>`
+- **Findings:** `<IDs or None identified within reviewed scope / Not assessed>`
+- **Lead re-review after CLEAN:** `<who re-reviewed the final artifacts and the resulting content verdict>`
+- **Enforcement:** `<violation block, rejection/re-run, penalty or ledger record>`
+- **Verdict:** `<CLEAN / INTEGRITY VIOLATION / Not applicable>`
+
+## 5. Findings
+
+### 5.1 P0/P1/P2 finding records
+
+#### `<ID>` — `<title>` (`P1`, `Open (Pre-Remediation)`)
+
+1. **Title, priority, status:** `<...>`
+2. **Contract provenance:** `<exact invariant / decision / contract / external norm>`
+3. **Source evidence:** `<commit-pinned links, lines, symbol, transcript step>`
+4. **Trigger:** `<concrete input/state/interleaving/instruction>`
+5. **Expected / actual:** `<mismatch; observed vs source-derived>`
+6. **Impact:** `<consequence and scope>`
+7. **Required remediation:** `<behavior to restore, compatibility constraints, affected surfaces>`
+8. **Acceptance evidence:** `<regression case and assertions, or source reconciliation>`
+9. **Root cause / related IDs:** `<cross-layer connection>`
+10. **Closure:** `<fix commit, evidence at that revision, recheck, residual limits>`
+
+### 5.2 P3 advisory table
+
+| ID | Wave/Session | Cat | Status | Source | Defect / Proposal | Disposition / Fix | Verification & Bundle SHA |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `<ID>` | &lt;wave/session&gt; | &lt;cat&gt; | &lt;status&gt; | `<path#line>` | &lt;defect summary&gt; | &lt;fix summary&gt; | `<evidence or sha>` |
+
+## 6. Cross-category root causes and remediation order
+
+- **Root cause 1:** `<description>` — `<categories and IDs>`
+- **Remediation order:** `<ordered steps with dependencies and rationale>`
+
+## 7. Overall disposition, Direction decision, and finding closure
+
+### 7.1 Overall disposition
+
+- **Coverage:** `<complete / partial / incomplete>` across `<n>` material categories.
+- **Blocking findings:** `<IDs>` or `None`.
+- **Disposition:** `<Approve / Request changes / Incomplete / Not applicable>`.
+- **Reason:** `<coverage and blocking-finding basis; never a pass percentage>`.
+
+### 7.2 Direction decision (required when the user asks what to do)
+
+- **Decision question:** `<one sentence>`
+- **Role separation:** `<content owner / integrity auditor / lead re-review after CLEAN, or Not applicable>`
+- **Hard constraints:** `<constraint>` — `<citation>`
+- **Preferences:** `<preference>` — `<citation>`
+
+| Option | Preserves | Costs / risks | Dependencies | Reversibility | Evidence for | Evidence against |
+| --- | --- | --- | --- | --- | --- | --- |
+| `<status quo>` | | | | | | |
+| `<option B>` | | | | | | |
+| `<option C>` | | | | | | |
+
+- **Recommendation:** `<option and rationale>`
+- **Load-bearing evidence:** `<IDs and citations>`
+- **Falsifiers:** `<what evidence would change the recommendation>`
+- **Immediate next actions:** `<ordered actions with acceptance tests>`
+- **What not to do:** `<ruled-out action and evidence>`
+
+### 7.3 Finding closure table
+
+| ID | Category | Priority | Status | Fix / evidence at revision | Recheck result |
+| --- | --- | --- | --- | --- | --- |
+| `<ID>` | `<cat>` | `<P#>` | `<status>` | `<commit/link>` | `<closed/residual>` |
+
+## 8. Post-Remediation Residuals & Deferred Dispositions
+
+`<None (0 open residuals, 0 deferred items)>` or the atomic table:
+
+| ID | Wave/Session | Cat | Status | Source | Defect / Proposal | Disposition / Fix | Verification & Bundle SHA |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `<ID>` | `<wave>` | `<cat>` | `<Residual (Open) / Closed (Post-Remediation) / Deferred / Won't Fix / Closed (By Design) / Informational>` | `<link>` | `<defect>` | `<disposition>` | `<evidence>` |
+
+## 9. `/self-diagnosis` Cohort & Bundle Ledger
+
+Include only when cohorts were dispatched.
+
+### 9.1 Cohort Provenance
+
+| Wave | Session ID | Stage | Subagent IDs | Pre-Fix Bundle SHA | Re-Verify Bundle SHA | Teardown |
+| --- | --- | --- | --- | --- | --- | --- |
+| `<wave>` | `<id>` | `<stage>` | `<ids>` | `<sha or N/A>` | `<sha>` | `<retained/torn down>` |
+
+### 9.2 Wave Finding Ledger
+
+| ID | Category | Priority | Status | Specialist / Cohort Verification |
+| --- | --- | --- | --- | --- |
+| `<ID>` | `<cat>` | `<P#>` | `<status>` | `<evidence>` |
+
+## Appendix A — Verification record
+
+| Check | Revision | Environment | Result | Evidence |
+| --- | --- | --- | --- | --- |
+| `<command>` | `<sha>` | `<OS/runtime>` | `<pass/fail/blocked>` | `<output/link>` |
+
+## Appendix B — Quoted evidence
+
+| EID / locator | Quote | Class | What it establishes |
+| --- | --- | --- | --- |
+| `<step/line>` | &lt;short verbatim quote&gt; | &lt;user/model/tool/source&gt; | &lt;bounded claim&gt; |
+
+## Quality gates
+
+- [ ] The standard was read; target, base, dirty state, evidence manifest, and exclusions are pinned.
+- [ ] Every changed file or artifact is mapped to one primary category; all ten categories have scope, coverage, P1/P2/P3, verification, and verdict.
+- [ ] Every finding has one ID, one status, and the required fields; no umbrella or range IDs.
+- [ ] Every material claim has a locator; observed and inferred are separated.
+- [ ] Prior findings are explicitly accepted, revised, or rejected.
+- [ ] Verification gaps are separate from defects; unavailable evidence is stated.
+- [ ] Section 8 contains every residual, deferred, by-design, and informational item.
+- [ ] A requested direction decision has constraints, options, a recommendation, and falsifiers.
+- [ ] When an integrity audit is used: the content and integrity verdicts are separate, the auditor did not approve content, the lead re-reviewed after `CLEAN`, and `INTEGRITY VIOLATION` hard-blocks acceptance.
+- [ ] The disposition matches coverage and open findings; no approval from a pass rate or an unreviewed category.
+- [ ] Formatting & Readability: prose and table cells avoid unnecessary inline backticks on numbers, statuses, and quoted sentences, and avoid fenced code blocks inside narrative/tables.
+- [ ] The report is saved at a stable path and linked from the response.

package/.agents/skills/full-review/references/review-roles.md

@@ -0,0 +1,91 @@
+# Review roles: content acceptance vs integrity audit
+
+This reference supports the `full-review` non-negotiable on role separation. It exists because a review can fail even when every checklist item is covered: the reviewer may conflate **whether the content is acceptable** with **whether the work was produced authentically**.
+
+## 1. Two questions, two verdicts
+
+| Role | Question | Verdict enum | Authority | Typical evidence |
+| --- | --- | --- | --- | --- |
+| Responsible reviewer / squad lead | Does the deliverable satisfy the request and its contracts? | `APPROVE` / `REQUEST_CHANGES`, or `PASS` / `FAIL` / `BLOCKED` | Final content acceptance; parent of the leaf agents | requirements, artifacts, tests, diffs, source lines |
+| Independent integrity auditor | Was the deliverable produced authentically, with the claimed tool execution and evidence, without gaming the process or the result? | `CLEAN` / `INTEGRITY VIOLATION` | Cannot approve content; can block acceptance and require rework | transcripts, tool traces, hashes, execution logs, reasoning/evidence correspondence |
+
+Do not collapse these into one role. An integrity auditor that issues `PASS` becomes a second content gate; a content reviewer that waives integrity defects as “advisories” becomes an accomplice.
+
+## 2. Required ordering
+
+1. The responsible reviewer or lead prepares the content verdict on the draft. This is provisional.
+2. The independent integrity auditor runs after the working cohort has completed and before acceptance. It audits process and evidence, not content quality.
+3. If the audit is `CLEAN`, the responsible reviewer re-reviews the final artifacts and issues the **final content verdict**. The auditor does not issue it.
+4. If the audit is `INTEGRITY VIOLATION`, acceptance stops. Record the violation, reject the work, and require a re-run or a recorded remediation. The violation cannot be downgraded to `PASS with advisories`.
+5. The acceptance record contains both verdicts, the auditor identity, the reviewed revision, and the lead's post-audit recheck.
+
+A content `PASS` that predates the integrity audit is not final. A `CLEAN` audit is necessary but not sufficient for acceptance.
+
+## 3. Verdict discipline
+
+- Content verdicts are exact enum values: `PASS`, `FAIL`, `BLOCKED` or `APPROVE`, `REQUEST_CHANGES`. No `PASS with …`, `CONDITIONAL PASS`, `PASS (advisories)`, or other compound forms.
+- Integrity verdicts are exact enum values: `CLEAN`, `INTEGRITY VIOLATION`. No `PASS`, no `FAIL`, no `CLEAN with advisories`.
+- An advisory or observation is a separate record. It is not a verdict and cannot soften an `INTEGRITY VIOLATION`.
+- A compound or conditional verdict is itself a finding: it usually means the role is confused or the parser can be evaded.
+
+## 4. What the integrity auditor must examine
+
+- Tool execution versus claims: did the agent actually run the commands/searches it cites? Are exit codes and outputs present and consistent?
+- Reasoning versus evidence: does the reported conclusion follow from observed evidence, or was it pre-concluded and then backfilled?
+- Artifact authenticity: are files, hashes, and citations real, current, and within scope? Were tests or fixtures fabricated, stubbed, or bypassed?
+- Process compliance: scope limits, banned behaviors, prompt-injection resistance, and whether the agent tried to satisfy a checker rather than the task.
+- Result validity is necessary but not sufficient. A valid-looking deliverable can still be an integrity violation if the process or evidence was fabricated.
+
+## 5. Enforcement, not prose
+
+A warning such as “cheating will be detected and rejected” is only true if a mechanism exists:
+
+- an independent auditor with the authority to issue `INTEGRITY VIOLATION`;
+- a hard acceptance block on that verdict, with no `PASS` override;
+- a recorded violation and a re-run/remediation requirement;
+- a visible penalty or ledger entry that survives teardown.
+
+If no such mechanism exists, label the warning as advisory. Do not claim it is enforced. Prose alone does not deter a model that is optimizing for the visible verdict.
+
+### Warning template (only with enforcement)
+
+> **MANDATORY INTEGRITY WARNING:**
+>
+> DO NOT CHEAT. All implementations must be genuine. DO NOT hardcode test results, create dummy/facade implementations, or circumvent the intended task. An independent integrity auditor will verify your work. Integrity violations WILL be detected and your work WILL be rejected.
+
+Do not use this text unless the independent auditor, the `INTEGRITY VIOLATION` block, the rejection/re-run path, and the recorded penalty actually exist. Otherwise the warning is a false claim, which is worse than no warning.
+
+## 6. Proportional coverage and transcript audits
+
+- **Layered cohort:** Phase 2 Agy-Squad cohorts (`mcp/planner.mjs`, `docs/roles-and-workflows.md`) default to one flat peer `audit-<id>` Integrity Auditor (`integrity_auditor:<id>`); use hierarchical multi-layer auditors only when manually configured without flat `audit-<id>`.
+- **Flat cohort:** use a flat integrity audit; every specialist is covered directly.
+- Coverage must be explicit: which transcripts, which step ranges, which tool traces, which artifacts, and which evidence classes. State what was not covered.
+- Define a query budget and merge/deduplicate transcript ranges. A single-pass batch query is the default; repeated overlapping queries are a finding unless a new evidence class requires them.
+- The specialist doing transcript forensics needs the batch/coverage instruction too, not only the lead. Otherwise one specialist over-queries and another barely queries, and the audit quality becomes random.
+
+## 7. Worked contrast (Agy-Squad PR #3)
+
+| System | Integrity role | Verdict | Content role | Verdict |
+| --- | --- | --- | --- | --- |
+| Teamwork audit (`35bebb82…`, step 0/89) | `teamwork_auditor`, forensic integrity auditor | `CLEAN` / `INTEGRITY VIOLATION` | `teamwork_reviewer` (`3f31598b…`, step 0/105) | `APPROVE` / `REQUEST_CHANGES` |
+| PR #3 adversarial squad (`3303968c…`, step 0/111) | Adversarial Review Lead | `PASS` / `FAIL` / `BLOCKED` | Working squad lead | Already issued `PASS` before the audit; no post-audit re-review |
+
+Observed consequences in PR #3:
+
+- The adversarial lead's brief required `Verdict: PASS or FAIL/BLOCKED`; its report returned `PASS with Preserved Advisories & Corrective Remediation Ledger` (`3303968c…`, step 111/159).
+- Specialist 1 returned `CONDITIONAL PASS / PARTIAL COMPLIANCE` (`eaad8f1a…`, step 73); Specialist 2 returned `PASS with Preserved Advisories & Temporal Working Tree Notice` (`bba13371…`, step 111).
+- The lead tested the verdict parser, saw `Set(2) { 'PASS', 'FAIL' }`, then produced a report whose verdict set was `Set(1) { 'PASS' }` (`3303968c…`, steps 156–158). That is a content-verdict optimization applied to an integrity role.
+- Specialist 1 made 10 `query_transcript` calls over overlapping ranges; Specialist 2 made 2 summary queries (`eaad8f1a…`, steps 27–45; `bba13371…`, steps 75/77). The leaf brief did not contain the batch-efficiency instruction given to the lead.
+
+Lesson: the integrity auditor must not be asked to produce a content verdict. If it is, it will optimize the content verdict and can waive the integrity defects it was created to catch.
+
+## 8. Review checklist
+
+- [ ] Is content acceptance owned by a named reviewer/lead, not the integrity auditor?
+- [ ] Is the integrity auditor independent of the work being audited?
+- [ ] Are the two verdict enums distinct and exact?
+- [ ] Does the lead re-review and issue the final content verdict after a `CLEAN` audit?
+- [ ] Does `INTEGRITY VIOLATION` hard-block acceptance, with a recorded violation and re-run/penalty?
+- [ ] Is audit coverage proportional, explicit, and recorded?
+- [ ] Are transcript queries batch-oriented, deduplicated, and budgeted?
+- [ ] Are compound/conditional verdicts treated as findings?

package/.agents/skills/pr-review/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: pr-review
+description: >-
+  [Task Spec — PR/branch diff & CI review; pair with swarm-governance on /swarm]
+  Use this skill when the user asks to perform, update, or verify a pull request
+  or branch review in Agy-Squad. Enforces the Agy-Squad PR Review Standard
+  (v1.4.0) with commit-pinned and session-pinned metadata, architecture-before-runtime
+  tracing, ten mandatory categories (ARCH, DOC, SKILL, MCP, RUN, SVC, DB,
+  SCRIPT, TEST, DEP), 1-ID-per-row finding records, post-remediation residual
+  tracking, and structured reports under docs/reviews/.
+---
+
+# Agy-Squad PR Review Skill (Standard v1.4.0)
+
+Conduct pull request and branch diff/CI reviews in `Agy-Squad`. For broad non-diff evidence bundles, repo-wide triage, or Direction decisions, use [`full-review`](../full-review/SKILL.md). To run multi-agent reviews on `/swarm`, pair this **Task Spec** with [`swarm-governance`](../swarm-governance/SKILL.md) (which owns `squad_planner` / `node bin/agy-squad.mjs plan`, `open_board`, `swarm_wait`, pointer receipts, and closure; `dispatch_squad` / `agy-squad dispatch` is `invoke_subagent` fallback only). Consult [references/pr-review-standard.md](./references/pr-review-standard.md), [Core workflows](../../../docs/core-workflows.md), and [Roles & skill workflows](../../../docs/roles-and-workflows.md#pr-review).
+
+---
+
+## Invariants
+
+1. **Architecture Before Runtime & Ledger Distinction:** Passing tests, polished docs, and prior approvals are inputs, not proof that implementation satisfies architecture. For every behavior change, trace `design thesis / invariant -> current architecture decision -> public contract -> implementation -> verification`, distinguishing [`docs/plans/LEDGER.md`](../../../docs/plans/LEDGER.md) records: active POSIX/WSL architecture (`L1–L7, L21, L29–L31, L40–L43`), retired/superseded records (`L17` PTY `agy-squad run` retired, `L16`, `L8–L12, L35, L36, L38`), and external shared allocations (`L13–L15, L25–L27, L32–L34`). Never rewrite contracts or docs to match defective code.
+2. **Ten Mandatory Categories & Zero Finding Quotas:** Map every changed artifact to **one primary category** (`ARCH`, `DOC`, `SKILL`, `MCP`, `RUN`, `SVC`, `DB`, `SCRIPT`, `TEST`, `DEP`) and cross-reference affected categories without double-counting (`"No findings"` is valid; finding quotas are banned; mark filesystem-only persistence under `RUN`/`SVC` and `DB` as `Not applicable`).
+3. **Evidence Separation & Agy-Squad Runtime Boundaries:** Separate source inspection, attempted reproduction, local execution, and CI logs; inspect actual test assertions. Verify relevant boundaries:
+   - *Schema & Stdio Framing:* `request.jsonrpc === "2.0"`, `tools/list` (`mcp/index.js`) vs `dispatch_squad` / `squad_planner`, positive integer `AGY_MAX_STDIO_PAYLOAD_BYTES`, and `10 MiB` stdio cap.
+   - *Workspace & Descriptor Containment:* workspace-internal symlink resolution + `O_NOFOLLOW`/`O_NONBLOCK` + `/proc/self/fd/${fd}` in `mcp/dispatch.mjs`; strict symlink rejection in `mcp/handoffs.mjs`.
+   - *Worker Capability, Model Provenance & Input Guards:* disallowed built-in `TypeName`s (`research`, `browser`, `image-generator`), manifest agent `workspace === "inherit"` for `invoke_subagent` and `squad_planner` (`/swarm` copy isolation uses top-level `workspaceIsolation`), `modelProvenance` caveats vs `/swarm` pinning, `scopeFiles` path safety + writable overlap diagnostics, boolean `readOnly`, and camelCase/PascalCase conflict rejection.
+   - *Pointer-Over-Wire & Bundling:* `<= 500` UTF-8 byte single-line `READY`/`PARTIAL`/`NO_REPORT` grammar, custom `reportRoot` containment, atomic `publish()`, strict single-line verdicts (`mcp/verdicts.mjs`), default `requireIntegrityAudit: true` binding, and `bundle`/`verify`/`prune` SHA-256 verification.
+   - *External MCP & CLI:* real stdio subprocesses and `node bin/agy-squad.mjs` (`plan|dispatch|fingerprint|inspect|bundle|verify|prune|verdict`) vs in-process calls.
+4. **Strict Content vs. Integrity Gate:** Never conflate content acceptance (`Approve` / `Request Changes` or `Content Verdict: PASS | FAIL | BLOCKED`) with the flat Integrity Auditor gate (`audit-<id>` in `/swarm` or `integrity_auditor[:<id>]` in `invoke_subagent`: `Integrity Verdict: CLEAN | INTEGRITY VIOLATION`; `adversarial_*` was retired in Phase 2). Only finalize `Approve` after `CLEAN` and post-remediation re-verification at the fixed revision.
+5. **1 ID = 1 Row Durability & Plain-Text Readability:** Assign one stable ID per independently remediable problem and one of the 6 canonical statuses (`Open (Pre-Remediation)`, `Closed`, `Residual (Open)`, `Closed (Post-Remediation)`, `Deferred / Won't Fix`, `Closed (By Design)`; `Informational` in Section 8 only). Zero compression or omission: `docs/reviews/<slug>.md` is the surviving durable ledger once `prune` / `--teardown` removes `scratch/`. Reserve inline backticks strictly for identifiers, file paths, flags, and commands—never wrap plain numbers, English statuses, or multi-sentence quotes in inline backticks or fenced code blocks inside prose or table cells.
+
+---
+
+## Workflow
+
+### Step 0: Pre-Flight Intake (Neutral Topology, Evidence & Integrity Gate)
+If topology, workspace isolation, model, or retention options are unspecified, ask via `ask_question` (or multiple-choice prompt) without biasing `Flat` vs `Layered` (for `/swarm` launch templates, `open_board`, `swarm_wait`, and shutdown rules, follow [`swarm-governance`](../swarm-governance/SKILL.md#step-0-pre-flight-intake-ask-when-unspecified)):
+1. **Execution Topology & Isolation (Ask if Unspecified):**
+   - `Flat Cohort`: Specialists report directly to coordinator (`squad_planner` without per-squad leads; fewer coordination hops).
+   - `Layered Cohort`: Category specialists + squad leads + coordinator (domain synthesis per squad; higher coordination cost).
+   - `Single-Agent Audit`: Direct trace by one reviewer.
+   - On `/swarm`, confirm `workspaceIsolation` (`inherit` vs `share` vs `branch`) and model (coordinator default unless the user specifies otherwise).
+2. **Evidence Retention (`Scope 2` vs `Scope 3`):**
+   - `Scope 2 — Swarm bundle prune`: Pass `--keep-reports` to `node bin/agy-squad.mjs prune` to retain loose specialist reports in `scratch/agy-squad/squad-<id>/`, or omit to delete loose specialist files after SHA-256 bundling.
+   - `Scope 3 — Self-diagnosis teardown (L41)`: Delete completed `/self-diagnosis` directories (`diagnose.mjs --teardown`) once `docs/reviews/<slug>.md` is updated, or defer cleanup during active multi-wave triage.
+3. **Integrity Gate:** Confirm `Mandatory Flat Integrity Auditor Gate` (`audit-<id>` on `/swarm` or `integrity_auditor[:<id>]` on `invoke_subagent`).
+
+### Step 1: Pin Review & Session Provenance
+Record repository, target PR/branch/tree state, date, reviewer, standard version `1.4.0`, base/head SHAs, dirty delta, CI SHAs, and **Session Provenance** (`Session # | Operator Conversation ID | Parent Session | Date | Base..Head + Working-Tree State | Skill / Topology Invoked`). List changed files and unchanged dependencies, available evidence (`docs/plans/LEDGER.md`, `docs/plans/wsl-cli-verification.md`, prior reviews, transcripts, CI logs), and explicit exclusions.
+
+### Step 2: Trace Architecture Before Runtime
+For every behavior change, inspect and document the architecture chain (`design thesis -> decision -> contract -> implementation -> verification`) against `LEDGER.md` and public contracts before running or trusting runtime checks.
+
+### Steps 3–4: Execute Category Review, Runtime Verification & Record Findings
+Evaluate every primary and cross-referenced category (`ARCH` through `DEP`) and verify the runtime boundaries from Invariant 3 cleanly (coordinating multi-agent `/swarm` waves and flat `audit-<id>` via [`swarm-governance`](../swarm-governance/SKILL.md)). Record every distinct finding atomically:
+- **`P0` / `P1` / `P2`:** Concise 10-field records (title/priority/status, contract provenance, commit-pinned source evidence, trigger, expected/actual, impact, remediation, acceptance evidence, root cause/related IDs, closure).
+- **`P3`:** Atomic 1-row-per-ID table (`ID | Wave/Session | Cat | Status | Source | Defect / Proposal | Disposition / Fix | Verification & Bundle SHA`).
+
+### Step 5: Verdict, Remediation Re-Verification & Report Closure (`docs/reviews/`)
+Request changes if blocking (`P1`/`P2`) findings remain; mark `Incomplete` if a material category is unreviewed; recommend `Approve` only when all material categories are covered, `Integrity Verdict: CLEAN` completes (when audited), blocking findings are rechecked at the fixed revision, and verification has evidence. Write `docs/reviews/<review-slug>.md` using [references/pr-review-standard.md](./references/pr-review-standard.md) Sections 1–8 (plus Section 9 only when `/self-diagnosis` cohorts run; write `None (0 open residuals, 0 deferred items)` when Section 8 is empty).