opencode-codeops 1.4.0

package/_shared/layout-convention.md

@@ -0,0 +1,198 @@
+# CodeOps Layout Convention (shared reference)
+
+> **CodeOps Artifact Schema**: 1
+
+This is the **single source of truth** for where CodeOps artifacts live. It is a shared
+reference document, **not a skill** — it lives at the **plugin root** in `_shared/` (deliberately
+**outside** `skills/`), so the plugin loader, which treats each `skills/<dir>` as a skill, never
+meets a `SKILL.md`-less directory. Every layout-aware skill (`roadmap`, `make-requirements`,
+`make-plan`, `exec-plan`, `preflight`, `upgrade-plan`, `retro-requirements`, `techdocs`) **links here** (as
+`../../_shared/layout-convention.md`) for path resolution and ID rules instead of hardcoding
+paths. Change the layout in one place: here.
+
+CodeOps supports two layouts. A repo is in exactly one of them, decided by a single marker file.
+
+---
+
+## Detection rule (apply this first, every time)
+
+```
+1. If codeops/.codeops.yml exists AND it declares `codeopsLayout: nested`
+       → NESTED layout. Resolve all artifact paths under codeops/features/<feature>/…
+2. Otherwise (no marker, or a malformed/incomplete marker)
+       → FLAT layout (the pre-3.0.0 behavior, unchanged). Surface a warning if a marker
+         exists but is malformed, then proceed as flat — never crash.
+3. In NESTED layout, <feature> is the target feature, which the skill ASKS the user to
+       confirm/choose — it never silently guesses (see "Feature targeting" below).
+```
+
+Detection is a simple key match so it works without a YAML parser. The canonical check
+(mirroring the JSON/`grep` fallback pattern in `scripts/validate.sh`):
+
+```bash
+if [[ -f codeops/.codeops.yml ]] && grep -Eq '^codeopsLayout:[[:space:]]*nested[[:space:]]*$' codeops/.codeops.yml; then
+  layout=nested
+else
+  layout=flat
+fi
+```
+
+---
+
+## The path map (canonical)
+
+| Concept | Flat layout (marker absent) | Nested layout (marker present) |
+| ------- | --------------------------- | ------------------------------ |
+| Requirements dir | `requirements/` | `codeops/features/<f>/requirements/` |
+| RD document | `requirements/RD-NN-*.md` | `codeops/features/<f>/requirements/RD-NN-*.md` |
+| Plan folder | `plans/<plan>/` | `codeops/features/<f>/plans/<plan>/` |
+| 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` |
+| 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` |
+| Archive | `plans/_archive/<set>/` | `codeops/_archive/<f>/` |
+
+In nested layout, a feature's inner directories are created **lazily** — only when that
+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.
+
+### Scope-expansion register paths
+
+Scope-expansion register paths are collision-free because their authority is scoped to one audit or
+planning target:
+
+| Governed target | Register filename |
+|---|---|
+| Full requirements set, full plan, or plan execution | `00-scope-expansion-register.md` in the governed artifact directory |
+| Single requirement or single plan document | `00-scope-expansion-register-<document-name>.md` in the document directory |
+| Ad-hoc file | `scope-expansion-register-<artifact-name>.md` in the artifact directory |
+| Ad-hoc directory | `scope-expansion-register.md` inside the governed directory |
+
+The shared scope-expansion protocol owns register contents and lifecycle. This layout convention
+owns paths and target identity. `<document-name>` and `<artifact-name>` are the complete existing
+filename, including its extension; for example, `foo.md` and `foo.txt` resolve to different
+registers. Use only the final filename component and reject path separators, `..`, absolute paths,
+or a name that is not the governed target's exact filename. An ad-hoc directory's register lives
+inside that exact directory. Two governed targets must never resolve to the same register unless
+they intentionally share the full-set or full-plan scope baseline.
+
+---
+
+## ID rules
+
+- **RD ids reset per feature.** Within `codeops/features/billing/requirements/` the ids run
+  `RD-01, RD-02, …` independently of every other feature. (In flat layout there is one global
+  RD sequence, as before.)
+- **Cross-feature references are feature-qualified.** A plan's `00-index.md` declares one or more
+  requirements on a single line, for example `> **Implements**: billing/RD-01, billing/RD-02` in
+  nested layout or `> **Implements**: RD-01, RD-02` in flat layout. The roadmap matcher and plan
+  status parser read this line.
+- **Tasks use a separate per-feature sequence** `T-01, T-02, …`, so a task id never collides
+  with an RD id in the same feature. See the task-lane spec for the lightweight task model.
+
+---
+
+## Feature targeting (nested layout)
+
+When a layout-aware skill runs in a nested repo and the target feature is not already implied
+by context (e.g. the plan/RD being operated on), the skill **asks the user which feature** to
+work in, and **creates the feature folder lazily** if it is new. It never guesses.
+
+A new feature folder is `codeops/features/<feature>/` where `<feature>` is a sanitized slug:
+lowercase, words separated by `-`, no path separators, no `..`, never absolute. Reject or
+normalize any candidate that would traverse outside `codeops/features/` (see Error handling).
+
+---
+
+## Archiving (nested layout)
+
+Archiving is **feature-level and manual**: `git mv codeops/features/<f> codeops/_archive/<f>`.
+The portfolio roadmap keeps a compact Archived section — the feature's row is **moved** there
+(📦), not deleted. Never fragment a live feature (don't archive individual plans out of one).
+
+---
+
+## `codeops/.codeops.yml` marker schema
+
+Minimal and flat so it parses trivially. **`setup-codeops` is the sole writer of this file**
+(every other skill must leave it untouched; the `analyze-project` command may *read*
+`integrationBranch`, but never writes here).
+
+```yaml
+# CodeOps layout marker. Presence of this file opts the repo into the nested layout.
+codeopsLayout: nested
+layoutVersion: "3.0.0"
+integrationBranch: master       # branch where features integrate; analyze-project refreshes AGENTS.md here
+conventions:
+  rdIdScope: per-feature        # RD numbering resets per feature
+  taskIdPrefix: "T"             # lightweight task ids: T-01, T-02 …
+  maintenanceFeature: _maintenance
+  archiveDir: codeops/_archive
+```
+
+- Only `codeopsLayout: nested` is **required** for detection; the rest document the conventions
+  and let future versions evolve.
+- `integrationBranch` is **optional** — the branch where feature work integrates and
+  `analyze-project` regenerates `AGENTS.md` (folding in any staged `AGENTS.notes.md`). When absent,
+  `analyze-project` falls back to the repo default branch (`origin/HEAD`, else `main`/`master`), so
+  existing markers keep working. `setup-codeops` should emit it.
+- A committed sample marker lives at `scripts/fixtures/sample.codeops.yml` (used by
+  `validate.sh` ST-16 to assert the schema parses and carries `codeopsLayout`).
+
+---
+
+## Error handling
+
+| Error case | Handling strategy |
+| ---------- | ----------------- |
+| `.codeops.yml` present but malformed / missing `codeopsLayout` | Treat as **flat** (safe default) and surface a warning; do not crash |
+| Marker present but `codeops/features/` missing | Nested layout still selected; the feature dir is created lazily on first write |
+| Feature/slug contains `..`, `/`, or is absolute | Reject — normalize and refuse path-traversal before using it as a path component |
+| Skill cannot determine the target feature | Ask the user; never guess |
+
+---
+
+## Lightweight tasks (the task lane)
+
+Ad-hoc work — a bugfix, chore, or small change — is **not a feature**. It is a lightweight
+**task**, and its ceremony scales with size. This is the single source for the task model; the
+skills (`roadmap`, `make-requirements`, `make-plan`, `exec-plan`) reference it. The lane exists
+in **both layouts** (flat gained it in 3.2.0 — AR #6): nested tasks carry a per-feature `T-NN`
+id; flat tasks are simply a mini-plan folder (a `T-NN` roadmap row too when a roadmap exists).
+
+**Routing — feature or task?**
+
+```
+Is this a new cohesive capability with real requirements?
+  ├─ yes → FEATURE: make-requirements (RD) → make-plan → exec-plan
+  └─ no  → TASK (T-NN):
+            ├─ trivial     → a roadmap row + the commit; NO plan document
+            └─ non-trivial → a single mini-plan, then exec-plan runs it
+```
+If it is genuinely unclear, ask — never silently default to the heavy pipeline.
+
+**Where a task lives**
+
+- *Flat layout* → a mini-plan at `plans/<task-slug>/99-execution-plan.md` (plus a roadmap row if
+  `plans/00-roadmap.md` exists; a trivial task with a roadmap is just the row + commit).
+- *Nested, belongs to a feature* (e.g. a bug in billing) → a `T-NN` row in
+  `codeops/features/billing/00-roadmap.md`.
+- *Nested, standalone / cross-cutting* → a `T-NN` row in `codeops/features/_maintenance/00-roadmap.md`.
+  `_maintenance/` is a **normal feature folder** (same `00-roadmap.md` + `plans/`, rolls up into
+  the portfolio), created **lazily** on the first standalone task. It simply tends to hold tasks
+  rather than RDs.
+
+**Ceremony by size**
+
+- **Trivial** → just a roadmap row + the commit. No plan document.
+- **Non-trivial** → a single mini-plan at the resolved task path (flat:
+  `plans/<task-slug>/99-execution-plan.md`; nested:
+  `codeops/features/<f>/plans/<task-slug>/99-execution-plan.md`) — execution doc only: objective,
+  a short task checklist, and a verify line. **No RD, no 00–07 doc set, no Zero-Ambiguity Gate.**
+
+**Task lifecycle** — a compact subset of the stage machine: `⬜ Backlog → 🔄 Executing → ✅ Done`
+(plus `⛔ Blocked` / `⏸️ Deferred` overlays). Tasks never use the RD/Plan-Preflight stages.
+Specification-first ordering still applies *when a task warrants tests* (e.g. a bugfix gets a
+regression test); a trivial doc/config tweak may not.

package/_shared/quality-profile.md

@@ -0,0 +1,134 @@
+# Quality Profile (shared convention)
+
+> **CodeOps Artifact Schema**: 1
+
+This is the **single canonical definition** of the per-repo quality profile and the quality-agent
+conventions built on it. It lives at the plugin root in `_shared/`; dispatching skills link here
+instead of carrying copies.
+
+## Structured profile
+
+Quality and routing configuration lives in `codeops/codeops.json`, validated against
+`schemas/codeops-config.schema.json`. `AGENTS.md` contains project guidance, not mutable machine
+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
+specification select additional reviewer roles. Outcome metrics are disabled unless
+`metrics.enabled` is explicitly `true`.
+
+### Parsing, absence, and ownership
+
+- Missing quality configuration selects strict CodeOps defaults for planned complex-system work:
+  independent review on, at least one reviewer, and stop on major findings.
+- Invalid structured configuration is a readiness blocker; do not silently discard malformed
+  policy and continue with unknown guarantees.
+- setup-routing proposes and updates structured policy. Hand edits are valid and validated.
+- A missing optional custom agent never disables review; use a complete dynamic packet or inline
+  fallback.
+
+## Taxonomies
+
+### Lens enum (7 — grow-only; renaming or repurposing an existing value is forbidden)
+
+| Lens | Scope (one line) |
+|------|------------------|
+| `correctness` | Logic errors, broken behavior against the spec and tests. **Base.** |
+| `maintainability` | Design-quality judgment calls: clarity, structure, duplication, naming. **Base.** |
+| `standards` | Violations of the always-on written coding standards. **Base-only — never a valid profile add-on.** |
+| `security` | Injection, authorization, secrets handling, unsafe input. Add-on. |
+| `perf` | Hot paths, allocations, algorithmic complexity, blocking I/O. Add-on. |
+| `api-surface` | Public interface design, compatibility, versioning. Add-on. |
+| `concurrency` | Races, locking, ordering — explicitly **owns data-integrity**. Add-on. |
+
+The base lenses `correctness` + `maintainability` + `standards` are always on for every review;
+the profile's `lenses` list names **add-ons only**. Disambiguation: a violation of a written
+standard is `standards`; a design-quality judgment with no written rule behind it is
+`maintainability` — keeping the two distinguishable in findings and outcome evidence.
+
+### security_profile enum (5)
+
+| Profile | Focus |
+|---------|-------|
+| `owasp-web` | Classic web-app risks: injection, XSS, CSRF, broken access control, SSRF |
+| `auth-protocol` | Authentication/session flows: token handling, expiry, replay, fixation |
+| `financial-integrity` | Money movement: idempotency, double-spend, rounding, audit trails |
+| `tenant-isolation` | Multi-tenant boundaries: cross-tenant reads/writes, scoping, leakage |
+| `mcp-agent` | Agent/MCP integrations: prompt injection, tool abuse, secret exfiltration |
+
+The per-profile checklists live in `agent-templates/security-auditor.md`; this table is the naming
+authority. Both enums are grow-only: adding a value here legalizes it everywhere (the structural
+guards read the enums from this file).
+
+### Severity
+
+Findings reuse the preflight severity scale **by reference** — 🔴 CRITICAL / 🟠 MAJOR /
+🟡 MINOR as defined in the preflight skill — verbatim, with no extra levels.
+
+### 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.
+
+## Activation & supersession
+
+| Condition | Effect |
+|-----------|--------|
+| No structured profile | Strict defaults: one correctness review for every non-trivial executed phase |
+| `quality.independentReview: false` | Allowed only outside strict mode; announce that routine independent review is disabled. This never disables a required Complexity Escalation Gate challenger after an escalation is detected. |
+| Independent review on | Post-phase quality review runs for **all executed phases and task mini-plans** (whole-task diff); trivial tasks are never reviewed |
+| Docs-only diff | Phase reviewer still runs; security/perf auditors skip — the skip is logged, never silent |
+| Security risk tags active | Security auditor dispatches once per phase with the union of applicable checklists and supersedes the reviewer's security lens |
+| Performance-critical tag + code diff | Performance auditor dispatches and supersedes the reviewer's performance lens |
+
+Supersession exists so the same ground is never reviewed twice at different depths: a dedicated
+agent replaces the reviewer's matching add-on lens for that phase.
+
+## Dispatch packets & header
+
+**Line 1 of every quality-agent dispatch prompt** is a compact scope header:
+
+```
+[codeops-dispatch agent=<name> feature=<slug> phase=<id>]
+```
+
+The header makes parallel results attributable and auditable. Outcome metrics never parse prompt
+or response content.
+
+| Agent | Packet contents (the agent receives nothing else and must need nothing else) |
+|-------|------------------------------------------------------------------------------|
+| phase-reviewer, security-auditor, perf-auditor | Phase diff (`git diff <phase-start-ref>..HEAD`), original goal + smallest viable design, relevant approved complexity AR/PF/RV excerpts, the phase's task + Deliverable lines, active lenses, scope mode (`strict` or `explore`), confirmed scope baseline, profile excerpt, verify command + last result |
+| 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 |
+| 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 |
+
+## Budget caps
+
+- **Preflight fan-out:** ~5 clustered auditor dispatches — an exact partition of the preflight
+  skill's 13 dimensions, grouped by affinity: ① Ambiguities + Logical Contradictions +
+  Consistency (document soundness) · ② Implicit Assumptions + Codebase Alignment (grounding) ·
+  ③ Completeness Gaps + Dependency Issues + Ordering & Sequencing (delivery) · ④ Security Blind
+  Spots + Edge Cases + Feasibility Concerns (risk) · ⑤ Testability + Scope Creep Indicators
+  (fit). `--thorough` expands to one dispatch per dimension.
+- **Re-review:** at most ONE re-review per phase, only after 🔴/🟠 fixes, scoped to the fix
+  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.
+
+## Model, effort, and agent resolution
+
+Routing policy lives in `codeops/codeops.json`; see the setup-routing skill. Policy names roles and capabilities, not vendor tiers. A role may optionally declare a current OpenCode model, reasoning effort, and sandbox, but no gate depends on a particular model being available.
+
+Resolution order is:
+
+1. an explicit model/effort requested for the current dispatch;
+2. a generated or hand-authored project agent in `.opencode/agents/<role>.md`;
+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.
+
+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/recommendation-hardening.md

@@ -0,0 +1,166 @@
+# Recommendation Hardening Protocol
+
+> Shared reference for the **Grounded Options & Recommendations** directive
+> (`standards/coding-standards.md` → Working style). Linked by the recommendation-producing skills.
+> **CodeOps Artifact Schema**: 1
+
+This protocol makes recommendations trustworthy on the **first** pass. It is the standing answer to
+the question *"are these your best possible recommendations?"* — asked and answered **before** you
+present, every time, so the operator never has to ask it.
+
+## Why this exists
+
+Left unstructured, a model **satisfices**: it returns the first adequate set of options drawn from
+"what does a reasonable answer look like," not "what is the best answer after exhausting the space."
+The Grounded Options *second-guess* step, run in the same forward pass that produced the options,
+shares that pass's framing and blind spots — so it rarely finds the better answer that an external
+challenge would.
+
+When a human challenges the recommendation, two different things can happen, and only one is good:
+
+1. **Genuine deeper search** — a fresh pass takes the first pass as adversarial input, sees its gaps,
+   and finds a better answer. *This is the lift we want.*
+2. **Sycophantic drift** — the model produces a *different* answer because it read the challenge as
+   "you were wrong," not because the new answer is better. *This is noise, and it is corrosive to
+   trust.*
+
+> **Convergence, not drift.** The goal of this protocol is to institutionalize (1) and design out
+> (2). You do not "try harder when poked" — you run a **structured** hardening pass that *converges*
+> on a verified-best recommendation. Reflexively changing an answer under perceived pressure is a
+> failure of this protocol, not a success of it.
+
+## When it applies
+
+Apply the full protocol to every **consequential** recommendation: code-modifying directions,
+architecture and design choices, scope decisions, defect-resolution directions, requirements
+choices, plan-making and plan-execution decisions, and preflight findings.
+
+> **Proportionality.** Trivial, easily-reversible, or obvious choices get a one-line recommendation
+> and skip the ceremony — drowning the operator in hardening theater wastes their time as surely as
+> strawman options do. Match the ceremony to the stakes.
+
+## Layer 1 — Forced reframing
+
+Before presenting a consequential recommendation, generate your candidate set, then **answer these
+four prompts** (internally for ordinary decisions; surfaced briefly for high-stakes ones). They are
+the forcing functions that break you out of the obvious framing:
+
+- **10× budget:** "What would I recommend with **10× the time/budget**?"
+- **Contrarian expert:** "What's the option a **contrarian senior expert** would push that I
+  dismissed or didn't consider?"
+- **Obsolescence:** "What would make my current top pick **obsolete or wrong**?"
+- **Pre-empt the challenge:** "If the operator asks *'is this your best?'* — **answer that now.**
+  What changes?"
+
+Revise your candidate set with whatever these surface *before* moving on.
+
+## Layer 2 — Definition-of-done rubric
+
+A consequential recommendation may **not** be presented until **all** of these hold. This is the
+**definition-of-done** for a recommendation — it operationalizes "best" so it is a checklist, not a
+vibe:
+
+- [ ] **≥1 genuinely non-obvious option considered** — never a strawman. (When only one option is
+  genuinely viable, that is a valid outcome: present it alone, say it is the only viable one, and
+  name what you rejected and why.)
+- [ ] **Confidence level set** — High / Med / Low, with the specific thing that would change it.
+- [ ] **Strongest counter-argument named** — the best case *against* your chosen pick, stated in one
+  line.
+
+## Layer 3 — Confidence & trust disclosure (conditional)
+
+The disclosure exists to surface **residual uncertainty** — so it appears only when there is some:
+
+```text
+Confidence: High | Med | Low — <the specific thing that would change this>
+Hardening: <what the deeper pass changed, or "no change">
+```
+
+The disclosure is REQUIRED when any of these hold:
+- confidence is **Med or Low**;
+- the hardening pass **changed something** (an option added/dropped, the pick revised);
+- the recommendation is **high-stakes** (see below).
+
+Otherwise — High confidence, hardening changed nothing, not high-stakes — **omit the disclosure**:
+a boilerplate "Hardening: no change" at High confidence carries no information and trains the
+operator to skip the lines that matter. (The layers 1–2 work still runs; only the two-line
+disclosure is conditional.)
+
+For a **high-stakes** recommendation, also state the challenger's verdict:
+`Challenger: converged` or `Challenger: diverged — <how>`.
+
+This disclosure is **presentation-layer only**. It may appear in a saved artifact (e.g. a preflight
+report), but it is **not** a newly-required, validated field — existing artifacts remain valid
+without it, and no migration is implied.
+
+## Layer 4 — Tiered independent challenger
+
+The independence layer is what actually closes the *trust* gap, because a self-critique in the same
+context inherits the same blind spots. Run it **tiered by stakes**:
+
+- **Always (every consequential recommendation):** Layers 1–3, in-context.
+- **High-stakes only:** additionally spawn **one independent challenger** subagent.
+
+### Challenger budget (hard caps)
+
+- **One challenger per preflight scan, not per finding.** A preflight run with multiple
+  CRITICAL/MAJOR findings spawns a SINGLE challenger that receives the whole finding batch
+  (each finding's statement + surviving options) **plus the scan's recon summary / Codebase
+  Context section**, so it challenges from evidence rather than from a cold start. It returns a
+  per-finding verdict list.
+- **At most 2 challenger spawns per skill run**, total — e.g. one for the finding batch and one
+  for a late-discovered decision. Beyond the cap, proceed with Layers 1–3 and disclose
+  `Challenger: budget exhausted` (cap confidence at Med for those items).
+
+### The challenger mechanism
+
+1. Dispatch **one** independent `design-challenger` role in a fresh subagent context. Give it the
+   problem statement and surviving options — but **NOT** your chosen pick. Packet convention:
+   `_shared/quality-profile.md`. A generated custom agent is optional; a generic subagent with the
+   complete challenger contract is equivalent.
+2. Instruct it to produce **its own** best recommendation and the strongest case for it, blind to
+   your choice. Challenger prompt template:
+
+   > *"Here is a decision and the candidate options: <problem + options>. Independently recommend the
+   > single best option and give the strongest grounded case for it. You do not know my current pick.
+   > If a better option is missing from the list, propose it. State your confidence and the strongest
+   > argument against your own pick."*
+
+3. **Reconcile** the challenger's recommendation with yours:
+   - **Converged** → present with raised confidence; note `Challenger: converged`.
+   - **Diverged** → present **both**, with a grounded reconciliation of why you land where you do;
+     note `Challenger: diverged — <how>`. Never silently overwrite either side.
+
+> **Fallback.** If the challenger subagent is unavailable or returns nothing usable, proceed with
+> Layers 1–3, disclose `Challenger: unavailable`, and **cap confidence at Med**. Exception: a
+> detected complexity escalation cannot proceed. The Complexity Escalation Gate requires an
+> independent verdict, so it stays blocked when the challenger is unavailable or its budget is
+> exhausted.
+
+## High-stakes definition (the escalation trigger)
+
+A recommendation is **high-stakes** — and therefore gets the challenger — when any of these hold:
+
+- it is a **preflight** finding at **CRITICAL/MAJOR** severity (challenged as a batch — one
+  challenger per preflight scan, see the budget above); or
+- it is a **make-plan** (Phase 1C) or **make-requirements** (Phase 2B) gate decision tagged
+  **complex/sensitive** (the project routing tags); or
+- it triggers the shared **Complexity Escalation Gate**, regardless of routing tag; or
+- the **user explicitly requests a challenger** for a decision, in any skill.
+
+Everything else — minor/observation findings, trivial/standard-tagged decisions, ad-hoc choices —
+gets Layers 1–3 only. When a gate decision carries no routing tag, treat it as `standard` (the
+documented default) → no challenger. Skills without their own trigger (grill-me, exec-plan, the
+wrappers) escalate ONLY via this definition — they carry no private one.
+
+## Anti-patterns
+
+- ❌ Changing your recommendation reflexively because you were questioned (drift, not convergence).
+- ❌ Presenting >2 options without filtering, or padding with strawmen to manufacture a choice.
+- ❌ Skipping the confidence/`Hardening:` disclosure where Layer 3 requires it (Med/Low
+  confidence, a changed pick, or high stakes) — or padding every answer with a contentless
+  "Hardening: no change" where it doesn't.
+- ❌ Spawning a challenger for a trivial or easily-reversible choice (ceremony without stakes).
+- ❌ Spawning per-finding challengers when the batch rule applies, or exceeding the 2-spawn cap.
+- ❌ Giving the challenger your chosen pick (destroys its independence).
+- ❌ Deriving "best" from how much effort you spent rather than from the definition-of-done rubric.