liteagents 2.9.0 → 2.10.0

package/CHANGELOG.md

@@ -17,6 +17,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [2.10.0] - 2026-06-16
+
+### Changed
+- **`/friction` collapsed into `/remember`; the hot-memory pipeline is now two commands (`/stash → /remember`), down from three.** `/remember` now runs `friction.js` itself as a best-effort first step before consolidating — so the antigen data is always fresh and friction can't be forgotten. Friction targets the tool's **global sessions root** (all projects, since behavioral patterns are cross-project), resolved from an editable, never-prompt probe list baked into `remember.md` (Claude Code, Droid/Factory, Amp, opencode, plus Codex and Antigravity roots; add your own at the top). A no-sessions miss is surfaced **loudly** and degrades to stash-only — never a silent skip. The standalone `/friction` command was removed across all four packages (the `friction.js` script stays, directly runnable for inspection). Counts: claude commands 9→8, droid/opencode/ampcode 17 each.
+- **`/stash` now nudges toward consolidation.** After saving, it derives the unprocessed backlog (`stash files − .processed manifest entries`) and, at ≥5, emits a one-line prompt to run `/remember`. No counter is stored — the count is derived from ground truth, and running `/remember` clears it. The nudge is informational; `/remember` never runs automatically.
+
+### Fixed
+- **`friction.js` no longer crashes on a single malformed JSONL line.** The four mirrored copies parsed session logs and `friction_raw.jsonl` with bare `.map(line => JSON.parse(line))` — one corrupt line aborted the whole run. A new `parseJsonl(raw, source)` helper skips bad lines with a one-line stderr warning (line number + source) and keeps the good records; the whole-file `friction_analysis.json` read is now wrapped in a try/catch that reports the file and bails with exit 1 instead of throwing. Mirrored identically (modulo `.claude`/`.factory`/`.opencode`/`.amp` branding) across all four tool packages.
+- **`packages/subagentic-manual.md` restored after a range-sed corrupted ~310 lines.** A `sed '/start/,/end/{s/.../...}'` earlier this session had `test-generate$` as the end pattern; the range matched far past its intended scope (later occurrences in tree diagrams and category bullets), overwriting the entire tail of the document — Subagents reference, Commands reference, Hot Memory, Usage Patterns, Platform Architecture, Frontmatter Architecture, Contributing — with ~310 duplicate copies of the "Simple Commands" bullet. Restored from the pre-corruption snapshot and re-applied all the renames + count updates that should have happened cleanly. Same fix mirrored to `agentic-toolkit/ai/subagentic/subagentic-manual.md`.
+
+### Changed
+- **Root `package.json` `engines.node` bumped `>=14.0.0` → `>=18.0.0`.** Node 14 has been EOL since 2023-04; the floor now matches the bundled `live-canvas-channel` plugin (`>=18`) and sits well under what CI publishes on (Node 22). As a minimum it excludes no one currently on a supported runtime.
+- **`/review` renamed to `/diff-review` across all four tool packages.** Avoids the name collision with the Anthropic-official `code-review` plugin (which also ships a skill named `review` that operates on PRs). `/diff-review` is more accurate to what the command does — it operates on a diff (staged, working tree, branch range, or against a ref), not on a remote PR. Mirrored into `~/.claude/commands/` and all docs/agents/`opencode.jsonc` references swept.
+- **`/diff-review` absorbed `/code-review`; collapsed to a single command across all four tool packages.** `/diff-review` now accepts a file, a branch (`/diff-review main` diffs `merge-base(main, HEAD)..HEAD` — the common "review my branch before merging" path), or an explicit range (`main..HEAD`). It bakes in the user's standing review focus: bugs needing a fix, dead code, loose ends (added TODO/FIXME, swallowed errors, stubs, abandoned flags), correctness, security, performance, maintainability.
+- **`/diff-review` and `/security` now verify findings, selectively auto-fix, and stop to ask only when needed.** After listing findings, each cited `file:line` is re-grounded in context (and `git grep`'d for dead-code claims) and marked confirmed / false-positive / uncertain. Confirmed + unambiguous + no-contract-change fixes apply directly; the changed region is re-read after the edit. HITL gates fire only for: uncertain findings, multiple reasonable fix shapes, downstream-affecting changes (signatures / response shape / schema / public symbol removal), security primitives (auth / crypto / session / token), or "dead code" that looks intentionally kept. `/diff-review` ends with a one-line **Ready to merge? Yes / No / With fixes** verdict.
+- **Skills renamed to short 2-word slugs (round 2).** `testing-anti-patterns` → **`test-traps`** (now includes timing/polling as AP6 after the fold). `test-driven-development` → **`tdd-flow`** (slug short, H1 short, `TDD` prose preserved as the industry term). `verification-before-completion` → **`verify-done`** (rhythmically mirrors `test-first`). Round 2 paired with round 1 (`systematic-debugging` → `debug-method`, `root-cause-tracing` → `trace-back`) gives a scannable cluster: `tdd-flow / test-generate / test-traps` and `debug-method / trace-back / verify-done`. All references swept across docs, agent files, opencode.jsonc, and the debug-method skill's cross-refs.
+- **Skills renamed to short 2-word slugs (round 1).** `systematic-debugging` → **`debug-method`** (the 4-phase framework with its 4 pressure-test scenarios + creation log preserved). `root-cause-tracing` → **`trace-back`** (the backward-tracing technique with its `find-polluter.sh` bisection helper preserved). Names are shorter, cluster alphabetically under `debug-`, and the "method vs technique" split is now obvious at a glance. All references swept across docs, agent files, and the debug-method skill's internal cross-refs to trace-back.
+- **`/test-generate` rewritten as a generate-and-verify loop, not just a generator.** New flow: discover the existing test framework (refuses to add a new runner) → mirror nearby tests for style/fixtures → generate happy / edge / error cases → **run the new tests** with the project's real test command → **verify each test bites** (mentally swap a broken impl — does the assertion catch it?). Superficial tests (`expect(true).toBe(true)`, mock-asserting-itself, setup-masked passes) count as a failure to ship. Same claim → verify → report shape as `/diff-review` and `/security`. HITL gates: a meaningful test would require a non-obvious design change in production code, ambiguous existing test patterns, or a mock style the project doesn't currently use.
+- **`/optimize` now verifies bottleneck claims before optimizing.** Each cited `file:line` must have at least one of: a profile / benchmark / log line showing call frequency or duration, an obvious hot loop / per-request handler, or user-provided evidence. Unverified claims are marked **uncertain — don't optimize on speculation**. Auto-fixes only when confirmed + unambiguous + no behavior/API change. HITL gates: uncertain (no profile), multiple reasonable shapes (cache vs precompute vs batch vs paginate vs index), public-API / response / schema changes, correctness-for-speed trades, or concurrency primitives.
+- **`/refactor` now runs the tests after the edit.** The "existing tests must pass" constraint was load-bearing but unverified — `/refactor` now detects the project's test command (`package.json` scripts, `pytest`, `go test`, `cargo test`, `Makefile`), runs it scoped to the affected area when possible, and reports pass/fail. If tests fail it **stops and asks** with three options (revert / patch the refactor / update the test with reasoning) rather than auto-reverting (destroys work) or pushing forward (breaks the invariant). Also stops on scope creep and public-API-boundary changes.
+- **`condition-based-waiting` folded into `test-traps` as Anti-Pattern 6: Timeout-Based Waiting.** The two skills covered the same domain (test quality) but only one auto-triggered; folding promotes the timing/polling guidance to auto-trigger coverage. The `example.ts` helper (domain-specific `waitForEvent` / `waitForEventCount` / `waitForEventMatch`) moves with it and is referenced from AP6. Counts: claude skills 10 → 9; droid/opencode/ampcode commands 19 → 18.
+- **CI:** the publish workflow now polls the npm registry for ~2 min (was ~15s; `--prefer-online` skips npm's view cache) and accepts an `exit 0` publish even if the registry hasn't reflected it yet, so a successful-but-slow-to-reflect publish no longer reports a false failure.
+- **`publish.yml` is now manual-only (`workflow_dispatch`) — npm OIDC trusted publishing with provenance, idempotent, and verifies the registry end-state.**
+- **`publish.yml` install step `npm ci` → `npm install`.** This toolkit is dependency-free (no `package-lock.json`), so `npm ci` failed with `EUSAGE`; `npm install` is a fast no-op here and still works if deps are ever added. Removed the superseded manual `scripts/publish.sh` (NPM_TOKEN-via-`pass` flow) — publishing now goes solely through the `publish.yml` GitHub Actions workflow.
+
+### Removed
+- `/code-review` (was: workflow ceremony about *when* to request a review, mostly overlapping `/diff-review`'s purpose). Use `/diff-review` instead — `/diff-review main` for branch-vs-main, `/diff-review` with no args for staged/working-tree.
+- **`/debug`** — was a thin 17-line echo of the `systematic-debugging` skill. The skill (now `debug-method`) carries the real workflow with its pressure-test scenarios; the command added nothing.
+- **`/explain`** — was 11 lines of "explain this code" with no real constraints or workflow. The model does this naturally from a plain prompt.
+- **`/git-commit`** — Claude Code has built-in commit handling and the other three tools don't need a thin wrapper around `git diff --staged` + a templated message either. Use natural-language prompts instead.
+
+---
+
 ## [2.9.0] - 2026-05-26
 
 Redesign of the `/friction` → `/remember` memory pipeline so friction stops poisoning hot memory and antigens come from what the user actually said. Applied identically across all four tool packages (claude, opencode, ampcode, droid).

package/README.md

@@ -9,7 +9,7 @@
          ╚══════╝╚═╝   ╚═╝   ╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝
 ```
 
-**AI development toolkit with 11 specialized agents and 23 commands per tool**
+**AI development toolkit with 11 specialized agents and 17 commands per tool**
 
 <p align="center">
   <img src="https://img.shields.io/github/package-json/v/hamr0/liteagents?label=version&color=2a4f8c" alt="version (auto from package.json)">
@@ -45,10 +45,10 @@ liteagents
 
 ### Supported Tools
 
-- **Claude Code** - 11 subagents + 11 skills + 12 commands (+ optional live-canvas channel plugin)
-- **Opencode** - 11 agent references + 23 commands
-- **Ampcode** - 11 subagents + 23 commands
-- **Droid** - 11 agent references + 23 commands
+- **Claude Code** - 11 subagents + 9 skills + 8 commands (+ optional live-canvas channel plugin)
+- **Opencode** - 11 agent references + 17 commands
+- **Ampcode** - 11 subagents + 17 commands
+- **Droid** - 11 agent references + 17 commands
 
 **Key Difference:**
 - **Claude Code**: Full subagent system with orchestrator + skills (auto-triggering)
@@ -61,30 +61,29 @@ liteagents
 @orchestrator help
 @1-create-prd Create a PRD for a task management app
 /brainstorming Explore authentication approaches
-/test-driven-development Implement user login
+/tdd-flow Implement user login
 
 # Opencode/Ampcode/Droid examples
 /1-create-prd Create a PRD for a task management app
 /brainstorming Explore authentication approaches
-/test-driven-development Implement user login
+/tdd-flow Implement user login
 ```
 
 ---
 
 ## Hot Memory — project-local learning from your own sessions
 
-Liteagents ships a three-command pipeline that turns Claude Code's session logs into project-local memory. No databases, no external services, just markdown files the assistant reads via `@MEMORY.md`.
+Liteagents ships a two-command pipeline that turns Claude Code's session logs into project-local memory. No databases, no external services, just markdown files the assistant reads via `@MEMORY.md`.
 
 ```
-/stash  →  /friction  →  /remember
-capture    analyze        consolidate
+/stash  →  /remember
+capture    analyze + consolidate
 ```
 
-- **`/stash`** — snapshot the current session's context before compaction or handoff
-- **`/friction`** — mine JSONL session logs for frustration signals, failed flows, and abandonment patterns; cluster them into antigen candidates per project
-- **`/remember`** — consolidate stashes + friction antigens into `.claude/memory/MEMORY.md`; auto-injected into `CLAUDE.md` via `@MEMORY.md` so every future session in the project benefits
+- **`/stash`** — snapshot the current session's context before compaction or handoff; nudges you to consolidate once a few stashes pile up
+- **`/remember`** — runs friction analysis automatically (mining JSONL session logs across *all* your projects for frustration signals, failed flows, and abandonment patterns, clustered into antigen candidates), then consolidates stashes + friction antigens into `.claude/memory/MEMORY.md`; auto-injected into `CLAUDE.md` via `@MEMORY.md` so every future session benefits
 
-What you get is a memory that *learns from your own mistakes and interventions*, grows quietly in your repo, and works anywhere Claude Code runs. The friction analyzer alone scans all your projects and gives you a per-repo reliability verdict:
+What you get is a memory that *learns from your own mistakes and interventions*, grows quietly in your repo, and works anywhere Claude Code runs. The friction pass inside `/remember` scans all your projects and gives you a per-repo reliability verdict:
 
 ```
 Per-Project:
@@ -98,7 +97,7 @@ BEST:  web-client/0202-2121-8d8608e1  peak=0  turns=4
 Verdict: USEFUL    Intervention predictability: 93%
 ```
 
-Results land in `.claude/friction/antigen_review.md` with projects, error patterns, and offending tool sequences called out per cluster — so `/remember` can pick them up and encode them as rules the next session sees.
+Results land in `.claude/friction/antigen_review.md` with projects, error patterns, and offending tool sequences called out per cluster — which `/remember` then encodes as rules the next session sees.
 
 > This is the thing in liteagents that nothing else ships. Normal skill bundles give you instructions. The hot-memory pipeline gives you instructions the assistant wrote for itself, from your own logs.
 
@@ -123,14 +122,14 @@ Results land in `.claude/friction/antigen_review.md` with projects, error patter
 - **system-architect** - System design, technology selection, API design, scalability planning
 - **ui-designer** - UI/UX design, wireframes, prototypes, accessibility, design systems
 
-### 23 Commands/Skills
+### 18 Commands/Skills
 
 **Auto-Triggering Skills (3)** - Claude Code only:
-- **test-driven-development** - Write test first, watch fail, minimal passing code
-- **testing-anti-patterns** - Prevent mocking anti-patterns
-- **verification-before-completion** - Verify before claiming done
+- **tdd-flow** - Write test first, watch fail, minimal passing code
+- **test-traps** - Prevent mocking anti-patterns
+- **verify-done** - Verify before claiming done
 
-**Manual Skills/Commands (20):**
+**Manual Skills/Commands (15):**
 
 *Hot Memory Pipeline (3)* — see the [Hot Memory](#hot-memory--project-local-learning-from-your-own-sessions) section above for the full walkthrough:
 - **stash** - Snapshot session context to `.claude/stash/` before compaction, handoff, or ending complex work
@@ -142,19 +141,14 @@ Results land in `.claude/friction/antigen_review.md` with projects, error patter
 
 *Workflow & analysis*:
 - **brainstorming** - Structured brainstorming sessions
-- **code-review** - Implementation review against requirements
-- **condition-based-waiting** - Replace timeouts with condition polling
 - **docs-builder** - Project documentation generation
-- **root-cause-tracing** - Trace bugs backward through call stack
+- **trace-back** - Trace bugs backward through call stack
 - **skill-creator** - Guide for creating new skills
-- **systematic-debugging** - Four-phase debugging framework
-- **debug** - Systematic issue investigation
-- **explain** - Explain code for newcomers
-- **git-commit** - Intelligent commit creation
+- **debug-method** - Four-phase debugging framework
 - **optimize** - Performance analysis
 - **refactor** - Safe refactoring with behavior preservation
-- **review** - Comprehensive code review
-- **security** - Vulnerability scanning
+- **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`
 - **ship** - Pre-deployment checklist
 - **test-generate** - Generate test suites
 
@@ -186,8 +180,8 @@ Results land in `.claude/friction/antigen_review.md` with projects, error patter
 **Code Quality:**
 ```
 @quality-assurance Review this PR before merge
-/code-review Check security and performance
-/systematic-debugging Investigate this race condition
+/diff-review main  # review branch vs main, fixes confirmed issues, asks on ambiguous ones
+/debug-method Investigate this race condition
 ```
 
 **Architecture & Design:**

package/installer/cli.js

@@ -15,7 +15,11 @@ const path = require('path');
 const readline = require('readline');
 
 // Single source of truth for version; UPDATE_VERSION.sh bumps only package.json.
-const PACKAGE_VERSION = require('../package.json').version;
+const PACKAGE_JSON = require('../package.json');
+const PACKAGE_VERSION = PACKAGE_JSON.version;
+// Banner counts derived from the description field — same source as README.
+const AGENT_COUNT = (PACKAGE_JSON.description.match(/(\d+)\s+specialized agents/) || [, '11'])[1];
+const COMMAND_COUNT = (PACKAGE_JSON.description.match(/(\d+)\s+commands/) || [, '18'])[1];
 
 // ANSI color codes
 const colors = {
@@ -459,7 +463,7 @@ ${colors.bright}${colors.cyan}██╔══██║██║   ██║█
 ${colors.bright}${colors.cyan}██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ██║╚██████╗    ██║  ██╗██║   ██║${colors.reset}
 ${colors.bright}${colors.cyan}╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═╝ ╚═════╝    ╚═╝  ╚═╝╚═╝   ╚═╝${colors.reset}
 
-${colors.bright}v${PACKAGE_VERSION} | 11 agents + 23 commands per tool${colors.reset}
+${colors.bright}v${PACKAGE_VERSION} | ${AGENT_COUNT} agents + ${COMMAND_COUNT} commands per tool${colors.reset}
     `);
   }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "liteagents",
-  "version": "2.9.0",
-  "description": "AI development toolkit with 11 specialized agents and 23 commands including live-canvas UI design with click-to-annotate feedback. Simple one-question installer for Claude, Opencode, Ampcode, and Droid.",
+  "version": "2.10.0",
+  "description": "AI development toolkit with 11 specialized agents and 17 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": {
     "liteagents": "./installer/cli.js",
@@ -59,7 +59,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=14.0.0"
+    "node": ">=18.0.0"
   },
   "files": [
     "installer/",

package/packages/ampcode/AGENT.md

@@ -22,38 +22,32 @@ These subagents are available when using Ampcode CLI.
 | system-architect | Architect | Use for system design, architecture documents, technology selection, API design, and infrastructure planning |
 | ui-designer | UX Expert | Use for UI/UX design, wireframes, prototypes, front-end specifications, and user experience optimization |
 
-### Skills (10 total)
+### Skills (9 total)
 
 | ID | Description | Usage | Auto |
 |---|---|---|---|
 | brainstorming | Refines rough ideas into fully-formed designs through collaborative questioning | /brainstorming <session-type> <topic> | false |
-| code-review | Reviews implementation against plan or requirements before proceeding | /code-review <review-scope> <focus-areas> | false |
-| condition-based-waiting | Replaces arbitrary timeouts with condition polling to wait for actual state changes | /condition-based-waiting <condition-type> <timeout-specs> | false |
 | docs-builder | Create comprehensive project documentation with structured /docs hierarchy | /docs-builder | false |
-| root-cause-tracing | Systematically traces bugs backward through call stack to identify source | /root-cause-tracing <issue-description> | false |
+| trace-back | Systematically traces bugs backward through call stack to identify source | /trace-back <issue-description> | false |
 | skill-creator | Guide for creating effective skills and extending Claude capabilities | /skill-creator <skill-type> <skill-description> | false |
-| systematic-debugging | Four-phase debugging framework - investigate root cause before any fixes | /systematic-debugging <bug-or-error-description> | false |
-| test-driven-development | Write test first, watch it fail, write minimal code to pass | /test-driven-development <feature-or-behavior-to-test> | true |
-| testing-anti-patterns | Prevents testing mock behavior and production pollution with test-only methods | /testing-anti-patterns <testing-scenario> | true |
-| verification-before-completion | Requires running verification commands before making any success claims | /verification-before-completion <work-to-verify> | true |
+| debug-method | Four-phase debugging framework - investigate root cause before any fixes | /debug-method <bug-or-error-description> | false |
+| tdd-flow | Write test first, watch it fail, write minimal code to pass | /tdd-flow <feature-or-behavior-to-test> | true |
+| test-traps | Prevents testing mock behavior and production pollution with test-only methods | /test-traps <testing-scenario> | true |
+| verify-done | Requires running verification commands before making any success claims | /verify-done <work-to-verify> | true |
 
-### Commands (12 total)
+### Commands (8 total)
 
 | ID | Description | Usage |
 |---|---|---|
-| debug | Debug an issue systematically using structured investigation techniques | /debug <issue-description> |
-| explain | Explain code for someone new to the codebase | /explain <code-section> |
-| friction | Analyze session logs for failure patterns and behavioral signals | /friction <sessions-path> |
-| git-commit | Analyze changes and create intelligent git commits | /git-commit |
 | live-canvas | Design UI variations and collect click-to-annotate feedback from the browser (batch mode only on Amp) | /live-canvas |
 | 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 |
-| review | Comprehensive code review including quality, tests, and architecture | /review |
+| 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 |
 | stash | Save session context for compaction recovery or handoffs | /stash ["optional-name"] |
-| test-generate | Generate comprehensive test suites for existing code | /test-generate <code-section> |
+| test-generate | Generate tests, run them, verify each one actually exercises the code | /test-generate <file> |
 
 All resources are auto-discovered from frontmatter in their respective directories:
 - **Agents**: `./agents/*.md`

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

@@ -41,7 +41,7 @@ digraph CodeDeveloper {
   context_discovery [label="Context Discovery\n(search related code,\ndeps, usages)", fillcolor=lightyellow];
 
   // Debug path
-  use_debug [label="Use /systematic-debugging\nor /root-cause-tracing"];
+  use_debug [label="Use /debug-method\nor /trace-back"];
 
   // Refactor path
   use_refactor [label="Use /refactor"];
@@ -54,12 +54,12 @@ digraph CodeDeveloper {
 
   // Conditional testing
   tdd_needed [label="TDD specified\nor tests needed?", shape=diamond];
-  use_tdd [label="Use /test-driven-development\nor /test-generate"];
+  use_tdd [label="Use /tdd-flow\nor /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 if needed)"];
+  fix_issues [label="Fix issues\n(use /debug-method if needed)"];
   failure_count [label="3+ failures?", shape=diamond];
 
   // Security check
@@ -75,8 +75,8 @@ digraph CodeDeveloper {
   regression_fixable [label="Fixable?", shape=diamond];
 
   // Review and complete
-  code_review [label="Run /code-review"];
-  verification [label="Run /verification-before-completion", fillcolor=orange];
+  code_review [label="Run /diff-review"];
+  verification [label="Run /verify-done", fillcolor=orange];
 
   // Story-specific
   update_story [label="Update story\n(checkbox, changelog)"];
@@ -184,15 +184,14 @@ All require `*` prefix. Invocation commands in table above. Additional:
 
 | Situation | Delegate To |
 |-----------|-------------|
-| Bug encountered | `/systematic-debugging` first, then `/debug` |
-| Error deep in stack | `/root-cause-tracing` |
+| 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 `/test-driven-development` |
-| Writing any test | `/testing-anti-patterns` (avoid mocks, production pollution) |
-| Before completion | `/verification-before-completion` |
+| Need tests (when required) | `/test-generate` or `/tdd-flow` |
+| Writing any test | `/test-traps` (avoid mocks, production pollution) |
+| Before completion | `/verify-done` |
 | After code changes | `/security` |
-| Task complete (vs plan) | `/code-review` (checks against requirements/plan) |
-| General code review | `/review` (comprehensive quality check) |
+| Task complete / general review | `/diff-review` (diffs branch or staged changes, verifies, fixes confirmed issues, asks on ambiguous ones) |
 | 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: `/code-review`, `/security`, `/debug`, `/review`, `/verification-before-completion`
+Use these during analysis: `/diff-review`, `/security`, `/verify-done`
 
 ## Analysis Areas
 

package/packages/{droid/commands/systematic-debugging.md → ampcode/commands/debug-method.md}

@@ -1,11 +1,11 @@
 ---
-name: systematic-debugging
+name: debug-method
 description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes - four-phase framework (root cause investigation, pattern analysis, hypothesis testing, implementation) that ensures understanding before attempting solutions
-usage: /systematic-debugging <bug-or-error-description>
+usage: /debug-method <bug-or-error-description>
 auto_trigger: false
 ---
 
-# Systematic Debugging
+# Debug Method
 
 ## Overview
 
@@ -113,7 +113,7 @@ You MUST complete each phase before proceeding to the next.
 
    **WHEN error is deep in call stack:**
 
-   **REQUIRED SUB-SKILL:** Use root-cause-tracing for backward tracing technique
+   **REQUIRED SUB-SKILL:** Use trace-back for backward tracing technique
 
    **Quick version:**
    - Where does bad value originate?
@@ -178,7 +178,7 @@ You MUST complete each phase before proceeding to the next.
    - Automated test if possible
    - One-off test script if no framework
    - MUST have before fixing
-   - **REQUIRED SUB-SKILL:** Use test-driven-development for writing proper failing tests
+   - **REQUIRED SUB-SKILL:** Use tdd-flow for writing proper failing tests
 
 2. **Implement Single Fix**
    - Address the root cause identified
@@ -280,13 +280,13 @@ If systematic investigation reveals issue is truly environmental, timing-depende
 ## Integration with Other Skills
 
 **This skill requires using:**
-- **root-cause-tracing** - REQUIRED when error is deep in call stack (see Phase 1, Step 5)
-- **test-driven-development** - REQUIRED for creating failing test case (see Phase 4, Step 1)
+- **trace-back** - REQUIRED when error is deep in call stack (see Phase 1, Step 5)
+- **tdd-flow** - REQUIRED for creating failing test case (see Phase 4, Step 1)
 
 **Complementary skills:**
 - **defense-in-depth** - Add validation at multiple layers after finding root cause
-- **condition-based-waiting** - Replace arbitrary timeouts identified in Phase 2
-- **verification-before-completion** - Verify fix worked before claiming success
+- **test-traps** (Anti-Pattern 6) - Replace arbitrary timeouts identified in Phase 2
+- **verify-done** - Verify fix worked before claiming success
 
 ## Real-World Impact
 

package/packages/ampcode/commands/diff-review.md

@@ -0,0 +1,78 @@
+---
+name: diff-review
+description: Review diff [file, branch, or range]
+usage: /diff-review
+argument-hint: [file, branch (e.g. main), range (main..HEAD), or empty]
+allowed-tools: Read, Edit, Grep, Glob, 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 *)
+---
+Review $ARGUMENTS. Interpret in this order:
+1. **Empty** → staged diff (`git diff --staged`); if empty, working-tree diff
+   (`git diff`).
+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`) → diff that ref's merge-base against `HEAD` (i.e. everything on
+   the current branch since it diverged: `git diff $(git merge-base <ref>
+   HEAD)..HEAD`). This is the common "review my branch before merging" path.
+4. **A file or directory path** → that target.
+5. Otherwise → ask.
+
+The diff is the subject; widen to surrounding code only as needed to judge a
+hunk. For multi-commit ranges, also skim `git log <range>` to understand
+intent before judging.
+
+## Check For
+- **Bugs needing a fix.** Logic errors, off-by-one, null/undefined paths,
+  races, wrong defaults, broken edge cases. Concrete failure modes only — not
+  vibes.
+- **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.
+- **Security.** OWASP Top 10, auth, data exposure. (`/security` for depth.)
+- **Performance.** N+1, blocking calls in hot paths, unbounded loops, indexes
+  the diff actually touches.
+- **Maintainability.** Complexity, naming, duplication — only when material.
+
+## Output Format
+### 🚨 Critical (blocks merge)
+### ⚠️ Warnings (should fix)
+### 💡 Suggestions (nice to have)
+
+Each finding: **Location** (`file:line`), **What's wrong**, **Why it matters**,
+**Concrete fix** — not "consider improving".
+
+## After the review — verify, then fix
+
+Findings are claims, not facts. Validate before acting; validate again after.
+
+**Verify each claim.** Re-read the cited `file:line` in context. For
+dead-code or unused-symbol claims, `git grep` the name across the repo before
+trusting it. Mark each **confirmed**, **false positive** (with reason), or
+**uncertain**.
+
+**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 does what you intended
+without breaking nearby logic. A fix isn't done until you've grounded it the
+same way you grounded the claim.
+
+**Stop and ask** when any of these hold (HITL gates — not all the time, only
+here):
+- the finding is **uncertain** after grounding,
+- the fix has **multiple reasonable shapes** (e.g. delete-vs-keep-behind-flag,
+  extract-vs-inline, patch-vs-rewrite) — present options with tradeoffs, not a
+  chosen path,
+- it **affects downstream** (signatures, response shape, schema, any caller
+  contract) or removes a public/exported symbol, or
+- the "dead code" looks intentionally kept (stub for upcoming work, framework
+  hook, documented extension point) — confirm before deleting.
+
+Final report: **confirmed-and-fixed** · **confirmed-but-asking** (why +
+options) · **false-positive** (why) · **uncertain** (what's needed to decide).
+
+End with a one-line verdict: **Ready to merge? Yes / No / With fixes** — and
+the reason in a sentence.

package/packages/ampcode/commands/friction/friction.js

@@ -81,6 +81,24 @@ function loadConfig() {
   return CONFIG;
 }
 
+/**
+ * Parse newline-delimited JSON, skipping (and warning about) malformed lines
+ * instead of crashing the whole run on one bad record.
+ */
+function parseJsonl(raw, source) {
+  const records = [];
+  const lines = raw.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (!lines[i].trim()) continue;
+    try {
+      records.push(JSON.parse(lines[i]));
+    } catch (e) {
+      console.error(`Warning: skipping malformed JSONL line ${i + 1}${source ? ` in ${source}` : ''}: ${e.message}`);
+    }
+  }
+  return records;
+}
+
 function parseISODate(s) {
   if (!s) return null;
   try {
@@ -235,9 +253,7 @@ function extractSignals(sessionFile) {
   const metadata = {};
 
   const raw = fs.readFileSync(sessionFile, 'utf-8');
-  const events = raw.split('\n')
-    .filter(line => line.trim())
-    .map(line => JSON.parse(line));
+  const events = parseJsonl(raw, sessionFile);
 
   let turnCount = 0;
   const userMessages = [];
@@ -1695,7 +1711,7 @@ function extractContextWindow(sessionFile, anchorTs, windowSize) {
   windowSize = windowSize || 5;
 
   const raw = fs.readFileSync(sessionFile, 'utf-8');
-  const events = raw.split('\n').filter(l => l.trim()).map(l => JSON.parse(l));
+  const events = parseJsonl(raw, sessionFile);
 
   const turns = [];
   for (const event of events) {
@@ -2180,14 +2196,20 @@ function extractMain(sessionsDir) {
     return 1;
   }
 
-  const analyses = JSON.parse(fs.readFileSync(analysisFile, 'utf-8'));
+  let analyses;
+  try {
+    analyses = JSON.parse(fs.readFileSync(analysisFile, 'utf-8'));
+  } catch (e) {
+    console.log(`Error: ${analysisFile} is not valid JSON (${e.message}). Re-run friction analysis.`);
+    return 1;
+  }
 
   // Load raw signals
   const rawFile = '.amp/friction/friction_raw.jsonl';
   let signals = [];
   if (fs.existsSync(rawFile)) {
     const rawContent = fs.readFileSync(rawFile, 'utf-8');
-    signals = rawContent.split('\n').filter(l => l.trim()).map(l => JSON.parse(l));
+    signals = parseJsonl(rawContent, rawFile);
   }
 
   // NEW: no per-session BAD verdict. Seed from ALL sessions; the observed-only

package/packages/ampcode/commands/optimize.md

@@ -3,6 +3,7 @@ name: optimize
 description: Optimize performance [target]
 usage: /optimize <target-area>
 argument-hint: [file-or-function]
+allowed-tools: Read, Edit, Grep, Glob, Bash(git diff *), Bash(git log *), Bash(git grep *), Bash(rg *)
 ---
 Analyze $ARGUMENTS for performance.
 
@@ -14,7 +15,47 @@ Analyze $ARGUMENTS for performance.
 - Unnecessary allocations
 
 ## Output
-- Current bottlenecks
-- Specific optimizations
-- Expected improvement
-- Trade-offs involved
+Per bottleneck:
+- **Location** (`file:line`)
+- **Cost** — what's slow and by how much. Concrete ("N+1 over ~1k rows on
+  every page load"), not vague ("could be faster").
+- **Optimization** — specific change.
+- **Expected improvement** — order-of-magnitude estimate.
+- **Trade-offs** — readability / memory / consistency cost.
+
+## After the analysis — verify, then fix
+
+Performance claims are easy to invent. Validate before acting.
+
+**Verify each bottleneck.** Re-read the cited `file:line` in context.
+Confirm the path is **actually hot** — look for at least one of:
+- a profile / benchmark / log line showing call frequency or duration,
+- the path sits on an obvious hot loop / per-request handler with real
+  volume,
+- the user provided evidence in the request.
+
+Without one of those, the claim is **uncertain — don't optimize on
+speculation.** Mark each finding **confirmed**, **false positive** (with
+reason), or **uncertain (needs profiling data)**.
+
+**Fix what's confirmed and unambiguous** — minimal change, one obvious
+shape, **no behavior change**, no API change. Apply directly. After
+each edit, re-read the changed region and confirm it still computes the
+same answer (perf optimizations that quietly change semantics are the
+worst kind).
+
+**Stop and ask** when (HITL gates — not all the time, only here):
+- the bottleneck is **uncertain** after grounding (no profile / log and
+  not obviously hot),
+- the fix has **multiple reasonable shapes** (cache vs precompute vs
+  batch vs paginate vs index) — present options with tradeoffs, not a
+  chosen path,
+- it changes **public API / response shape / DB schema / caller contract**,
+- it trades **correctness for speed** (lossy approximation, weaker
+  consistency, eventual-vs-strict) — even when "obviously" faster, or
+- it touches **concurrency primitives** (locks, atomics, ordering) —
+  easy to introduce races.
+
+Final report: **confirmed-and-fixed** · **confirmed-but-asking** (why +
+options) · **false-positive** (why) · **uncertain** (what profiling /
+data is needed to decide).