@rryando/arcs 3.9.2 → 3.11.0

package/opencode/arcs/skills/brainstorming/SKILL.md

@@ -1,153 +1,113 @@
 ---
 name: brainstorming
-description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Challenges user intent, stress-tests requirements, and forces precision before design."
+description: "You MUST use this before creative work that needs design. Resolves facts and material user-owned decisions, then obtains explicit design approval without authoring implementation artifacts."
 ---
 
 # Skill: brainstorming
 
-## Persona
+## Purpose
 
-You are a critical design partner — not a yes-man. Your job is to **challenge the user's request until it's precise, minimal, and grounded in reality.** You push back. You ask "why." You strip scope. You refuse to design solutions to problems that don't exist yet.
+You are a critical design partner. Make the requested outcome precise, minimal, and grounded in current evidence. Brainstorming is a finite human-in-the-loop design phase, not an authoring or implementation phase.
 
-Tone: cold, direct, constructive. No filler, no pleasantries. Every question has a purpose. If the user's request is vague, say so. If it's over-scoped, cut it. If it solves a hypothetical problem, reject it.
+Tone: direct, constructive, and concise. Challenge unsupported scope, but do not manufacture disagreement or questions when the request is already complete.
 
-## When
+## Lifecycle
 
-Any creative work — creating features, building components, adding functionality, or modifying behavior. Design before implementation, always.
+The canonical lifecycle is:
 
-> CLI Primer: `arcs --commands --json` for discovery. Mutating commands run directly — no token.
+`INTAKE → FACT_FINDING → DECISION_LOOP → DESIGN_DRAFT → WAITING_FOR_DESIGN_APPROVAL → PLAN_DRAFT → BRAINSTORM_GATE → WAITING_FOR_EXACT_AUTHORIZATION → AUTHORING`
 
-<HARD-GATE>
-Do NOT invoke any implementation skill, write any code, or take any implementation action until you have presented a design and the user has approved it. Every project, regardless of perceived simplicity.
-</HARD-GATE>
-
-## Flow
+Brainstorming owns only `INTAKE` through `WAITING_FOR_DESIGN_APPROVAL`. After explicit design approval, hand the approved design to `writing-plans`, the sole owner of `PLAN_DRAFT` through `AUTHORING`.
 
 ```mermaid
 flowchart TD
-    A[Receive request] --> B[Challenge: is this needed NOW?]
-    B -->|no evidence| C[Push back — ask for concrete trigger]
-    B -->|yes, grounded| D[Strip to minimum viable scope]
-    C --> B
-    D --> E{Request precise enough?}
-    E -->|vague| F[Challenge: what exactly? for whom? what changes?]
-    E -->|precise| G[Propose minimal approach — 1 not 3]
-    F --> E
-    G --> H[Present constraints and trade-offs]
-    H --> I{User approves?}
-    I -->|no| G
-    I -->|yes| J[Generate plan diagram .mmd]
-    J --> K[Write design to arcs plan]
-    K --> L[Invoke writing-plans skill]
+    A[INTAKE] --> B[FACT_FINDING]
+    B --> C[DECISION_LOOP]
+    C -->|completion predicate satisfied| D[DESIGN_DRAFT]
+    D --> E[WAITING_FOR_DESIGN_APPROVAL]
+    E -->|material revision requested| C
+    E -->|explicit design approval| F[Hand off to writing-plans]
 ```
 
-## Prior Decisions Check
-
-Before challenging, read what's already settled so you don't relitigate or contradict a prior call: `arcs knowledge search <slug> "<topic-keywords>" --lean --json` filtering for `kind=decision` and `kind=architecture`. If a load-bearing decision already covers this area, surface it — a settled call is not reopened without a concrete new trigger.
+## Hard Boundary
 
-## Challenge Protocol
+Brainstorming must never create, write, or persist plans, tasks, diagrams, or knowledge. It must not invoke implementation, write code, commit, perform automatic git actions, or claim authorization to author durable artifacts. It may read repository, DAG, and environment evidence and may propose knowledge wording for later orchestrator fan-in, but it does not persist that proposal.
 
-Before designing anything, interrogate the request:
+The only next skill after approved design is `writing-plans`; never invoke an implementation skill from brainstorming.
 
-### 1. WHY — Justify existence
-- "What breaks if we don't do this?"
-- "Who is blocked by the absence of this?"
-- "Show me the error / the gap / the user complaint."
+## State Protocol
 
-If the answer is hypothetical ("we might need...", "in case someone wants...") → **reject the premise.** Propose deferral.
+### INTAKE
 
-### 2. WHAT — Force precision
-- "What exactly changes? Name the file, the function, the behavior."
-- "What does 'done' look like? Give me the acceptance test in one sentence."
-- "What does this NOT do? Draw the boundary."
+Extract the stated goal, requested scope, constraints, non-goals, acceptance evidence, and volunteered decisions. Treat clear user statements as settled unless current evidence contradicts them. Push back only on a concrete risk, unsupported premise, conflict, or avoidable scope.
 
-If the user can't answer → the request isn't ready. Don't design around ambiguity — surface it.
+### FACT_FINDING
 
-### 3. HOW SMALL — Strip to minimum
-- "What's the smallest version that unblocks you?"
-- "Can this be a 1-file change instead of a system?"
-- "Does this need a new abstraction, or can the existing pattern absorb it?"
+Resolve repository-, DAG-, environment-, and tool-discoverable facts before asking the user. Read established patterns and settled architecture or decision knowledge so you do not ask the user to locate files, recite current behavior, or relitigate prior calls.
 
-Always propose the brutal minimum first. Let the user argue for more.
+Use `arcs knowledge search <slug> "<topic-keywords>" --lean --json` for relevant decisions, patterns, and architecture. Reads are evidence gathering only.
 
-## YAGNI Enforcement (Non-Negotiable)
+### DECISION_LOOP
 
-| Signal | Response |
-|--------|----------|
-| "We might need X later" | "What's the concrete trigger? Until it fires, we don't build it." |
-| "Let's make it configurable" | "How many configs exist today? If 1, hardcode it." |
-| "Add a plugin/hook system" | "Name 2 plugins that exist right now. If you can't, no." |
-| "Generic interface for future use" | "1 consumer = no interface. Inline it." |
-| "Let's plan for scale" | "What's current load? Solve for 10x of that, nothing more." |
-| User adds scope during discussion | "That's a separate request. Finish this one minimal first." |
+Maintain a finite list of unresolved material user-owned decisions. A decision is material when different answers alter externally visible behavior, scope, acceptance, irreversible choices, security/privacy posture, or a load-bearing trade-off.
 
-**Do not soften these.** State them flat. The user can override with justification, but they must explicitly argue past you.
+- Ask one coupled material user-owned decision at a time, with a recommended answer and concise trade-off.
+- Accept multiple answers when the user volunteers them; do not ask them again.
+- Batch only independent factual confirmations when a tool cannot resolve them.
+- Choose trivial, reversible implementation details from existing conventions without consuming a user turn.
+- Do not ask a question merely to demonstrate challenge. If no material user-owned decision remains, proceed.
 
-## Best Practices — Force Them
+The explicit completion predicate is satisfied only when all five are known: **goal, scope, non-goals, acceptance criterion, and all material decisions**. Stop questioning immediately when the completion predicate is satisfied.
 
-When the user's approach conflicts with established patterns, **don't ask if they want best practices — enforce them:**
+### DESIGN_DRAFT
 
-- **Existing codebase patterns win.** If the repo does X one way, new code does it the same way. No "let's also refactor while we're here."
-- **Separation of concerns.** One thing per unit. If a proposal mixes responsibilities, split it before designing.
-- **Testability first.** If a design can't be tested in isolation, reject it. "How do you test this without spinning up the whole system?"
-- **Explicit over implicit.** If behavior is hidden behind magic (auto-detection, convention-over-configuration chains), make it explicit.
-- **Reversibility.** Prefer changes that are easy to undo. Flag irreversible decisions loudly.
+Present one minimal design, scaled to the problem. Include:
 
-## Q&A Rhythm
+- one-sentence goal and done criterion;
+- in-scope and non-goals;
+- behavior and boundaries;
+- affected surfaces at design-level precision;
+- load-bearing decisions, constraints, and trade-offs;
+- test or verification strategy.
 
-- **One challenge per message** — focused, pointed, impossible to dodge
-- **Multiple choice when forcing a decision** — 2-3 options, each with clear trade-off stated
-- **Cut scope aggressively**: if request describes multiple independent concerns, split immediately. "That's 3 separate things. Which one is blocking you right now?"
-- No open-ended "what do you think?" — always propose a position and let user argue against it
-- When the user explicitly requests a grill, or an ordinary challenge leaves a material decision unresolved, investigate environment- or tool-discoverable facts before asking the user. Then ask exactly one user-owned decision at a time, with a recommended default.
+Do not include a plan, task decomposition, execution diagram, implementation steps, or persistence commands. The design may describe a visual interaction, but it is not an agentic execution map.
 
-## Design Presentation
+### WAITING_FOR_DESIGN_APPROVAL
 
-When the request survives the challenge protocol:
+Ask the current user to approve or revise the presented design. Design approval means only that `writing-plans` may draft authoring artifacts; it is not authorization to persist a plan, tasks, a diagram, or knowledge.
 
-- **One approach, not three.** Present the minimal viable design. If the user wants alternatives, they'll ask.
-- State constraints and trade-offs up front — what this design gives up, what it can't do, where it'll hurt if scope grows.
-- Cover only what's needed: affected files, behavior change, test strategy. No boilerplate sections.
-- Scale each section to its complexity (1 sentence → 200 words max). Don't pad.
+If the user requests a material design change, return to `DECISION_LOOP`, revise the design, and request approval of the new design. If the user approves, hand the exact approved design to `writing-plans`.
 
-## Diagram Creation
+## Scope Discipline
 
-<HARD-GATE>
-A plan diagram MUST be generated and presented before proceeding to storage. Draft in memory or `/tmp` — never write to DAG before the user confirms the design.
-</HARD-GATE>
+Apply YAGNI against concrete evidence:
 
-- Load the `to-diagram` skill before generating any diagram content.
-- Use `flowchart TD` for task/dependency graphs; `stateDiagram-v2` for lifecycles
-- All nodes start `:::backlog`, stable IDs (`T001`, `T002`, ...)
-- Persist only after user confirms
-
-## Storage
-
-```bash
-arcs plan create <slug> --title="YYYY-MM-DD <topic> Design" --summary="..." --status=proposed --keywords="spec,design" --body="<markdown>" --json
-```
-
-When creating tasks from the plan, wire execution order with `--dependsOn=dep-task-id-1,dep-task-id-2`. The `dependsOn` graph determines what `arcs next` returns — priority is a tiebreaker within the same topological level.
-
-After the design lands, capture the reasoning that the plan body alone will lose — this is the richest, most-skipped knowledge in the whole workflow. For each load-bearing DECISION and each REJECTED ALTERNATIVE (with the rationale for rejection), emit/run an upsert: `arcs knowledge upsert <slug> "<decision title>" --kind=decision --summary="<what was decided and why; what was rejected and why>" --keywords="<k1,k2>" --source-files="<path[:anchor],...>" --json`. Upsert is idempotent by title, so no dedup search is needed. (When the orchestrator drives this skill, emit the upsert command for it to run; standalone with bash, run it directly.)
+| Signal | Response |
+|--------|----------|
+| Hypothetical future need | Defer until a named trigger occurs |
+| Configuration with one current value | Keep the value local unless variability is required now |
+| Generic interface with one consumer | Use the existing concrete pattern |
+| Unrelated cleanup | Exclude it from scope |
+| Multiple independent outcomes | Separate them and identify which outcome is currently required |
 
-After storage: _"Spec saved to plan `<planId>`. Review it. Push back if anything's wrong."_
+Existing codebase patterns win unless the approved goal requires changing them. Prefer reversible choices. Never simplify away security, accessibility, validation, or data-loss prevention.
 
 ## Visual Companion
 
-Browser-based companion for mockups/diagrams. Offer once when visual questions are anticipated:
+Browser-based companion for mockups and visual design questions. Offer once when seeing is materially clearer than reading:
 
 > "This might be easier to show visually. Want a browser companion?"
 
-- This offer MUST be its own message (no other content)
-- Per-question: use browser only when **seeing** beats **reading**
-- If accepted, read `skills/brainstorming/visual-companion.md`
+- This offer must be its own message with no other content.
+- Use the browser only for questions where seeing beats reading.
+- If accepted, read `skills/brainstorming/visual-companion.md`.
+- A visual companion is exploratory design evidence, not a plan diagram or durable artifact.
+
+## Exit
+
+Exit only with either:
 
-## Constraints
+1. a specifically identified unresolved material user-owned decision; or
+2. an exact approved design handed to `writing-plans`.
 
-- The ONLY next skill after brainstorming is `writing-plans` — never implementation skills
-- Every project needs a design, no matter how "simple"
-- One challenge per message, multiple choice when forcing decisions
-- YAGNI is not a suggestion — it's a hard filter. Every feature must justify its existence NOW.
-- Existing codebases: explore first, follow patterns, don't propose unrelated refactoring
-- **Never agree easily.** If the user's first description is accepted without pushback, you failed. There's always something to clarify, trim, or ground.
+Never imply that brainstorming must always ask something. Finite completion is the objective.

package/opencode/arcs/skills/brainstorming/scripts/server.js

@@ -1,7 +1,10 @@
-const crypto = require('crypto');
-const http = require('http');
-const fs = require('fs');
-const path = require('path');
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 // ========== WebSocket Protocol (RFC 6455) ==========
 
@@ -79,6 +82,24 @@ const URL_HOST = process.env.BRAINSTORM_URL_HOST || (HOST === '127.0.0.1' ? 'loc
 const SCREEN_DIR = process.env.BRAINSTORM_DIR || '/tmp/brainstorm';
 const OWNER_PID = process.env.BRAINSTORM_OWNER_PID ? Number(process.env.BRAINSTORM_OWNER_PID) : null;
 
+function isLiteralBindLoopback(host) {
+  return host === '127.0.0.1';
+}
+
+function isLoopbackUrlHost(host) {
+  return host === '127.0.0.1' || host === 'localhost';
+}
+
+if (!isLiteralBindLoopback(HOST)) {
+  console.error('Brainstorm server bind host must be a literal loopback address.');
+  process.exit(1);
+}
+
+if (!isLoopbackUrlHost(URL_HOST)) {
+  console.error('Brainstorm server URL host must be loopback-only.');
+  process.exit(1);
+}
+
 const MIME_TYPES = {
   '.html': 'text/html', '.css': 'text/css', '.js': 'application/javascript',
   '.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg',
@@ -295,7 +316,10 @@ function startServer() {
   });
   watcher.on('error', (err) => console.error('fs.watch error:', err.message));
 
+  let shuttingDown = false;
   function shutdown(reason) {
+    if (shuttingDown) return;
+    shuttingDown = true;
     console.log(JSON.stringify({ type: 'server-stopped', reason }));
     const infoFile = path.join(SCREEN_DIR, '.server-info');
     if (fs.existsSync(infoFile)) fs.unlinkSync(infoFile);
@@ -320,10 +344,15 @@ function startServer() {
   }, 60 * 1000);
   lifecycleCheck.unref();
 
+  process.once('SIGINT', () => shutdown('SIGINT'));
+  process.once('SIGTERM', () => shutdown('SIGTERM'));
+
   server.listen(PORT, HOST, () => {
+    const address = server.address();
+    const port = typeof address === 'object' && address ? address.port : Number(PORT);
     const info = JSON.stringify({
-      type: 'server-started', port: Number(PORT), host: HOST,
-      url_host: URL_HOST, url: 'http://' + URL_HOST + ':' + PORT,
+      type: 'server-started', port, host: HOST,
+      url_host: URL_HOST, url: 'http://' + URL_HOST + ':' + port,
       screen_dir: SCREEN_DIR
     });
     console.log(info);
@@ -331,8 +360,6 @@ function startServer() {
   });
 }
 
-if (require.main === module) {
-  startServer();
-}
+startServer();
 
-module.exports = { computeAcceptKey, encodeFrame, decodeFrame, OPCODES };
+export { computeAcceptKey, decodeFrame, encodeFrame, OPCODES };

package/opencode/arcs/skills/brainstorming/scripts/start-server.sh

@@ -8,9 +8,8 @@
 # Options:
 #   --project-dir <path>  Store session files under <path>/.superpowers/brainstorm/
 #                         instead of /tmp. Files persist after server stops.
-#   --host <bind-host>    Host/interface to bind (default: 127.0.0.1).
-#                         Use 0.0.0.0 in remote/containerized environments.
-#   --url-host <host>     Hostname shown in returned URL JSON.
+#   --host <bind-host>    Loopback host/interface to bind (default: 127.0.0.1).
+#   --url-host <host>     Loopback hostname shown in returned URL JSON.
 #   --foreground          Run server in the current terminal (no backgrounding).
 #   --background          Force background mode (overrides Codex auto-foreground).
 
@@ -51,6 +50,19 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
+is_literal_bind_loopback() {
+  [[ "$1" == "127.0.0.1" ]]
+}
+
+is_loopback_url_host() {
+  [[ "$1" == "127.0.0.1" || "$1" == "localhost" ]]
+}
+
+if ! is_literal_bind_loopback "$BIND_HOST"; then
+  echo "{\"error\": \"Brainstorm server bind host must be a literal loopback address: $BIND_HOST\"}"
+  exit 1
+fi
+
 if [[ -z "$URL_HOST" ]]; then
   if [[ "$BIND_HOST" == "127.0.0.1" || "$BIND_HOST" == "localhost" ]]; then
     URL_HOST="localhost"
@@ -59,6 +71,11 @@ if [[ -z "$URL_HOST" ]]; then
   fi
 fi
 
+if ! is_loopback_url_host "$URL_HOST"; then
+  echo "{\"error\": \"Brainstorm server URL host must be loopback-only: $URL_HOST\"}"
+  exit 1
+fi
+
 # Some environments reap detached/background processes. Auto-foreground when detected.
 if [[ -n "${CODEX_CI:-}" && "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "true" ]]; then
   FOREGROUND="true"

package/opencode/arcs/skills/brainstorming/scripts/stop-server.sh

@@ -2,8 +2,8 @@
 # Stop the brainstorm server and clean up
 # Usage: stop-server.sh <screen_dir>
 #
-# Kills the server process. Only deletes session directory if it's
-# under /tmp (ephemeral). Persistent directories (.superpowers/) are
+# Kills the server process. Only deletes generated /tmp/brainstorm-* session
+# roots. Persistent generated directories (.superpowers/) are
 # kept so mockups can be reviewed later.
 
 SCREEN_DIR="$1"
@@ -13,16 +13,35 @@ if [[ -z "$SCREEN_DIR" ]]; then
   exit 1
 fi
 
-PID_FILE="${SCREEN_DIR}/.server.pid"
+if [[ "$SCREEN_DIR" != /* || "$SCREEN_DIR" =~ (^|/)\.\.(/|$) ]]; then
+  echo '{"error": "Invalid brainstorm session root"}'
+  exit 1
+fi
+
+CANONICAL_DIR="$(realpath -- "$SCREEN_DIR" 2>/dev/null)"
+if [[ -z "$CANONICAL_DIR" ]]; then
+  echo '{"error": "Brainstorm session root does not exist"}'
+  exit 1
+fi
+
+EPHEMERAL="false"
+if [[ "$CANONICAL_DIR" =~ ^/tmp/brainstorm-[0-9]+-[0-9]+$ ]]; then
+  EPHEMERAL="true"
+elif [[ ! "$CANONICAL_DIR" =~ ^/.+/\.superpowers/brainstorm/[0-9]+-[0-9]+$ ]]; then
+  echo '{"error": "Refusing non-generated brainstorm session root"}'
+  exit 1
+fi
+
+PID_FILE="${CANONICAL_DIR}/.server.pid"
 
 if [[ -f "$PID_FILE" ]]; then
   pid=$(cat "$PID_FILE")
   kill "$pid" 2>/dev/null
-  rm -f "$PID_FILE" "${SCREEN_DIR}/.server.log"
+  rm -f "$PID_FILE" "${CANONICAL_DIR}/.server.log"
 
   # Only delete ephemeral /tmp directories
-  if [[ "$SCREEN_DIR" == /tmp/* ]]; then
-    rm -rf "$SCREEN_DIR"
+  if [[ "$EPHEMERAL" == "true" ]]; then
+    rm -rf -- "$CANONICAL_DIR"
   fi
 
   echo '{"status": "stopped"}'

package/opencode/arcs/skills/brainstorming/visual-companion.md

@@ -2,6 +2,8 @@
 
 Browser-based visual brainstorming companion for showing mockups, diagrams, and options.
 
+The companion is loopback-only: it serves the local browser on the same machine and rejects non-loopback host configuration.
+
 ## When to Use
 
 Decide per-question, not per-session. The test: **would the user understand this better by seeing it than reading it?**
@@ -70,16 +72,7 @@ scripts/start-server.sh --project-dir /path/to/project --foreground
 
 **Other environments:** The server must keep running in the background across conversation turns. If your environment reaps detached processes, use `--foreground` and launch the command with your platform's background execution mechanism.
 
-If the URL is unreachable from your browser (common in remote/containerized setups), bind a non-loopback host:
-
-```bash
-scripts/start-server.sh \
-  --project-dir /path/to/project \
-  --host 0.0.0.0 \
-  --url-host localhost
-```
-
-Use `--url-host` to control what hostname is printed in the returned URL JSON.
+`--host` and `--url-host` accept loopback names and addresses only. Remote/container port exposure is intentionally unsupported.
 
 ## The Loop
 

package/opencode/arcs/skills/deep-pr-review/SKILL.md

@@ -9,7 +9,7 @@ description: Use when the user provides a GitHub PR link with a "deep review" tr
 
 User gives a GitHub PR URL plus a "deep review" trigger inside the locally cloned repo of that PR. Reviewer-side workflow: read-only by default, posts to GitHub only after explicit user gate.
 
-> CLI: `arcs --commands --json` for discovery. Posting is user-gated. ARCS writes (optional knowledge harvest) run directly via the CLI.
+> CLI: `arcs --commands --json` for discovery. Posting is user-gated. Knowledge is proposal-only unless the user separately and explicitly authorizes that exact ARCS write.
 
 ## Flow
 
@@ -84,7 +84,7 @@ Agent picks dimensions from diff context. **Correctness is always evaluated.** O
 | **SOLID** | Module gains responsibilities, dependency direction shifts, large classes touched |
 | **Convention fit** | AGENTS.md or DAG `pattern`/`architecture` knowledge applies to changed files |
 | **Architectural risk** → handoff to the tech-architect agent (structural audit) | Diff crosses module boundaries, touches god nodes, changes public API |
-| **Performance risk** → handoff to the oncall-ops agent (performance investigation) | Hot paths, loops over external IO, new queries, allocations in render |
+| **Performance/incident risk** → handoff to the software-engineer agent in incident mode with systematic-debugging | Hot paths, loops over external IO, new queries, allocations in render |
 
 Skipped dimensions are reported as `cleared (not applicable: <reason>)`. Never silently dropped.
 
@@ -106,7 +106,7 @@ Format: `L<line>: <tag> <what>. <replacement>.` — use `<file>:L<line>: ...` fo
 
 End with the only metric that matters: `net: -<N> lines, -<M> deps possible.` Nothing to cut → `Lean already. Ship.`
 
-Boundary: never flag the single ONE-runnable-check that `the-ladder` requires for non-trivial logic as bloat.
+Boundary: never flag the single runnable check that implementation minimalism requires for non-trivial logic as bloat.
 
 ## Severity Prefixes
 
@@ -184,7 +184,7 @@ gh api POST /repos/{owner}/{repo}/pulls/{number}/reviews \
 
 ## Knowledge Proposals (standard report output)
 
-A recurring finding — the same class of bug, the same convention violation, a trap seen more than once across the diff — is durable knowledge, not just a one-off comment. Make proposing it a standard part of the report, not an afterthought: for each recurring finding, include a proposed `arcs knowledge upsert <slug> "<title>" --kind=<pattern|gotcha> --summary="<the recurring issue and the fix convention>" --keywords="<k1,k2>" --source-files="<path,...>" --json` in the report. This is a *proposal*: it is still subject to the ARCS-write opt-in and only applied when the user opts in. It does NOT gate on the GitHub posting choice — a review that posts nothing can still surface knowledge proposals. Upsert is idempotent by title.
+A recurring finding — the same class of bug, the same convention violation, a trap seen more than once across the diff — is durable knowledge, not just a one-off comment. Make proposing it a standard part of the report, not an afterthought. First use `arcs knowledge template --kind=<kind> --json`; then include a proposed `arcs knowledge upsert <slug> "<title>" --kind=<pattern|gotcha> --summary="<the recurring issue and the fix convention>" --body="<substantive filled template>" --keywords="<k1,k2>" --source-files="<path,...>" --json` in the report. Do not execute `arcs knowledge upsert` without explicit user authorization for that exact command. This opt-in is separate from the GitHub posting choice: a review that posts nothing can still surface knowledge proposals. Upsert is idempotent by title.
 
 ## Report Structure
 
@@ -210,7 +210,7 @@ A recurring finding — the same class of bug, the same convention violation, a
 - Cite every finding — no uncited claims
 - ` ```suggestion ` blocks only for small line-replacement fixes
 - Defer to the tech-architect agent (structural audit) for full structural drift; surface as handoff flag, do not run inline
-- Defer to the oncall-ops agent (performance investigation) for perf work; surface as risk flag
+- Defer performance or incident investigation to the software-engineer agent with `AGENT_MODE: incident` and mandatory systematic-debugging; surface as a risk flag
 - Review dimensions are defined in this skill (Adaptive Rubric); inline findings use the one-line format `<file>:L<line>: problem. fix.` — do not duplicate
 - Re-review detection: if AI has reviewed before, scope to diff since last review's commit_id
 - Tag each posted suggestion with `<!-- arcs:deep-review:<finding-id> -->` for re-review tracking

package/opencode/arcs/skills/deep-pr-review/review-template.md

@@ -26,7 +26,7 @@ Used as the `body` field of `gh api repos/{owner}/{repo}/pulls/{pull_number}/rev
 ### Architectural / Performance Handoffs
 <only if any; otherwise omit section>
 - [tech-architect] <reason — e.g. crosses 3 modules, touches god node X>
-- [oncall-ops] <reason — e.g. new query in render path>
+- [software-engineer, AGENT_MODE: incident, systematic-debugging] <reason — e.g. new query in render path>
 
 ### Citations Used
 - AGENTS.md §<section> — <what was checked>

package/opencode/arcs/skills/enriching-codegraph-proposals/SKILL.md

@@ -13,7 +13,7 @@ The CLI surfaced raw codegraph proposals and is waiting for an agent to turn the
 - `arcs codegraph-sync` returned `pending_enrichment: true`.
 - User said "enrich the proposals", "process the codegraph queue", "promote the pending proposals", or similar.
 
-> **Read-write skill.** This skill mutates the DAG via `arcs proposal promote/drop`. Before each promote, meet an evidence threshold: verify the proposal's structural facts, dedup candidates, natural kind, and source files support the authored entry. If that evidence is incomplete, drop or defer it; the orchestrator/devil-advocate gate independently checks the resulting workflow.
+> **Read-only proposal skill.** This skill reads the queue, reaches verdicts only after the evidence threshold below is met, and returns exact commands under `PROPOSED_MUTATIONS:`. It does not execute `arcs proposal promote/drop` or `arcs knowledge upsert`; the orchestrator applies approved mutations.
 
 ## Flow
 
@@ -27,12 +27,12 @@ flowchart TD
     B -->|No| C[Pick highest-degree proposal]
     C --> D[Read structuralFacts + suggestedDedupCandidates]
     D --> E{Verdict}:::decision
-    E -->|drop| F[arcs proposal drop slug id --reason='...']
+    E -->|drop| F[Propose drop command + reason]
     E -->|keep| G[Author title + summary + body]
     E -->|merge| H[Identify dedup target id]
     H --> I[Author append-style body]
-    I --> J[arcs proposal promote slug id --merge-with=target ...]
-    G --> K[arcs proposal promote slug id ...]
+    I --> J[Propose merge command]
+    G --> K[Propose promote command]
     F --> L{Budget left?}
     J --> L
     K --> L
@@ -57,7 +57,7 @@ Promote as a fresh knowledge entry when ALL of:
 
 ### Drop
 
-Reject the proposal (use `arcs proposal drop`) when ANY of:
+Propose `arcs proposal drop` when ANY of:
 
 - `structuralFacts.fileTypeBreakdown` has zero code (all `.md`, `.mdx`, `.txt`, `.html` templates, skill files). T007 should already filter these — drop is defense-in-depth.
 - Cluster covers test directories only (`test/`, `__tests__/`, `*.test.ts`, `*.spec.ts`, `tests/`).
@@ -70,7 +70,7 @@ Always pass a `--reason` string. The reason is durable on the proposal-store led
 
 ### Merge
 
-Use `arcs proposal promote --merge-with=<existing-id>` when:
+Propose `arcs proposal promote --merge-with=<existing-id>` when:
 
 - `suggestedDedupCandidates` lists an existing knowledge entry whose `kind` matches the proposal's natural kind, AND
 - The proposal adds genuinely new structural facts the existing entry does not already document (e.g. precise degree numbers, additional top hubs, cross-module edges, fileCount).
@@ -113,17 +113,17 @@ Always pass `--source-files` listing the files in `structuralFacts.fileList` (or
 
 - **Cap at 12 enrichments per session.** If proposals list exceeds 12, drop low-signal entries en masse before enriching the keep set.
 - **Process highest-degree clusters first.** Sort proposals by `structuralFacts.degree` descending; the top 3–5 carry most of the value.
-- **Bulk drop early.** A single triage pass over all proposals — calling `arcs proposal drop` on obvious noise — is cheaper than enriching one and discovering the next is also noise.
+- **Bulk-triage early.** Proposing drops for obvious noise in one pass is cheaper than enriching one and discovering the next is also noise.
 - **Stop early on budget.** If the agent has spent ~12 enrichments, drop the remainder with reason `"session budget exhausted; reconsider next sync"` rather than producing rushed entries.
 
 ## Failure Modes
 
 | Symptom                                                   | Recovery                                                                                       |
 |-----------------------------------------------------------|------------------------------------------------------------------------------------------------|
-| `promote --merge-with=<id>` fails: target doesn't exist   | Drop the merge plan; re-run as a fresh `promote` (no `--merge-with`).                          |
+| Proposed merge target no longer exists at apply time     | Orchestrator rejects it; return for re-audit rather than changing the command during apply.    |
 | Body too long for shell argv (errno E2BIG / argv overflow)| Switch to `--body-file=path/to/body.md` or pipe via `--body-stdin`.                            |
-| `proposal_not_found` on promote/drop                      | Another agent already handled it. Skip and continue — proposal-store lock is first-come-first-serve. |
-| Promote succeeds but knowledge graph misses the edge      | Verify `--source-files` was passed and points at real paths under the project root.            |
+| Proposal disappears before return                         | Re-list read-only, omit it, and report the race.                                                |
+| Proposed entry would miss graph edges                     | Verify `--source-files` is present and points at real paths under the project root.             |
 | `structuralFacts` field absent                            | Treat as drop candidate — proposal has no evidence to enrich from.                             |
 | Verdict drift: same proposal triaged twice in one session | Re-list with `arcs proposal list --json` — the store is the single source of truth.            |
 
@@ -132,8 +132,8 @@ Always pass `--source-files` listing the files in `structuralFacts.fileList` (or
 - **Do not invent structural facts** not present in `structuralFacts`. If real-code grounding is needed, defer to `arcs context <slug> --audience=<role>` or `arcs related <slug> <id>` and read source. Hallucinated graph facts poison every downstream retrieval.
 - **Always specify `--source-files`** on promote — graph-retrieval depends on it (per AGENTS.md "Knowledge gravity"). An entry without source files is a leaf with no inbound edges.
 - **Never edit `.mmd` files** directly — diagram ownership rules in AGENTS.md still apply during enrichment.
-- **No batch promote.** Each promote is one decision, one `arcs proposal promote` call. Bulk-promoting via `arcs batch` bypasses dedup checks and per-proposal review.
-- **Preserve proposal IDs in commit messages / summaries** when reporting back so the human can audit the verdict ledger.
+- **No batch promote.** Each proposed promote is one decision and one command. Bulk promotion bypasses dedup checks and per-proposal review.
+- **Preserve proposal IDs in summaries** when reporting back so the human can audit the verdict ledger.
 
 ## Worked Example
 
@@ -141,11 +141,11 @@ Always pass `--source-files` listing the files in `structuralFacts.fileList` (or
 # 1. List pending proposals (highest-degree first by default)
 arcs proposal list arcs --json
 
-# 2. Drop obvious noise in bulk
+# 2. PROPOSED_MUTATIONS: drop obvious noise
 arcs proposal drop arcs prop_test_dirs_only \
   --reason="cluster covers test/ only — defense in depth past T007 filter" --json
 
-# 3. Promote a keep verdict with full enrichment
+# 3. PROPOSED_MUTATIONS: promote a keep verdict with full enrichment
 arcs proposal promote arcs prop_storage_hub \
   --title="Storage hub re-exporting helpers to all persistent stores" \
   --summary="Central re-export point for nowISO and sanitizeFileRefs used by task/plan/knowledge stores; edits ripple through every persistent surface." \
@@ -154,17 +154,16 @@ arcs proposal promote arcs prop_storage_hub \
   --source-files=src/utils/storage-utils.ts,src/utils/task-store.ts,src/utils/plan-store.ts,src/utils/knowledge-store.ts \
   --json
 
-# 4. Merge into an existing entry
+# 4. PROPOSED_MUTATIONS: merge into an existing entry
 arcs proposal promote arcs prop_cli_registry \
   --merge-with=cli-registry-pattern-handlers-typed-via-parsedparams \
   --body-file=/tmp/cli-registry-graph-evidence.md \
   --source-files=src/cli/command-registry.ts,src/cli/index.ts \
   --json
 
-# 5. Confirm queue drained
-arcs proposal list arcs --json   # expect data.proposals == []
+# Return these commands without executing them; the orchestrator applies approved mutations.
 ```
 
 ## Exit
 
-When `arcs proposal list <slug> --json` returns an empty `proposals` array, the enrichment pass is done. Surface a one-line summary to the orchestrator: kept N, merged M, dropped K, deferred D.
+Return `PROPOSED_MUTATIONS:` with one stable proposal ID, verdict, rationale, and exact command per item. Do not execute `arcs knowledge upsert` or proposal mutations. Surface a one-line summary to the orchestrator: proposed keeps N, merges M, drops K, deferred D.