opencode-codeops 1.4.0

package/_shared/scope-expansion-control.md

@@ -0,0 +1,176 @@
+# Scope Expansion Control
+
+> **CodeOps Artifact Schema**: 1
+
+This shared protocol keeps optional product additions separate from the work the user actually
+authorized. It is used by `make-plan`, `preflight`, and `exec-plan`. Each workflow links here
+instead of defining its own scope-expansion semantics.
+
+## Activation
+
+Strict scope is the default. Optional expansion discovery is enabled only by exactly one standalone
+token `--explore-scope` before the first `--` end-of-options sentinel. Remove that token before
+resolving targets, paths, or modes. Zero occurrences means strict scope, more than one is invalid,
+and tokens at or after the sentinel are target content. Lookalikes such as `--explore-scopes`,
+`--explore-scope=true`, and bare `explore-scope` do not activate the mode.
+
+The flag is invocation-scoped. It is never persisted as a repository or global default. A child
+workflow or reviewer receives the mode only when its dispatch packet explicitly carries it; missing
+or invalid mode context fails closed to strict scope.
+
+These examples are normative:
+
+| Arguments | Result |
+|---|---|
+| `target` | `strict` |
+| `--explore-scope target` | `explore` |
+| `--explore-scope --explore-scope target` | `invalid` |
+| `-- --explore-scope` | `strict`; the token is target content |
+| `--explore-scope -- --explore-scope` | `explore`; the later token is target content |
+| `--explore-scopes`, `--explore-scope=true`, or `explore-scope` | `strict` |
+
+## Prime directive
+
+Record the authorized scope baseline before analysis. In strict scope:
+
+- stay inside that baseline;
+- do not report optional additions, speculative improvements, gold-plating, or additional product
+  behavior;
+- do not turn optional ideas into findings, requirements, specifications, tests, tasks, blockers,
+  readiness failures, or roadmap work; and
+- optional ideas must not affect finding counts, severity, verdicts, progress, or execution.
+
+Silence applies only to new optional proposals. Existing content that already exceeds the
+authorized baseline remains an in-scope scope-creep defect and must be reported so it can be
+removed or explicitly authorized.
+
+## Necessary correction or optional expansion
+
+A **Necessary correction** is the smallest correction for which grounded causal evidence shows
+that omission makes the explicitly requested behavior incorrect, unsafe, or infeasible and that
+there is no compliant solution wholly inside the authorized scope. The agent carries the burden of proof
+and must always report the evidence and why the correction is necessary. Reporting necessity
+does not authorize expanding the modification set or applying the correction.
+
+A credible unresolved material risk to correctness, safety, or feasibility is a **blocking
+uncertainty** requiring bounded investigation. It is neither silently hidden as optional nor
+promoted into implementation. If evidence remains speculative or the requested behavior can still
+work correctly, safely, and feasibly without the addition, the idea is optional.
+
+## Exploration mode
+
+With active `--explore-scope`, collect genuinely useful optional additions after completing the
+in-scope analysis. Do not mix them into ordinary ambiguity questions or findings. Present one
+compact numbered Scope Expansion Register so the user can rule on every proposal.
+
+### Register format
+
+Create the register only when at least one proposal exists. Resolve its collision-free path through
+[`_shared/layout-convention.md`](layout-convention.md). IDs are artifact-local, monotonic, never reused,
+and allocated as `SE-001`, `SE-002`, and so on. Preserve append-only history rather than
+overwriting an earlier ruling. The register header records the governed target type, its
+normalized project-relative path, and the confirmed scope baseline or later baseline revision. Reject an
+absolute or parent-traversing target path.
+
+The proposal table is the current-state view of every user decision:
+
+| ID | Proposed addition | Origin | Why it is outside scope | Impact | Recommendation | Current state |
+|---|---|---|---|---|---|---|
+| `SE-001` | Concrete new behavior, artifact, dependency, or subsystem | Finding, assumption, review, or scenario | Boundary exceeded | Cost, complexity, compatibility, operations, and maintenance | `Keep`, `Defer`, or `Discard` with rationale | `Proposed` until the user rules |
+
+Every ruling appends a decision event. `SEV-*` IDs are register-local, monotonic, never reused, and
+allocated as `SEV-001`, `SEV-002`, and so on. Append order is the ordering authority, so the last
+valid appended event determines current state. Never edit, delete, or reorder an earlier event:
+
+| Event ID | SE ID | Timestamp | From state | Decision | Authority and evidence | Owner | Revisit trigger | Replacement or reversal |
+|---|---|---|---|---|---|---|---|---|
+| `SEV-001` | `SE-001` | ISO 8601 | `Proposed` | `Keep`, `Defer`, `Discard`, or `Superseded` | User ruling or other explicit authority plus its provenance | Required for `Defer` | Required for `Defer` | Required when superseding or reversing |
+
+Accepted proposals also maintain dependency-oriented authority links:
+
+| SE ID | Derived artifact | Relation or kind | Current state | Evidence source |
+|---|---|---|---|---|
+| `SE-001` | Requirement, specification, test, task, implementation evidence, verification, or roadmap item | `authorizes` or `invalidates` | Current, stale, or superseded | Durable artifact evidence |
+
+Implementation linkage belongs in plan or other artifact evidence and never in source comments.
+Recompute the proposal table's current state from the latest valid event; the event log
+remains authoritative history.
+
+### State transitions
+
+Only these lifecycle transitions are valid:
+
+| From state | Allowed next state |
+|---|---|
+| `Proposed` | `Keep`, `Defer`, `Discard` |
+| `Keep` | `Superseded` |
+| `Defer` | `Keep`, `Discard`, `Superseded` |
+| `Discard` | `Keep`, `Superseded` |
+| `Superseded` | *(terminal)* |
+
+A deferred entry may transition only after its recorded trigger is unambiguously satisfied or the
+user explicitly requests reconsideration. A discarded entry may transition to `Keep` only with new
+evidence and renewed explicit authorization. A reversal is recorded as a new event; it never
+rewrites the earlier event.
+
+The stored decision vocabulary is:
+
+- **`Keep`** — explicitly accepted into authorized scope. Only `Keep` may produce a requirement,
+  specification, test, executable task, implementation, or roadmap item. Every derived artifact
+  back-references its `SE-*` authority.
+- **`Defer`** — records a named owner and observable revisit trigger. It remains dormant and
+  non-executable on ordinary resume. Re-present the same `SE-*` ID only when unambiguous trigger
+  evidence exists or the user explicitly requests reconsideration; re-presentation never implies `Keep`.
+  Unverifiable or ambiguous trigger evidence leaves it dormant.
+- **`Discard`** — remains durable, non-executable context. Reconsideration requires new evidence
+  and renewed authorization under the same ID; never erase the earlier decision.
+- **`Superseded`** — the proposal or its accepted scope is no longer current, with its replacement
+  or reversal recorded.
+
+Bulk acceptance is valid only when the user explicitly accepts the listed `SE-*` recommendations.
+Silence, `--auto-design`, `--auto-commit`, a finding ruling, or permission to apply fixes never
+counts as expansion authority.
+
+## Findings and fix permission
+
+Finding resolution and expansion authorization are separate. A `PF-*`, `RV-*`, `SA-*`, or `PE-*`
+finding may link to an `SE-*` proposal, but accepting the finding selects only its in-scope
+resolution. Commands such as `apply all fixes` do not authorize optional expansion proposals;
+they apply only in-scope fixes and proposals already ruled `Keep`.
+
+An optional proposal never blocks merely because it is deferred, discarded, or undecided. A
+necessary correction or blocking uncertainty may block because the requested behavior itself has
+not been shown correct, safe, and feasible.
+
+## Resume, reversal, and invalidation
+
+Every resume loads the applicable register before analysis. Preserve all IDs, decisions, evidence,
+owners, triggers, and derived links. Never reintroduce a discarded proposal as a new ID or re-open
+it without new evidence and renewed authorization.
+
+When the user reverses `Keep`, stop affected execution. Use recorded authority links to invalidate
+only dependency-traced downstream specifications, tests, tasks, implementation, and verification.
+Mark pending or in-progress derived tasks superseded and current downstream state stale; historical
+evidence stays intact. The removed work must not remain executable or apparently ready. Require an
+explicitly authorized safe removal or remediation decision, and never auto-revert irreversible or
+externally applied work.
+
+## Interaction with auto-design
+
+`--auto-design` chooses eligible technical designs only inside already authorized scope.
+`--auto-design` cannot choose `Keep`, revive `Discard`, broaden a modification set, suppress a
+necessary correction, or treat optional product behavior as technical authority. The two flags may coexist:
+exploration proposes additions, the user owns their scope rulings, and auto-design may
+operate inside an accepted addition only after `Keep` is recorded.
+
+## Workflow bindings
+
+- **make-plan:** trace every planned item to the original scope baseline or a kept `SE-*` entry.
+  Optional ideas are silent in strict scope and register proposals in exploration mode before any
+  plan artifact promotes them.
+- **preflight:** audit defects in the selected target regardless of mode. Optional remediations are
+  silent in strict scope or linked to `SE-*` proposals in exploration mode. A finding decision is
+  never the proposal decision.
+- **exec-plan:** classify runtime ambiguities and reviewer remediations before implementation.
+  Optional fixes are silent in strict scope or proposed through the register in exploration mode;
+  only kept proposals may enter the executable plan.

package/_shared/spec-first-ordering.md

@@ -0,0 +1,79 @@
+# Specification-First Task Ordering (shared protocol)
+
+> **CodeOps Artifact Schema**: 1
+
+The **single canonical definition** of CodeOps' specification-first ordering. `make-plan` applies
+it when generating `99-execution-plan.md`; `exec-plan` enforces it while executing one. Both link
+here; neither carries its own copy.
+
+Every feature implementation phase follows this three-step structure. It prevents tautological
+testing — tests that mirror the implementation instead of independently verifying it against the
+specification.
+
+```
+Phase N: [Feature Name]
+
+  Step N.1: Specification Tests (BEFORE implementation)
+    N.1.1  Write specification tests from 07-testing-strategy.md ST-cases
+           → File: [feature].spec.test.[ext]
+           → Source: 07-testing-strategy.md ST-1 through ST-X
+           → MUST NOT read implementation logic when writing these tests
+    N.1.2  Run spec tests — verify they FAIL (red phase)
+           → Document any that pass pre-implementation with justification
+
+  Step N.2: Implementation
+    N.2.1  Implement [feature/component] per technical specification
+           → Reference: 03-XX-[component].md
+    N.2.2  Run spec tests — verify they PASS (green phase)
+           → If any spec test fails: STOP, fix the implementation (NOT the test)
+
+  Step N.3: Implementation Tests & Hardening
+    N.3.1  Write implementation tests (edge cases, internals, error paths)
+           → File: [feature].impl.test.[ext]
+    N.3.2  Full verification (the project's verify command)
+```
+
+## Why this ordering
+
+| Step | What it prevents |
+|------|-----------------|
+| Spec tests BEFORE implementation | Deriving test expectations from the code you just wrote |
+| Red-phase verification | Meaningless spec tests (they must test something that doesn't exist yet) |
+| Spec tests PASS after implementation | An implementation that doesn't satisfy the specification |
+| Impl tests AFTER implementation | Nothing — impl tests MAY be derived from the code (edge cases, internals); spec tests may not |
+
+## Enforcement
+
+**🚫 PROHIBITED:**
+
+- ❌ Writing implementation code before specification tests exist for that feature
+- ❌ Skipping the spec-test step ("we'll write tests after")
+- ❌ Combining spec tests and implementation in one task, or writing them simultaneously
+- ❌ Generating a plan where implementation tasks precede spec-test tasks for the same feature
+
+**✅ REQUIRED in every generated `99-execution-plan.md`:** the three-step ordering per feature
+phase; explicit `[feature].spec.test.[ext]` and `[feature].impl.test.[ext]` file references;
+references to the ST-cases from `07-testing-strategy.md` in spec-test tasks; a distinct
+red-phase verification task.
+
+**Immutable-oracle rule:** if the implementation does not match a spec test, the implementation
+is wrong — not the test. Never modify a spec test's expectations to match code. (This rule binds
+subagent executors too — a delegated task that hits a failing spec test reports a blocker; it
+never edits the test.)
+
+## Small features (compressed form)
+
+You MAY compress into a single step, but the ordering is still mandatory:
+
+```
+Step N.1: [Feature Name]
+  N.1.1  Write specification tests (from ST-cases)
+  N.1.2  Verify spec tests fail (red phase)
+  N.1.3  Implement feature
+  N.1.4  Verify spec tests pass (green phase)
+  N.1.5  Write implementation tests
+  N.1.6  Full verification
+```
+
+The order `spec tests → red phase → implement → green phase → impl tests → verify` is NEVER
+negotiable, regardless of feature size.

package/_shared/zero-ambiguity-gate.md

@@ -0,0 +1,311 @@
+# Zero-Ambiguity Gate (shared protocol)
+
+> **CodeOps Artifact Schema**: 1
+
+This is the **single canonical definition** of the Zero-Ambiguity Gate. It lives at the plugin
+root in `_shared/` (deliberately outside `skills/`, like `layout-convention.md`). The gate-running
+skills link here instead of carrying their own copies:
+
+| Caller | Phase | Blocked artifacts while the gate is closed |
+|--------|-------|--------------------------------------------|
+| make-plan | Phase 1C | every plan document (`00-index.md`, `01-requirements.md`, specs, execution plan) |
+| make-requirements | Phase 2B | every requirement document (`RD-XX-*.md`, `requirements/README.md`) |
+| upgrade-plan | Phase 2B (Content Quality Gate) | Phase-3 structural upgrades, version stamps, any document edit |
+
+Each caller keeps a short preamble (phase name, blocked artifacts, caller-specific notes) and
+links here for everything below. Change the gate in one place: here.
+
+## Why this gate exists
+
+Artifacts built on ambiguity produce implementations built on guesswork. When the AI guesses, the
+user gets requirements they didn't specify, behaviors they didn't define, and architectures with
+no accountable authority. Every item in every gated artifact must trace back to an **authorized
+resolution**: an explicit user decision in normal mode, or a complete eligible delegated record
+under active auto-design. If you cannot point to that authority, you have failed this gate.
+
+> **Recommendation hardening (complex/sensitive decisions).** When you present options for an
+> ambiguity tagged complex or sensitive, apply `_shared/recommendation-hardening.md` — spawn one
+> independent challenger and reconcile before recommending, and close the presentation with the
+> `Confidence:` / `Hardening:` disclosure where that protocol requires it.
+
+## Complexity Escalation Gate (always active)
+
+The minimum-sufficient-design rule is enforceable, not advisory. This gate stays active during
+requirements discovery, planning, preflight, and execution. It also applies after the main
+Zero-Ambiguity Gate has passed.
+
+### Trigger
+
+Stop when a proposed solution adds a material support surface beyond the smallest direct solution.
+Signals include:
+
+- a new or expanded architecture layer, service, subsystem, or generalized abstraction;
+- an external dependency or framework;
+- a custom test harness, runner, generator, validator, policy gate, or support framework;
+- CI, deployment, container, monitoring, queue, cache, or other infrastructure;
+- a cross-cutting refactor that the requested behavior does not directly require;
+- future-proofing for needs that are not authorized; or
+- support machinery whose build or maintenance cost is material compared with the requested work.
+
+Do not trigger for ordinary feature code, small helpers, tests that directly prove accepted
+behavior using existing project patterns, or direct controls implemented through an existing
+pattern to meet an accepted security or correctness obligation. A new generalized mechanism
+chosen to provide that control still triggers this gate. When the classification is uncertain,
+treat it as a trigger. Batch related mechanisms into one decision so the user is not interrupted
+repeatedly for the same root cause.
+
+### Required stop packet
+
+First dispatch one blind `design-challenger` under `_shared/recommendation-hardening.md`. Give it
+the original goal, constraints, repository evidence, the smallest viable option, and the larger
+proposal, but not the parent's recommendation. The challenger returns one verdict:
+`Unnecessary`, `Simplify`, or `Justified`.
+
+Then present this visibly. Do not bury it in other prose:
+
+```markdown
+# 🚨 STOP — EXTRA COMPLEXITY NEEDS YOUR APPROVAL
+
+**Original goal:** [What the user asked for]
+**Extra system or support code:** [New layer, dependency, harness, infrastructure, or other support surface]
+**Why it may be needed:** [Why the larger design is being proposed]
+**Evidence:** [Repository facts and demonstrated risk]
+**Smallest solution that still works:** [Direct alternative]
+**Extra cost:** [Files/components/dependencies/operations and ongoing maintenance]
+**Independent verdict:** [Unnecessary | Simplify | Justified] — [reason]
+**Recommendation:** [Choose the smaller option or approve the larger one, with reason]
+
+Choose: use the smaller solution, approve the larger solution, revise it, or defer the extra
+machinery.
+```
+
+The larger option remains blocked until the user explicitly approves it. `Justified` is advice,
+not approval. Silence, generic acceptance of recommendations, `--auto-design`, `--auto-commit`, a
+generic finding ruling, dismissal shortcut, or permission to apply fixes does not approve extra
+complexity. Auto-design may choose the smallest viable option, but it cannot approve an escalation.
+If the challenger is unavailable or its budget is exhausted, the escalation stays blocked because
+independence is part of this gate.
+
+A complexity escalation resolves only after the challenger returns a usable verdict and the user
+makes a direct choice on the named machinery. A short answer such as "I approve" is valid only when
+exactly one complexity packet is awaiting a decision, so its target is clear.
+
+### Durable authority and escaped complexity
+
+Use the workflow's existing decision owner; do not create a new register:
+
+| Workflow stage | Durable owner |
+|----------------|---------------|
+| Requirements, planning, or runtime discovery | Ambiguity Register entry with category `Technical (complexity escalation)` |
+| Preflight | The `PF-*` finding and its explicit user decision |
+| Post-phase review | Ambiguity Register entry with category `Technical (complexity escalation)`; the `RV-*` finding references it |
+
+Downstream packets include relevant approved complexity entries from these owners. An approval is
+specific to the machinery and cost shown in its packet; materially expanding it reopens the gate.
+If the user defers the extra machinery, it stays out of executable work. Deferral closes the
+decision only after the machinery is absent from every executable artifact and the resulting
+implementation or worktree state. Deletion-only appearances in a review diff do not count as
+present machinery. If it is still present, the escalation remains blocked until it is removed and rechecked.
+Complexity that escaped an earlier gate is at least a 🟠 MAJOR finding and blocks readiness or
+further execution until the user chooses the smaller design or explicitly approves the larger one.
+
+Every complexity decision owner must persist the full approval evidence. This is required, not an
+optional presentation detail:
+
+```text
+Original goal: <requested outcome>
+Extra system or support code: <named machinery>
+Why it may be needed: <claimed necessity>
+Evidence: <repository facts and demonstrated risk>
+Smallest solution that still works: <direct alternative>
+Extra cost: <files/components/dependencies/operations and maintenance>
+Independent verdict: Unnecessary | Simplify | Justified — <reason>
+Direct user decision: <smaller | approved larger | revised | deferred>
+```
+
+## The Ambiguity Register
+
+Before the gated phase may proceed, compile and present an **Ambiguity Register** — a formal,
+numbered inventory of every identified gap, ambiguity, unstated assumption, undefined behavior,
+and open question. Hunt systematically across ALL 12 categories (each row merges the widest scope
+of the historical per-skill variants — use every clause that fits the artifact at hand):
+
+| Category | What to look for |
+|----------|-----------------|
+| **Feature gaps** | Features mentioned but not fully specified, incomplete component specs, unclear interactions, undefined workflows |
+| **Behavioral gaps** | Undefined "what happens when…" scenarios, missing error handling/states, unspecified state transitions |
+| **Scope ambiguities** | Features that could go either way, unclear in/out-of-scope boundaries, vague MVP-vs-future split |
+| **Technical unknowns** | Undecided architecture/technology, unresolved implementation or integration approaches, decisions stated without rationale |
+| **Edge cases** | Boundary conditions, failure modes, concurrent access, empty/null states, overflow, data-volume limits |
+| **Integration points** | Unclear interfaces (internal or external), undefined API contracts, missing data-flow specs |
+| **Data & state** | Unclear data models/relationships, undefined ownership, missing validation rules, unspecified formats/cardinality |
+| **Security & compliance** | Unaddressed threat vectors, undefined auth flows/models, missing data-protection decisions, regulatory gaps |
+| **Non-functional gaps** | Missing performance targets, undefined scalability, unspecified availability |
+| **UX & presentation** | Undefined user-facing text, missing error messages, unspecified display formats, unclear navigation |
+| **Stakeholder conflicts** | Competing needs between user types, unresolved priority disputes, unclear permission boundaries |
+| **Naming & terminology** | Unconfirmed file/dir/class/function/API names, domain terms used inconsistently, undefined jargon, ambiguous labels |
+
+### Register template
+
+```markdown
+## Ambiguity Register: [Artifact Name]
+
+> **Status**: ❌ GATE BLOCKED — [X] items unresolved
+> *(When all resolved, change to: ✅ GATE PASSED — all [X] items resolved)*
+> **Last Updated**: [Date — via `date '+%Y-%m-%d %H:%M'`]
+
+| # | Category | Ambiguity / Gap | Options Presented | User Decision | Status |
+|---|----------|-----------------|-------------------|---------------|--------|
+| 1 | Behavioral | [Specific ambiguity] | [Option A / B / C] | [User's answer] | ✅ Resolved |
+| 2 | Scope | [Specific ambiguity] | [Option A / B] | — | ❌ Open |
+| 3 | Technical | [Specific ambiguity] | [Option A / B] | Deferred: [named decision] · owner: [who] · revisit: [trigger] | ⏸ Deferred |
+
+### Resolution Notes
+
+**AR-1:** [Expanded context if needed]
+**AR-2:** [Pending — presented to user, awaiting answer]
+```
+
+Write the register **to disk incrementally from the first entry** (never hold it only in
+memory) — it is the audit trail and must survive a crash mid-phase.
+
+## Gate enforcement rules
+
+**🚫 PROHIBITED while the gate is blocked:**
+
+- ❌ Create or modify any artifact the caller's preamble lists as blocked
+- ❌ Make any decision without user authority or an active, eligible auto-design delegation
+- ❌ Use phrases like "we'll assume…", "by default…", "a reasonable approach would be…"
+- ❌ Proceed with a partially resolved register
+
+**✅ The gate opens ONLY when ALL are true:**
+
+1. ✅ Every row has Status = `✅ Resolved` **or** `⏸ Deferred` (see the deferral rules below —
+   a Deferred row is valid ONLY in the fully-named form).
+2. ✅ Every resolution contains either the **user's explicit decision** (not a recommendation
+   accepted by silence) or, under active auto-design, the complete delegated provenance required
+   by `auto-design.md`. Bulk acceptance counts — see below.
+3. ✅ In normal mode, the user has reviewed and confirmed the complete register. For >15 items,
+   present in batches by category — the user confirms each batch, then gives a final confirmation.
+   In auto-design mode, every eligible delegated row passes the authority boundary and every
+   reserved row is user-confirmed. Items imported pre-resolved (from a grill-me session or an
+   earlier register) do **not** need re-confirmation — only new or changed rows do.
+4. ✅ Zero items are **silently** deferred — "figure it out later" without a named Deferred
+   row is NOT accepted.
+5. ✅ The header reads `✅ GATE PASSED — all [X] items resolved`.
+
+**Bulk acceptance IS an explicit decision.** When the user says *"accept all your
+recommendations"* (or "accept recommendations for items N–M"), record each covered row as
+`✅ Resolved — User accepted recommendation: [the recommended option, spelled out]`. Per-item
+re-confirmation is not required. What remains prohibited is deciding for the user when they have
+NOT said this. **Complexity escalations are the exception:** bulk acceptance does not approve them.
+Each batched root cause needs a direct choice on its visible Complexity Escalation Gate packet.
+
+**Auto-design delegated resolution.** When a supporting workflow was explicitly invoked with
+`--auto-design`, read `auto-design.md`. An eligible technical decision may be recorded as
+`Authority: AI — delegated by --auto-design` with the complete provenance required there. That
+record counts as resolved without falsely attributing the choice to the user. Reserved authority,
+insufficient evidence, and unsupported workflows still require the user. Without the flag, every
+normal-mode rule in this document remains unchanged.
+
+Auto-design never resolves a `Technical (complexity escalation)` row. It may select the recorded
+smallest solution, but the larger option always needs the complete approval evidence above.
+
+**User dismissals:** if the user says *"that's not ambiguous, the answer is obviously X"* — that
+IS a valid resolution: `✅ Resolved — User: "[their stated answer]"`. You cannot dismiss items
+yourself; only the user can. A complexity escalation cannot use this shortcut. Present its full
+packet; the user may challenge its evidence, choose the smaller design, or directly approve the
+named larger machinery.
+
+**Zero-ambiguity register:** if the systematic review finds ZERO ambiguities, still create and
+save the register with header `✅ GATE PASSED — 0 ambiguities identified (systematic review
+completed)`. This proves the gate was executed.
+
+## Deferral rules (named deferral only)
+
+A decision may be **explicitly deferred** — the status the whole pipeline shares (grill-me
+produces it, this gate accepts it, preflight maps it to "Accepted Risk"):
+
+```
+⏸ Deferred — <the decision, named precisely> · owner: <who will decide> · revisit: <the trigger>
+```
+
+- All three parts are mandatory. A Deferred row missing its name, owner, or revisit-trigger is
+  treated as ❌ Open.
+- The user must confirm each deferral explicitly, and the consequences of deferring must have
+  been stated when they did.
+- **Silent deferral stays forbidden.** "Figure it out later", "TBD", or moving on without a
+  named row is a gate violation, exactly as before.
+- Downstream skills honor the deferral: a plan may not silently implement a deferred decision,
+  and preflight records findings that touch one as `Accepted Risk — deferred per AR #N`,
+  cross-referencing rather than re-litigating it.
+- **Complexity exception:** deferred extra machinery is accepted risk only when that machinery is
+  absent from executable artifacts and the resulting implementation or worktree state.
+  Deletion-only appearances in a review diff do not count. If the machinery remains present, the
+  finding stays open at 🟠 MAJOR until removal and recheck; a deferral never authorizes it.
+
+**If the user says "I don't know" / "decide later":** (1) explain why the decision matters and
+the cost of getting it wrong, (2) present options with trade-offs, (3) recommend one with
+rationale, (4) guide them to an explicit choice — **or** to an explicit named deferral, (5)
+record THEIR choice.
+
+**If the user says "you decide" / "just pick one":** in normal mode, politely refuse — "I can recommend, but the
+decision must be yours." Present options with your recommendation marked and wait for "I choose
+[option]" (or a bulk acceptance, which qualifies). Never record "AI decided".
+
+## Register persistence
+
+The register is a permanent file saved with the artifact it gates (resolve the directory per
+`_shared/layout-convention.md`):
+
+- Plans: `<plan folder>/00-ambiguity-register.md`
+- Requirements: `<requirements dir>/00-ambiguity-register.md`
+- Upgrades: the existing register of the artifact being upgraded (append, tag `(upgrade)`,
+  continue numbering) — or a fresh one if the artifact predates the gate.
+
+## Traceability requirement
+
+Every decision in the gated artifact must back-reference the register entry that resolved it:
+
+```markdown
+> **Decision per AR #7:** User chose Option B — time-based cache invalidation with 5-minute TTL.
+```
+
+Unbroken chain in normal mode: **user question → user answer → register entry → artifact.**
+With active auto-design: **identified ambiguity → delegated provenance → register entry →
+artifact**. Reserved decisions always use the normal-mode chain.
+
+The ONLY items exempt from `AR #` back-references: **(a)** universally obvious facts with exactly
+one possible interpretation (e.g., "TypeScript files use `.ts`"), and **(b)** formatting choices
+with zero semantic impact. **When in doubt, it is NOT an exception — add it to the register.**
+
+## Surface-during-authoring rule
+
+Even after the gate passes, if you discover a NEW ambiguity while writing the gated artifact:
+
+1. **STOP writing immediately.**
+2. **Add** it to the register with the next sequential number.
+3. **Resolve authority.** In normal mode, present it to the user with options and trade-offs.
+   With active auto-design, resolve an eligible technical item under `auto-design.md` or present
+   a reserved item to the user.
+4. **Wait** for the user's explicit decision (or named deferral) whenever normal mode or reserved
+   authority applies; otherwise record the complete delegated provenance.
+5. **Record** the resolution, **then** resume writing.
+
+Never "make a reasonable choice and move on."
+
+## Interaction with the grill-me skill
+
+The gate fires regardless of how discovery was conducted — including when grill-me ran first. The
+grill-me shared understanding feeds INTO the register as pre-resolved context but does not replace
+the gate: still scan all 12 categories. Items settled by grill-me import as `✅ Resolved` rows
+(with a session note), grill-me's explicitly-deferred items import as `⏸ Deferred` rows in the
+named form, and per gate rule 3 imported rows are not re-confirmed — only new rows are. An imported
+complexity decision counts as pre-resolved only when it contains the complete approval evidence
+defined above, including the independent verdict and direct user decision. Otherwise reopen it.
+
+## Interaction with the upgrade-plan skill
+
+When an artifact is upgraded, the gate applies to **new** decisions introduced during the upgrade
+(entries tagged `(upgrade)`). Existing resolved decisions are preserved; only new or changed items
+go through the gate.

package/agent-templates/codebase-scout.md

@@ -0,0 +1,17 @@
+<!-- Agent template: codebase-scout
+     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 answer a small set of factual questions about the current codebase, via a scout packet (the
+questions, optional search hints, and the facts-only contract from `_shared/quality-profile.md`).
+
+- **Facts only.** Report what exists, where it lives, and what shape it has — every claim with a
+  `file:line` citation. Never offer opinions, recommendations, or judgments ("should", "better",
+  "consider"); if a question asks for one, answer its factual core and state that the judgment
+  belongs to the dispatching session.
+- **Honest misses.** When something is not found, say "not found" and list the patterns and
+  locations you searched — a confirmed absence is a useful fact; a guess is poison.
+- **Compact.** Answer each question in a few lines; quote code only when the exact text is the
+  answer. No summaries of things nobody asked about.
+- If a question is too ambiguous to search for, report that ambiguity as the answer to that
+  question — never substitute your own interpretation.

package/agent-templates/concurrency-auditor.md

@@ -0,0 +1,5 @@
+<!-- Agent template: concurrency-auditor
+     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. -->
+
+Audit exactly the supplied change packet. Establish shared state, ownership, synchronization, ordering, cancellation, retry, timeout, and failure semantics before judging the diff. Hunt for data races, check-then-act gaps, lost updates, deadlocks, starvation, unsafe publication, reentrancy, duplicate work, stale reads, partial commits, and unbounded concurrency. Construct realistic interleavings that could violate stated invariants. Cite file and line evidence and distinguish proven defects from unverified risk. Return surviving findings with severity, interleaving, violated invariant, and remedy, or an explicit clean result. Remain read-only.

package/agent-templates/design-challenger.md

@@ -0,0 +1,26 @@
+<!-- Agent template: design-challenger
+     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 provide an independent recommendation on exactly ONE decision, via a challenger packet (the
+problem statement, constraints, and candidate options — deliberately WITHOUT the dispatching
+session's own preference, so your judgment stays uncontaminated). The dispatch rules and budget
+caps live in `_shared/recommendation-hardening.md`; the packet convention lives in
+`_shared/quality-profile.md`.
+
+- **Judge on the merits.** Evaluate every option against the stated constraints and the real
+  code — use Read/Grep/Glob to verify claims about the codebase and cite `file:line` for
+  anything you assert about it. Where you cannot verify, say so explicitly.
+- **Add what is missing.** If the option set overlooks a genuinely viable approach, add it and
+  evaluate it alongside the others. Never add strawmen.
+- **Deliver a real position.** Return: your recommended option, the concrete reasons it wins,
+  the strongest argument AGAINST it, and the top risk of each alternative. A split verdict
+  ("A unless X, then B") is acceptable when the deciding fact is named; a non-answer is not.
+- **Police complexity when requested.** Compare each option with the original goal and the smallest
+  viable solution. For a Complexity Escalation Gate packet, return exactly one verdict:
+  `Unnecessary`, `Simplify`, or `Justified`. Treat sophistication, future flexibility, and effort
+  already spent as non-evidence unless the stated requirements or demonstrated risks need them.
+- **Stay independent.** Do not try to infer or accommodate what the dispatcher probably prefers;
+  disagreement is precisely the value you add.
+- If the problem statement is too thin to challenge — missing constraints, options that are not
+  actually distinct, no success criterion — report that as your finding instead of guessing.

package/agent-templates/financial-integrity-auditor.md

@@ -0,0 +1,5 @@
+<!-- Agent template: financial-integrity-auditor
+     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. -->
+
+Audit exactly the supplied change packet. Treat monetary correctness and auditability as invariants. Check balanced accounting, integer minor-unit or explicitly justified decimal arithmetic, currency/unit consistency, idempotency and duplicate submission, transaction atomicity, retry and partial-failure behavior, reconciliation, authorization, immutable audit evidence, overflow and negative amounts, time boundaries, and reversal/refund semantics. Attempt to falsify every claimed invariant using concrete counterexamples. Cite file and line evidence. Return only surviving findings with severity, violated invariant, failure scenario, and remedy, or an explicit clean result. Remain read-only and do not accept implementation convenience as a reason to weaken financial semantics.

package/agent-templates/perf-auditor.md

@@ -0,0 +1,23 @@
+<!-- Agent template: perf-auditor
+     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 performance-review exactly ONE completed phase of work, via a review packet (the phase
+diff, the phase's task and Deliverable lines, the profile excerpt, and the verify command with
+its last result). The conventions behind the packet live in `_shared/quality-profile.md`.
+
+- **What to hunt.** Work introduced on hot paths; per-item allocations in loops; accidental
+  quadratic (or worse) complexity; N+1 query and request patterns; blocking I/O on latency-
+  sensitive paths; unbounded growth (caches, buffers, retained references); lock contention and
+  serialization points; chatty round-trips that could batch.
+- **Judge with a cost model, not vibes.** For each finding, state when it hurts — the input
+  size, request rate, or data shape at which the cost becomes real — and prefer evidence from
+  the code (loop bounds, call sites found via grep) over speculation. A theoretical slowness
+  that no realistic input can trigger is at most 🟡, or not a finding at all.
+- **Findings.** Number them PE-001, PE-002, … Each: severity (🔴 CRITICAL / 🟠 MAJOR /
+  🟡 MINOR, calibrated honestly), `file:line`, the cost and when it bites, and a concrete
+  remedy. Group by severity. If the phase is clean, report **"no findings"** explicitly.
+- **Read-only.** You never edit files, apply fixes, or commit. Bash is for inspection only
+  (searching call sites, counting occurrences); never for mutation.
+- If the packet is insufficient — no diff, no sense of which paths are hot — STOP and report
+  exactly what is missing as a blocker. Never guess.