opencode-codeops 1.7.1 → 1.8.1

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 All notable changes to CodeOps are recorded here.
 
+## 1.8.1 — 2026-10-04
+
+### Documentation
+
+- agents: refresh project guidance with specialist facts
+- plan: record ST-43 and final verification evidence
+- plan: add ST-44 for the ask-and-create acceptance path
+- plan: record ST-34 dispatch acceptance evidence
+
+### Fixes
+
+- test: broaden availability regression guard per re-review
+- docs: complete AR #27 availability correction per phase-4 review
+- docs: correct specialist availability per ST-35 observation
+
+## 1.8.0 — 2026-10-04
+
+### Documentation
+
+- readme: document project specialists
+- skills: wire specialist agents into planning and execution
+- specialist-agents: add canonical protocol and content spec tests
+- plan: add specialist-agents plan set and roadmap
+
+### Fixes
+
+- installer: refuse a symlinked codeops parent in migration
+- installer: harden removal and migration per phase-3 review
+- installer: harden specialist generation per phase-2 review
+- test: strengthen specialist content oracle per phase-1 review
+
+### Features
+
+- installer: add migration guard and lifecycle coverage
+- installer: add specialist check, removal, and AGENTS.md sync
+- installer: generate specialist agents from project briefs
+
+### Tests
+
+- installer: lock the routing sandbox enum per re-review observation
+- installer: cover sanitizer fixed point and parser edge cases
+
 ## 1.7.1 — 2026-09-24
 
 ### Fixes

package/README.md

@@ -151,6 +151,37 @@ To pin specific models per role, use the `setup-routing` skill or add overrides
 }
 ```
 
+## Project specialists
+
+CodeOps can recommend project-specific specialist subagents when repository evidence shows a
+capability gap the twelve catalog roles and dynamic packets cannot close. Specialists are created
+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.
+- **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
+  `--sync-agents-md`.
+- **Route** — a plan's `## Specialist Agents` table maps roles to phases. During `exec-plan`,
+  listed specialists are dispatched as **additional** reviewers or executors: they never replace a
+  required reviewer or gate, reviewer findings use the `SR-NNN` prefix, and the generated agent
+  defaults to `reasoningEffort: max` (override it with `routing.roles.<role>.reasoning`).
+- **Fallback** — a specialist is available as soon as its generated agent exists; OpenCode's
+  discovery timing is whatever your build provides. If it is missing, invalid, or a dispatch fails,
+  dispatch falls back to a generic subagent carrying the brief excerpt and reports the fallback.
+  No review depends on a specialist existing.
+
+Lifecycle checks: `--check` reports `INVALID`, `MISSING`, `STALE`, `ORPHAN`, `HAND-AUTHORED`, and
+`AGENTS.md` states; `--remove-custom <role> --yes` deletes the generated agent and its brief and
+updates the index.
+
+> **Upgrading:** specialist agents embed the generic template contract. When a newer plugin changes
+> those templates, `--check` reports the agent as `STALE`; re-run
+> `python3 "${CODEOPS_PLUGIN_ROOT}/scripts/install_agents.py" --project . --custom <role>` (then
+> `--sync-agents-md`) to regenerate it.
+
 ## Requirements
 
 - OpenCode (current)

package/_shared/layout-convention.md

@@ -49,6 +49,7 @@ fi
 | Feature roadmap | `plans/00-roadmap.md` | `codeops/features/<f>/00-roadmap.md` |
 | Portfolio roadmap | *(n/a)* | `codeops/00-roadmap.md` |
 | Staged AGENTS.md notes | *(n/a)* | `codeops/features/<f>/AGENTS.notes.md` |
+| Specialist briefs | `codeops/specialists/<role>.md` (project-level) | `codeops/specialists/<role>.md` (project-level) |
 | Ambiguity register | `requirements/00-ambiguity-register.md` or `plans/<plan>/00-ambiguity-register.md` | the same file, under the feature |
 | Scope-expansion register | See the target-qualified rules below | the same target-qualified filename, under the feature |
 | Task mini-plan | `plans/<task-slug>/99-execution-plan.md` | `codeops/features/<f>/plans/<task-slug>/99-execution-plan.md` |
@@ -58,6 +59,10 @@ In nested layout, a feature's inner directories are created **lazily** — only
 feature's first RD, plan, or task is written. The marker and the (possibly empty) portfolio
 roadmap are the only things `setup-codeops` creates up front.
 
+Specialist briefs are **project-level in both layouts**: a specialist describes a project-wide
+domain or capability, so it is never scoped to one feature. The flat-to-nested migration leaves
+`codeops/specialists/` in place.
+
 ### Scope-expansion register paths
 
 Scope-expansion register paths are collision-free because their authority is scoped to one audit or

package/_shared/quality-profile.md

@@ -13,7 +13,7 @@ Quality and routing configuration lives in `codeops/codeops.json`, validated aga
 configuration.
 
 The quality section controls independent review and stop conditions. The routing section controls
-optional roles, effort, model pins, sandboxes, and concurrency. Domain/risk tags in the active
+optional roles, effort, reasoning, model pins, sandboxes, and concurrency. Domain/risk tags in the active
 specification select additional reviewer roles. Outcome metrics are disabled unless
 `metrics.enabled` is explicitly `true`.
 
@@ -67,9 +67,9 @@ Findings reuse the preflight severity scale **by reference** — 🔴 CRITICAL /
 
 ### Finding prefixes
 
-RV (phase-reviewer) · SA (security-auditor) · PA (preflight-auditor) · PE (perf-auditor), each
-numbered `XX-NNN`. Every finding-producing agent reports "no findings" explicitly rather than
-returning empty output.
+RV (phase-reviewer) · SA (security-auditor) · PA (preflight-auditor) · PE (perf-auditor) ·
+SR (domain-specialist-reviewer), each numbered `XX-NNN`. Every finding-producing agent reports
+"no findings" explicitly rather than returning empty output.
 
 ## Activation & supersession
 
@@ -102,9 +102,20 @@ or response content.
 | plan-task-executor, plan-task-executor-opus | Phase task + Deliverable + Verify lines, governing spec/ST/AR excerpts, original goal + smallest viable design, relevant approved complexity PF/RV excerpts, target paths, scope mode (`strict` or `explore`), confirmed scope baseline, verify command |
 | spec-test-author | Spec excerpts + test cases, planned interface signatures from the plan documents, test framework/conventions, the FORBIDDEN implementation-file list, verify command (expected RED) |
 | preflight-auditor | The artifact under audit + ONE assigned dimension cluster + original goal + smallest viable design + relevant approved complexity AR/PF/RV excerpts + scope mode (`strict` or `explore`) + confirmed scope baseline |
+| domain-specialist-reviewer | Line-1 dispatch header; phase diff; original goal + smallest viable design; phase task + Deliverable lines; active lenses plus the brief's domain checklist; scope mode + confirmed baseline; verify command + last result; the specialist brief excerpt |
+| domain-specialist-executor | Phase task + Deliverable + Verify lines; governing spec/ST/AR excerpts; original goal + smallest viable design; target paths; scope mode + confirmed baseline; verify command; the specialist brief excerpt |
 | design-challenger | Problem + candidate options, **without** the parent's preferred choice (per `_shared/recommendation-hardening.md`) |
 | codebase-scout | The factual questions, search hints, and the facts-only contract |
 
+## Project specialists
+
+A project may define specialist roles on top of the catalog (see `_shared/specialist-agents.md`).
+Specialists resolve like any project agent; routing policy may pin model, effort, sandbox, and
+reasoning, and a generated agent embeds `reasoningEffort` (default `max`). Dispatch only roles
+listed in the plan's `## Specialist Agents` table, as **additional** reviewers or executors — a
+specialist never replaces a required reviewer or gate, and an unavailable or invalid-brief
+specialist falls back to a complete dynamic packet with the fallback reported.
+
 ## Budget caps
 
 - **Preflight fan-out:** ~5 clustered auditor dispatches — an exact partition of the preflight
@@ -117,6 +128,8 @@ or response content.
   diff — never a third pass.
 - **Scout:** ≤3 codebase-scout dispatches per skill run, enforced by the dispatching parent.
 - **Challenger:** caps live in `_shared/recommendation-hardening.md` and apply unchanged.
+- **Specialist dispatch:** limited to the roles listed in the plan's `## Specialist Agents` table;
+  no additional fan-out.
 
 ## Model, effort, and agent resolution
 
@@ -129,6 +142,6 @@ Resolution order is:
 3. project `[agents]` defaults in `opencode.json`;
 4. the parent session's model and effort.
 
-Use `python3 "${CODEOPS_PLUGIN_ROOT}/scripts/install_agents.py" --project . --roles ...` to create optional project agents. Generated agent files carry a CodeOps marker. The installer owns only marked files and preserves every hand-authored file. Use `--check` to detect missing or stale generated agents and `--dry-run` to preview changes.
+Use `python3 "${CODEOPS_PLUGIN_ROOT}/scripts/install_agents.py" --project . --roles ...` to create optional project agents. Generated agent files carry a CodeOps marker. The installer owns only marked files and preserves every hand-authored file. Use `--check` to detect missing or stale generated agents and `--dry-run` to preview changes. Project specialists are generated with `--custom <role>` from `codeops/specialists/<role>.md` and indexed into `AGENTS.md` with `--sync-agents-md`; their routing policy may also set `reasoning`.
 
 Dynamic packets are the correctness baseline. If a named agent is missing or a model pin is unavailable, spawn a generic subagent with the complete packet or run inline. Report the fallback and preserve required reviewer independence, sandbox intent, and every ambiguity/readiness/verification gate.

package/_shared/specialist-agents.md

@@ -0,0 +1,147 @@
+# Specialist Agents (shared convention)
+
+> **CodeOps Artifact Schema**: 1
+
+This is the **single canonical definition** of project-specific specialist subagents: how a
+capability gap is detected, how a candidate is proposed and approved, and how the specialist is
+created, used, and retired. It lives at the plugin root in `_shared/`; the participating skills
+(`make-requirements`, `make-plan`, `analyze-project`, `setup-routing`) link here instead of
+carrying copies. `exec-plan` dispatches per `_shared/quality-profile.md`, which owns the
+dispatch, independence, and fallback rules.
+
+A specialist is a project-local agent that carries durable domain knowledge a generic catalog role
+does not have. Routing is an optimization and a context mechanism, **never a correctness source**.
+Dynamic packets remain the dispatch baseline: a missing or unavailable specialist falls back
+without weakening any gate, reviewer count, or verification step.
+
+## Detection criteria
+
+Run the check after domain-lens selection, when the work's domain and risk profile are known.
+A specialist is warranted only with repository evidence and no disqualifier.
+
+| Strong signal (at least one, evidenced) | Disqualifier (any one blocks) |
+| --------------------------------------- | ----------------------------- |
+| A specialized framework, DSL, codegen, or protocol with non-obvious conventions a generic executor repeatedly rediscovers | A catalog role plus a dynamic packet already covers the need |
+| An active domain lens plus project-specific invariants (regulatory, numerical, protocol, compatibility) checked every phase | One-off use with no recurring value |
+| Repeated review findings or rework in the same area (from existing review evidence) | The specialist would only restate `AGENTS.md`, a lens, or base review lenses |
+| An isolated, large-context capability (migration, compatibility audit) a packet cannot carry well | No unique evidence source, checklist, or capability beyond the base lenses |
+| A project convention that must be enforced across phases and would otherwise be re-examined each time | An executor specialist with no demonstrated write-access need (prefer reviewer) |
+
+Every candidate must name the **smallest alternative** (usually "keep sending the context in each
+packet") and why it is insufficient. Sophistication, future flexibility, and effort already spent
+are not evidence.
+
+## Candidate packet
+
+The candidate is presented to the user as a bounded packet and persisted with the approval
+evidence in the owning requirements or plan ambiguity register as a `Technical (complexity
+escalation)` entry.
+
+| Field | Content |
+| ----- | ------- |
+| Role | Proposed slug (validated: `^[a-z][a-z0-9-]{1,40}$`, not a catalog or built-in name) |
+| Kind | `reviewer` or `executor` |
+| Capability | One line: what it knows or does that no catalog role does |
+| Evidence | Repository facts with `file:line` |
+| Why existing options fail | Catalog-role analysis + why a dynamic packet is insufficient |
+| Smallest alternative | The direct alternative and why it is not enough |
+| Use map | Intended features/phases/tags |
+| Permissions | Read-only (reviewer) or the explicit write need (executor) |
+| Effort / reasoning | Optional overrides; default effort `high`, reasoning `max` |
+| Maintenance cost | Files, upkeep, and review attention |
+| Independent verdict | `Unnecessary` / `Simplify` / `Justified` from a blind `design-challenger` |
+| Direct user decision | `approved` / `rejected` / `deferred` — explicit, never silence |
+
+## Authority and budget
+
+- Creation is **reserved authority**. `--auto-design` may never approve it; only the user's direct
+  choice on the visible Complexity Escalation Gate packet authorizes creation
+  (`_shared/zero-ambiguity-gate.md`).
+- The gate's complete approval evidence (original goal, machinery, evidence, smallest solution,
+  cost, verdict, decision) is persisted in the owning register entry.
+- At most **two** candidates per requirements set or plan, proposed in one batch; candidates are
+  deduplicated against installed project agents and `codeops.json` routing roles.
+- Rejection and deferral are valid outcomes. A rejected candidate may not reappear in the same
+  scope without new evidence.
+
+## Routing layers
+
+| Layer | Owner | Content | Consumer |
+| ----- | ----- | ------- | -------- |
+| `.opencode/agents/<role>.md` description | installer, from the brief | Mandatory when-to-use text | OpenCode model (task list) |
+| `codeops/codeops.json` → `routing.roles.<role>` | `setup-routing` | model / effort / sandbox / reasoning policy | installer + CodeOps skills |
+| `codeops/specialists/<role>.md` | `setup-routing`, user-approved | Capability, scope, evidence, checklist, description | installer + skills |
+| Plan `00-index.md` "Specialist Agents" | `make-plan` | phase → role selection map | `exec-plan` |
+| `AGENTS.md` managed block | `setup-routing` (rendered by `install_agents.py --sync-agents-md`) | Compact index with when-to-use / required-for rules | every project agent |
+
+## Detection integration
+
+### 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.
+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.
+
+### make-plan
+
+1. After re-running lens selection and decomposing phases, run the detection criteria against the
+   phase plan.
+2. Record the outcome in `00-index.md` under `## Specialist Agents`, **always** — including the
+   **negative outcome**:
+
+   ```markdown
+   ## Specialist Agents
+
+   | Role | Kind | Use | AR Ref |
+   | ---- | ---- | --- | ------ |
+   | pg-migration-reviewer | reviewer | Phase 2 (backfill), Phase 3 (cutover) | AR #7 |
+
+   _Detection evidence: db/migrations/0042_backfill.sql requires mixed-version compatibility; no
+   catalog role carries the project's migration ordering rule._
+   ```
+
+   ```markdown
+   ## Specialist Agents
+
+   **None** — the capability-gap check ran against this repository's evidence and found no gap a
+   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.
+
+### 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
+   `AGENTS.md` compact.
+3. Preserve the `<!-- CODEOPS-SPECIALISTS:START -->` / `<!-- CODEOPS-SPECIALISTS:END -->` block
+   byte-for-byte when refreshing managed guidance.
+
+## Lifecycle
+
+| Stage | Action |
+| ----- | ------ |
+| Detect | Skills run the gap check and record outcomes |
+| Propose | Candidate packet + independent verdict + user decision |
+| Create | `setup-routing` drafts the brief, the user reviews it, routing policy is written first, the installer generates the agent, `--sync-agents-md` updates AGENTS.md, and `--check` verifies last |
+| Use | `exec-plan` selects per the plan table; reviewers are additional and independent; fallback on unavailability |
+| Review | Optional guidance: after first use, the user may evaluate benefit against the evidence and keep, revise, or remove the specialist. Not a gate |
+| Retire | `install_agents.py --remove-custom <role> --yes` removes agent + brief after confirmation; `setup-routing` drops the routing policy and the AGENTS.md entry |
+
+## Dispatch and fallback
+
+The authoritative dispatch rules live in `_shared/quality-profile.md` (resolution order, finding
+prefix `SR`, additional-reviewer independence, and dynamic-packet fallback). A specialist
+dispatches only when the plan's `00-index.md` "Specialist Agents" table assigns it to the phase.
+When the agent is unavailable — for example its generated file is missing, its brief is invalid,
+or a dispatch fails — dispatch a generic subagent with the complete packet, including the brief
+excerpt, and report the fallback. The phase is never marked complete unreviewed because a
+specialist was missing.

package/agent-templates/domain-specialist-executor.md

@@ -0,0 +1,20 @@
+You are a project domain specialist executor. The project brief below is embedded into this
+agent at generation time and is your durable source of domain knowledge. You implement exactly
+one dispatched unit — normally a whole phase, occasionally a single task — with that knowledge.
+
+- Implement only what the dispatch packet assigns. Do not expand scope. In strict mode do not
+  report optional additions; in explore mode return optional ideas as separate `SE-*` proposals
+  to the parent, never as implemented changes.
+- Follow the project's `AGENTS.md` for build, test, and verify commands and for code conventions.
+- Never update execution plans, roadmaps, or progress marks; the parent owns those. Never edit a
+  specification test to make it pass — a failing specification test means the implementation is
+  wrong.
+- Run the packet's verify command per task and report pass or fail with the evidence the packet
+  asks for. Keep full verify output out of your report; surface one line on pass and the failure
+  excerpt on fail.
+- Stop and return a blocker report when the packet is missing context, a specification test
+  fails for a reason the packet does not explain, or the work hits an ambiguity. Never guess and
+  never widen your own authority.
+- Never copy plan, requirement, ambiguity-register, or test-case identifiers, or `codeops/`,
+  `plans/`, or `requirements/` paths, into code or doc comments. Those files are ephemeral; keep
+  the behavior and drop the citation.

package/agent-templates/domain-specialist-reviewer.md

@@ -0,0 +1,17 @@
+You are a project domain specialist reviewer. The project brief below is embedded into this
+agent at generation time and is your durable source of domain knowledge. You bring that knowledge
+to a dispatched phase diff as an additional, independent reviewer.
+
+- Stay read-only. Never edit files, fix findings, commit, or run commands that change the
+  worktree; shell access is for inspection only.
+- Review the phase diff against the brief's capability, scope, and domain checklist. Hunt for the
+  domain-specific problems a generic reviewer would miss.
+- Report every finding as a numbered `SR-NNN` entry using the standard severity scale (critical,
+  major, minor). Each finding needs the exact file and line, the concrete risk, and a concrete
+  remedy. State "no findings" explicitly when the diff is clean.
+- Respect the dispatch's scope mode. In strict mode report only necessary corrections; never
+  propose optional additions. In explore mode you may return optional ideas as separate proposals.
+- You are additional: never replace a required reviewer or gate, and never review a phase you
+  implemented.
+- Keep the output terse and structured so the parent can merge it directly: findings first, then
+  explicit open questions, then "no findings" if applicable. Do not restate the diff.

package/package.json

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

package/schemas/codeops-config.schema.json

@@ -39,7 +39,8 @@
             "properties": {
               "model": {"type": "string", "minLength": 1},
               "effort": {"type": "string", "minLength": 1},
-              "sandbox": {"enum": ["read-only", "workspace-write", "danger-full-access"]}
+              "sandbox": {"enum": ["read-only", "workspace-write", "danger-full-access"]},
+              "reasoning": {"enum": ["none", "minimal", "low", "medium", "high", "xhigh", "max"]}
             }
           }
         }

package/scripts/codeops-migrate.sh

@@ -14,6 +14,10 @@
 # means "already migrated"), and applies via `git mv` (history preserved), writing the marker and
 # the seeded portfolio roadmap LAST so an interrupted run never leaves a false "migrated" marker.
 #
+# Existing config: an existing codeops/codeops.json is never overwritten — a valid file is
+# preserved byte-for-byte (the preview prints PRESERVE) and a malformed one refuses the run
+# before any move.
+#
 # Security: never executes repo data; the feature slug is sanitized so it can never escape
 # codeops/features/. All mutation requires an explicit --yes; absent that, it only previews.
 #
@@ -105,6 +109,50 @@ if [[ -e codeops && ! -d codeops ]]; then
   exit 1
 fi
 
+# A symlinked `codeops` would redirect every write and every `git mv` outside the repository.
+# Refuse it before anything moves; `-L` also catches a dangling symlink, which `-e` misses.
+if [[ -L codeops ]]; then
+  printf 'ERROR: `codeops` is a symlink — refusing to migrate through it.\n' >&2
+  printf '       Replace it with a real directory (or remove it), then re-run. Nothing was modified.\n' >&2
+  exit 1
+fi
+
+# Committed symlinks or special files at the written targets would make `cat >`
+# write through the link (or block forever); refuse up front, before any move.
+for target in codeops/codeops.json codeops/.codeops.yml codeops/00-roadmap.md; do
+  if [[ -L "$target" || ( -e "$target" && ! -f "$target" ) ]]; then
+    printf 'ERROR: %s is a symlink or not a regular file — refusing to migrate.\n' "$target" >&2
+    printf '       Replace it with a regular file (or remove it), then re-run. Nothing was modified.\n' >&2
+    exit 1
+  fi
+done
+
+# -----------------------------------------------------------------------------
+# Existing structured config: never overwrite it.
+#
+# `codeops/specialists/` is project-level and survives migration; a specialist
+# brief's routing policy may already live in codeops/codeops.json. A valid file
+# is preserved byte-for-byte (the preview says PRESERVE instead of CREATE) and
+# a malformed one refuses the run before anything moves, so a broken config can
+# never be silently replaced by the seeded defaults.
+# -----------------------------------------------------------------------------
+PRESERVE_CONFIG=0
+if [[ -f codeops/codeops.json ]]; then
+  if [[ "$HAVE_PY3" -eq 1 ]]; then
+    if python3 -c 'import json, sys; json.load(open(sys.argv[1], encoding="utf-8"))' codeops/codeops.json 2>/dev/null; then
+      PRESERVE_CONFIG=1
+    else
+      printf 'ERROR: codeops/codeops.json exists but is not valid JSON — refusing to migrate.\n' >&2
+      printf '       Fix or remove it, then re-run. It was not modified.\n' >&2
+      exit 1
+    fi
+  else
+    # Without python3 the file cannot be validated; preserving it is the only
+    # safe choice (the migration never overwrites an existing config).
+    PRESERVE_CONFIG=1
+  fi
+fi
+
 # -----------------------------------------------------------------------------
 # Derive the feature slug (roadmap header → else repo dir name), then sanitize.
 # -----------------------------------------------------------------------------
@@ -155,6 +203,9 @@ fi
 # Hazard scan → warnings (never block; the user resolves these by hand after the move).
 # -----------------------------------------------------------------------------
 warnings=()
+if [[ "$PRESERVE_CONFIG" -eq 1 ]]; then
+  warnings+=("config-preserved: codeops/codeops.json already exists and is kept byte-for-byte — review it against the seeded defaults")
+fi
 # (a) plan folders on disk but not referenced in the roadmap.
 if [[ -f plans/00-roadmap.md ]]; then
   for d in plans/*/; do
@@ -230,7 +281,11 @@ for m in "${moves[@]}"; do
   printf 'MOVE %s -> %s\n' "${m%%|*}" "${m##*|}"
 done
 printf 'CREATE codeops/.codeops.yml\n'
-printf 'CREATE codeops/codeops.json\n'
+if [[ "$PRESERVE_CONFIG" -eq 1 ]]; then
+  printf 'PRESERVE codeops/codeops.json (existing file kept byte-for-byte)\n'
+else
+  printf 'CREATE codeops/codeops.json\n'
+fi
 printf 'CREATE codeops/00-roadmap.md\n'
 for w in "${warnings[@]:-}"; do
   [[ -n "$w" ]] && printf 'WARN %s\n' "$w"
@@ -294,7 +349,8 @@ find plans requirements -type d -empty -delete 2>/dev/null || true
 integration_branch="$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##')"
 [[ -n "$integration_branch" ]] || integration_branch="$(git symbolic-ref --quiet --short HEAD 2>/dev/null)"
 [[ -n "$integration_branch" ]] || integration_branch="main"
-cat > codeops/codeops.json <<'JSON' || fail_apply "write codeops/codeops.json"
+if [[ "$PRESERVE_CONFIG" -ne 1 ]]; then
+  cat > codeops/codeops.json <<'JSON' || fail_apply "write codeops/codeops.json"
 {
   "schema": 1,
   "mode": "strict",
@@ -307,6 +363,7 @@ cat > codeops/codeops.json <<'JSON' || fail_apply "write codeops/codeops.json"
   "metrics": {"enabled": false}
 }
 JSON
+fi
 # Seeded portfolio roadmap — one row for the migrated feature. The roadmap skill refines the
 # stage/progress on the next /update_roadmap; this is a valid starting point.
 today="$(date '+%Y-%m-%d')"

package/scripts/fixtures/catalog-executor.golden.md

@@ -0,0 +1,59 @@
+# Generated by CodeOps install_agents.py
+# Role: executor | Template: plan-task-executor
+# Do not edit this file manually — regenerate with: install_agents.py
+---
+description: CodeOps plan-task-executor agent
+mode: subagent
+temperature: 0.1
+hidden: true
+permission:
+  read: allow
+  grep: allow
+  glob: allow
+  edit: allow
+  bash: allow
+---
+
+<!-- Agent template: plan-task-executor
+     See agents/ for the OpenCode agent definition files generated from this template.
+     Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
+
+You execute exactly ONE dispatched unit — normally a whole phase, occasionally a single task —
+from a CodeOps execution plan, via a phase packet (the phase's task lines, Deliverables and
+Verify lines, spec excerpts, ST-cases, AR decisions, relevant approved complexity PF/RV decisions,
+original goal, smallest viable design, scope mode, confirmed product scope baseline, target files,
+verify command). Missing or invalid scope context fails closed to strict mode. Missing or invalid
+original-goal or smallest-design context blocks execution; report it to the parent.
+- Follow the project's AGENTS.md for build/test/verify commands and conventions.
+- Work the packet's tasks in order; implement only what it assigns and what the confirmed product
+  scope baseline authorizes — do not expand scope. In strict mode, do not report optional additions.
+  In explore mode, return optional ideas as `SE-*` proposals to the parent; never implement or
+  authorize them.
+- **Documentation ban (non-negotiable).** The packet quotes AR decisions, ST-cases, and spec
+  excerpts for YOUR understanding only — never copy a plan/requirement/AR/RD/ST/PA/task identifier
+  or a `codeops/`/`plans/`/`requirements/` path into a code comment or doc comment. Those files are
+  ephemeral; the shipped code must stand on its own. Keep the behavior a plan note describes, drop
+  the citation, and restate any rationale in plain language.
+- **Documentation gate (non-negotiable).** Before reporting a task done, read the changed code as a
+  junior developer. Document every public/exported class, interface, method, function, property,
+  type, and constant, plus every non-trivial internal entity, in the language's doc-comment format.
+  Cover applicable purpose, parameters, return value, thrown errors, side effects, and invariants.
+  Explain complex logic and non-obvious decisions in calm comments, and add `@example` to public API
+  wherever practical. Do not pad trivial private code with comments that merely restate it.
+  **Missing documentation blocks completion.** Use the project's documentation linter when
+  configured, but also perform this semantic read. Finally, grep your
+  changed files for `\b(RD|AR|PA|PF|HR|GATE|AC|ST|ADR|DEF)-[0-9]` and `(codeops|plans|requirements)/`
+  and fix any hit that landed in a comment.
+- Write/update tests as the plan specifies, then run the verify command with output captured
+  to a temp log — report a PASS one-liner per task, or the last 50 log lines on failure.
+- Never modify a spec test's expectations (`*.spec.test.*`) — if a spec test fails, the
+  implementation is wrong; report it as a blocker instead of changing the test.
+- **Complexity checkpoint.** Before editing each task, compare the intended approach with the
+  original goal, existing patterns, approved complexity decisions, and the smallest viable
+  solution. If it would add a material layer, dependency, harness, framework, infrastructure
+  surface, cross-cutting refactor, or future-proofing without specific approval, STOP and return a
+  Complexity Escalation Gate blocker to the parent. Do not build it or approve it yourself.
+- If the packet is insufficient, or you hit a decision it doesn't cover, STOP and report
+  exactly what is missing or ambiguous as a blocker — never guess, and never edit the
+  execution plan or roadmap (the parent session owns those and the user conversation).
+- Report per task, 3-4 lines each: what changed, test status, any blocker.