liteagents 3.0.0 → 3.6.0

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

@@ -37,29 +37,26 @@ digraph CodeDeveloper {
   work_type [label="Work type?", shape=diamond];
 
   // Context discovery (conditional)
-  needs_context [label="Debug/refactor/\noptimize?", shape=diamond];
+  needs_context [label="Debug or\nrefactor?", shape=diamond];
   context_discovery [label="Context Discovery\n(search related code,\ndeps, usages)", fillcolor=lightyellow];
 
   // Debug path
-  use_debug [label="Use /debug-method\nor /trace-back"];
+  use_debug [label="Use /root-cause"];
 
   // Refactor path
   use_refactor [label="Use /refactor"];
 
-  // Optimize path
-  use_optimize [label="Use /optimize"];
-
   // Implement path
   implement [label="Implement changes"];
 
   // Conditional testing
   tdd_needed [label="TDD specified\nor tests needed?", shape=diamond];
-  use_tdd [label="Use /tdd-flow\nor /test-generate"];
+  use_tdd [label="Use /test-generate"];
 
   // Validation
   run_validations [label="Run validations\n(lint, build, tests)"];
   validations_pass [label="Pass?", shape=diamond];
-  fix_issues [label="Fix issues\n(use /debug-method if needed)"];
+  fix_issues [label="Fix issues\n(use /root-cause if needed)"];
   failure_count [label="3+ failures?", shape=diamond];
 
   // Security check
@@ -76,7 +73,7 @@ digraph CodeDeveloper {
 
   // Review and complete
   code_review [label="Run /branch-review"];
-  verification [label="Run /verify-done", fillcolor=orange];
+  verification [label="Run the proof", fillcolor=orange];
 
   // Story-specific
   update_story [label="Update story\n(checkbox, changelog)"];
@@ -100,12 +97,10 @@ digraph CodeDeveloper {
 
   work_type -> use_debug [label="debug"];
   work_type -> use_refactor [label="refactor"];
-  work_type -> use_optimize [label="optimize"];
   work_type -> implement [label="implement"];
 
   use_debug -> implement;
   use_refactor -> implement;
-  use_optimize -> implement;
 
   implement -> tdd_needed;
   tdd_needed -> use_tdd [label="YES"];
@@ -184,14 +179,13 @@ All require `*` prefix. Invocation commands in table above. Additional:
 
 | Situation | Delegate To |
 |-----------|-------------|
-| Bug encountered | `/debug-method` (use `/trace-back` when the error is deep in the stack) |
-| Error deep in stack | `/trace-back` |
-| Refactoring code | `/refactor` |
-| Need tests (when required) | `/test-generate` or `/tdd-flow` |
-| Writing any test | `/test-traps` (avoid mocks, production pollution) |
-| Before completion | `/verify-done` |
+| Bug encountered | `/root-cause` |
+| Error deep in stack | `/root-cause` (Phase 1, step 5) |
+| Refactoring code, or a perf problem | `/refactor` (its perf pass is on by default) |
+| Need tests (when required) | `/test-generate` |
+| Writing any test | AGENT_RULES.md → Testing Standards |
+| Before completion | Run the proof and read its output |
 | After code changes | `/security` |
 | 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/orchestrator.md

@@ -66,7 +66,7 @@ On-demand, read from these locations:
 | Resource | Global Paths | Local Path |
 |----------|--------------|------------|
 | Agents | `~/.config/amp/agents/*.md`, | `./.amp/agents/*.md` |
-| Commands | `~/.config/amp/commands/*.md` |`./.amp/commands/*.md` |
+| Skills | `~/.config/amp/skills/*/SKILL.md` | `./.amp/skills/*/SKILL.md` |
 
 Parse frontmatter for `name`, `description`, `when_to_use`. Present as numbered list.
 

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

@@ -59,13 +59,15 @@ digraph QualityAssurance {
 
 Before any analysis, read (if exists):
 - `AGENT.md` - Project instructions, patterns, conventions
+<!-- mirror:literal:start — names every tool's config file on purpose -->
 - `AGENT.md` / `AGENTS.md` - Agent configurations
+<!-- mirror:literal:end -->
 - `README.md` - Project overview
 - Test config files (`jest.config`, `pytest.ini`, etc.)
 
 ## Slash Commands Available
 
-Use these during analysis: `/branch-review`, `/security`, `/verify-done`
+Use these during analysis: `/branch-review`, `/security`
 
 ## Analysis Areas
 

package/packages/ampcode/{commands/brainstorming.md → skills/brainstorming/SKILL.md}

@@ -1,8 +1,7 @@
 ---
 name: brainstorming
 description: Use when creating or developing, before writing code or implementation plans - refines rough ideas into fully-formed designs through collaborative questioning, alternative exploration, and incremental validation. Don't use during clear 'mechanical' processes
-usage: /brainstorming <session-type> <topic>
-auto_trigger: false
+allowed-tools: Read, Grep, Glob
 ---
 
 # Brainstorming Ideas Into Designs
@@ -43,7 +42,7 @@ Start by understanding the current project context, then ask questions one at a
 
 **Implementation (if continuing):**
 - Ask: "Ready to set up for implementation?"
-- Create isolated workspace (use git worktrees if needed)
+- Create isolated workspace for implementation
 - Create detailed implementation plan
 
 ## Key Principles

package/packages/ampcode/{commands/branch-review.md → skills/branch-review/SKILL.md}

@@ -1,9 +1,9 @@
 ---
 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 *)
+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:*)
+disable-model-invocation: true
 ---
 Pre-merge review gate. Two stages — **general review** then a **full security
 audit** — followed by an adversarial verify pass. It **never edits code**: it
@@ -11,7 +11,7 @@ reports findings and hands them back. Fixing is a separate, separately
 authorized action.
 
 Only **Critical** and **High** findings block the merge. Everything else is
-appended to the **fix ledger** (`.claude/remember/fix-ledger.md`) — a local,
+appended to the **fix ledger** (`.amp/remember/fix-ledger.md`) — a local,
 cumulative list, living beside `MEMORY.md`, that `/refactor` (no arguments)
 works through between features. Like its neighbours it is a private working
 artifact, usually gitignored; it persists across reviews, it is not a
@@ -44,17 +44,17 @@ at the current HEAD SHA.
   review of a report. (Same rule `/security` carries inside stage 2.)
 - **No edits — two exceptions.** You have no authorization to change code,
   even for a finding you are certain about. Report it. The only files you may
-  write are `.claude/remember/fix-ledger.md` (append bullets; never rewrite or
-  delete) and `.claude/remember/last-review.md` (overwrite; the review record
+  write are `.amp/remember/fix-ledger.md` (append bullets; never rewrite or
+  delete) and `.amp/remember/last-review.md` (overwrite; the review record
   described at the end of this file).
 - **Prove it with two checks, because neither sees what the other does.**
   `git status --porcelain`, at start and again before you report, proves no
   **tracked** file changed — that is the "never edits code" guarantee, and it
-  is the one that matters. It cannot police your own two writes: `.claude/`
+  is the one that matters. It cannot police your own two writes: `.amp/`
   is normally gitignored, so porcelain stays empty whether you wrote the
   allowed files, wrote nothing, or overwrote `MEMORY.md`. `git status
-  --ignored` does not close it either — it collapses to `!! .claude/`, the
-  directory, not the files. So also take `md5sum .claude/remember/*` before
+  --ignored` does not close it either — it collapses to `!! .amp/`, the
+  directory, not the files. So also take `md5sum .amp/remember/*` before
   you start and again before you report, and show the comparison: only
   `fix-ledger.md` and `last-review.md` may differ.
 
@@ -95,11 +95,25 @@ Record the **HEAD SHA** you reviewed, and **report the target you resolved**
 (the literal range or path) in your output, so the orchestrator can see what
 was actually read rather than assuming.
 
-**Re-review after fixes: read `.claude/remember/last-review.md` first.** Its
+**Re-review after fixes: read `.amp/remember/last-review.md` first.** Its
 `sha:` line is the previously-reviewed commit and its `blockers:` list is what
 you owe an answer on — take both from the file, never from the orchestrator's
 recollection, for the same reason `/release` does. Then:
 
+- **First, check the record belongs to this branch.** There is one record file
+  per repo, not one per branch. Validate `<that sha>` first with
+  `git rev-parse --verify <that sha>` — a value that fails this (e.g. a
+  corrupted or hand-edited record, or one starting with `-`, which git would
+  otherwise parse as an option) is a malformed record; treat it exactly as
+  **No file** below. If it validates, and its `branch:` line differs from the
+  current branch, or `git merge-base --is-ancestor <that sha> HEAD` exits
+  non-zero, the record describes a different or rewritten history — treat it
+  exactly as **No file** below and review the whole branch. Skipping this
+  resolves `<that sha>..HEAD` against a merged, renamed, or rebased sha, which
+  is not a subset of this branch but a range that never existed. Check both:
+  the branch name catches a switch, the ancestry check catches a rebase or
+  squash under the same name. Otherwise:
+
 - **`sha:` ≠ HEAD** → this is a re-review. Target the range
   `<that sha>..HEAD`. Stage 1 reads only the commits since, and stage 3
   re-verifies each recorded blocker as fixed, unfixed, or dismissed with a
@@ -231,7 +245,7 @@ check before escalating.
 
 ### Ledger (non-blocking — medium / low)
 Not in the report. **Append** each one as a single bullet to
-`.claude/remember/fix-ledger.md` (create the file with the header below if
+`.amp/remember/fix-ledger.md` (create the file with the header below if
 missing):
 
 ```
@@ -256,7 +270,7 @@ with `UNVERIFIED:` so `/refactor` retests before acting.
 The **snippet is the anchor**: 20–60 verbatim characters from the line,
 unique enough for `git grep -F` to find it after lines shift. No line
 numbers, no TODO comments in code — the ledger is the single writer. Before
-appending, dedupe with **plain `grep -F "<snippet>" .claude/remember/fix-ledger.md`**;
+appending, dedupe with **plain `grep -F "<snippet>" .amp/remember/fix-ledger.md`**;
 if it is already there, skip it. Do not touch existing bullets.
 
 **A bullet you disprove is deleted, not annotated.** If you establish that an
@@ -280,7 +294,7 @@ Then a coverage line: stage 1 at level `<level>`, stage 2 full, stage 3 —
 each `ran ✓/✗` with its evidence. A stage you did not actually run is a **✗**, never an
 assumed pass.
 
-**Write the review record** to `.claude/remember/last-review.md`, overwriting
+**Write the review record** to `.amp/remember/last-review.md`, overwriting
 it. `/release` reads this file; a SHA that lives only in a chat message is
 gone after a compaction or a handover, and the only remaining source is the
 orchestrator — the one party this command already refuses to take a review's
@@ -326,7 +340,7 @@ does not move — which means nothing was fixed, which is the correct outcome.
 
 End with:
 - **Reviewed at HEAD `<sha>` on `<branch>`, target `<resolved range or path>`,
-  tree clean at start; at exit clean or the two `.claude/remember/` paths
+  tree clean at start; at exit clean or the two `.amp/remember/` paths
   only.**
 - **Fix ledger: N open, M added this run** (N = bullet count). When N > 0,
   add: "N fixes waiting — run `/refactor` between features." The ledger is a

package/packages/{claude/commands/docs-builder.md → ampcode/skills/docs-builder/SKILL.md}

@@ -1,9 +1,9 @@
 ---
 name: docs-builder
 description: Reorg a docs corpus, split an oversized doc, search it, keep pages current, index them
-usage: /docs-builder [reorg | cleanup <file.md> | search <query words...>]
 argument-hint: [reorg | cleanup <file.md> | search <query words...> — empty asks first run vs. drift]
 allowed-tools: Read, Write, Edit, Grep, Glob, Task, AskUserQuestion, Bash(node:*), Bash(git:*), Bash(rg:*)
+disable-model-invocation: true
 ---
 
 # docs-builder

package/packages/ampcode/{commands/live-canvas.md → skills/live-canvas/SKILL.md}

@@ -1,6 +1,7 @@
 ---
 name: live-canvas
 description: Conduct design interviews, generate UI variations, and collect live click-to-annotate feedback that streams into the session so edits land without leaving the browser. Use when the user wants rapid iterative UI refinement, not just batched feedback.
+allowed-tools: Read, Grep, Glob
 ---
 
 # Live Canvas Skill
@@ -26,7 +27,7 @@ Live Canvas supports two feedback transports. **The user picks every time** —
 
 ### Host detection — do this first
 
-This SKILL.md is the Claude Code variant of the skill. Same content is mirrored as docs for Droid/Amp/Opencode under `packages/<tool>/commands/live-canvas/`, but those tools don't support the MCP channel.
+This SKILL.md is the Claude Code variant of the skill. Same content is mirrored as docs for Droid/Amp/Opencode under `packages/<tool>/` beside the other capabilities, but those tools don't support the MCP channel.
 
 **If running under Droid, Amp, or Opencode (not Claude Code):**
 - Skip the mode question entirely.
@@ -109,6 +110,8 @@ Or pick JSON now to stay in this session — feedback gets written to a file
 you paste back here. No relaunch needed.
 ```
 
+<!-- mirror:literal:start — Live mode is the Claude Code MCP plugin; these are
+     Claude's real paths in every kit, because no other tool can install it -->
 **Case C — first-time setup block:**
 
 ```
@@ -125,6 +128,7 @@ Live mode needs a one-time install. Two steps:
 That's it — once the plugin is installed, /live-canvas in any session can
 claim the channel. Re-run /live-canvas and pick Live.
 ```
+<!-- mirror:literal:end -->
 
 Do not try to run any of these commands yourself. Three reasons:
 1. The `/plugin` steps are Claude Code slash commands — not doable from inside a running session.
@@ -418,7 +422,7 @@ Create all files under `.claude-design/`:
 
 ### The overlay
 
-**One template, every framework:** `~/.claude/skills/live-canvas/templates/overlay-vanilla.js`. Single file, zero dependencies, plain DOM. Works in vanilla JS, Vue, Svelte, Rails, Django, Phoenix, plain HTML, Next.js, Vite-React, Remix — anywhere a `<script>` tag runs.
+**One template, every framework:** `~/.config/amp/skills/live-canvas/templates/overlay-vanilla.js`. Single file, zero dependencies, plain DOM. Works in vanilla JS, Vue, Svelte, Rails, Django, Phoenix, plain HTML, Next.js, Vite-React, Remix — anywhere a `<script>` tag runs.
 
 Copy it into a directory served by the dev server (e.g. `public/overlay-vanilla.js` for Next.js, `static/overlay-vanilla.js` for Vite, the public dir for Rails/Django). Reference it from the lab page.
 
@@ -545,7 +549,7 @@ The Live Canvas page must include:
 1. **Header** with:
    - Design Brief summary (target, scope, key requirements)
    - Instructions for reviewing
-   - **Lab banner (REQUIRED)** — paste `~/.claude/skills/live-canvas/templates/lab-banner.html` at the top of the lab page. Same text in any mode. For React/TSX labs, translate the inline style to a JS object: camelCase keys, string values. E.g. `style="border-radius:8px; padding:10px 14px; font-size:13px"` → `style={{ borderRadius: '8px', padding: '10px 14px', fontSize: '13px' }}`. Keep the text and `role="note"`.
+   - **Lab banner (REQUIRED)** — paste `~/.config/amp/skills/live-canvas/templates/lab-banner.html` at the top of the lab page. Same text in any mode. For React/TSX labs, translate the inline style to a JS object: camelCase keys, string values. E.g. `style="border-radius:8px; padding:10px 14px; font-size:13px"` → `style={{ borderRadius: '8px', padding: '10px 14px', fontSize: '13px' }}`. Keep the text and `role="note"`.
 
 2. **Variant Grid** with:
    - Clear labels (A, B, C, D, E)
@@ -568,7 +572,7 @@ The Live Canvas page must include:
 
    The overlay (`overlay-vanilla.js`) enables users to click on elements and leave comments. Without it, the Live Canvas is just a static page with no way to collect structured feedback.
 
-   - Copy `~/.claude/skills/live-canvas/templates/overlay-vanilla.js` into a directory served by the dev server (e.g. `public/`, `static/`, or wherever the framework serves static assets).
+   - Copy `~/.config/amp/skills/live-canvas/templates/overlay-vanilla.js` into a directory served by the dev server (e.g. `public/`, `static/`, or wherever the framework serves static assets).
    - Reference it from the lab page via `<script>` tag and call `LiveCanvas.init({...})` once with `target`, `channelUrl` (Live mode), and optional `batchEndpoint`. See "Wiring the overlay" above for the exact snippets per framework.
    - Every variant container in the lab page MUST have a `data-variant="X"` attribute (A, B, C, D, E, or F). The overlay uses this to route comments to the right variant file.
 

package/packages/ampcode/{commands/refactor.md → skills/refactor/SKILL.md}

@@ -1,11 +1,12 @@
 ---
 name: refactor
-description: Refactor [code]
-usage: /refactor <code-section> | /refactor (no args = fix-ledger mode)
+description: Refactor and optimize [code]
 argument-hint: [file-or-function, or empty for the fix ledger]
-allowed-tools: Read, Edit, Grep, Glob, Bash(npm test *), Bash(npx jest *), Bash(npx vitest *), Bash(pnpm test *), Bash(yarn test *), Bash(pytest *), Bash(python *), Bash(go test *), Bash(cargo test *), Bash(make test *), Bash(git diff *), Bash(git grep *), Bash(git status *), Bash(git rev-parse *), Bash(git switch *)
+allowed-tools: Read, Edit, Grep, Glob, Bash(npm test:*), Bash(npx jest:*), Bash(npx vitest:*), Bash(pnpm test:*), Bash(yarn test:*), Bash(pytest:*), Bash(python:*), Bash(go test:*), Bash(cargo test:*), Bash(make test:*), Bash(git diff:*), Bash(git grep:*), Bash(git status:*), Bash(git rev-parse:*), Bash(git switch:*)
+disable-model-invocation: true
 ---
-Refactor $ARGUMENTS.
+Refactor $ARGUMENTS. A targeted refactor includes the performance pass
+below — it is on by default, not a separate command.
 
 ## Guardrails
 - **Spawn a worker and explicitly select your tool's mid tier.** State the
@@ -44,15 +45,15 @@ Refactor $ARGUMENTS.
   other does.** `git status --porcelain` at exit must list only files a
   surviving bullet named — that is this command's scope guarantee, and unlike
   `/branch-review` it is not expected to be empty. It cannot police the
-  memory directory: `.claude/` is normally gitignored, so porcelain stays
+  memory directory: `.amp/` is normally gitignored, so porcelain stays
   empty whether you deleted a fixed bullet, wrote nothing, or overwrote
-  `MEMORY.md`. So also take `md5sum .claude/remember/*` before you start and
+  `MEMORY.md`. So also take `md5sum .amp/remember/*` before you start and
   again before you report, and show the comparison: only `fix-ledger.md` may
   differ. `last-review.md` in particular is `/branch-review`'s to write —
   a fixer that touches it forges the gate that judges its own work.
 
 ## Ledger mode — `$ARGUMENTS` empty
-Work through `.claude/remember/fix-ledger.md`, the non-blocking findings
+Work through `.amp/remember/fix-ledger.md`, the non-blocking findings
 `/branch-review` has accumulated. Everything below (goals, constraints,
 verification, HITL gates) still applies; this section only says what to
 refactor and how to close each item.
@@ -87,6 +88,35 @@ refactor and how to close each item.
 - Apply DRY
 - Better naming
 - Smaller functions (single responsibility)
+- Remove needless work — the performance pass below
+
+## Performance — part of every targeted refactor
+When `$ARGUMENTS` names a target, look for wasted work as well as messy
+work: time and space complexity, N+1 queries, I/O inside a loop, needless
+allocations, the same value recomputed repeatedly.
+
+**Ground every finding before you touch it.** Performance claims are easy
+to invent. A finding counts as **confirmed** only with at least one of:
+- a profile, benchmark or log line showing call frequency or duration,
+- the path sits on an obvious hot loop or per-request handler with real
+  volume,
+- the user supplied evidence in the request.
+
+Without one of those it is **uncertain — report it, do not optimise it.**
+Speculative optimisation is scope creep with a stopwatch.
+
+Fix confirmed findings under the same constraints as any other refactor:
+minimal change, one obvious shape, no behaviour change, no API change.
+After each such edit, re-read the changed region and confirm it still
+computes the same answer — a perf change that quietly alters semantics is
+the worst kind. Report per finding: **location** (`file:line`), **cost**
+(concrete — "N+1 over ~1k rows on every page load", not "could be
+faster"), **change**, **expected improvement**, **trade-off**
+(readability / memory / consistency).
+
+In ledger mode the surviving bullets are the whole scope — do not add
+perf findings of your own. One you notice goes back to the orchestrator
+as a new bullet, like any other side finding.
 
 ## Constraints
 - **NO behavior changes**
@@ -120,8 +150,20 @@ honest way to know is to run them.
 - the change is **bigger than the user asked for** (scope creep —
   unrelated cleanups, formatting, comment edits). Confirm before
   applying.
+- a perf fix has **multiple reasonable shapes** (cache vs precompute vs
+  batch vs paginate vs index) — present the options with trade-offs, not
+  a chosen path.
+- a perf fix trades **correctness for speed** (lossy approximation,
+  weaker or eventual consistency) — even when it is "obviously" faster.
+- a perf fix touches **concurrency primitives** (locks, atomics,
+  ordering) — easy to introduce a race.
+- a perf fix changes a **DB schema, response shape or caller contract**.
 
 Final report:
 - **refactor done, tests N pass / 0 fail** — ready, OR
 - **refactor done, but K tests fail** — awaiting direction (revert /
   patch / update test).
+
+Plus the performance pass: **confirmed-and-fixed** · **confirmed-but-asking**
+(why + options) · **uncertain** (what profiling or data would settle it) ·
+**none found**.

package/packages/ampcode/{commands/release.md → skills/release/SKILL.md}

@@ -1,8 +1,8 @@
 ---
 name: release
 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 *)
+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:*)
+disable-model-invocation: true
 ---
 Release **preparation** orchestrator for the **current branch**. It runs your
 existing pre-deploy gate, sweeps the docs, bumps the version and commits —
@@ -57,7 +57,7 @@ A review must have run on this branch **at the current HEAD SHA**.
 
 **Compare the SHAs yourself; do not settle for an answer.** Run `git rev-parse
 HEAD` and compare it against the `sha:` line in
-`.claude/remember/last-review.md`, which `/branch-review` writes. Asking the
+`.amp/remember/last-review.md`, which `/branch-review` writes. Asking the
 orchestrator "did a review run?" puts the question to the one party with an
 incentive to say yes, so its word is not evidence — and neither is a SHA
 quoted from a chat message, which is the same claim in another costume and is
@@ -72,7 +72,7 @@ that predates this file's introduction has no record, so it does not count.
   is what makes "all findings fixed" checkable instead of promised.
   **No exceptions — including the fix ledger.** It is normally gitignored, so
   appending to it moves nothing and this never comes up. A repo that tracks
-  `.claude/` instead will see a ledger commit land after the review and make
+  `.amp/` instead will see a ledger commit land after the review and make
   it stale. That is the rule working, not a case to carve out: re-review, or
   leave the ledger uncommitted until after the release.
 - **`coverage:` naming any stage `NOT RUN`** → **stop**. A `ready` from a run

package/packages/{claude/commands → ampcode/skills}/remember/AGENT_RULES.md

@@ -130,90 +130,50 @@ A problem you see and don't fix goes in the report, never in a comment. Comments
 
 ## Testing Standards
 
-### Rules
-
-**Test behavior, not implementation.** A test suite must give you confidence to refactor freely. If changing internal code (without changing behavior) breaks tests, those tests are liabilities, not assets.
-
-**Follow the Testing Trophy** (not the Testing Pyramid):
-- Few unit tests — only for pure logic, algorithms, and complex calculations
-- Many integration tests — the sweet spot; test real components working together
-- Some E2E tests — cover critical user journeys end-to-end
-- Static analysis — types and linters catch bugs cheaper than tests
-
-### When to Write Tests
-
-- **After the design stabilizes, not during exploration.** Do not TDD a prototype — you'll write 500 tests for code you delete tomorrow. First make it work (POC), then make it right (refactor + tests), then make it fast
-- **Write tests when the code has users.** If a function is called by other modules or exposed to users, it needs tests. Internal helpers that only serve one caller don't need their own test file
-- **Write tests for bugs.** Every bug fix must include a regression test that fails before the fix and passes after. This is the highest-value test you can write
-- **Write tests before refactoring.** Before changing working code, write characterization tests first to lock in current behavior, then refactor with confidence
-- **Do not write tests for glue code.** Code that just wires components together (calls A then B then C) is tested at the integration level, not unit level
-
-### TDD: When It Works and When It Doesn't
-
-- **TDD works for:** Pure functions, algorithms, parsers, validators, data transformations — anything with clear inputs and outputs
-- **TDD does not work for:** Exploring a design, building a POC, or unstable interfaces. Writing tests for unstable APIs creates churn and false confidence
-- **The rule:** You must understand what you're building before you TDD it. TDD is a design tool for known problems, not a discovery tool for unknown ones
-- **Red-green-refactor discipline:** If you do TDD, follow the cycle strictly. Write a failing test, write minimal code to pass, refactor. Do not write 20 tests then implement — that's front-loading waste
-
-### What Makes a Good Test
-
-- **Tests real behavior.** Call the public API, assert on observable output. Do not reach into internals
-- **Fails for the right reason.** A good test fails when the feature is broken, not when the implementation changes
-- **Reads like a spec.** Someone unfamiliar with the code must understand what the feature does by reading the test
-- **Self-contained.** Each test sets up its own state, runs, and cleans up. No ordering dependencies between tests
-- **Fast and deterministic.** Flaky tests erode trust. If a test depends on timing, network, or global state, fix that dependency
-
-### Anti-Patterns — Do Not Do These
-
-- **Mocking more than 60% of the test.** If most of the test is mock setup, you're testing mocks, not code. Use real implementations with `tmp_path`, `:memory:` SQLite, or test containers
-- **Smoke tests.** `assert result is not None` proves nothing. Assert on specific values, structure, or side effects
-- **Testing private methods.** If you need to test a private method, either it should be public or the public method's tests should cover it
-- **Mirroring implementation.** Tests that replicate the source code line-by-line break on every refactor and catch zero bugs
-- **Test-only production code.** Never add methods, flags, or branches to production code solely for testing. Use dependency injection instead
-
-### Test Organization
-
-- **Co-locate tests with packages:** `packages/<pkg>/tests/` not a root `tests/` directory. Each package owns its tests
-- **Separate by type:**
-  ```
-  packages/<pkg>/tests/
-    unit/           # Fast, isolated, mocked deps, <1s each
-    integration/    # Real DB, filesystem, multi-component, <10s each
-    e2e/            # Full workflows, subprocess calls, <60s each
-    conftest.py     # Shared fixtures for this package
-  ```
-- **One test file per module** (not per function). `test_auth.py` tests the auth module, not `test_login.py` + `test_logout.py` + `test_session.py`
-- **No duplicate test files.** Before creating a new test file, check if one already exists for that module
-
-### Markers and Signals
-
-| Marker | Purpose | CI Behavior |
-|--------|---------|-------------|
-| `@pytest.mark.slow` | Runtime > 5s | Run in full suite, skip in quick checks |
-| `@pytest.mark.ml` | Requires ML deps (torch, etc.) | Skip if deps not installed |
-| `@pytest.mark.real_api` | Calls external APIs | Skip in CI — run manually before release |
-
-**CI runs for fast signals:**
-- `pytest -m "not slow and not ml and not real_api"` — fast gate on every push (~30s)
-- `pytest` — full suite on PR merge or nightly
-- Package-level runs for targeted debugging: `pytest packages/core/tests/`
-
-### Coverage and Ratios
-
-- **Do not chase a coverage number.** 80% coverage with meaningless tests is worse than 40% with behavior-testing integration tests
-- **Cover the critical path first.** Data layer, auth, payment, core business logic — before helper utilities
-- **Coverage tells you what's NOT tested, not what IS tested.** High coverage with bad assertions is false confidence
-- **Delete tests that don't catch bugs.** If a test has never failed (or only fails on refactors), it's not providing value
-
-**Target ratio:** ~20% unit, ~60% integration, ~15% E2E, ~5% manual/exploratory
-
-### Test Tooling Standards
-
-- Use `tmp_path` for filesystem tests, `:memory:` or `tmp_path` SQLite for DB tests
-- Use dependency injection over `@patch` — it's more readable and survives refactors
-- Tests must be self-sufficient — no dependency on project directories, user config, or environment state
-- Use factories or builders for test data, not raw constructors with 15 arguments
-- Keep test fixtures close to where they're used. Shared fixtures in `conftest.py`, not a global test utilities package
+Principles, not a framework. Whatever the language, follow its ecosystem's conventions for
+runner, layout and fixtures — these rules govern what a test must *do*, never how a
+particular toolchain spells it.
+
+### What a test is for
+
+**Test behavior, not implementation.** A suite must give you confidence to refactor freely. If changing internal code without changing behavior breaks tests, those tests are liabilities, not assets.
+
+**Shape — the Testing Trophy, not the Pyramid:** static analysis catches the cheapest bugs; few unit tests, for pure logic and algorithms; many integration tests, the sweet spot, real components working together; some end-to-end tests over the critical journeys. Target roughly 20% unit, 60% integration, 15% E2E, 5% manual.
+
+### When to write them
+
+- **After the design stabilizes, not during exploration.** Do not test a prototype — you will write tests for code you delete tomorrow. First make it work (POC), then make it right (tests), then make it fast
+- **Tests first when you already know the contract.** Pure functions, algorithms, parsers, validators, data transformations — write the test, watch it fail, then implement. When you are still discovering the interface, that same discipline produces churn and false confidence
+- **Write tests for bugs.** Every fix ships a regression test that fails before the fix and passes after — the highest-value test there is
+- **Write tests before refactoring.** Characterization tests lock in current behavior first, then change the code
+- **Write tests when the code has users.** Called by other modules or exposed externally means it needs tests; a helper serving one caller does not need its own file
+- **Do not test glue code.** Something that only wires A to B to C is covered at the integration level
+
+### What makes a good test
+
+- **Tests real behavior.** Call the public interface, assert on observable output. Never reach into internals
+- **Fails for the right reason.** It breaks when the feature breaks, not when the implementation moves
+- **Reads like a spec.** Someone new to the code should learn what the feature does by reading it
+- **Self-contained.** Sets up its own state, runs, cleans up. No ordering dependencies, and no reliance on project directories, user config, or ambient environment
+- **Deterministic.** Flaky tests erode trust. A dependency on timing, network, or global state is a defect in the test
+- **Never sleep for a condition — poll for it.** Sleeping then asserting is wrong at every value: too short and it flakes under load, too long and the suite drags, and a real async bug looks identical to a guess that was too short. Wait on the condition itself, re-reading the state *inside* the loop, with a timeout that names what it was waiting for. A fixed delay is only correct once you have waited for the triggering condition, the delay comes from a documented interval rather than a guess, and a comment says why
+
+### Anti-patterns
+
+- **Mocking most of the test.** If mock setup outweighs the logic, you are testing mocks. Prefer the real thing against a temporary directory, an in-memory store, or a disposable container
+- **Partial mocks.** Mirror the complete structure the real thing returns, not only the fields this test reads. A mock missing a field downstream code consumes passes here and fails in production
+- **Smoke tests.** Asserting a result merely exists proves nothing. Assert on specific values, structure, or side effects
+- **Testing private internals.** If it needs its own test, it should be part of the public interface; otherwise the public tests should reach it
+- **Mirroring implementation.** A test that restates the source line by line breaks on every refactor and catches nothing
+- **Test-only production code.** Never add a method, flag, or branch to production solely for tests. Inject the dependency instead
+- **Chasing a coverage number.** 80% of meaningless tests is worse than 40% of behavioural ones. Coverage tells you what is *not* tested, never that what is covered is correct. Cover the critical path first — data, auth, money, core logic — before helpers
+
+### Organization
+
+- **Mirror the source structure**, at whatever level the ecosystem puts tests. One test file per module, not per function, and never a second file covering a module that already has one
+- **Separate by cost so CI gets a fast signal.** Keep quick isolated tests apart from ones needing real IO or a full workflow, and let the slow ones — long runtimes, heavy optional dependencies, live external APIs — be excluded from the gate that runs on every push and included in the full run
+- **Fixtures live near what uses them**, shared upward only when genuinely shared. Build test data with factories or builders, never a constructor taking fifteen positional arguments
+- **Delete tests that never catch anything.** A test that has only ever failed during refactors is a maintenance cost, not a safety net
 
 ---