Migrate dev loop to agent-folder skills + harden brain self-shutdown guard (#553)

* Migrate dev loop to agent-folder skills (context → quality → test → ship)

Replace the .claude/commands slash commands with agent-folder skills under
.agents/skills, ported from Versic's dev-loop pattern and re-grounded in ADE:

- context (new): branch-area primer that folds in untracked files and lazy-loads
  only the matching docs + perf skill via references/doc-map.md
- quality (new): thermo dual-review (correctness/security + maintainability /
  code-judo) with ADE-specific review rules — runtime-backed null services,
  daemon action-domain wiring, cr-sqlite CRR, IPC contract drift, fast-tier
- test: automate reformatted 1:1; now consumes the /quality gate as regression
  targets and runs CI-mirrored shards
- ship: shipLane's loop de-bundled — pure poll → fix → rebase → merge, no
  automate/finalize; preserves @copilot/@codex pings, conflict-only rebase, admin merge
- audit / finalize / optimize / release kept as reformatted utility skills

Delete the migrated commands and the source-command-audit wrapper; symlink
.claude/skills -> .agents/skills for native Claude discovery; de-bundle the
ship-lane playbook Phase 0; repoint the Path-to-Merge orchestrator source-of-truth
refs from the deleted command to docs/playbooks/ship-lane.md; add a Dev loop
section to AGENTS.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Harden brain self-shutdown guard: typed flag, not message match

The brain-restart path detected a blocked uninstall by substring-matching the
human-readable refusal message ("running inside that brain" +
"ADE_ALLOW_RUNTIME_SERVICE_SELF_MUTATION=1") that installLaunchd.ts produces
independently. Rewording either string would silently let `brain restart`
re-install after a blocked stop, defeating the #549 guard.

Add a typed `selfMutationBlocked` flag to ServiceManagerResult, set it where the
block is produced, and branch on the flag in cli.ts instead of the message text.
Behavior-preserving; serviceManager/common.test.ts (46) green, ade-cli typecheck clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: arul28

.claude/commands/audit.md .agents/skills/audit/SKILL.md.claude/commands/audit.md renamed to .agents/skills/audit/SKILL.md

@@ -1,4 +1,5 @@
 ---
+name: audit
 description: Audit recent work — trace error paths, probe edge cases, fix any bugs or gaps found
 ---
 

.agents/skills/context/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: context
+description: >-
+  Session primer for ADE work: what ADE is, the dev loop, the tooling you can
+  reach (the `ade` CLI control plane, app/browser/iOS-sim control, Linear,
+  computer-use), and what's in flight on this branch. Auto-detects the active
+  feature area from branch changes (or explicit keywords) and loads only the
+  relevant docs + the matching perf skill — never a broad dump.
+---
+
+# Context Skill
+
+Session primer. Run once at the start of a session to learn what ADE is, how we
+work, the tooling you can reach, and what (if anything) is in flight on this
+lane. Feature-aware — load only the docs relevant to the work, never a broad
+dump.
+
+**Invocation:** `/context` or `/context <keywords>`
+**Arguments:** optional feature/domain keywords (e.g., `prs`, `lanes rebase`, `tui`).
+
+---
+
+## Step 1 — Determine scope
+
+**Args given:** parse the feature/domain keywords; pick the product area; build
+the doc + perf-skill set from `references/doc-map.md`.
+
+**No args:** auto-detect from the lane.
+
+```bash
+git diff main --name-only                       # tracked changes vs main
+git status --short                              # NEW (untracked) files git diff misses
+git log main..HEAD --oneline                    # commits unique to this lane
+```
+
+`git diff main` does **not** list untracked files — on a lane whose whole point
+is new files (a new service, a new skill), the changes are invisible without
+`git status`. Always fold both in. Then infer the area from the changed paths and
+resolve docs + the matching `ade-perf-*` skill via `references/doc-map.md`.
+
+---
+
+## Step 2 — Baseline (always read)
+
+- `AGENTS.md` — how to run/build/test, working norms, gotchas, the dev loop.
+- `docs/README.md` — the internal-docs navigation map.
+- `docs/PRD.md` — what ADE is, who it's for, the feature index.
+- `docs/ARCHITECTURE.md` — read the **section** relevant to the touched area
+  (IPC, data plane, build/test/deploy), not the whole file. It's large.
+
+---
+
+## Step 3 — Feature docs + perf skill
+
+Match changed paths / keywords against `references/doc-map.md` and load that doc
+set only. Each `docs/features/<area>/README.md` opens with a **Source file map**
+and a **gotchas / fragile areas** section — read those first; a flagged
+invariant usually deserves care (and a test later in `/test`).
+
+If the area maps to a performance skill (`ade-perf-boot`, `ade-perf-lanes`,
+`ade-perf-prs`, `ade-perf-work`, or `ade-tui-web-preview`), open that skill too
+**before editing** — it records measured patterns you must preserve.
+
+---
+
+## Step 4 — Ongoing work (the *why*, not just filenames)
+
+```bash
+git log main..HEAD --stat        # what the lane's commits changed
+git diff main                    # committed + uncommitted tracked work
+git status --short               # new/untracked work the diff omits
+```
+
+- Read the diff to understand the purpose of the in-flight work.
+- If a commit or branch name carries a Linear ID (e.g. `ADE-123`), read the
+  issue for intent (`ade linear` — see the `ade-linear` skill).
+- Cross-check the feature doc's task tracking (`[ ]` / `[x]`).
+- **No lane commits and no diff → say "Fresh lane — no in-flight work."**
+  Don't invent context.
+
+---
+
+## Step 5 — Summarize
+
+Emit this and nothing more (keep it scannable):
+
+```markdown
+## Context Loaded
+
+**Project:** ADE — local-first desktop env for orchestrating coding agents,
+lanes, PRs, and proof/artifacts (Electron + React + TS; CLI in `apps/ade-cli`).
+**Branch:** [name] · [N changed files | fresh lane]
+**Area:** [feature] — [desktop / cli / tui / ios / cross-cutting]
+**Docs:** [loaded list]   **Perf skill:** [ade-perf-* loaded | none for this area]
+
+**In flight:** [what the work does + why, or "Fresh lane — no in-flight work"]
+**Tracking:** [open N / done N · Linear: IDs or none · gaps if any]
+
+**Tools (configured — use them for live state, don't ask):** `ade` CLI control
+plane · app/browser/iOS-sim/macOS-VM control · Linear (via `ade`) · computer-use
++ proof drawer. Depth → the matching `ade-*` skill.
+**Dev loop:** /context → work → /quality → /test → /ship. Utilities: /audit,
+/finalize, /optimize, /release. Open each skill when you reach it.
+**Tests:** [commands for this area — see AGENTS.md "Validation"]
+
+Ready to assist with [feature].
+```
+
+---
+
+## Tooling you have
+
+ADE ships its capabilities as Agent Skills. State them briefly in the summary;
+open the relevant one only when a task needs it.
+
+- **`ade` CLI** — the control plane for ADE state (lanes, chats, actions, PRs,
+  proof, runtime/socket). Ground truth is `ade help <command>` and
+  `ade actions list --text`, not memory. → `ade-cli-control-plane`.
+- **Lanes & git** → `ade-lanes-git`. **PR workflows** → `ade-pr-workflows`.
+- **App / browser / iOS-sim / macOS-VM control** → `ade-app-control`,
+  `ade-browser`, `ade-ios-simulator`, `ade-macos-vm`.
+- **Linear** (no API key needed; routed through ADE) → `ade-linear`.
+- **Proof & computer-use** (screenshots, video, traces → proof drawer) →
+  `ade-proof-artifacts`. **Deeplinks** → `ade-deeplinks`.
+
+**Worktree note:** ADE runs this session inside a lane worktree
+(`.ade/worktrees/<lane>/`). Every edit must target a path under that worktree,
+never the project-root checkout.
+
+---
+
+## Optional deepening (load only when architecture detail is needed)
+
+`docs/ARCHITECTURE.md` covers IPC, the data plane, and build/test/deploy in full
+— read the specific section when touching `preload/`, `shared/ipc.ts`,
+`registerIpc`, or a cross-app/service boundary.

.agents/skills/context/references/doc-map.md

@@ -0,0 +1,73 @@
+# Feature Path → Doc + Perf-Skill Mapping
+
+Resolve changed file paths (or keyword arguments) to the canonical internal docs
+under `docs/` and, where one exists, the performance skill that records measured
+patterns for that surface. Load the doc set **and** open the perf skill before
+editing that surface.
+
+Internal docs live under `docs/` (rebuilt tree). The public Mintlify site
+(`docs.json` + root-level `*.mdx`) is **out of scope** for context loading.
+
+---
+
+## Desktop — main-process services
+
+| Path pattern | Feature docs | Perf skill |
+|---|---|---|
+| `apps/desktop/src/main/services/projects/` | `docs/features/project-home/` | `ade-perf-boot` |
+| `apps/desktop/src/main/services/lanes/` | `docs/features/lanes/` | `ade-perf-lanes` |
+| `apps/desktop/src/main/services/prs/`, `services/review/` | `docs/features/pull-requests/` | `ade-perf-prs` |
+| `apps/desktop/src/main/services/proof/` | `docs/features/proof.md` | — |
+| `apps/desktop/src/main/services/remoteRuntime/`, `services/localRuntime/`, `services/runtime/` | `docs/features/remote-runtime/` | `ade-perf-boot` |
+| `apps/desktop/src/main/services/cto/` | `docs/features/cto/` + `linear-integration/` | — |
+| `apps/desktop/src/main/services/ai/` | `docs/features/chat/` + `features/agents/` | `ade-perf-work` |
+| `apps/desktop/src/main/services/chat/` | `docs/features/chat/` | `ade-perf-work` |
+| `apps/desktop/src/main/services/automations/` | `docs/features/automations/` | — |
+| `apps/desktop/src/main/services/computerUse/` | `docs/features/computer-use/` | — |
+| `apps/desktop/src/main/services/deeplinks/` | `docs/features/deeplinks/` | — |
+| `apps/desktop/src/main/services/orchestration/` | `docs/features/agents/` (orchestrator) | — |
+| `apps/desktop/src/main/services/conflicts/` | `docs/features/conflicts/` | — |
+| `apps/desktop/src/main/services/files/` | `docs/features/files-and-editor/` | `ade-perf-work` |
+| `apps/desktop/src/main/services/history/` | `docs/features/history/` | — |
+| `apps/desktop/src/main/services/onboarding/`, `services/config/` | `docs/features/onboarding-and-settings/` | `ade-perf-boot` |
+| `apps/desktop/src/main/services/pty/`, `sessions/`, `processes/` | `docs/features/terminals-and-sessions/` | `ade-perf-work` |
+| `apps/desktop/src/main/services/sync/` | `docs/features/sync-and-multi-device/` | — |
+| `apps/desktop/src/main/services/git/` | `docs/ARCHITECTURE.md` (Git engine) + `lanes/` | `ade-perf-lanes` |
+| `apps/desktop/src/main/services/ipc/`, `src/preload/` | `docs/ARCHITECTURE.md` (IPC contract) | — |
+| `apps/desktop/src/main/main.ts`, app bootstrap | `docs/ARCHITECTURE.md` (Apps & Processes) | `ade-perf-boot` |
+
+## Desktop — renderer
+
+| Path pattern | Feature docs | Perf skill |
+|---|---|---|
+| `apps/desktop/src/renderer/components/lanes/**` | `docs/features/lanes/` | `ade-perf-lanes` |
+| `apps/desktop/src/renderer/components/prs/**` | `docs/features/pull-requests/` | `ade-perf-prs` |
+| `apps/desktop/src/renderer/components/chat/**`, Work tab panes (Tools, Git, Files, iOS, App Control, Browser, Mac VM) | `docs/features/chat/` + relevant feature | `ade-perf-work` |
+| `apps/desktop/src/renderer/components/app/**` (App shell) | `docs/ARCHITECTURE.md` (UI framework) | `ade-perf-boot` |
+| `apps/desktop/src/renderer/components/graph/**` | `docs/features/workspace-graph/` | — |
+| `apps/desktop/src/renderer/components/<area>/**` | `docs/features/<same-area>/` (note: renderer dir names don't always equal feature dir names — e.g. `graph/`→`workspace-graph/`, `vm/`→no doc) | match by area above |
+| `apps/desktop/src/renderer/state/` (incl. `appStore.ts`) | `docs/ARCHITECTURE.md` (UI framework) | `ade-perf-lanes` |
+| `apps/desktop/src/shared/**` | `docs/ARCHITECTURE.md` + the touching feature's doc | — |
+
+## ADE CLI & TUI
+
+| Path pattern | Feature docs | Perf skill |
+|---|---|---|
+| `apps/ade-cli/src/tuiClient/**` | `docs/features/ade-code/README.md` + `ARCHITECTURE.md` (ADE CLI) | `ade-tui-web-preview` |
+| `apps/ade-cli/**` (non-TUI) | `docs/ARCHITECTURE.md` (ADE CLI / Build/Test/Deploy) + `features/agents/` | — |
+
+## iOS, web, CI
+
+| Path pattern | Feature docs | Perf skill |
+|---|---|---|
+| `apps/ios/**` | `docs/features/sync-and-multi-device/ios-companion.md` + `features/ios-simulator/` | — |
+| `apps/web/**` | `docs/ARCHITECTURE.md` (Apps & Processes) | — |
+| `.github/workflows/**` | `docs/ARCHITECTURE.md` (Build/Test/Deploy) | — |
+
+---
+
+**Cross-cutting:** any change to `preload/`, `shared/ipc.ts`, or `registerIpc`
+also loads `docs/ARCHITECTURE.md` (IPC + data plane sections). Keep IPC
+contracts, preload types, shared types, and renderer usage in sync — see the
+`runtime-backed null services` rule in the `/quality` skill's
+`references/ade-review-rules.md` for the bug class this guards against.

.claude/commands/finalize.md .agents/skills/finalize/SKILL.md.claude/commands/finalize.md renamed to .agents/skills/finalize/SKILL.md

@@ -3,19 +3,24 @@ name: finalize
 description: 'Final gate: simplify code, validate docs, and run local CI checks before pushing'
 ---
 
-# Finalize Command
+# /finalize — Pre-push Local-CI Gate
 
-This command is the final gate before pushing and opening a PR.
+This skill is the final local gate before pushing and opening a PR.
+
+> In the dev loop, deep bug-finding and code cleanup are `/quality`'s job (the
+> loop default) and test-suite work is `/test`'s. `/finalize` is **optional**:
+> run it when you want a full **local** CI gate before `/ship` pushes — a final
+> simplification sweep plus typecheck/lint/sharded-tests/build/doc-validation.
 
 It guarantees three outcomes:
-1. Code quality cleanup is complete
-2. Docs changed by `/automate` are still valid
+1. A final code-simplification sweep is complete (`/quality` already did the heavy lifting)
+2. Docs changed by `/test` are still valid
 3. Local CI checks pass
 
 It does **not** guarantee that remote PR review is complete after a push. GitHub's
 first visible check list can look quiet before delayed checks, bot reviews, and
 inline comments arrive. After pushing a finalized branch, hand off to
-`/shipLane` or an equivalent PR poll loop. Use the ship-lane cadence: poll
+`/ship` or an equivalent PR poll loop. Use the ship-lane cadence: poll
 immediately after a push, wait 270s if CI has not registered, wait 720s while CI
 is running, and wait 1800s only when CI is done and the PR is just waiting on
 review.
@@ -112,7 +117,7 @@ Prompt each with:
 
 Wait for all simplifier agents to complete before moving to Phase 3.
 
-Docs, mobile, CLI, and TUI parity reviewers have moved to `/automate` — they should run before `/finalize`. Do not re-spawn them here.
+Docs, mobile, CLI, and TUI parity reviewers have moved to `/test` — they should run before `/finalize`. Do not re-spawn them here.
 
 ---
 
@@ -282,7 +287,7 @@ surface looks complete. In particular:
 Handoff rule:
 
 ```bash
-# After the branch is pushed, continue with /shipLane or equivalent:
+# After the branch is pushed, continue with /ship or equivalent:
 # - poll PR checks, status rollup, review comments, issue comments, and reviews
 # - poll immediately after a push so early CI registration/failures are visible
 # - if CI has not started yet, wait 270s
@@ -291,7 +296,7 @@ Handoff rule:
 # - poll again before declaring the PR clean or ready for human merge
 ```
 
-If `/finalize` is running as a sub-step inside `/shipLane`, return a summary that
+If `/finalize` is running as a sub-step inside `/ship`, return a summary that
 explicitly says remote checks/comments still require the ship-lane poll loop.
 Do not report "PR clean" from `/finalize` alone.
 
@@ -322,7 +327,7 @@ Do not report "PR clean" from `/finalize` alone.
 
 ### Remote PR Handoff:
 - Post-push polling required: YES
-- Poll loop: `/shipLane` branch-specific cadence
+- Poll loop: `/ship` branch-specific cadence
 - Reason: delayed checks and bot comments may arrive after first visible green state
 
 ### Status: Ready to push / Issues found
@@ -332,4 +337,4 @@ Do not report "PR clean" from `/finalize` alone.
 
 ## Completion Checklist
 
-Before marking complete: every Phase 3 step (3a–3j) must report PASS in the Phase 4 summary, and Phase 2 simplifier agents must have reported back. Remote PR review is **not** declared clean by `/finalize` — handoff to `/shipLane` (Phase 3j) is mandatory after push.
+Before marking complete: every Phase 3 step (3a–3j) must report PASS in the Phase 4 summary, and Phase 2 simplifier agents must have reported back. Remote PR review is **not** declared clean by `/finalize` — handoff to `/ship` (Phase 3j) is mandatory after push.