liteagents 2.19.0 → 2.21.0

package/CHANGELOG.md

@@ -9,12 +9,72 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.21.0] - 2026-08-30
+
+### Changed
+- **`/diff-review` renamed to `/branch-review`, in all four kits.** The command's subject is
+  the branch, not a diff — it reads whole files around each hunk, skims `git log` for intent,
+  and now runs a repo- and history-scoped security audit — so the old name described neither
+  its input nor its output. No command-count change; `/code-review` (Anthropic's plugin
+  skill) is untouched.
+- **`/branch-review` gains effort levels and a second stage.** `low | medium | high | max`
+  (default `medium`) governs the general review's breadth. Stage 2 delegates to `/security`
+  and **always runs it in full at every level** — a shallow security pass reads as coverage
+  while missing the class of bug that costs the most. Stage 3 verifies adversarially (try to
+  break each claim, not confirm it), and **every surviving finding must carry a concrete
+  failure scenario** — inputs/state → wrong output, crash, or exposure — or it is dropped.
+- **`/branch-review` and `/security` never edit code.** Both previously applied "confirmed and
+  unambiguous" fixes directly, which contradicted the gate they are meant to be; `/security`
+  also lost `Edit` from its tool list. They report and escalate; fixing is a separate,
+  separately authorized action. `/security` behaves identically standalone or as stage 2 —
+  only the report's recipient changes.
+- **`/release` no longer reviews, and no longer touches the remote.** Review moved out
+  entirely (anything that returns a work-list forks into fix→re-review and does not belong
+  inside a linear release run). It now gates on a **review precondition**: a review must have
+  run at the current HEAD SHA, which makes "all findings fixed" mechanically checkable, since
+  a fix commit moves HEAD and staleness forces a re-review. It releases the **current branch**
+  only — no branch argument, no branch creation, and on `main` it stops and asks. It runs
+  `/ship`, sweeps the docs, bumps the version, commits locally, then **stops and reports the
+  remaining push → PR → merge → tag → publish sequence** for a human to authorize.
+- **`/ship` is now purely mechanical.** Every item is answerable by running a command and
+  reading an exit code. Dropped four code-judgment checks (error handling, authorization,
+  rate limiting, data-access scoping) that duplicated `/security` in weaker form, plus the
+  "run `/security` before shipping" line. The secrets grep stays, deliberately and with the
+  reason stated inline. New evidence rule: record the exact command and exit code; a check you
+  did not run is a fail, and **N/A requires a stated reason**.
+- **Worker guardrails, in `/branch-review`, `/release`, `/stash` and `/remember`.** The
+  mid-tier model rule no longer names vendor models (they drift, and these kits ship to four
+  tools); it now says "your tool's balanced default tier" and explicitly excludes the
+  cheapest/fastest tier, which measurably degrades on judgment work. All four also carry an
+  "escalate, never assume" rule, and `/stash` gains a "write only what the brief contains"
+  rule — its subagent expands a brief, which is exactly where fabrication happens.
+
+### Fixed
+- `/stash` carried two guardrails about writing minimal code, in a command that writes one
+  markdown file.
+
 ### Planned
 - Community marketplace submissions
 - Additional skills for data analysis
 - Enhanced testing capabilities
 - Performance optimizations
 
+## [2.20.0] - 2026-08-29
+
+### Changed
+- **`AGENT_RULES.md` template (all 4 kits): the spec layer now requires the interview to
+  happen but leaves its shape free.** PRD is defined as a portal with 5 minimum fields
+  (problem & goal, go/no-go, out of scope, modules, open questions) that every POC refines.
+- **Four one-sentence execution-order rules (Sequence / Selection / Iteration / Verify) added
+  to Operating Flow.**
+- **"Build incrementally" replaced by "One module at a time"** (works alone, then connects,
+  both proven) and a separate "No fitting to pass" rule, with a matching Red Flag.
+- **New safeguard: never commit to `main`** — branch, then propose `/code-review` followed by
+  `/release`; merge/release only on a named go.
+- **Removed restated content**: the "AI Agent Instructions" section, the "Safety First"
+  bullet, the "POC scope" bullet, and duplicated spec/POC prose in the Communication Protocol
+  and the CLAUDE.md stub.
+
 ## [2.19.0] - 2026-08-26
 
 ### Changed

package/README.md

@@ -148,10 +148,10 @@ Results land in `.claude/remember/friction/antigen_review.md` with projects, err
 - **debug-method** - Four-phase debugging framework
 - **optimize** - Performance analysis
 - **refactor** - Safe refactoring with behavior preservation
-- **diff-review** - Review a file, branch, or range; verifies findings, fixes confirmed/unambiguous ones, asks on ambiguous or downstream-affecting ones
-- **security** - Vulnerability scan; same verify→fix→ask flow as `/diff-review`
+- **branch-review** - Pre-merge gate: general review at a chosen effort level plus a full security audit, adversarial verify pass; reports findings, never fixes
+- **security** - Standalone vulnerability scan; also runs as stage 2 of `/branch-review`
 - **ship** - Pre-deployment checklist
-- **release** - Deliver a feature end-to-end: verify → docs → merge → tag (publish stays manual)
+- **release** - Prepare a release on the current branch: verify → docs sweep → version bump → local commit, then hand back the merge/tag/publish sequence (never pushes)
 - **test-generate** - Generate test suites
 
 > **Claude-only plugin:** `live-canvas-channel` is a bundled Claude Code MCP channel plugin that ships under `~/.claude/plugins/live-canvas-marketplace/`. One-time `/plugin install` + a session started with `--dangerously-load-development-channels` unlocks live mode. Skill probes for the channel on each invocation and handholds setup when missing. See [`packages/claude/skills/live-canvas/README.md`](packages/claude/skills/live-canvas/README.md) for the full walkthrough.
@@ -184,7 +184,7 @@ Results land in `.claude/remember/friction/antigen_review.md` with projects, err
 **Code Quality:**
 ```
 @quality-assurance Review this PR before merge
-/diff-review main  # review branch vs main, fixes confirmed issues, asks on ambiguous ones
+/branch-review main medium  # review branch vs main + security audit; reports, never fixes
 /debug-method Investigate this race condition
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "liteagents",
-  "version": "2.19.0",
+  "version": "2.21.0",
   "description": "AI development toolkit with 11 specialized agents and 18 commands including live-canvas UI design with click-to-annotate feedback. Simple one-question installer for Claude, Opencode, Ampcode, and Droid.",
   "main": "index.js",
   "bin": {

package/packages/ampcode/AGENT.md

@@ -43,10 +43,10 @@ These subagents are available when using Ampcode CLI.
 | optimize | Analyze and optimize performance issues | /optimize <target-area> |
 | refactor | Refactor code while maintaining behavior and tests | /refactor <code-section> |
 | remember | Consolidate stashes + friction into project memory | /remember |
-| diff-review | Comprehensive code review including quality, tests, and architecture | /diff-review |
-| security | Security vulnerability scan and analysis | /security |
-| ship | Pre-deployment verification checklist | /ship |
-| release | Deliver a feature end-to-end: verify, docs, merge, tag (publish stays manual) | /release [branch] |
+| branch-review | Pre-merge review: general review + full security audit, verify pass, no fixes | /branch-review [target] [level] |
+| security | Security audit — recurring six, injection, auth, trust boundaries; reports, never fixes | /security [target] |
+| ship | Mechanical pre-deploy gate — tests, build, tree state | /ship |
+| release | Verify, sweep docs, cut a version — then hand back the merge/tag/publish sequence | /release |
 | stash | Save session context for compaction recovery or handoffs | /stash ["optional-name"] |
 | test-generate | Generate tests, run them, verify each one actually exercises the code | /test-generate <file> |
 

package/packages/ampcode/agents/code-developer.md

@@ -75,7 +75,7 @@ digraph CodeDeveloper {
   regression_fixable [label="Fixable?", shape=diamond];
 
   // Review and complete
-  code_review [label="Run /diff-review"];
+  code_review [label="Run /branch-review"];
   verification [label="Run /verify-done", fillcolor=orange];
 
   // Story-specific
@@ -191,7 +191,7 @@ All require `*` prefix. Invocation commands in table above. Additional:
 | Writing any test | `/test-traps` (avoid mocks, production pollution) |
 | Before completion | `/verify-done` |
 | After code changes | `/security` |
-| Task complete / general review | `/diff-review` (diffs branch or staged changes, verifies, fixes confirmed issues, asks on ambiguous ones) |
+| Task complete / general review | `/branch-review` (reviews the branch + full security audit, verifies claims, reports findings — never fixes) |
 | Performance issues | `/optimize` |
 
 You are an autonomous implementation specialist. Execute with precision, delegate appropriately, and communicate clearly when you need guidance or encounter blockers.

package/packages/ampcode/agents/quality-assurance.md

@@ -65,7 +65,7 @@ Before any analysis, read (if exists):
 
 ## Slash Commands Available
 
-Use these during analysis: `/diff-review`, `/security`, `/verify-done`
+Use these during analysis: `/branch-review`, `/security`, `/verify-done`
 
 ## Analysis Areas
 

package/packages/ampcode/commands/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/ampcode/commands/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/ampcode/commands/remember/AGENT_RULES.md

@@ -10,7 +10,6 @@
 7. [Development Workflow](#development-workflow)
 8. [Twelve-Factor Checklist](#twelve-factor-checklist)
 9. [AGENT.md Stub](#agentmd-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 `.amp/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 AGENT.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 AGENT.md. These are mandatory rules, not suggestions.
 
 For full development and testing standards, see `.amp/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