opencode-codeops 2.0.4 → 2.1.1

package/CHANGELOG.md

@@ -2,8 +2,77 @@
 
 All notable changes to CodeOps are recorded here.
 
+## 2.1.1 — 2026-10-09
+
+### Fixes
+
+- plugin: stop deleting the shared scratch directory on unload
+
+### Tests
+
+- plugin: pin the scratch-directory lifecycle contract (red phase)
+
+### Documentation
+
+- changelog: add the 2.1.0 usage notes and complete the feature
+
+## 2.1.0 — 2026-10-09
+
+### Usage
+
+- Run the `analyze-agents` skill on demand for a project-level specialist check; it records
+  `codeops/specialist-check.json`, and `analyze-project` reports the coverage line.
+- `exec-plan` records each ruling batch in `plans/<plan>/05-findings.md`, which feeds finding-area
+  recurrence in the check.
+
+### Documentation
+
+- readme: list the analyze-agents skill and the on-demand detection flow
+- exec-plan: record ruling batches in the per-plan findings ledger
+- skills: complete T-07 with the coverage-line smoke and render clarifications
+- skills: surface specialist checks and split proposals from the creation gate
+- plans: resolve the analyze-agents preflight findings and pass the plan
+- plans: add the analyze-agents feature plan set (gate passed)
+- changelog: add the 2.0.4 upgrade notes and record the release
+
+### Chores
+
+- plan: record the 3.1.1 live smoke
+- plan: record 2.1.3 full verification
+- plan: record 1.1.3 full verification
+- plan: use plain-bullet deliverables so progress counts only tasks
+- plan: record T-07.3 full verification
+- plan: complete T-06 - v2.0.4 verified and issue #2 closed
+
+### Fixes
+
+- skills: harden the ledger assertions per the phase-2 review
+- skills: anchor the phase-1 review assertions and clarify the fallback wording
+- tests: drop the borrowed ST id from the T-07 content suite
+- skills: resolve the T-07 review findings
+
+### Tests
+
+- skills: extend the analyze-agents content tests with the ledger wiring (red phase)
+- skills: add analyze-agents content spec tests (red phase)
+- skills: add specialist awareness content tests (red phase)
+
+### Features
+
+- skills: add the analyze-agents check skill and protocol wiring
+
 ## 2.0.4 — 2026-10-09
 
+### Upgrade Notes
+
+- Existing installs upgrade in place: run `npx opencode-codeops update` (package-scope installs) or
+  re-run `install_agents.py --roles` / `--custom` (project-generated agents); `--check` reports
+  `STALE` until the files are regenerated.
+- Generated agent files now open with `---`, so OpenCode parses `mode`, `hidden`, `permissions`,
+  descriptions, and model pins. Catalog roles are hidden subagents instead of selectable primary
+  agents. `temperature`/`reasoningEffort` values remain preserved but are not yet sent by the
+  OpenCode V2 runner.
+
 ### Chores
 
 - plan: sync the T-06 progress header (6/8 tasks)

package/README.md

@@ -16,6 +16,7 @@ Turn an idea or existing system into ambiguity-free requirements, grounded speci
 | `exec-plan` | Execute a plan — implement → verify → commit loop with quality reviews |
 | `roadmap` | Live feature-set roadmap — make, update, review, archive |
 | `analyze-project` | Analyze repo and create/refresh CodeOps-aware `AGENTS.md` guidance |
+| `analyze-agents` | Run the project-level specialist check on demand — proposals or a recorded None, with check state |
 | `setup-codeops` | Set up or migrate CodeOps in a git repo |
 | `setup-routing` | Configure per-role subagent model and policy routing |
 | `upgrade-plan` | Upgrade legacy CodeOps artifacts to current schema |
@@ -144,11 +145,11 @@ The plugin also warns (non-blocking) if any tool attempts to edit `codeops/.code
 
 Every session also gets a workspace-hygiene guard: the plugin exports `CODEOPS_TMPDIR`, a scratch
 directory under the OS temp directory that belongs to the running OpenCode plugin instance. Skills
-and agents put temporary files there and delete them when the run completes; the plugin removes the
-directory when it unloads and sweeps directories abandoned by interrupted runs at startup, so
-CodeOps does not accumulate scratch data. Because OpenCode 2 does not expose a session id to shell
-hooks, concurrent sessions served by one instance share this directory. The full protocol is in
-`_shared/workspace-hygiene.md`.
+and agents put temporary files there and delete them when the run completes; the plugin sweeps
+directories abandoned by interrupted runs at startup (older than seven days), so CodeOps does not
+accumulate scratch data. Because OpenCode 2 does not expose a session id to shell hooks, concurrent
+sessions served by one instance share this directory, and no session's scratch is deleted while
+others may still use it. The full protocol is in `_shared/workspace-hygiene.md`.
 
 ## Agent model configuration
 
@@ -191,8 +192,10 @@ capability gap the twelve catalog roles and dynamic packets cannot close. Specia
 only with your explicit approval — the `--auto-design` mode cannot approve them.
 
 - **Detect** — `make-requirements`, `make-plan`, and `analyze-project` run an evidence-based check
-  and record the outcome (including a negative one). At most two candidates are proposed per
-  requirements set or plan.
+  and record the outcome (including a negative one); the `analyze-agents` skill runs the same
+  check on demand and maintains `codeops/specialist-check.json` for the coverage line. At most two
+  candidates per scope surface as lightweight, evidence-backed proposals; the creation gate
+  applies when you choose to proceed.
 - **Create** — after you approve the candidate packet, `setup-routing` writes a brief at
   `codeops/specialists/<role>.md`, writes routing policy first, generates a visible agent with
   `install_agents.py --custom <role>`, and updates a managed index block in `AGENTS.md` with

package/_shared/specialist-agents.md

@@ -64,6 +64,52 @@ escalation)` entry.
 - Rejection and deferral are valid outcomes. A rejected candidate may not reappear in the same
   scope without new evidence.
 
+## Proposals and the creation gate
+
+A **lightweight proposal** is a short, evidence-backed suggestion — role slug, kind, one-line
+capability, evidence (`file:line`), the smallest alternative and why it is insufficient — surfaced
+in the normal findings/plan flow. Proposals need no gate: they are suggestions, not machinery.
+
+The Complexity Escalation Gate, the independent challenger verdict, and the reserved-authority
+decision apply only when the user chooses to proceed to creation. Approved roles are then created
+through `setup-routing` as described below; the lightweight proposal format is what `analyze-agents`
+and every detection step emit for at most two candidates per scope.
+
+## Check state
+
+Running the check records one small project file:
+
+```json
+{
+  "checkedAt": "<ISO-8601 timestamp>",
+  "plans": ["<plan folder>", "<plan folder>"]
+}
+```
+
+- Path: `codeops/specialist-check.json` (project-level in both layouts).
+- Written at the end of every check run — including `None` outcomes — by the execution surface
+  (`analyze-agents`); the `plans` list is layout-aware.
+- Absent, unreadable, or malformed state means **never checked** for consumers; the
+  `analyze-project` coverage line then recommends a run. Fail loud, never silent.
+
+## Findings ledger
+
+`exec-plan` records each ruling batch in the plan's findings ledger — one compact row per batch,
+identifiers and area tokens only:
+
+- Location: `plans/<plan>/05-findings.md` (flat) or
+  `codeops/features/<f>/plans/<plan>/05-findings.md` (nested), per
+  [`layout-convention.md`](layout-convention.md).
+- Format:
+
+  | Finding | Phase | Severity | Area | Ruling |
+  | ------- | ----- | -------- | ---- | ------ |
+  | RV-001 | 2 | MAJOR | scripts/install_agents.py | fixed |
+
+- Writer: `exec-plan`'s ruling step appends the batch's rows after each ruling batch; runtime
+  complexity decisions stay in the ambiguity register.
+- The `analyze-agents` check reads these rows for finding-area recurrence.
+
 ## Routing layers
 
 | Layer | Owner | Content | Consumer |
@@ -76,15 +122,21 @@ escalation)` entry.
 
 ## Detection integration
 
+The `analyze-agents` skill is the execution surface for the criteria in every flow below; each
+step keeps an instruction referencing these criteria so the flow still works when the skill is
+unavailable.
+
 ### make-requirements
 
 1. After domain-lens selection and scope confirmation, run the detection criteria.
-2. For each candidate, open an ambiguity-register entry (`Technical (complexity escalation)`) with
-   the candidate packet, run the challenger, and obtain the user's decision.
+2. Surface at most two candidates in one batch as lightweight proposals (§Proposals and the
+   creation gate). When the user chooses to proceed to creation, open an ambiguity-register entry
+   (`Technical (complexity escalation)`) with the candidate packet, run the challenger, and obtain
+   the user's decision.
 3. Approved candidates are created through `setup-routing` or noted for creation before the first
    implementing plan; rejected candidates are recorded and dropped.
-4. Record the check in the final summary. No new requirements-template section is created; the
-   brief and the register are the durable records.
+4. Record the check in the final summary as a `Specialist check:` line. No new requirements-template
+   section is created; the brief and the register are the durable records.
 
 ### make-plan
 
@@ -111,16 +163,18 @@ escalation)` entry.
    standing specialist would close.
    ```
 
-3. Candidate approval, challenger, and persistence follow the shared gate exactly. Approved roles
-   are created through `setup-routing` before execution begins; the plan remains valid without them
-   via dynamic-packet fallback.
+3. Candidates surface as lightweight proposals (§Proposals and the creation gate); when the user
+   chooses to proceed to creation, the Complexity Escalation Gate, the challenger, and persistence
+   apply exactly as defined there. Approved roles are created through `setup-routing` before
+   execution begins; the plan remains valid without them via dynamic-packet fallback.
 
 ### analyze-project
 
 1. While inspecting manifests and conventions, note specialization signals (specialized
    framework/DSL, domain invariants, conventions a generic agent would miss).
-2. When a signal is strong and no specialist exists, report the candidate with evidence and
-   recommend running `setup-routing`; never write agent files or candidate artifacts, and keep
+2. When a signal is strong and no specialist exists, surface the candidate as a lightweight
+   proposal (§Proposals and the creation gate) with evidence, and recommend running `setup-routing`
+   when the user chooses to proceed; never write agent files or candidate artifacts, and keep
    `AGENTS.md` compact.
 3. Preserve the `<!-- CODEOPS-SPECIALISTS:START -->` / `<!-- CODEOPS-SPECIALISTS:END -->` block
    byte-for-byte when refreshing managed guidance.

package/_shared/workspace-hygiene.md

@@ -51,7 +51,9 @@ keep scratch file names specific to the run to avoid collisions.
 
 ## Automatic safety net
 
-The CodeOps plugin exports `$CODEOPS_TMPDIR` for each runtime and removes that runtime's
-directory when the plugin unloads. At startup it also removes CodeOps temp directories older
-than seven days, so an interrupted run cannot leak storage forever. The safety net is a
-fallback, not a substitute: the run itself still performs the cleanup pass above.
+The CodeOps plugin exports `$CODEOPS_TMPDIR` for each runtime. At startup it removes CodeOps
+temp directories older than seven days, so an interrupted run cannot leak storage forever.
+The plugin never deletes a runtime's directory while sessions may still be running — several
+sessions can share one directory, so reclamation happens only through the age-based sweep.
+The safety net is a fallback, not a substitute: the run itself still performs the cleanup
+pass above.

package/bin/lib/tmp-hygiene.d.mts

@@ -33,6 +33,3 @@ export interface CleanStaleTmpDirsOptions {
 
 /** Remove session directories abandoned by interrupted or crashed runs. */
 export declare function cleanStaleTmpDirs(options?: CleanStaleTmpDirsOptions): string[]
-
-/** Remove exactly one session's temp directory. */
-export declare function removeSessionTmpDir(sessionID?: string, base?: string): boolean

package/bin/lib/tmp-hygiene.mjs

@@ -9,8 +9,7 @@
  * - it computes the per-session directory the plugin exports as
  *   `$CODEOPS_TMPDIR`, under a CodeOps-owned root inside the OS temp directory;
  * - it sweeps directories abandoned by interrupted runs once they are older
- *   than a safety cap; and
- * - it removes exactly one session's directory when that session is deleted.
+ *   than a safety cap.
  *
  * Safety is the whole point: every path derives from a sanitized session
  * identifier, the sweep walks only the CodeOps-owned root, symlinked entries
@@ -22,7 +21,7 @@
 
 import { lstatSync, mkdirSync, readdirSync, rmSync } from "node:fs"
 import { tmpdir } from "node:os"
-import { join, resolve, sep } from "node:path"
+import { join, resolve } from "node:path"
 
 /**
  * Age after which a session directory is treated as abandoned.
@@ -147,34 +146,3 @@ export function cleanStaleTmpDirs({
 
   return removed
 }
-
-/**
- * Remove exactly one session's temp directory.
- *
- * Used when a session is deleted: its scratch can no longer be needed. The
- * removal refuses anything that is not a regular directory strictly inside
- * the CodeOps temp root, so a symlink or an unexpected path is left alone.
- *
- * @param sessionID - Session identifier whose directory should be removed
- * @param base - Base temp directory (injectable for tests)
- * @returns True when the directory was removed
- */
-export function removeSessionTmpDir(sessionID, base = tmpdir()) {
-  const root = resolve(codeopsTmpRoot(base))
-  const dir = sessionTmpDir(sessionID, base)
-
-  if (!resolve(dir).startsWith(root + sep)) return false
-
-  try {
-    if (!lstatSync(dir).isDirectory()) return false
-  } catch {
-    return false
-  }
-
-  try {
-    rmSync(dir, { recursive: true, force: true })
-    return true
-  } catch {
-    return false
-  }
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-codeops",
-  "version": "2.0.4",
+  "version": "2.1.1",
   "description": "Specification-first engineering for complex systems — CodeOps plugin for OpenCode",
   "type": "module",
   "engines": {

package/plugin/index.ts

@@ -8,7 +8,6 @@ import { fileURLToPath } from "node:url"
 import {
   cleanStaleTmpDirs,
   ensureSessionTmpDir,
-  removeSessionTmpDir,
 } from "../bin/lib/tmp-hygiene.mjs"
 import {
   appendEffortTrace,
@@ -70,9 +69,9 @@ const standardsText = `${codingStandards}\n\n${outputStyle}`
 // OpenCode 2 does not expose a session identifier to shell hooks, so the plugin
 // owns one scratch directory per plugin runtime instead of one per session.
 // Skills and subagents still receive it as CODEOPS_TMPDIR and delete their own
-// scratch; the plugin removes the runtime directory on unload and sweeps
-// directories abandoned by earlier runs. Two sessions served by the same
-// runtime share this directory; see _shared/workspace-hygiene.md.
+// scratch; the startup sweep reclaims directories abandoned by earlier runs.
+// Several sessions can share one runtime directory, so the plugin must never
+// delete it on unload; see _shared/workspace-hygiene.md.
 // ---------------------------------------------------------------------------
 const runtimeID = `runtime-${randomUUID()}`
 
@@ -386,16 +385,12 @@ export default Plugin.define({
     })
 
     // ---------------------------------------------------------------------
-    // Plugin cleanup: stop listening for events and remove the runtime's
-    // scratch directory. Both are best effort.
+    // Plugin cleanup: stop listening for events. The runtime's scratch
+    // directory is deliberately left in place — other sessions may still be
+    // using it — and the startup sweep reclaims abandoned directories.
     // ---------------------------------------------------------------------
     return () => {
       controller.abort()
-      try {
-        removeSessionTmpDir(runtimeID)
-      } catch {
-        // Best effort only.
-      }
     }
   },
 })

package/plugin/temp-lifecycle.spec.test.mjs

@@ -0,0 +1,55 @@
+/**
+ * Specification tests for the scratch-directory lifecycle.
+ *
+ * The plugin exports one scratch directory (`$CODEOPS_TMPDIR`) per plugin
+ * runtime, and every session served by that runtime shares it. Deleting the
+ * directory when a plugin instance unloads destroys in-flight scratch files of
+ * sessions that are still running, so the contract is: the plugin never
+ * deletes the shared directory; the age-based sweep reclaims abandoned
+ * directories instead.
+ *
+ * This is the regression oracle for that contract: a failure here means the
+ * repository reintroduced early deletion, never that the test is wrong.
+ *
+ * @module temp-lifecycle.spec.test
+ */
+
+import assert from "node:assert/strict"
+import { readFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { describe, it } from "node:test"
+import { fileURLToPath } from "node:url"
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..")
+
+/**
+ * Read a repository file as UTF-8 text.
+ * @param {string} relativePath - Path relative to the repository root.
+ * @returns {string} The file contents.
+ */
+function read(relativePath) {
+  return readFileSync(join(ROOT, relativePath), "utf8")
+}
+
+describe("scratch-directory lifecycle", () => {
+  it("keeps the plugin free of scratch-directory deletion", () => {
+    const plugin = read("plugin/index.ts")
+    assert.doesNotMatch(plugin, /removeSessionTmpDir/)
+    assert.match(plugin, /cleanStaleTmpDirs\(\)/)
+    assert.match(plugin, /controller\.abort\(\)/)
+  })
+
+  it("keeps the temp hygiene module free of exact-directory deletion", () => {
+    assert.doesNotMatch(read("bin/lib/tmp-hygiene.mjs"), /removeSessionTmpDir/)
+    assert.doesNotMatch(read("bin/lib/tmp-hygiene.d.mts"), /removeSessionTmpDir/)
+  })
+
+  it("documents the age-based sweep as the automatic cleanup", () => {
+    const hygiene = read("_shared/workspace-hygiene.md")
+    assert.doesNotMatch(hygiene, /removes that runtime's\s+directory when the plugin unloads/i)
+    assert.match(hygiene, /seven days/i)
+    const readme = read("README.md")
+    assert.doesNotMatch(readme, /removes the\s+directory when it unloads/i)
+    assert.match(readme, /sweeps\s+directories abandoned/i)
+  })
+})

package/skills/analyze-agents/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: analyze-agents
+description: Run the project-level specialist check on demand. Reads the repository's requirements, plans, findings ledgers, and manifests directly (no script), applies the specialist-agent detection criteria, presents at most two evidence-backed lightweight proposals or a None with evidence, and records the check state consumed by the analyze-project coverage line.
+---
+
+# analyze-agents
+
+Run this check to re-evaluate whether a project would benefit from a project-specific specialist
+subagent — on request, or because `analyze-project` reported the coverage as due. This skill is the
+execution surface for the detection criteria in
+[`../../_shared/specialist-agents.md`](../../_shared/specialist-agents.md); it reads the
+repository's own artifacts and never invokes a script.
+
+## Evidence
+
+Read these sources for the current project. All paths are layout-aware per
+[`../../_shared/layout-convention.md`](../../_shared/layout-convention.md): flat `plans/` or nested
+`codeops/features/<f>/plans/`.
+
+- requirements and plan documents — domain/lens tags and scope history;
+- per-plan findings ledgers (`05-findings.md`) — finding-area recurrence;
+- manifests (`package.json`, `pyproject.toml`, `go.mod`, and similar) — specialized framework,
+  DSL, codegen, or protocol signals;
+- existing `codeops/specialists/` briefs and `codeops/codeops.json` routing roles —
+  deduplicate against installed specialists;
+- `codeops/specialist-check.json` — the prior check state.
+
+## Detection flow
+
+1. Collect the evidence sources above.
+2. Apply the detection criteria and disqualifiers from the protocol document: a candidate needs
+   evidenced strong signal(s) and no disqualifier.
+3. Recurrence anchor: one area appearing in at least two plans or three findings ranks as a strong
+   signal; thresholds anchor judgment, not hard gates.
+4. Present at most two candidates in one batch as **lightweight proposals** — role slug, kind, a
+   one-line capability, evidence with `file:line`, and the smallest alternative with why it is
+   insufficient — or record `None` with evidence.
+5. Write the check state (below) on every run, including a `None` outcome.
+6. Hand-off: on user interest, hand off to the `setup-routing` flow for creation. Never create or
+   modify agent files, briefs, routing policy, or `AGENTS.md`.
+
+## Check state
+
+Write `codeops/specialist-check.json` (project-level in both layouts; create the `codeops/`
+directory lazily when it does not exist):
+
+```json
+{
+  "checkedAt": "<ISO-8601 timestamp>",
+  "plans": ["<plan folder>", "<plan folder>"]
+}
+```
+
+The `plans` list contains the plan folders present at check time (layout-aware). Consumers treat
+absent, unreadable, or malformed state as **never checked** and recommend a run — fail loud, never
+silent.
+
+## Output
+
+A short human summary: the candidate proposals in the lightweight format above, or `None` with
+evidence, plus the state write result. The state file is the machine-readable artifact; there is no
+separate JSON output mode.
+
+## Degradation
+
+- Missing findings ledger: the output states that the ledger was missing and the check ran on
+  reduced evidence (documents and manifests only).
+- Malformed ledger rows: skip the row with a note; never guess its fields.
+- Empty repository (no plans or requirements): record `None` with evidence and still write the
+  check state.
+
+---
+
+> **Workspace hygiene (non-negotiable):** put every temporary artifact this run creates in
+> `$CODEOPS_TMPDIR` (fallback: the OS temp directory), never in the repository, and delete them
+> all before reporting completion. Never delete user files, versioned artifacts, worktrees, or
+> another session's temporary files. Full rules:
+> [_shared/workspace-hygiene.md](../../_shared/workspace-hygiene.md).

package/skills/analyze-project/SKILL.md

@@ -24,7 +24,7 @@ description: Analyze the current repository and create or refresh concise CodeOp
 7. On a non-integration branch, preview changes to repository-wide guidance and ask before writing unless repository policy explicitly permits branch-local updates.
 8. In compact mode, remove duplication and stale generated detail from the managed section only. Flag suspected hand-authored bloat; never silently rewrite it.
 9. Validate every recorded command or mark it explicitly unverified.
-10. When a specialization signal is strong and no specialist covers it, report the candidate with evidence and recommend the `setup-routing` creation flow ([../../_shared/specialist-agents.md](../../_shared/specialist-agents.md)); never write agent files here. Preserve the `<!-- CODEOPS-SPECIALISTS:START -->` / `<!-- CODEOPS-SPECIALISTS:END -->` block byte-for-byte when refreshing the managed section.
+10. Specialist coverage: read `codeops/specialist-check.json` when present and include a `Specialist coverage:` line in the managed section — `up to date (<YYYY-MM-DD>)` (from `checkedAt`) when the recorded plan set matches the current one; `check due — run analyze-agents` otherwise; when the state is absent or corrupt, render `check due — run analyze-agents (never checked)`. The `analyze-agents` skill runs the check (criteria: [../../_shared/specialist-agents.md](../../_shared/specialist-agents.md)); when a specialization signal is strong and no specialist covers it, report the candidate with evidence and recommend the `setup-routing` creation flow; never write agent files here. Preserve the `<!-- CODEOPS-SPECIALISTS:START -->` / `<!-- CODEOPS-SPECIALISTS:END -->` block byte-for-byte when refreshing the managed section.
 
 Keep `AGENTS.md` small. Operational routing belongs in `codeops/codeops.json` or `opencode.json`, not prose.
 

package/skills/exec-plan/SKILL.md

@@ -229,9 +229,9 @@ links to them, never restates them.
 The flow: the protocol records a phase-start ref when the phase begins; after the phase's last
 task verifies, the correctness reviewer and any active auditors are dispatched **in parallel** on
 the phase diff, their findings are merged and presented in severity-grouped batches, and each
-ruling is recorded in the durable finding artifact. Specialist roles listed in the plan's
-`## Specialist Agents` table dispatch per `_shared/quality-profile.md`; an unavailable specialist
-falls back to a generic packet and the fallback is reported.
+ruling is recorded in the plan's findings ledger (`05-findings.md`). Specialist roles listed in
+the plan's `## Specialist Agents` table dispatch per `_shared/quality-profile.md`; an unavailable
+specialist falls back to a generic packet and the fallback is reported.
 
 > **🚨 Finding gate (load-bearing).** In normal mode, 🔴 CRITICAL and 🟠 MAJOR findings PAUSE
 > execution for the user's ruling in ALL commit modes. With active auto-design, select and record

package/skills/exec-plan/execution-protocol.md

@@ -199,9 +199,17 @@ whole-task diff. Activation rules, packets, supersession, and caps are defined i
    `[!]`, preserve the diff without marking it verified, and switch to the full standalone-plan
    path. The new `00-ambiguity-register.md` owns the packet and decision. Resume only after that
    plan's gates pass.
-4. **Record decisions durably** in the finding artifact after each ruling batch. When the user
-   approves larger machinery, also append a `Technical (complexity escalation)` runtime AR with
-   every approval-evidence field required by the shared gate; the RV finding references that AR.
+4. **Record decisions durably** in the plan's findings ledger after each ruling batch. The ledger
+   is `plans/<plan>/05-findings.md` (flat) or
+   `codeops/features/<f>/plans/<plan>/05-findings.md` (nested), created lazily on first use, with a
+   one-line title and one compact row per batch:
+   `| Finding | Phase | Severity | Area | Ruling |` — finding ids use the review prefixes
+   `RV-`/`SA-`/`PE-`/`SR-` (for example `RV-001`), followed by the phase number,
+   `CRITICAL`/`MAJOR`/`MINOR`, a path or domain token, and
+   `fixed`/`accepted`/`deferred`/`dismissed`; identifiers and area tokens only, never prose. Task
+   mini-plans keep their ledger in their own plan folder. When the user approves larger machinery,
+   also append a `Technical (complexity escalation)` runtime AR with every approval-evidence field
+   required by the shared gate; the RV finding references that AR.
 5. **Accepted fixes:** implement → verify → follow-up commit per the commit mode. If any 🔴/🟠
    fix was applied, dispatch ONE re-review scoped to the fix diff — never a third pass. A fix
    the re-review still rejects is reported. Normal mode returns the ruling to the user; active

package/skills/make-plan/SKILL.md

@@ -71,7 +71,7 @@ with active scope exploration.
 
 Re-run [../../references/domains/selection.md](../../references/domains/selection.md) before component decomposition. Requirements-stage lens selection is evidence, not a permanent assumption. Apply every selected lens to specifications, acceptance criteria, failure narratives, and test strategy.
 
-After lens selection and phase decomposition, run the specialist-gap check in [../../_shared/specialist-agents.md](../../_shared/specialist-agents.md). Record the outcome in `00-index.md` under `## Specialist Agents` — always, including `None` with its reason and evidence. Candidate creation is reserved authority: `--auto-design` may not approve it, and approved roles are created through `setup-routing`.
+After lens selection and phase decomposition, run the specialist-gap check in [../../_shared/specialist-agents.md](../../_shared/specialist-agents.md). The `analyze-agents` skill executes the same detection flow on demand; the manual criteria in the linked protocol document remain the fallback when the skill is unavailable. Record the outcome in `00-index.md` under `## Specialist Agents` — always, including `None` with its reason and evidence. In the final plan summary, include a `Specialist check:` line — `None — <evidence>` or the candidate names. Candidate creation is reserved authority: `--auto-design` may not approve it, and approved roles are created through `setup-routing`.
 
 A folder `plans/<feature-name>/` containing:
 
@@ -274,6 +274,8 @@ Report what was created:
 
 **Summary:** Total Phases: X · Total Sessions: X · Estimated Time: X–X hours
 
+**Specialist check:** [None — evidence / candidate names]
+
 **To begin implementation:** use the exec-plan skill on `[feature-name]`.
 ```
 

package/skills/make-plan/quality-checklist.md

@@ -7,6 +7,7 @@ Run this before finalizing the plan documents. The **Specification-First Testing
 - [ ] All affected components identified
 - [ ] All scope decisions documented
 - [ ] All dependencies mapped
+- [ ] The `## Specialist Agents` outcome is recorded in `00-index.md` (candidate or `None` with evidence)
 - [ ] Every planned item traces to the confirmed scope baseline or a user-kept `SE-*` entry
 - [ ] Strict scope contains no optional suggestions; exploration proposals remain non-executable
       until the user chooses `Keep`

package/skills/make-requirements/SKILL.md

@@ -55,7 +55,7 @@ than stored as a second mutable status.
 
 Before discovery, read [../../references/domains/selection.md](../../references/domains/selection.md), select every applicable system lens, and read those lens files completely. Record selected lenses and evidence in the requirements index. Re-evaluate selection when discovery reveals another domain; a financial web service, for example, requires financial, web, distributed/concurrent, and data/migration lenses.
 
-After lens selection and scope confirmation, run the specialist-gap check in [../../_shared/specialist-agents.md](../../_shared/specialist-agents.md). Propose at most two candidates in one batch, each through the Complexity Escalation Gate; creation is reserved authority (`--auto-design` may never approve it). Record the check outcome — including "none" — in the final summary.
+After lens selection and scope confirmation, run the specialist-gap check in [../../_shared/specialist-agents.md](../../_shared/specialist-agents.md). The `analyze-agents` skill executes the same detection flow on demand; the manual criteria in the linked protocol document remain the fallback when the skill is unavailable. Surface at most two candidates in one batch as lightweight proposals (that document's §Proposals and the creation gate); the Complexity Escalation Gate and the reserved-authority approval apply only when the user chooses to proceed to creation (`--auto-design` may never approve it). Record the outcome in the final summary as a `Specialist check:` line — including `Specialist check: None — <evidence>`.
 
 You are NOT a passive interviewer. You are a **domain-aware consultant** that: