neo-agent-skills 0.1.0

package/.agents/skills/debugging-antigravity/references/debugging-guide.md

@@ -0,0 +1,73 @@
+# Antigravity 2.x Debugging Guide
+
+Use this guide to establish the current configuration authority before changing an Antigravity MCP setup. Product documentation and the installed bundle are the evidence sources; old workspace recipes are not.
+
+## 1. Establish the MCP Authority
+
+Antigravity 2.x documents two valid MCP scopes:
+
+- global: `~/.gemini/config/mcp_config.json`
+- workspace: `.agents/mcp_config.json`
+
+Choose one owner for each server. A workspace definition is valid, but declaring the same server globally and in the workspace can create two independently managed subprocesses. The canonical paths come from the current [Antigravity MCP documentation](https://antigravity.google/docs/mcp).
+
+Keep adjacent configuration families separate:
+
+- Antigravity CLI preferences live at `~/.gemini/antigravity-cli/settings.json`; that preferences file is not the MCP registry.
+- Workspace rules and skills live under `.agents/rules/` and `.agents/skills/`; the [Gemini CLI migration guide](https://antigravity.google/docs/gcli-migration) describes how existing `AGENTS.md`, `GEMINI.md`, skills, and MCP definitions migrate.
+- `--user-data-dir` selects an Electron/Chromium UI profile. It does not prove or relocate the language-server MCP root. Re-probe the installed bundle after a product upgrade instead of deriving an MCP path from the UI-profile flag.
+
+If installed behavior disagrees with the docs, collect the Antigravity version, resolve symlinks, inspect the running process arguments, and search the installed language-server binary for `mcp_config.json` plus its parent root. Record the version boundary; do not promote a compatibility path into a universal rule.
+
+## 2. Diagnose Duplicate Processes Before Explaining Them
+
+Do not assume a twin-language-server cause. First build a process census:
+
+```bash
+pgrep -fl 'Antigravity|language_server|mcp-server'
+ps -o pid=,ppid=,pgid=,etime=,command= -p <pid-list>
+```
+
+For each Neo MCP process, capture its PID, parent PID, process group, working directory, and command. Then inspect both documented MCP authorities. A duplication claim is established only when the same logical server has multiple live owners or definitions.
+
+Correction order:
+
+1. Decide whether the server is global or workspace-owned.
+2. Remove only the duplicate definition from the other authority.
+3. Fully quit and relaunch Antigravity so the MCP client performs a fresh handshake.
+4. Repeat the process census and the server healthchecks.
+
+## 3. Keep Neo Lifecycle Ownership Intact
+
+Neo MCP servers are stdio clients of shared services; the orchestrator owns background Chroma, summary, Dream, and sync schedules. Do not reintroduce per-server `autoStartDatabase` or related auto-* flags to repair an Antigravity symptom. That recreates the retired per-instance lifecycle and can multiply work across harness-spawned servers.
+
+Verify the four frontier-harness servers independently:
+
+- GitHub Workflow
+- Knowledge Base
+- Memory Core
+- Neural Link
+
+A healthy tool surface with a broken MCP settings panel is a UI-state incident, not proof that the backend servers failed.
+
+## 4. Investigate a Spinner or `__store` Failure Safely
+
+The historical `__store` null signature has involved stale workspace UI state, but the signature alone does not establish the current cause. Start read-only:
+
+```bash
+find "$HOME/Library/Application Support/Antigravity/User/workspaceStorage" -name workspace.json 2>/dev/null
+sqlite3 "$HOME/Library/Application Support/Antigravity/User/globalStorage/state.vscdb" \
+  "SELECT key FROM ItemTable WHERE key LIKE '%sidebarWorkspaces%';"
+```
+
+Before mutating sqlite state, quit Antigravity and create a database backup. If the exact stale key is present and the operator has authorized repair, delete only that key, relaunch, and re-run the healthchecks. Do not purge auth tokens, caches, or entire workspace-storage trees as a first response.
+
+## 5. Validate Tool-Shape Changes with a Fresh Client
+
+The primary IDE connection can retain an older MCP tool manifest after server code changes. Use Neo's isolated client to prove the live shape:
+
+```bash
+node ai/mcp/client/mcp-cli.mjs --server memory-core --call-tool "your_modified_tool" '{"param":"test"}'
+```
+
+This creates a fresh client/server handshake without treating a cached IDE definition as current evidence.

package/.agents/skills/epic-create/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: epic-create
+description: "Authoritative protocol for authoring an Epic body — the creation-side dual of `ticket-create` + entry partner of `epic-review`/`epic-resolution`. Enforces: epic body = problem-scope + intended-solution (NOT pseudo-subs / ACs); ACs live in the SUB tickets; subs are LINKED via `update_issue_relationship` + added incrementally; the body MUST NOT hardcode a sub-list (it stales out → FAIL). Triggers: before creating an Epic (a parent issue labeled `epic`) via `create_issue`, or before decomposing one into sub-tickets."
+---
+# Epic Create Skill
+If you are about to author an Epic (a parent issue labeled `epic`) or decompose one into sub-tickets, you MUST immediately use the `view_file` tool to read and strictly adhere to `.agents/skills/epic-create/references/epic-create-workflow.md` before proceeding.

package/.agents/skills/epic-create/references/epic-create-workflow.md

@@ -0,0 +1,62 @@
+# Epic Creation Workflow
+
+Authoritative protocol for authoring an **Epic** body — the creation-side dual of `ticket-create`, and the entry partner of `epic-review` (pre-work review) + `epic-resolution` (closeout). An Epic is a parent issue (label `epic`) that coordinates multiple sub-tickets toward one shared outcome.
+
+## The Core Rule: an Epic body describes the PROBLEM, not the plan
+
+An Epic body is **problem-scope + intended-solution** — the durable "why + what-shape." It is NOT a container for the sub-decomposition or the acceptance criteria.
+
+- **ACs live in the SUB tickets, never the Epic body.** Each sub owns its own acceptance criteria + Contract Ledger (per `ticket-create`).
+- **Subs are LINKED, not listed.** Attach each sub to the Epic via `update_issue_relationship` (parent-child). The live sub-set is the linked relationship graph, queried on demand — NOT prose in the body.
+- **The Epic body MUST NOT hardcode a sub-list or sub-content.** A body that enumerates "Sub 1 / Sub 2 / …" or bakes their ACs goes stale the moment a sub is added, split, renamed, or dropped → the body contradicts the relationship graph → **FAIL**. Subs are added incrementally at any time; the body must stay valid across that churn.
+
+**Empirical anti-pattern (why this skill exists):** epics #12440 + #12442 baked full AC lists + a sub-decomposition into the body, then created the subs separately — the body now duplicates (and will out-stale) the linked subs. `epic-review`/`epic-resolution` (the entry/exit duals) existed, but no creation-side discipline did.
+
+## What an Epic body SHOULD contain
+
+Epic creation uses the same importance order as ticket and PR review: the problem/premise and intended placement dominate the verdict. Sub AC detail belongs in leaf tickets; an Epic with exhaustive sub mechanics but a weak premise or wrong owning substrate is not ready.
+
+1. **Problem scope** — the friction / antipattern-cluster / goal, with empirical anchors. State why this needs an Epic (multi-sub coordination) rather than a single ticket.
+2. **Intended solution shape** — the architectural direction (the "what-shape"), NOT the per-sub task breakdown. Enough that a reader knows the convergent shape the subs will serve.
+3. **(If Discussion-graduated) the §6.6 Signal Ledger** — the graduation consensus record (family-keyed quorum, unresolved dissent / liveness, criteria-mapping) per `ideation-sandbox-workflow.md §6`. This is the one structured matrix that belongs in an Epic body, because it records the graduation event, not the sub-plan.
+4. **Out of scope** — sibling efforts + explicitly-deferred directions.
+5. **Avoided traps / rejected shapes** — the divergence preserved from the source Discussion (if any).
+
+## What an Epic body MUST NOT contain
+
+- A `## Acceptance Criteria` checklist — those are per-sub.
+- A `## Sub-tickets` registry that enumerates subs with content. The body MAY reference a sub by `#N` in prose where load-bearing, but must not be the canonical sub registry (that is the `update_issue_relationship` graph).
+- **Pseudo-subs** — placeholder sub descriptions the body pretends to own before the real subs exist.
+
+## Sub-decomposition: the leaf-sub close-target contract
+
+Each sub the decomposition creates MUST be a **leaf that a single PR can FULLY deliver and `Resolves`** — a hard contract, because the `lint-pr-body` CI requires every PR body to carry a `Resolves #N` where N is a fully-delivered leaf.
+
+- **Each sub = one-PR-deliverable leaf.** Never bundle separable deliverables (e.g. "declarative reshape" + "lint guard", or "fix" + "observability") into one sub. A bundled sub cannot be cleanly `Resolves`'d by either PR → it forces mid-review leaf-splitting churn.
+- **The Epic is the umbrella, never a PR close-target.** It carries the `epic` label, is `Refs`'d (never `Resolves`/`Closes`) by its subs' PRs, and must NEVER be a PR close-target — the `pr-review` close-target audit forbids closing an `epic`-labeled issue (an epic auto-closed while subs are still open is the canonical close-target sabotage). The Epic closes via `epic-resolution` once its leaf subs are done.
+- **Multi-cause symptom tickets** → one leaf per cause; each PR `Resolves` its own leaf and `Refs` the symptom.
+
+## Lifecycle position
+
+| Skill | Phase | Owns |
+|---|---|---|
+| **`goal-scoping`** | Front-end (upstream) | Scope a GOAL → the set of owned LANES this skill then authors (one epic per lane); peers self-select their lane |
+| **`epic-create`** (here) | Creation | Problem-scope + intended-solution body; `epic` label; title hygiene |
+| `epic-review` | Pre-work entry | Roadmap fit, approach elegance, source-Discussion mapping, sub-structure coherence; seeds the Stage 3.1 closeout matrix |
+| `epic-resolution` | Closeout exit | Reconciles delivered subs against the parent ACs (which live in the subs) |
+
+## Procedure
+
+1. **Confirm Epic-shape.** The work needs ≥2 coordinated subs. A single bounded artifact (≈1 PR's worth) is a standalone ticket (`ticket-create`), not an Epic.
+2. **Run the Agent OS structure map.** Before authoring the body, run `npm run --silent ai:structure-map -- --files --loc`; use it for Agent OS / architecture placement claims or record N/A.
+3. **Graduation gate (if from a Discussion).** High-blast Epics require the §6.2 family-keyed quorum + the §5.1 divergence matrix in the source Discussion before filing (per `ideation-sandbox-workflow.md` + `ideation-sandbox/audits/double-diamond-divergence-guard.md`). Carry the `Signal Ledger` / dissent / liveness / criteria-mapping sections into the body.
+4. **Author the body** = problem-scope + intended-solution (+ ledger if graduated). NO ACs, NO sub-list.
+5. **Label `epic`** + apply title hygiene (per `ticket-create`).
+6. **Create subs separately** (via `ticket-create` — each with its own ACs + Contract Ledger) and **link each via `update_issue_relationship`** (parent = the Epic). Add subs incrementally as decomposition clarifies; that governs Epic life. Goal-scoping graduation is stricter: full v1 leaves are filed/native-linked, while the Epic body stays sub-list-free.
+7. **Verify** (pre-flight, before `create_issue`):
+   - [ ] Body contains **no** `## Acceptance Criteria` block.
+   - [ ] Body contains **no** hardcoded sub-registry (subs discoverable via parent-child relationship instead).
+   - [ ] Body answers "why an Epic (multi-sub coordination), not a single ticket?".
+   - [ ] Structure-map gate executed or N/A recorded.
+   - [ ] If Discussion-graduated: `Signal Ledger` present + quorum met.
+   - [ ] Each planned sub is a one-PR-deliverable **leaf** (no bundled separable deliverables); the Epic is `Refs`'d by subs, never a PR close-target.

package/.agents/skills/epic-resolution/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: epic-resolution
+description: "Closeout protocol for parent epics — answers \"we resolved all epic subs, are we done now?\" with a structured matrix + verdict recommendation (close / keep open / create missing subs / retire-supersede). Sibling to epic-review (which handles entry); this is the exit gate. Triggers: Use this skill when the last required sub of an epic closes, when a team member claims an epic is complete or substrate-side complete, before closing an epic as COMPLETED, or when a peer broadcasts an epic-readiness signal that needs reconciliation against parent ACs."
+---
+# Epic Resolution
+If you are about to declare an epic complete, close an epic, propose creating new subs to complete one, or react to a peer broadcast that an epic is "ready for handoff" / "components look solid", you MUST immediately use the `view_file` tool to read and strictly adhere to `.agents/skills/epic-resolution/references/epic-resolution-workflow.md` before posting any verdict or recommendation.

package/.agents/skills/epic-resolution/references/epic-resolution-workflow.md

@@ -0,0 +1,190 @@
+# Epic Resolution Workflow
+
+Closeout gate for parent epics. Answers the canonical question: **"we resolved all epic subs, are we done now?"**
+
+Sibling to `epic-review` (which is the *entry* gate at sub-creation time). `epic-resolution` is the *exit* gate at sub-closure time. Both skills share the same matrix shape on the parent epic body — `epic-review` seeds the AC → sub mapping; `epic-resolution` reconciles delivered evidence against required evidence and produces a verdict recommendation.
+
+**Origin:** Discussion #10697 + issue #10698. Empirical anchor: PR #10696 / Epic #10671 cycle, where peer broadcasts of "Epic substrate side complete" went unchallenged despite RESIDUAL_L4 ACs and a BLOCKER sub. Mental model per @tobiu: "turn friction into gold."
+
+## 1. When to invoke this skill
+
+Trigger conditions (any one fires the workflow):
+
+1. **Last required sub closes.** When you merge or observe-merged the final sub linked to an epic, run this workflow on the parent.
+2. **Peer broadcasts epic-readiness.** Phrases like "Epic #N substrate side complete," "components look solid," "ready for human handoff" are TRIGGERS for closeout reconciliation, NOT closeouts themselves. Run the workflow before agreeing.
+3. **Team member claims completion.** A team member (operator or peer agent) directly states an epic is done.
+4. **Before closing an epic as COMPLETED.** Any time you would otherwise post a closure-rationale comment on an epic, run this workflow first.
+
+**Trigger does NOT fire for:** routine sub-merge events that aren't the last required sub; epics where ACs have not been formally articulated; non-epic issues.
+
+## 2. Concurrency guard (epic-closeout discipline-layer mutex)
+
+Before populating the matrix, check whether another agent is already running the closeout for this epic.
+
+**Steps:**
+1. Read the recent comments on the epic. If a comment titled `## Epic Resolution Review (in progress)` exists with a timestamp less than 30 minutes old AND from a different agent identity, STOP.
+2. If you stopped, A2A the active closeout reviewer with `subject: "Re: Epic #N closeout — joining your review"` and cite the active comment-id. Do NOT post a parallel verdict.
+3. If no recent in-progress comment exists, post your own `## Epic Resolution Review (in progress)` comment immediately as a claim, before populating the matrix. The claim comment should be a single line: `Reviewing epic closeout — matrix population in progress. Started by @<your-identity> at <ISO-timestamp>.`
+4. Update your in-progress comment to the final verdict comment via `manage_issue_comment` action `update` once the matrix is built. The same comment evolves from claim → verdict.
+
+**Optional primary-owner restriction:** if the epic has an explicit assignee, only the assignee runs the closeout. Other agents detecting the trigger A2A-ping the assignee instead of running the workflow.
+
+## 3. Populate the matrix
+
+The shared matrix shape (used by both `epic-review` entry-pass and `epic-resolution` exit-pass):
+
+```md
+| Parent AC | Required evidence | Owning sub(s) | Delivered PR(s) | Achieved evidence | Residual state |
+|---|---|---|---|---|---|
+```
+
+For each parent AC of the epic:
+
+1. **Parent AC** — quote or reference the AC text from the epic body.
+2. **Required evidence** — L1 / L2 / L3 / L4 per the [Substrate Evidence Ladder](../../../../learn/agentos/process/evidence-ladder.md). The `epic-review` entry pass should have set this; if missing, derive from the AC text (does it require runtime / live / observable behavior?).
+3. **Owning sub(s)** — the sub-issue(s) addressing this AC. From the epic's native sub-issue links (`update_issue_relationship` graph) or AC-explicit references.
+4. **Delivered PR(s)** — the merged PR(s) closing each sub. Use `gh pr list --search "linked-to:<sub-number>"` or check sub-issue's `closedByPullRequestsReferences`.
+5. **Achieved evidence** — read the merged PR body's `Evidence:` declaration. If two ceilings (sandbox vs achievable), report both: `L2 (sandbox) / L4 (achievable)`. If no Evidence declaration, mark as `L?? — declaration missing` and flag in residuals.
+6. **Residual state** — one of:
+   - `none — closed` (achieved >= required)
+   - `RESIDUAL_L<N> — <reason>` (operator handoff window pending, etc.)
+   - `BLOCKER` (sub not started, sub failing, evidence below required with no path to close)
+   - `RESIDUAL_AC<N> [#<followup-ticket>]` (split-follow-up filed for unproven AC)
+
+## 3.5. Source Discussion Closeout Gate
+
+**Trigger:** Epic body cites a source Discussion (e.g., `Resolves Discussion #N`, `Graduates from Discussion #N`, or contains a Signal Ledger), OR the Epic was created via `epic-review` Stage 2.5 mapping (#11349) and has a `## Source Discussion Criteria Mapping` section. **N/A** for standalone Epics with no source Discussion — skip directly to §4.
+
+Before §4 verdict computation, reconcile upstream Discussion criteria against delivered Epic substrate. The Closeout Gate sits alongside §3's matrix and uses Discussion criteria as the row key:
+
+```md
+| Source Discussion criterion | Epic AC(s) | Owning sub(s) | Delivered PR(s) | Achieved evidence | Residual / deferral |
+|---|---|---|---|---|---|
+```
+
+For each criterion from the source Discussion's Graduation Criteria section (the post-consensus criterion list, NOT the open-question list):
+
+1. **Source Discussion criterion** — quote or reference the criterion text from the Discussion body. Each `[RESOLVED_TO_AC]` Cycle 2 resolution + each Graduation Criteria bullet + each Pilot Shape commitment counts as a criterion.
+2. **Epic AC(s)** — which Epic AC row(s) cover this criterion. If multiple criteria collapse to one Epic AC, that's fine — note the AC reference once. If no Epic AC covers the criterion, the row's residual is `LOST` (see below).
+3. **Owning sub(s) / Delivered PR(s) / Achieved evidence** — derived from §3 matrix row(s) for the corresponding Epic AC.
+4. **Residual / deferral** — one of:
+   - `none — delivered via AC<N>` (criterion fully realized in the Epic substrate)
+   - `EXPLICITLY DEFERRED — <rationale>` (criterion intentionally not addressed in this Epic; rationale must be public + part of original graduation acceptance OR documented in epic body)
+   - `CONVERTED TO FOLLOW-UP [#<followup-ticket>]` (criterion split out to a separate ticket post-graduation; ticket must exist + be reachable)
+   - `LOST` (criterion not mapped to any Epic AC; not explicitly deferred; not converted) — this is the silent-promise-loss class
+
+**Verdict integration:** the Closeout Gate output feeds §4 verdict computation. Any `LOST` criterion blocks `RECOMMEND_CLOSE_COMPLETED` even when all §3 Epic AC rows are green. The remediation path:
+
+- **Recoverable in existing subs:** if the LOST criterion can be addressed by extending an existing sub's scope, recommend `KEEP_OPEN` + flag the sub for scope-extension
+- **Requires new sub:** if the LOST criterion needs new substrate work, recommend `CREATE_MISSING_SUBS` per the standard §4 + §5 path
+- **Was-actually-deferrable:** if the LOST criterion was implicitly deferred during graduation and just never explicitly captured, file a `CONVERTED TO FOLLOW-UP` ticket retroactively + update the gate row before re-verdict
+
+`EXPLICITLY DEFERRED` and `CONVERTED TO FOLLOW-UP` are acceptable closeout states with same tracked-elsewhere semantics as §3 `RESIDUAL_<X> [#<followup-ticket>]`.
+
+**Empirical anchor:** Discussion #11341 → ticket #11342 chain. The Discussion's `[RESOLVED_TO_AC]` Cycle 2 resolutions (≥30% demotion threshold + Markdown Form distinction + #11330-bound measurement + Pilot Shape: INV1 cascade detail with measurement contract) became #11342 ACs via `epic-review` Stage 2.5 mapping (#11349). At closeout this gate verifies each `[RESOLVED_TO_AC]` line and the Pilot Shape AC are delivered, explicitly deferred, or converted. Without this gate, the Pilot's "≥30% byte reduction" criterion could silently drift to "some byte reduction" if Epic ACs were diluted at creation time and never re-checked at closure.
+
+## 4. Compute the verdict
+
+Apply the verdict logic in this order (highest precedence first):
+
+| Condition | Verdict |
+|---|---|
+| Any source Discussion criterion in `LOST` state per §3.5 Closeout Gate | `RECOMMEND_KEEP_OPEN` (if recoverable in existing subs) OR `RECOMMEND_CREATE_MISSING_SUBS` (if new sub needed) |
+| Any row has `BLOCKER` state | `RECOMMEND_KEEP_OPEN` |
+| Any row has `RESIDUAL_L<N>` AND no follow-up ticket exists | `RECOMMEND_CREATE_MISSING_SUBS` |
+| All rows are `none — closed` OR `RESIDUAL_<X> [#<followup-ticket>]` (residuals tracked elsewhere) AND §3.5 Closeout Gate passes or is N/A | `RECOMMEND_CLOSE_COMPLETED` |
+| Epic's purpose has been superseded by another effort, later ADR / Decision Record authority, or the AC framing is no longer valid | `RECOMMEND_RETIRE_OR_SUPERSEDE` |
+
+If an epic closeout hinges on ADR chronology, apply the ADR successor-risk audit before computing the verdict. The closeout comment must name the related ADR, whether it supersedes the epic or requires a challenge/amendment path, and the public evidence that supports the route.
+
+**Verdict authority:** the skill produces a structured review + recommendation. **Terminal-action shape depends on the verdict**:
+
+- **`RECOMMEND_CLOSE_COMPLETED` (with zero unresolved residuals)**: the reviewer-agent SHOULD close the epic as completed via `gh issue close --reason completed` as the natural downstream of the review. The review IS the gate; the close-act is not a separate operator-gate. **This is NOT a §0 Invariant 1 parallel** — §0 strictly forbids `gh pr merge` (PR merge action only); epic-close is downstream of the review verdict, not in §0 scope. Failing to close after a clean CLOSE_COMPLETED verdict produces stale-pending-action board pollution (empirical anchor: #10691 verdict 2026-05-04 → epic closed 2026-05-11 after operator surfaced the misframing).
+
+- **`RECOMMEND_KEEP_OPEN`**: no terminal action. Review surfaces blockers/residuals; operator or sub-owner decides path forward.
+
+- **`RECOMMEND_CREATE_MISSING_SUBS`**: no terminal action. Recommendation surfaces; operator authorizes new-sub creation; assigned owner files via `/ticket-create`.
+
+- **`RECOMMEND_RETIRE_OR_SUPERSEDE`**: no terminal action. Reviewer-agent does NOT auto-close-as-not-planned; operator authority for substrate-cohesion reasons (potential separate substrate concern — could be sub-issue if a §0-parallel claim is correct for retire-action specifically).
+
+For `RECOMMEND_CREATE_MISSING_SUBS`:
+1. List the gaps explicitly (which AC, what evidence is missing).
+2. Identify proposed owners (agents) for each new sub. If unclear, A2A the team to volunteer.
+3. Coordinate via A2A — DO NOT autonomously create the new subs without operator approval.
+4. The skill output recommends; the operator authorizes; the assigned owner files via `ticket-create`.
+
+For `RECOMMEND_RETIRE_OR_SUPERSEDE`:
+1. Articulate the rationale clearly (what changed since the epic was filed; what supersedes it).
+2. Cross-reference the superseding epic / discussion if any.
+3. Operator acts on the recommendation.
+
+## 5. Post the verdict comment
+
+Update your `## Epic Resolution Review (in progress)` comment to the final shape via `manage_issue_comment` action `update`:
+
+```md
+## Epic Resolution Review
+
+**Reviewer:** @<your-identity>
+**Started:** <ISO-timestamp> (in-progress claim)
+**Completed:** <ISO-timestamp>
+**Verdict:** RECOMMEND_<CLOSE_COMPLETED | KEEP_OPEN | CREATE_MISSING_SUBS | RETIRE_OR_SUPERSEDE>
+
+### Matrix
+
+| Parent AC | Required evidence | Owning sub(s) | Delivered PR(s) | Achieved evidence | Residual state |
+|---|---|---|---|---|---|
+| ... | ... | ... | ... | ... | ... |
+
+### Rationale
+
+<2-4 paragraphs explaining the verdict. For KEEP_OPEN: which residuals/blockers + path to close. For CREATE_MISSING_SUBS: enumerate gaps + proposed owners. For RETIRE: superseding artifact. For CLOSE_COMPLETED: confirmation that all residuals are tracked elsewhere.>
+
+### Required operator action
+
+<For RECOMMEND_CLOSE_COMPLETED: "Close epic as completed when convenient." For RECOMMEND_CREATE_MISSING_SUBS: "Authorize creation of N new subs (proposed owners listed above)." Etc.>
+
+### A2A coordination
+
+<List peers A2A'd, with subject + commentId for the operator's audit trail.>
+
+Origin Session ID: <your session UUID>
+```
+
+## 6. A2A peer coordination
+
+After posting the verdict comment, A2A the relevant peers:
+
+- For `RECOMMEND_CLOSE_COMPLETED`: A2A all agents who had subs in the epic, FYI of closure recommendation.
+- For `RECOMMEND_KEEP_OPEN` with BLOCKER: A2A the blocked sub's owner with the blocker rationale + ask whether they need help unblocking.
+- For `RECOMMEND_CREATE_MISSING_SUBS`: A2A proposed owners with the gap + ask whether they accept ownership.
+- For `RECOMMEND_RETIRE_OR_SUPERSEDE`: A2A the superseding effort's owner with the link.
+
+Per `feedback_a2a_commentid_pre_flight`: post the verdict comment FIRST, capture the literal commentId, THEN compose the A2A messages with the literal commentId substituted.
+
+## 7. Cross-references
+
+- `learn/agentos/process/evidence-ladder.md` — L1-L4 definitions + matrix schema authority
+- `.agents/skills/epic-review/` — entry-pass sibling (seeds matrix at sub-creation time + Source Discussion Criteria Mapping per Stage 2.5 #11349)
+- `.agents/skills/pr-review/` — sub-execution gate (audits Evidence declaration on each merging PR)
+- `.agents/skills/pull-request/` — author-side Evidence declaration template
+- `.agents/skills/ticket-create/` — invoked by the operator on `RECOMMEND_CREATE_MISSING_SUBS`
+- AGENTS.md §0 Invariant 1 — PR-merge gate (NOT a verdict-authority parallel; §4 above documents why epic-close is downstream of the review verdict, not in §0 scope). Cross-referenced here because both invariants share the empirical pattern of agent-derived-recommendation + operator-authorized-action, but the substrate-effect / reversibility / blast-radius profiles differ materially.
+- Discussion #10697 — origin ideation
+- Issue #10698 — graduation artifact
+
+## 8. Empirical anchor — Epic #10671 (motivating example)
+
+> ⚠️ **Frozen teaching example — not a live verdict.** The matrix below is Epic #10671's state *as of 2026-05-04* (when this section was authored), kept to illustrate the `RECOMMEND_KEEP_OPEN` *reasoning*. It is deliberately **decoupled from live ticket state** — never copy its verdict. For any epic (including #10671 today), **re-derive the verdict from current sub/PR state** (`gh` / GraphQL), as §1–§7 require. A snapshot pinned to a live ticket inevitably inverts as the organism evolves; the freeze-date is its sunset marker.
+>
+> **Lifecycle update:** #10671 has since closed `CLOSE_COMPLETED` (2026-06-05) — 19/19 subs closed; the blockers below (#10676 / #10679 / #10696) all resolved. The `KEEP_OPEN → CLOSE` arc is the lesson: the *reasoning* held; the *verdict* moved because the live state moved.
+
+Snapshot as authored (2026-05-04) — the epic whose closeout-friction motivated #10697 + #10698:
+
+- 9 subs across substrate-restart components (forensic, detector, in-flight lock, idle-out, sunset-mode, harness adapters, Codex Desktop primitive, mock-test discipline)
+- Most subs delivered at L2 (mock dispatch) or L3 (live binary verification by reviewer)
+- AC5 verify-effect (sessionId distinctness via MCP from spawned session) = RESIDUAL_L4 across #10676, #10695, #10696
+- #10679 (Codex Desktop primitive) = BLOCKER (sub blocked on MC startup diagnosis)
+- Verdict *at that snapshot*: `RECOMMEND_KEEP_OPEN` until either #10696 merges + AC5 L4 logged + #10679 unblocks, OR #10679 explicitly retired with rationale
+
+When you run this skill against any epic, populate the matrix from current public sub/PR state and let it produce the live verdict. If your result differs from a frozen snapshot, the snapshot is stale — not your run.

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

@@ -0,0 +1,11 @@
+---
+name: epic-review
+description: "Authoritative protocol for pre-work review of epics. Six-stage gating chain — roadmap fit, approach elegance, source discussion mapping, sub-structure coherence, prescription layer, avoided-traps completeness — posted as a structured comment on the epic ticket. Per-agent-per-epic one-shot; subsequent sub pickups cite the prior review. Triggers: Use this skill when an agent is about to pick up its first sub from an unreviewed epic (per model-identity OTHER than the epic's author — you never review your own epic). Also use when a user explicitly requests an epic review, or when an epic is freshly filed and a reviewer pre-validates before any sub pickup begins. Participated in the source Discussion? The participant path narrows the chain; it never exempts it."
+---
+# Epic Review Skill
+
+If you are about to pick up your first sub-issue from an epic that your model-identity has not yet reviewed, you MUST immediately use the `view_file` tool to read and strictly adhere to `.agents/skills/epic-review/references/epic-review-workflow.md` before running `ticket-intake` or any sub-work steps.
+
+Subsequent sub pickups from the same epic by the same model-identity cite the prior review by URL reference instead of re-running the skill.
+
+Authored this epic yourself, or participated in its source Discussion? Read `references/participant-path.md` first.

package/.agents/skills/epic-review/assets/epic-review-comment-template.md

@@ -0,0 +1,87 @@
+<!--
+Epic Review Comment Template
+Post via manage_issue_comment with action=create on the epic ticket.
+Short form vs long form depends on stage 1-2.5 gating outcome.
+Remove HTML comments before posting.
+-->
+
+## Epic Review by [model-identity] ([harness])
+
+### Stage 1 — Roadmap Fit
+
+[✅ / ❌]
+
+[1-2 sentences on current strategic alignment. Cite Golden Path node, Memory Core context, or sibling epic # if relevant.]
+
+<!-- If Stage 1 = ❌, stop here and close with a challenge section: -->
+<!--
+### Challenge
+
+[Named alternative: merge with epic #N, postpone until #M ships, reframe as X.]
+
+[Rationale: why this epic as currently framed does not fit the roadmap.]
+
+---
+
+Origin Session ID: [reviewer's session UUID]
+-->
+
+### Stage 2 — Approach Elegance
+
+[✅ / ❌]
+
+[1-2 sentences on architectural load-bearing of the approach. Cite reuse-vs-parallel-substrate observation, Gold Standard match or divergence, testability.]
+
+<!-- If Stage 2 = ❌, stop here with an alternative proposal: -->
+<!--
+### Alternative Approach
+
+[Named alternative with 2-3 sentence architectural rationale.]
+
+[Expected effort delta, substrate-reuse benefit, or risk reduction vs current framing.]
+
+---
+
+Origin Session ID: [reviewer's session UUID]
+-->
+
+### Stage 2.5 — Source Discussion Criteria Mapping Gate
+
+[✅ / ❌ / N/A]
+
+[1-2 sentences verifying that all Graduation Criteria from the source Discussion have been correctly mapped to the Epic ACs/subs.]
+
+<!-- If Stage 2.5 = ❌, stop here with revisions requested: -->
+<!--
+### Missing/Incomplete Criteria Mapping
+
+[Specific list of missing, incomplete, or unexplained dropped criteria that were required by the source Discussion.]
+
+---
+
+Origin Session ID: [reviewer's session UUID]
+-->
+
+### Stage 3 — Sub-Structure Coherence
+
+[✅ / ❌ / ⚠️]
+
+[Findings: coverage gaps, overlapping subs, phase-boundary circularity, missing prerequisite subs. Call out specific sub # and concern.]
+
+### Stage 4 — Prescription Layer
+
+[✅ / ❌ / ⚠️]
+
+[Per-sub findings — call out only subs where prescription layer is questionable. Subs passing ✅ do not need individual mention.]
+
+### Stage 5 — Avoided Traps Completeness
+
+[✅ / ❌ / ⚠️]
+
+[Suggested additions if gaps exist. Reference training-data anchor drift candidates if relevant.]
+
+---
+
+**Review verdict:** [Greenlight / Revisions Requested / Block]
+
+Origin Session ID: [reviewer's session UUID]