liteagents 2.19.0 → 2.21.0

package/packages/opencode/command/branch-review.md

@@ -0,0 +1,123 @@
+---
+name: branch-review
+description: Review a branch before merge [target] [level]
+usage: /branch-review [target] [low|medium|high|max]
+argument-hint: [file, branch (e.g. main), range (main..HEAD), or empty] [effort level]
+allowed-tools: Read, Grep, Glob, Agent, Bash(git diff *), Bash(git log *), Bash(git show *), Bash(git status *), Bash(git grep *), Bash(git rev-parse *), Bash(git merge-base *), Bash(rg *)
+---
+Pre-merge review gate. Two stages — **general review** then a **full security
+audit** — followed by an adversarial verify pass. It **never edits code**: it
+reports findings and hands them back. Fixing is a separate, separately
+authorized action.
+
+Run this **before** `/release`. `/release` will refuse to run without a review
+at the current HEAD SHA.
+
+## Guardrails
+- **Spawn a worker on a mid-tier model, not hardcoded.** The review runs in a
+  subagent on your tool's balanced default tier — judgment-capable, cheaper and
+  faster than your top reasoning tier. **Not the cheapest/fastest tier**: on
+  judgment work it measurably degrades (misclassification rates several times
+  higher). Never hardcode a vendor-specific model name. Fall back to running
+  inline if your tool has no subagent mechanism.
+- **Escalate, never assume.** Anything you cannot decide, cannot verify, or
+  that this spec does not cover → **stop and report it to the orchestrator**
+  (the main session). Never improvise, never widen scope, never fix a side
+  issue you noticed along the way.
+- **No edits.** You have no authorization to change code, even for a finding
+  you are certain about. Report it.
+
+## Target — interpret `$ARGUMENTS` in this order
+1. **Empty** → the current branch vs its merge-base with `main`
+   (`git diff $(git merge-base main HEAD)..HEAD`). If that is empty, the
+   staged diff; if that is empty too, the working tree.
+2. **A range** like `main..HEAD` or `origin/main...HEAD` → `git diff <range>`.
+3. **A single ref** (branch / tag / SHA — confirm with `git rev-parse
+   --verify`) → that ref's merge-base against `HEAD`.
+4. **A file or directory path** → that target.
+5. Otherwise → ask.
+
+Record the **HEAD SHA** you reviewed. `/release` checks it, and any commit
+made after the review makes the review stale.
+
+## Effort level
+`low | medium | high | max` — default **medium** if not given. The level
+governs **stage 1 only**:
+- **low / medium** — fewer findings, only ones you are confident in.
+- **high / max** — broader coverage; uncertain findings are allowed, but each
+  must be labelled uncertain.
+
+**Stage 2 (security) always runs full, at every level.** A shallow security
+pass is worse than none — it reads as coverage while missing the class of bug
+that costs the most.
+
+## Stage 1 — General review
+The diff is the subject, but **read the whole file around every hunk** — a
+hunk-only read cannot see that a caller further down the same file is now
+wrong. For multi-commit ranges, skim `git log <range>` for intent before
+judging.
+
+- **Bugs needing a fix.** Logic errors, off-by-one, null/undefined paths,
+  races, wrong defaults, broken edge cases.
+- **Dead code.** Unreferenced functions / vars / imports / params, unreachable
+  branches, commented-out blocks, legacy paths the diff just obsoleted.
+  `git grep` the symbol before flagging — easy to be wrong.
+- **Loose ends.** TODO / FIXME / XXX added by this diff, half-finished
+  branches, silently swallowed errors, stub bodies, mocked-out paths,
+  "temporary" names, abandoned feature flags.
+- **Correctness.** Edge cases, error handling, type / contract violations,
+  broken invariants.
+- **Performance.** N+1, blocking calls in hot paths, unbounded loops, indexes
+  the diff actually touches.
+- **Maintainability.** Complexity, naming, duplication — only when material.
+
+## Stage 2 — Security (always full)
+**Delegate; do not re-implement.** Locate and **read** the installed
+`security.md` and run its actual checklist — the recurring six (secrets in the
+repo *and in git history*, data-access authorization / tenant isolation, rate
+limiting, unhappy-path error handling, authorization beyond authentication,
+inefficient data access) plus injection, auth/session, and trust boundaries.
+
+If `security.md` cannot be found, run what you can from the list above and
+**flag that the full checklist was unavailable** — never report it as passed.
+
+This stage is repo- and history-scoped, not diff-scoped: a key committed forty
+commits ago, an unbounded route the diff never touched, or a missing row
+policy on a table the new code now reads are all in scope.
+
+## Stage 3 — Verify (adversarial)
+Findings are claims, not facts. **Try to break each one, not to confirm it** —
+a pass that sets out to confirm reliably misses what an adversarial pass
+finds.
+
+- Re-read the cited `file:line` in full context.
+- `git grep` the name across the repo before trusting any dead-code or
+  unused-symbol claim.
+- Mark each **confirmed**, **false positive** (with the reason), or
+  **uncertain** (with what would settle it).
+
+**Every surviving finding must carry a concrete failure scenario**: specific
+inputs or state → the wrong output, crash, or exposure that results. If you
+cannot write that sentence, the finding is not ready — drop it or mark it
+uncertain. No vibes.
+
+## Report — then escalate
+Order findings most severe first.
+
+### 🚨 Critical (blocks merge)
+### ⚠️ Warnings (should fix)
+### 💡 Suggestions (nice to have)
+
+Each finding: **Location** (`file:line`) · **What's wrong** · **Failure
+scenario** (inputs/state → result) · **Why it matters** · **Suggested fix**
+(described, not applied) · **Verdict** (confirmed / uncertain).
+
+Then a coverage line: stage 1 at level `<level>`, stage 2 full — each `ran ✓/✗`
+with its evidence. A stage you did not actually run is a **✗**, never an
+assumed pass.
+
+End with:
+- **Reviewed at HEAD `<sha>` on `<branch>`.**
+- One-line verdict: **Ready to merge? Yes / No / Not until these are fixed.**
+- **Escalate to the orchestrator** with the findings. It decides what gets
+  fixed and by whom. Say plainly what you could not verify.

package/packages/opencode/command/release.md

@@ -1,90 +1,119 @@
 ---
 name: release
-description: Deliver a feature end-to-end — verify, docs, merge, tag (publish stays manual)
-usage: /release [branch]
-argument-hint: [branch — new or existing; else current]
-allowed-tools: Read, Grep, Glob, Edit, Write, Bash(git *), Bash(gh *), Bash(npm *), Bash(pnpm *), Bash(yarn *), Bash(pytest *), Bash(python *), Bash(go *), Bash(cargo *), Bash(make *)
+description: Verify, sweep docs, cut a version — then hand the release sequence back
+usage: /release
+allowed-tools: Read, Grep, Glob, Edit, Write, Agent, Bash(git status *), Bash(git diff *), Bash(git log *), Bash(git show *), Bash(git fetch *), Bash(git add *), Bash(git commit *), Bash(git rev-parse *), Bash(git merge-base *), Bash(npm *), Bash(pnpm *), Bash(yarn *), Bash(pytest *), Bash(python *), Bash(go *), Bash(cargo *), Bash(make *)
 ---
-End-to-end feature-delivery **orchestrator**. It does **not** re-implement
-checks — it runs your existing gates (`/ship`, `/security`, `/diff-review`)
-under `/verify-done` discipline, then performs the release actions. Two halves
-split by a hard gate: everything **before** the gate is safe and read-only;
-everything **after** rewrites history and is confirmed step by step.
-
-**A feature branch is required — `main` is only the merge target.** `$ARGUMENTS`
-names the branch to release. Omit it only if you are already on a feature
-branch. If you are on `main` with nothing named, a branch is created for you —
-but you should be releasing a deliberately-named feature branch.
-
-## Phase 0 — Preflight (resolve a feature branch — never `main`)
-- **Resolve the release branch** — whatever gets merged into `main`:
-  - `$ARGUMENTS` given → `git switch` to it (create it if it does not exist).
-  - else not on `main` → release the **current** branch.
-  - else on `main` with no arg → **create** `feat/<slug>` (named for the
-    change) and carry your working changes onto it. **Never release `main`.**
-- **Land the feature on the branch** — if the working tree still has
-  uncommitted feature changes, commit them now; the gates must review a real
-  diff, not a dirty tree.
-- `git fetch origin`; the release diff is `origin/main...HEAD` (now guaranteed
-  to be the resolved branch). If it is empty, **stop** — nothing to release.
-- Print a one-line plan: branch · commit count · files changed.
-
-## Phase 1 — VERIFY (delegate; no hand-waving)
-**First, load the real checklists.** Locate and **read** the sibling command
-definitions so you apply their exact checks, not an approximation — glob your
-installed commands/skills for `ship.md`, `security.md`, `diff-review.md`, and
-`verify-done` (a skill or command). If one cannot be found, run that check from
-its name and **flag that its full checklist was unavailable** — never pretend
-it passed.
-
-Then run each gate and capture **fresh evidence** — the exact command, its exit
-code, and the result. Per `/verify-done`: a check you did **not** actually run
-is a **FAIL**, never an assumed pass.
-- **`/ship`** — pre-deploy gate (tests, lint, build, secrets, authz, rate
-  limit, data scope, migrations, docs-sync).
-- **`/security`** — on the changed files.
-- **`/diff-review`** — on `origin/main...HEAD`.
-
-Emit a coverage table, one row per gate: `ran? ✓/✗` · evidence · verdict. If
-any row is ✗ (could not run), the run is **Blocked 🛑** — do not continue.
+Release **preparation** orchestrator for the **current branch**. It runs your
+existing pre-deploy gate, sweeps the docs, bumps the version and commits —
+then **stops and reports**. It never pushes, opens a PR, merges, tags, or
+publishes: those are yours to authorize by name.
+
+It does not re-implement checks, and it does not review code. Review is a
+separate command that must have run first.
+
+## Guardrails
+- **Spawn a worker on a mid-tier model, not hardcoded.** The run happens in a
+  subagent on your tool's balanced default tier — judgment-capable, cheaper and
+  faster than your top reasoning tier. **Not the cheapest/fastest tier**: on
+  judgment work it measurably degrades (misclassification rates several times
+  higher). Never hardcode a vendor-specific model name. Fall back to running
+  inline if your tool has no subagent mechanism.
+- **Escalate, never assume.** Anything you cannot decide, cannot verify, or
+  that this spec does not cover → **stop and report it to the orchestrator**
+  (the main session). Never improvise, never widen scope, never fix a finding
+  you noticed along the way.
+- **Nothing leaves the machine.** No `git push`, no `gh`, no `npm publish`,
+  under any circumstance — not even if every gate is green. You report the
+  sequence; a human authorizes it.
+
+## Phase 0 — Preflight (current branch, always)
+- **Release the branch you are on.** No branch argument, no branch creation.
+- **On `main` → stop and ask** what should be released. `main` is only ever
+  the merge target; never release it, never commit to it.
+- If the working tree still has uncommitted feature changes, commit them to
+  the branch now — the gate must see a real diff, not a dirty tree.
+- `git fetch origin`; the release diff is `origin/main...HEAD`. Empty →
+  **stop**, nothing to release.
+- Print a one-line plan: branch · commit count · files changed · HEAD SHA.
+
+## Phase 0.5 — Review precondition (do not skip)
+Ask the orchestrator: **has `/branch-review` or `/code-review` run on this
+branch at the current HEAD SHA?**
+
+- **No review** → **stop**: "No review at `<sha>`. Run `/branch-review medium`
+  (or `/code-review medium`) first."
+- **Stale** — the review ran at an earlier SHA, i.e. commits landed after it
+  (including fix commits) → **stop** and ask for a re-review. This is what
+  makes "all findings fixed" checkable instead of promised.
+- **Reviewed at this SHA with findings outstanding** → **stop**. Findings are
+  resolved before a release is cut.
+
+This is the only thing guaranteeing the branch was reviewed *and* security
+scanned, so treat a missing answer as a **stop**, never as a pass.
+
+## Phase 1 — Verify
+**Load the real checklist**: locate and **read** the installed `ship.md` so
+you apply its exact checks, not an approximation. If it cannot be found, run
+what you can from its name and **flag that the full checklist was
+unavailable** — never pretend it passed.
+
+- **`/ship`** — mechanical pre-deploy gate (tests, lint, build, debug
+  leftovers, secrets grep, migrations, docs/config sync, tree state).
+
+Capture **fresh evidence**: the exact command, its exit code, and the result.
+A check you did not actually run is a **FAIL**, never an assumed pass. Emit a
+coverage row: `ran? ✓/✗` · evidence · verdict. A ✗ is **Blocked 🛑**.
+
+Security is **not** re-run here — it is stage 2 of the review, already
+confirmed in Phase 0.5.
 
 ## 🚦 Gate
-- **Any Critical** (failing tests/build, a Critical security or diff-review
-  finding) → **stop**, report, ask how to proceed. Touch no history.
+- **Any Critical** (failing tests, broken build) → **stop**, report, escalate.
 - **Warnings, or anything you cannot confidently decide** → **stop**,
-  summarize, ask.
-- **All clean** → continue to Phase 2.
+  summarize, escalate. Do not weigh it yourself.
+- **All clean** → continue.
+
+## Phase 2 — Docs sweep
+Update what this feature actually changed, wherever those docs live in this
+project — match each file's existing format, touch nothing unrelated. Use
+`docs/index.md` when the project has one to find what exists.
 
-## Phase 2 — DOCS (only what the feature changed)
-Update as needed, matching each file's existing format; touch nothing
-unrelated. If a doc needs no change, **say so** rather than editing for its
-own sake.
 - **CHANGELOG.md** — new entry.
-- **PRD** — the feature's PRD entry / status.
-- **context / guide** — the project's context or guide doc.
 - **README.md** — only if user-facing usage changed.
+- **PRD** — the feature's entry / status.
+- **Guide / context docs** — the project's standing context.
+- **Findings / learnings** — where the project keeps them.
+- **Any other frequently-updated doc** this change makes stale.
+
+If a doc needs no change, **say so** rather than editing it for its own sake.
 
-## Phase 3 — RELEASE (irreversible — confirm each step)
+## Phase 3 — Cut (local only)
 1. **Version bump** — pick the semver level from the change (patch / minor /
-   major; ask if ambiguous) and update `package.json`.
-2. **Commit** — `release: vX.Y.Z — <summary>`, including the docs + bump.
-3. **Push** the branch.
-4. **Open PR** — `gh pr create` into `main` (main is PR-protected: 1 approving
-   review).
-5. **Merge** — `gh pr merge --delete-branch`. If the review requirement blocks
-   it, **stop** and ask — never force or silently bypass. On a **solo repo** you
-   cannot approve your own PR, so the expected path is an owner-authorized
-   admin-merge (`gh pr merge --admin`), run only on the user's explicit say-so.
-6. **Tag** — after the merge, `git tag vX.Y.Z` on `main` and push it. Keep
-   cut→tag tight — one frozen step.
-
-## Stop here — publish is your call
-Do **not** publish. `publish.yml` is manual `workflow_dispatch` **by design**.
-Print the handoff:
-> Merged, branch deleted, tagged **vX.Y.Z**. To publish, run it yourself:
-> `gh workflow run publish.yml`
-> Then confirm the version is actually live (`npm view <pkg> versions`) and
-> validate the **installed** artifact, not the working tree.
-
-Final report: **Delivered ✅ (vX.Y.Z — publish pending)** or **Blocked 🛑**
-with the specific reason.
+   major; **ask if ambiguous**) and update `package.json`. The bump must land
+   on the branch, before any merge — a version committed to `main` directly,
+   or added after the merge, breaks the tag/package match.
+2. **Commit** — `release: vX.Y.Z — <summary>`, including the docs and the
+   bump.
+
+Then **stop.** Nothing else.
+
+## Report — the sequence, for a human to authorize
+Print the evidence, then hand back the exact remaining steps so the
+orchestrator can run them on the user's named go:
+
+> **Cut ✅ vX.Y.Z on `<branch>`** — `/ship` green, docs updated, release commit
+> made locally. Reviewed at `<sha>`.
+> Ready when you are:
+> 1. `git push -u origin <branch>`
+> 2. `gh pr create` into `main`
+> 3. `gh pr merge --admin --squash --delete-branch` (main is PR-protected;
+>    owner-authorized admin merge on a solo repo)
+> 4. `git tag vX.Y.Z` on `main` and push the tag
+> 5. Publish **if this project has a publish path** (e.g.
+>    `gh workflow run publish.yml`) — manual by design
+> 6. Verify it is actually live (`npm view <pkg> version`, and the published
+>    tarball's contents), not the working tree
+
+Final line: **Cut ✅ (vX.Y.Z — ready to push)** or **Blocked 🛑** with the
+specific reason.

package/packages/opencode/command/remember/AGENT_RULES.md

@@ -10,7 +10,6 @@
 7. [Development Workflow](#development-workflow)
 8. [Twelve-Factor Checklist](#twelve-factor-checklist)
 9. [AGENTS.md Stub](#agentsmd-stub)
-10. [AI Agent Instructions](#ai-agent-instructions)
 
 ---
 
@@ -18,10 +17,25 @@
 
 Every task runs through three layers. Do not skip ahead to code.
 
-1. **Spec — agree on intent before touching anything.** Interview me up front to surface the *real* goal and the context you can't see — prompt the **decision I'm trying to make**, not the literal task I typed. Break the scope into small buckets with checkpoints. **State the load-bearing structural and logic decisions and get my explicit sign-off *before* you execute.** A wrong assumption caught at spec stage costs a sentence; caught after building it costs the build.
-2. **Verify — define "good" up front, then prove it.** Write down what success looks like *before* changing code. Prove with measurement and tests, not assertion (see [*Prove, don't assert*](#validate-before-you-build)). Gate security-sensitive work with `/security` and pre-deploy with `/ship`; a second-model pass (`/code-review`) on non-trivial output is worth the round-trip. External signal — a real test run, a real deploy, a gold-standard reference — beats a confident paragraph every time.
+1. **Spec — the interview must happen; its shape is yours.** Before touching anything, surface the *decision I'm actually making*, not the literal task I typed. Ask what you need to know — no more; how you ask is your call. Restate what you heard and get my explicit sign-off on the load-bearing decisions *before* you execute. A wrong assumption caught here costs a sentence; caught after building costs the build.
+
+   Write the outcome down as a **PRD**. A PRD is a portal, not a deliverable — where the conversation starts and the doc every POC refines. Minimum content, whatever the form:
+   - **Problem & goal** — what we're solving and why now
+   - **Go / no-go** — the 1–2 capabilities the product stands or falls on; usually module 0's riskiest assumption (e.g. "can a phone camera read the ID?"). Fails → stop
+   - **Out of scope** — what we're explicitly not doing
+   - **Modules** — the pieces to build, in order (see [*One module at a time*](#validate-before-you-build))
+   - **Open questions** — unknowns that don't block; never silently assumed
+
+   Every POC result updates the PRD; one that flips the go/no-go or a module's assumption is a spec change, not a footnote.
+2. **Verify — define "good" up front, then prove it.** Write down what success looks like *before* changing code. Prove with measurement and tests, not assertion (see [*Prove, don't assert*](#validate-before-you-build)). Gate security-sensitive work with `/security` and pre-deploy with `/ship`. When the work is done, propose `/code-review` and then `/release` — you never merge or release on your own (see [Required Safeguards](#required-safeguards-always--ask--never)). External signal — a real test run, a real deploy, a gold-standard reference — beats a confident paragraph every time.
 3. **Environment — the standing context.** This file primes every session. Critical-path protections (secrets, auth, schema, CI) are stated as **Always / Ask / Never** below and bind you as written. Where your tool offers a permission allow/ask/deny list, mirror them there so they are enforced and not merely requested.
 
+**Execution order — work the way a program runs, in this order, nothing skipped:**
+1. **Sequence** — do the PRD's modules in the order listed; never start module N+1 while module N is unproven.
+2. **Selection** — every POC is a branch: pass → next module, fail → back to the PRD as a spec change.
+3. **Iteration** — repeat POC → update PRD → next POC until the go/no-go is answered; the loop invariant is *everything built so far still works on its own*.
+4. **Verify** — assert before you move: a step is done when you ran the proof and saw it pass, not when you wrote that it did.
+
 > The model is brilliant at execution and blind to intent. You can outsource the typing; you cannot outsource the understanding. Surface assumptions — don't bury them.
 
 ---
@@ -29,16 +43,14 @@ Every task runs through three layers. Do not skip ahead to code.
 ## Communication Protocol
 
 ### Core Rules
-- **Spec before build**: Don't wait for ambiguity to block you — interview me up front to extract the real goal and the context you can't see. Prompt the *decision*, not the literal task. Restate what you heard before building
-- **Checkpoint before executing**: State the load-bearing structural and logic decisions and get my explicit sign-off *before* you write code. Never run ahead on an unverified assumption — flag it and stop
+- **Spec first, then checkpoint**: see [Operating Flow §1](#operating-flow). Never run ahead on an unverified assumption — flag it and stop
 - **Fact-Based**: Base all recommendations on verified, current information. Prefer external signal (a real run, a real source) over a confident guess
 - **Simplicity Advocate**: Call out overcomplications and suggest simpler alternatives
-- **Safety First**: Never modify critical systems without explicit understanding and approval
 
 ### User Profile
 - **Technical Level**: Non-coder but technically savvy
 - **Learning Style**: Understands concepts, needs executable instructions
-- **Expects**: Step-by-step guidance with clear explanations
+- **Expects**: Step-by-step guidance, ready-to-run commands, and the *why* behind each recommendation
 - **Comfortable with**: Command-line operations and scripts
 - **Builds a lot of web apps** — assume any UI work will be consumed on phones as well as desktop
 
@@ -49,6 +61,7 @@ Not courtesies. These bind you as written, whether or not your tool enforces the
 - **Always** identify affected files before making changes, and explain what will change and why
 - **Ask first** — stop and get explicit sign-off — before modifying authentication systems, database schema or migrations, CI workflows, or `.opencode/settings.json`
 - **Never** write secrets into the tree (`.env`/`*.env`, keys, credentials). They load from the environment at runtime; only a value-less `.env.example` is committed
+- **Never** commit to `main`. Commit to a new branch (name doesn't matter), then propose `/code-review` followed by `/release`; merging and releasing are my call, made by name — "approve", "good", or "go" on a draft is not that call
 
 ---
 
@@ -57,12 +70,12 @@ Not courtesies. These bind you as written, whether or not your tool enforces the
 ### Validate Before You Build
 
 - **POC everything first.** Before committing to a design, build a quick proof-of-concept (~15 min) that validates the core logic. Keep it stupidly simple — manual steps are fine, hardcoded values are fine, no tests needed yet
-- **POC scope:** Cover the happy path, 2-3 common edge cases, **and the riskiest assumption (see below) — not just the parts that are easy to check**. If those hold, the idea is sound
 - **Graduation criteria:** POC validates logic and covers most common scenarios → stop, design properly, then build with structure, tests, and error handling. Never ship the POC — rewrite it
-- **Aim the POC at the load-bearing claim — not the easy part.** Name the riskiest assumption first (does the cheap path actually run cheap? does the library really do X? does the perf hold?), then point the spike straight at *that*. A POC that confirms the happy-path shape while hand-waving the risky mechanism is theater. If you catch yourself writing "production would do X" instead of *doing* X in the spike, the POC has not validated X — go do X
+- **Aim the POC at the load-bearing claim — not the easy part.** Cover the happy path and 2-3 common edges, but name the riskiest assumption first (does the cheap path actually run cheap? does the library really do X? does the perf hold?), then point the spike straight at *that*. A POC that confirms the happy-path shape while hand-waving the risky mechanism is theater. If you catch yourself writing "production would do X" instead of *doing* X in the spike, the POC has not validated X — go do X
 - **Prove, don't assert — a POC's output is evidence you ran, not prose you wrote.** Every claim the design rests on must be something the spike actually exercised and you actually observed. **Measure anything you call "cheap," "fast," "constant," or "negligible"** — never state a cost you didn't time; a guessed number is a bug with a confident voice. State conclusions only at the confidence the evidence supports: if you didn't test it, say so plainly instead of rounding up to "it works." Better a small honest finding than a big-mouthed claim that measurement later falsifies
 - **The test must be able to FAIL — pre-flight check, not an afterthought.** Before trusting a POC's numbers, confirm three things: **(1) Can the test produce the negative?** A fixture you authored to contain the phenomenon you're testing can only confirm it — prefer real, uncrafted data over synthetic inputs; if synthetic is unavoidable, construct it so it *could* show no effect. **(2) Is the harness free of confounds?** A surprising or degenerate result is often an artifact of the setup, not a real finding — when output looks wrong, debug the test before believing it. **(3) Did the test actually exercise the variable?** If two conditions that should differ produce identical output, the variable isn't wired in — that's a finding, not noise. Run this checklist every time, especially when a result confirms what you hoped
-- **Build incrementally.** After POC graduates, break the work into small, independent modules. Focus on one at a time. Each piece must work on its own before integrating with the next
+- **One module at a time.** Build the PRD's modules in order, never several at once. Each module gets its own POC aimed at *its* riskiest assumption (module 0's is the go/no-go). A module is done when **(1)** it works on its own and **(2)** it connects to what's already built and the whole still works — both proven, not assumed. Only then start the next
+- **No fitting to pass.** Never narrow the input, move the threshold, or shrink the scope until a POC goes green. Report the failure and take it back to the PRD
 
 ### Dependency Hierarchy
 
@@ -106,6 +119,7 @@ Before adding any external dependency, all of these must be true:
 - Skipping POC validation for unproven ideas
 - POC-ing only the easy part while hand-waving the risky mechanism, or claiming a cost ("cheap"/"fast"/"constant") you never measured
 - Authoring a fixture/corpus that *guarantees* the result (a test that can't return the negative), or trusting a degenerate-looking number without auditing the harness for confounds — use real uncrafted data; the test must be able to fail
+- Fitting a POC to pass (narrowed input, moved threshold, shrunk scope) instead of reporting the failure; starting module N+1 while module N is unproven
 
 ---
 
@@ -269,9 +283,9 @@ Copy this to any project's AGENTS.md. These are mandatory rules, not suggestions
 ```markdown
 ## Dev Rules
 
-**POC first.** Always validate logic with a ~15min proof-of-concept before building. Cover happy path + common edges. POC works → design properly → build with tests. Never ship the POC. **Aim the spike at the riskiest assumption, not the easy part; prove, don't assert — measure anything you call "cheap"/"fast"/"constant," and claim only what the evidence supports (no big-mouthed conclusions measurement can falsify). The test must be able to FAIL: prefer real uncrafted data over a fixture you authored to contain the result, audit a degenerate number for harness confounds before believing it, and treat two should-differ conditions that match as a finding.**
+**Spec first.** Interview to find the decision, not the task; write a PRD with problem/goal, go/no-go, out-of-scope, modules, open questions. POCs refine it.
 
-**Build incrementally.** Break work into small independent modules. One piece at a time, each must work on its own before integrating.
+**POC first, one module at a time.** Each module's POC targets its riskiest assumption (module 0 = go/no-go); the test must be able to fail; prove, don't assert — measure anything you call cheap/fast/constant. No fitting to pass. A module works on its own, then connects to what's built, before the next starts. Never ship the POC.
 
 **Dependency hierarchy — follow strictly:** vanilla language → standard library → external (only when stdlib can't do it in <100 lines). External deps must be maintained, lightweight, and widely adopted. Exception: always use vetted libraries for security-critical code (crypto, auth, sanitization).
 
@@ -283,17 +297,3 @@ Copy this to any project's AGENTS.md. These are mandatory rules, not suggestions
 
 For full development and testing standards, see `.opencode/remember/AGENT_RULES.md`.
 ```
-
----
-
-## AI Agent Instructions
-
-When working with this user:
-1. **Interview before building** — extract the real goal and surface load-bearing decisions for sign-off before you execute (see [Operating Flow](#operating-flow))
-2. **Provide step-by-step** instructions with clear explanations
-3. **Include ready-to-run** scripts and commands
-4. **Explain the "why"** behind technical recommendations
-5. **Flag potential issues** before they become problems — name the assumption, don't bury it
-6. **Suggest simpler alternatives** when appropriate
-7. **Ask first** before touching auth, DB schema/migrations, CI, or settings; **never** commit secrets
-8. **Always identify** which files will be affected by changes

package/packages/opencode/command/remember.md

@@ -10,10 +10,10 @@ Run friction analysis, then consolidate session stashes + friction antigens into
 - Favor straightforward, minimal implementations first and add complexity only when requested or clearly required.
 - Keep changes tightly scoped to the requested outcome.
 - **Precision over recall for hot memory.** A false antigen loaded into `@MEMORY.md` steers every future session. When unsure, do not promote — leave it to recurrence (a ledger `observing` entry at 2 sessions, nothing at 1).
-- **Mid-tier model, not hardcoded.** Steps 2/3/4a delegate to a mid-tier model — capable of
-  semantic judgment, cheaper/faster than your top reasoning tier (e.g. Claude's Sonnet vs
-  Opus). Use whatever your tool designates as that balanced default; never hardcode a
-  vendor-specific model name.
+- **Mid-tier model, not hardcoded.** Steps 2/3/4a delegate to your tool's balanced default
+  tier — judgment-capable, cheaper and faster than your top reasoning tier. **Not the
+  cheapest/fastest tier**: on judgment work it measurably degrades (misclassification rates
+  several times higher). Never hardcode a vendor-specific model name.
 - **Batch stashes, don't fan out.** Step 2 gives each extraction agent **up to 5 stashes**
   and uses as few agents as possible (3 stashes → 1 agent, 7 → 2). One agent reading several
   sessions sees the same lesson recur and writes it once; one agent per stash writes it once

package/packages/opencode/command/security.md

@@ -1,12 +1,20 @@
 ---
 name: security
-description: Scan security [target]
+description: Security audit — recurring six, injection, auth, trust boundaries
 usage: /security
 argument-hint: [file, directory, or leave empty for full scan]
-allowed-tools: Read, Edit, Grep, Glob, Bash(git log *), Bash(git grep *), Bash(rg *)
+allowed-tools: Read, Grep, Glob, Bash(git log *), Bash(git grep *), Bash(rg *)
 ---
-Audit $ARGUMENTS for security vulnerabilities. Adapt scope to what the target
-actually is — a library, CLI, web app, and service won't all have every
+Audit $ARGUMENTS for security vulnerabilities. **Reports, never edits** — it
+verifies every claim, then hands the findings to whoever asked.
+
+**Runs identically standalone or as stage 2 of `/branch-review`.** The only
+difference is where the report goes: to the orchestrator when called as a
+stage, to you when you run it directly. Same checks, same verify pass, same
+escalation. It does **not** spawn a worker of its own — run it inline; when
+`/branch-review` calls it, it is already inside that command's worker.
+
+Adapt scope to what the target actually is — a library, CLI, web app, and service won't all have every
 category. Skip what genuinely doesn't apply; never invent findings to fill a
 section.
 
@@ -58,22 +66,23 @@ End with: which of the six classes were checked and found **clean**, and any
 marked **N/A** for this target — so the scan's coverage is auditable, not just
 its hits.
 
-## After the scan — verify, then fix
+## After the scan — verify, then escalate
 
-Findings are claims, not facts. Validate before acting; validate again after.
+Findings are claims, not facts. Validate every one before reporting it; an
+unverified finding wastes more time than a missed one.
 
-**Verify each claim.** Re-read the cited `file:line` in context. Confirm the
-risk actually holds here — not in the abstract. Mark each **confirmed**, **false
-positive** (with reason), or **uncertain**.
+**Verify each claim — adversarially.** Re-read the cited `file:line` in full
+context and **try to break the claim, not to confirm it**: is there a gate
+upstream, a framework default, a caller that already validates? A pass that
+sets out to confirm reliably misses what an adversarial pass finds. Mark each
+**confirmed**, **false positive** (with reason), or **uncertain** (with what
+would settle it).
 
-**Fix what's confirmed and unambiguous** — minimal shape, one obvious way, no
-change to a public API / response / caller contract. Apply directly. After
-each edit, re-read the changed region and confirm it closes the gap without
-breaking nearby logic. A fix isn't done until you've grounded it the same way
-you grounded the claim.
+**Never fix.** Not even a confirmed, one-line, obvious fix. Describe the
+minimal remediation and hand it back — applying it is a separate, separately
+authorized action.
 
-**Stop and ask** when any of these hold (HITL gates — not all the time, only
-here):
+**Flag these explicitly** — they need a human decision, not a recommendation:
 - the finding is **uncertain** after grounding (you'd need info you don't have),
 - the fix has **multiple reasonable shapes** (e.g. reject-vs-sanitize,
   index-vs-paginate) — present options with tradeoffs, not a chosen path,
@@ -82,5 +91,12 @@ here):
 - it touches **auth / crypto / session / token** primitives — even an "obvious"
   fix here warrants confirmation.
 
-Final report: **confirmed-and-fixed** · **confirmed-but-asking** (why + options)
-· **false-positive** (why) · **uncertain** (what's needed to decide).
+Final report: **confirmed** (with remediation described) · **needs a decision**
+(why + the options and their tradeoffs) · **false positive** (why) ·
+**uncertain** (what is needed to decide).
+
+**Escalate, never assume.** Anything you cannot decide, cannot verify, or that
+this spec does not cover → say so plainly in the report rather than guessing.
+When running as a stage of `/branch-review`, that report goes to the
+orchestrator; standalone, it goes to the user. Never widen scope, never fix a
+side issue you noticed along the way.