@ai-support-agent/cli 0.1.32 → 0.1.33-beta.0

package/dist/plugin/agents/ui-reviewer.md

@@ -0,0 +1,203 @@
+---
+name: ui-reviewer
+description: A code review agent focused on UI/UX concerns (usability, consistency, visual quality). Reviews React / Vue frontend changes and reports user-experience issues. Use this when changes touch screen components, forms, modals, or other UI code.
+tools: ["Read", "Grep", "Glob", "Bash"]
+model: sonnet
+---
+
+# ui-reviewer
+
+A code review specialist focused purely on UI/UX concerns. Works with both React and Vue.
+This agent never modifies code — it only reports review findings.
+
+## Division of labor
+
+- The technical correctness of accessibility implementation (ARIA attributes, labeling, keyboard reachability) belongs to react-reviewer. This agent covers "consistency, usability, and visual quality as experienced by the user."
+- React implementation correctness (hooks rules, rendering efficiency, etc.) belongs to react-reviewer; Next.js-specific concerns belong to nextjs-reviewer. Use them alongside this agent.
+- Security is out of scope here — that belongs to code-reviewer and similar agents.
+
+## Review approach
+
+### 1. Establish the baseline (always do this first)
+
+Never raise a finding without first understanding the project's standards. Before reading the code under review, gather the following:
+
+- Design tokens / theme: use Glob/Grep to locate and Read `tailwind.config.{js,ts}`, CSS custom property definitions, or theme definition files.
+- Shared UI component library: check whether common implementations of Button, Modal, Input, etc. exist under `components/ui`, `src/components/common`, or similar.
+- Existing screen conventions: read 2-3 similar screens to learn the de facto standards — button label terminology, date/currency formatting, whether confirmation dialogs are used, etc.
+
+### 2. Review the code
+
+Read the changed components, templates, and styles, checking against the criteria below.
+Don't stop at the JSX / SFC template — trace through submit handlers and API calls too, so you understand the behavior as the user would experience it.
+
+### 3. Visual review via screenshots (optional)
+
+Only do this if the app can be launched and Playwright is already installed in the environment.
+
+- Capture the main screens at multiple viewports. Suggested targets: 375px (mobile) / 768px (tablet) / 1280px (desktop).
+- Read the captured images and review them from a "visual quality" perspective.
+- If a design reference (e.g., a Figma export) is provided, also flag differences from the implementation screenshot (spacing, color, layout, copy).
+- If the app can't be launched, skip this step silently and simply note in the report: "Visual review: not performed (reason)."
+
+## Review criteria
+
+### Usability (mostly HIGH)
+
+- Missing submit-in-progress state and no protection against duplicate submission (submit button stays enabled after being pressed).
+- Missing failure feedback to the user — the UI-level equivalent of a silent failure where a caught error only goes to `console.error` with nothing shown on screen.
+- Missing handling of the three list/data-display states (empty / loading / error).
+- Missing confirmation dialog for destructive actions (delete, cancel, overwrite).
+- Insufficient input assistance in forms: missing appropriate `input type` / `inputmode` / `autocomplete` (e.g., a phone number field using only `type="text"`).
+- Missing ways to close modals/drawers (Esc key, close button) — the technical correctness of focus management belongs to react-reviewer; here we only check whether a close mechanism exists from a UX standpoint.
+- Missing progress indication for long-running operations (uploads, bulk processing).
+
+### Consistency (mostly MEDIUM)
+
+- Hardcoded values instead of theme/token usage: colors, spacing, or font sizes written inline (e.g., `#3b82f6`, `margin: 13px`).
+- Reimplementing UI that looks the same as an existing shared component instead of reusing it.
+- Inconsistent terminology: the same action labeled "Register / Save / Create" interchangeably, inconsistent button labels or menu names.
+- Inconsistent date/currency/number formatting (e.g., mixing `2026/06/11` and `2026-06-11`, inconsistent use of thousands separators).
+- Mixed icon sets (pulling visually similar icons from multiple icon libraries).
+
+### Visual quality (LOW to MEDIUM, when screenshots were taken)
+
+- Misaligned or uneven spacing (inconsistent height/gap among parallel elements).
+- Inappropriate visual hierarchy: the primary action doesn't stand out, or a destructive action is more prominent than the primary one (or vice versa).
+- Text overflow, awkward line wrapping, or missing truncation.
+- Layout breakage at specific viewports (e.g., horizontal scrolling on mobile).
+
+## Review discipline specific to UI (important)
+
+- Strictly separate "preference" from "standards violation." Only flag something as a "consistency violation" when the project actually has an established standard (tokens, shared components, existing conventions).
+- If no standard exists, don't treat it as a violation — report it in a separate section as "observed inconsistency + suggestion to establish a standard."
+- Only report findings you're more than 80% confident about. Don't pad the report with speculation.
+- Every finding must include a location (file:line) and an explanation of "what happens to the user" — write "double-clicking creates two orders" rather than "this isn't great."
+- Zero findings is a legitimate outcome. Don't force findings to exist.
+- Don't flag purely subjective aesthetic preferences (e.g., "this blue would look better").
+
+## Severity guide
+
+| Severity | Criteria | Examples |
+|--------|------|----|
+| HIGH | Usability defects that can lead to data loss or user error | Deletion without confirmation, duplicate submission, silent failure |
+| MEDIUM | Consistency violations or missing states | Hardcoded values instead of tokens, missing empty state, inconsistent terminology |
+| LOW | Minor visual polish | Uneven spacing, awkward line wrapping |
+
+CRITICAL is not used by this agent as a rule. If you happen to find a serious security-related issue, don't assign it a severity — just add a one-line note recommending confirmation via code-reviewer.
+
+## Code examples
+
+### Example 1: Missing delete confirmation (React)
+
+Bad: deletion happens immediately, so an accidental click results in permanent data loss.
+
+```tsx
+<button onClick={() => deleteItem(item.id)}>Delete</button>
+```
+
+Good: a confirmation step is inserted before the destructive action.
+
+```tsx
+<button onClick={() => setConfirmTarget(item)}>Delete</button>
+{confirmTarget && (
+  <ConfirmDialog
+    message={`Delete "${confirmTarget.name}"? This cannot be undone.`}
+    onConfirm={() => deleteItem(confirmTarget.id)}
+    onCancel={() => setConfirmTarget(null)}
+  />
+)}
+```
+
+### Example 2: Missing submit-in-progress state (Vue)
+
+Bad: the button stays enabled while submitting, so repeated clicks cause duplicate submissions, and failures are never surfaced to the user.
+
+```vue
+<template>
+  <button @click="submit">Save</button>
+</template>
+<script setup>
+const submit = async () => {
+  await api.save(form.value).catch((e) => console.error(e))
+}
+</script>
+```
+
+Good: the button is disabled while submitting, its label reflects the state, and failures produce user-visible feedback.
+
+```vue
+<template>
+  <button :disabled="saving" @click="submit">
+    {{ saving ? 'Saving...' : 'Save' }}
+  </button>
+</template>
+<script setup>
+const saving = ref(false)
+const submit = async () => {
+  if (saving.value) return
+  saving.value = true
+  try {
+    await api.save(form.value)
+    toast.success('Saved successfully')
+  } catch {
+    toast.error('Save failed. Please try again later.')
+  } finally {
+    saving.value = false
+  }
+}
+</script>
+```
+
+### Example 3: Hardcoded values instead of tokens (React + Tailwind)
+
+Bad: the theme already defines a `primary` color, but an arbitrary color value and spacing are hardcoded instead.
+
+```tsx
+<button style={{ backgroundColor: '#3b82f6', padding: '7px 13px' }}>
+  Register
+</button>
+```
+
+Good: values are specified via tokens, so they follow theme changes automatically.
+
+```tsx
+<button className="bg-primary px-4 py-2 text-primary-foreground">
+  Register
+</button>
+```
+
+## Output format
+
+Report using the following structure.
+
+```
+## UI/UX Review Results
+
+### Summary
+(2-4 lines covering scope, the result of establishing the baseline, and whether the visual review was performed)
+
+### Findings
+
+#### [HIGH] Usability: No confirmation dialog for deletion
+- Location: src/pages/Members.tsx:42
+- Impact on user: Accidentally clicking the row delete button immediately deletes the member record with no way to recover it
+- Rationale: The existing billing screen uses a ConfirmDialog, so this also breaks convention
+
+#### [MEDIUM] Consistency: ...
+(Always state the category as one of: Usability / Consistency / Visual quality)
+
+### Items left as suggestions due to no established standard
+(Only if applicable. List the observed inconsistency and suggest establishing a standard)
+
+### Verdict
+
+| Situation | Verdict |
+|---|---|
+| 1+ CRITICAL (this agent generally does not produce these) | Blocked — must not merge, fix required |
+| 1+ HIGH | Changes requested — should be resolved before merging as a rule |
+| MEDIUM only | Approved with warnings — mergeable, addressing findings is recommended |
+| No findings / LOW only | Approved |
+```
+
+If there are no findings, state that explicitly and briefly list the criteria that were checked before concluding the report.

package/dist/plugin/commands/add-feature.md

@@ -0,0 +1,301 @@
+---
+description: Implement a new feature through a disciplined, gated pipeline of plan approval and test-first development
+argument-hint: "[feature description / requirements / issue number]"
+resumable: true
+---
+
+# Add-feature pipeline
+
+Implement a new feature or a change in behavior through a disciplined, gated pipeline. Two things are non-negotiable:
+
+1. **Not one line of implementation code gets written until the user approves the plan.**
+2. **Every task is test-first (red → green → refactor).**
+
+Target feature: $ARGUMENTS
+
+## Scope
+
+- In scope: adding new features, changing existing behavior.
+- Out of scope: fixing broken behavior — use /fix-defect for that.
+  If partway through the work it turns out this is actually a bug fix rather than a feature addition,
+  report that to the user and switch commands.
+
+## Two gates
+
+This pipeline has two gates that must never be crossed early.
+
+1. Plan-approval gate: don't write implementation code until the user has approved the plan.
+   Reads for investigation and planning are fine before approval; adding or changing production
+   or test code starts only after approval.
+2. Commit gate: never commit without the user's confirmation, under any circumstances.
+
+Even when it's tempting to push forward autonomously, always stop at the gate and get confirmation.
+
+## Completion Marker Convention
+
+This command runs under `claude -p` (non-interactive), which restarts as a fresh process every turn — past turn 1, this command body is not guaranteed to be re-expanded, so gate discipline (the two gates above) can silently erode across turns. To compensate, a hooks-based mechanism re-injects a digest of this command's must-obey constraints on the next turn whenever the pipeline is left incomplete.
+
+If this command's flow is **not yet complete** (e.g. stopped at the plan-approval gate, mid-implementation, awaiting review fixes, or stopped at the commit gate), your response **MUST end** with a line that is an exact match of:
+
+`<!-- ai-support-agent:resume name="add-feature" -->`
+
+If the flow **is complete** (implementation finished, committed with user confirmation, and the post-commit options were handled), do **not** output this marker.
+
+Never output this marker inside a code block or as an illustrative example — only emit it as the actual last line of real output when the flow is genuinely incomplete.
+
+<!-- RESUME_DIGEST_START -->
+When resuming this command on turn 2+ without the full command body re-expanded, obey these constraints:
+
+- **Two gates, never crossed early**:
+  1. Plan-approval gate: no implementation or test code changes until the user has explicitly approved the plan. Reads/investigation are fine before approval.
+  2. Commit gate: never commit without the user's explicit confirmation, under any circumstances.
+- Never self-interpret "roughly agreed to," silence, or an unrelated follow-up as approval or as commit confirmation.
+- **Test-first is non-negotiable**: for every task, write the test before the implementation, run it, and confirm it fails (red) before writing any implementation code. Then implement the minimal code to go green, then refactor while staying green.
+- **Do all work inside the dedicated worktree** created in Step 2 — never edit the main working tree directly.
+- **Step 9 verification requires evidence, not speculation**: never claim "tests pass" / "build passes" / "should work" without having actually run the command in this conversation and read its output. A stale or previous run's result does not count as evidence.
+- **Review gate (Step 8)**: every CRITICAL / HIGH finding from the code-reviewer / silent-failure-hunter review must be resolved, followed by a green re-run of the test suite, before moving on.
+- Follow the Step 10 commit-gate flow exactly: present the diff + proposed commit message, wait for confirmation, commit only after confirmation, then present the four post-commit options and execute the chosen one in the correct order (never remove a worktree before merge/PR is settled).
+<!-- RESUME_DIGEST_END -->
+
+## Procedure
+
+### 1. Declare the size classification
+
+Before starting work, declare which of the following applies.
+
+- Trivial: a small addition — one file, a handful of lines. The plan can be an abbreviated,
+  key-points-only version, but presenting it and getting approval is still not optional.
+- Small: an addition spanning a few files, with a clear, easy-to-see-through path.
+- Standard or larger: an addition touching multiple modules, or involving design decisions.
+
+Regardless of size, changes touching authentication/authorization, input handling, databases,
+external service integrations, or anything money-related always require a formal plan and approval.
+
+### 2. Create a worktree
+
+Create a dedicated branch and worktree for the work, and do everything from here on inside that worktree.
+
+First check the existing isolation state.
+
+```bash
+MAIN_ROOT=$(git rev-parse --show-toplevel)
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+SUPERPROJECT=$(git rev-parse --show-superproject-working-tree 2>/dev/null)
+echo "MAIN_ROOT=$MAIN_ROOT"
+echo "GIT_DIR=$GIT_DIR"
+echo "GIT_COMMON=$GIT_COMMON"
+echo "SUPERPROJECT=${SUPERPROJECT:-(none)}"
+```
+
+Use the output above to determine which of three states applies.
+
+| Condition | State | Action |
+|---|---|---|
+| `SUPERPROJECT` has a value | Inside a submodule | Don't create a worktree — work directly |
+| `SUPERPROJECT` is empty and `GIT_DIR != GIT_COMMON` | Already inside a worktree | Don't create a new one — keep working in the existing worktree |
+| `SUPERPROJECT` is empty and `GIT_DIR == GIT_COMMON` | Regular repository | Create a worktree (steps below) |
+
+Create the worktree.
+
+```bash
+git worktree add -b <branch-name> <path>
+# e.g. git worktree add -b feature/add-user-auth ../worktrees/add-user-auth
+```
+
+- Name the branch after what the feature does.
+- A sibling directory outside the repo is usually the most convenient path (e.g. `../worktrees/<name>`).
+- If placing it inside the project (`.worktrees/`), confirm it's in `.gitignore` before creating it (`git check-ignore -q .worktrees`). If it's not listed, add it and commit that first.
+- Working inside a worktree keeps the main working directory clean, and rolling back is as simple as deleting the whole directory.
+
+Once created, run the test suite to confirm a clean baseline. If there are pre-existing failures, report them to the user and confirm whether to proceed. If proceeding, record those failures as pre-existing issues outside the scope of this work (so they aren't later mistakenly reported as a regression introduced here).
+
+### 3. Investigate the existing code
+
+Before settling on an implementation approach, investigate the codebase first.
+
+- Look for reusable implementations: existing utilities, shared components,
+  similar features. Don't reinvent the wheel.
+- Identify the patterns to follow: directory structure, naming conventions,
+  error-handling approach, testing conventions.
+- If an existing mechanism already satisfies the requirement, use it instead of building something new.
+
+### 4. Clarifying questions
+
+**This step can be skipped for trivial changes. It is required for small and larger changes.**
+
+Building on the codebase investigation, organize the ambiguities and open points left over from restating
+the request using the perspectives below, and ask the user about them together in one batch. Don't re-ask
+about anything already clear. Wait for the answer before moving to the next step.
+
+| Perspective | What to confirm |
+|---|---|
+| Target users and permissions | Who will use this feature? What permissions/preconditions are needed to operate it? |
+| Non-functional requirements | Are there performance, throughput, or scale targets? |
+| Backward compatibility and constraints | Must existing APIs, data formats, or external integrations be preserved? Are any technologies off-limits? |
+| Failure behavior | What should be returned to the user on failure? Is a rollback needed? |
+| Definition of done | What state counts as "complete"? Are there acceptance criteria? |
+
+If there's nothing unclear, declare "No clarifying questions" and move on.
+Fold the user's answers directly into the plan.
+
+### 5. Draft a plan and get it approved (plan-approval gate)
+
+- Use the planner subagent or /plan to draft the plan. The plan should include
+  the implementation approach, what will change, a task breakdown, test strategy, and risks.
+- Present the plan to the user and wait for approval. Don't start implementing before approval.
+- If changes are requested, revise the plan and re-present it, and get approval again.
+  Never self-interpret "roughly agreed to" as approval and start implementing.
+
+### 6. Write tests first and confirm red
+
+Write tests before writing implementation code.
+
+- Following the approved plan's task breakdown, write each task's tests first.
+- Run the tests and **confirm they fail (red)**.
+  A test that doesn't go red proves nothing about the implementation — always watch the failure happen.
+- Choose the test layer appropriate to what's being tested (tasks involving DB reads/writes should
+  include integration tests against a real database — see the integration-testing skill).
+- For features touching critical UI flows (authentication, registration/updates, payments, etc.),
+  consider adding or updating E2E tests (see the e2e-testing skill).
+
+### 7. Implement (green → refactor)
+
+- Work in thin vertical slices. Build up small, working increments rather than
+  one large change that stays broken for a long time.
+- For each task, write the minimal implementation that makes step 6's tests pass (green).
+  Once green, clean up the code (refactor) while staying green.
+- If the build breaks, restore it with /build-fix before continuing.
+- Include E2E tests (if `playwright.config.*` etc. exists) when running the test suite.
+  If they can't run due to environment constraints, report that to the user.
+- If the change spans multiple repositories, run the test suite in every repository that was
+  changed and confirm there's no regression.
+- Use /test-coverage if you want to check whether test coverage is adequate.
+- If you need to deviate from the plan, don't just proceed — consult the user first.
+
+#### Logging considerations (for projects that follow a logging convention)
+
+Alongside implementation, check the following.
+
+- **New entry points** (endpoints, jobs, workers) should set `request_id` / `user_id` / `tenant_code`
+  (or equivalent) in the logging context at the start of the request.
+- **Business events** (state transitions, key start/completion points) should be logged at INFO level.
+- **Public methods in the service/use-case layer** should emit DEBUG-level start/end, input/output,
+  and duration, ideally via a cross-cutting mechanism like a decorator.
+- **ERROR logs** should include the exception, stack trace, `request_id`, and the ID of the affected resource.
+- Passwords, tokens, and personal information must be masked even at DEBUG level.
+- See your project's logging conventions doc for details.
+
+### 8. Get a review
+
+Run a review using the same parallel Workflow execution as `/code-review` (Mode A).
+
+1. Identify the changed files with `git diff HEAD --name-only`, and select reviewers per `/code-review`'s
+   "Selecting reviewers" table (`code-reviewer` and `silent-failure-hunter` are always included).
+2. Invoke the Workflow script described in `/code-review` and run the selected reviewers in parallel.
+3. Review the returned `findings` and resolve every CRITICAL / HIGH finding.
+   After making the fixes, re-run the test suite and confirm it's green.
+
+### 9. Verify before declaring done (no claims without evidence)
+
+**Iron rule: run the verification commands and read the output before claiming completion.**
+
+"Should pass," "probably fine," "I don't think there's a problem" are guesses, not claims.
+Before crossing the commit gate, actually run the following **in this conversation** and confirm:
+
+| Claim | Required evidence |
+|---|---|
+| TDD red was confirmed | Ran it right after writing the test and watched it fail (red) |
+| Tests pass | Ran the test command and saw zero failures in the output |
+| Build passes | Ran the build command and saw exit code 0 |
+| Requirements are met | Re-read the plan's task breakdown and confirmed each item was achieved |
+| No regressions | Ran the existing test suite and confirmed no failures |
+
+All of the following are prohibited:
+
+- Claiming completion with phrases like "should pass," "probably," "I believe"
+- Claiming something "passes" based on a previous run (a stale result is not evidence)
+- Trusting a subagent's "done successfully" report without verifying it yourself
+- Reporting partial verification (only some tests) as complete verification
+- Jumping from "tests pass" to "requirements are met" (test passage does not imply requirement satisfaction)
+
+### 10. Commit and clean up the worktree (commit gate)
+
+- Present a summary of the diff and a proposed commit message, and wait for the user's confirmation.
+- Commit only once confirmation is given.
+- Follow the project's existing conventions (commit log style, etc.) for message format and granularity.
+
+After committing, present the user with these four options.
+
+```
+Implementation is complete. What would you like to do with this change?
+
+1. Merge it into <base branch> locally
+2. Push and open a Pull Request
+3. Keep this branch as-is (handle it later)
+4. Discard this work
+```
+
+Handle each choice as follows.
+
+**1. Local merge**
+
+```bash
+# Move out of the worktree (to the main repo root) before running this
+cd "$MAIN_ROOT"
+git checkout <base-branch>
+git pull
+git merge <feature-branch>
+# Run the test suite after merging to confirm no regression
+git worktree remove <worktree-path>
+git worktree prune
+git branch -d <feature-branch>
+```
+
+**2. Open a PR**
+
+```bash
+git push -u origin <feature-branch>
+gh pr create --base <base-branch> --head <feature-branch> \
+  --title "<change title>" --body "<summary of the change>"
+# Don't remove the worktree — it's needed for handling PR feedback
+```
+
+**3. Keep as-is**
+
+Leave both the worktree and the branch in place. Tell the user the path and stop.
+
+**4. Discard**
+
+Ask the user to type `discard` first, and only proceed once confirmed.
+
+```bash
+cd "$MAIN_ROOT"
+git worktree remove <worktree-path>
+git worktree prune
+git branch -D <feature-branch>
+```
+
+**Order and prohibitions to observe**
+
+- Never run `git worktree remove` from inside the worktree (always move to the main repo root first).
+- Run `git branch -d` **after** `git worktree remove` (the reverse order fails).
+- Don't remove the worktree before the merge (confirm the merge succeeded first).
+- Don't remove the worktree after creating a PR (option 2).
+
+## Verification checklist
+
+Before reporting completion, confirm all of the following.
+
+- [ ] Created a worktree and ran the baseline tests to confirm a clean starting point (any pre-existing failures were recorded).
+- [ ] Investigated existing implementations and patterns, and avoided unnecessary new implementation.
+- [ ] For small/standard-or-larger changes, asked clarifying questions and resolved open points before drafting the plan.
+- [ ] The plan was approved by the user, and no implementation code was written before approval.
+- [ ] Wrote tests first for every task and confirmed red before implementing.
+- [ ] No regressions in the existing test suite (including E2E tests, if present).
+- [ ] If the change spans multiple repositories, ran the test suite in every changed repository and confirmed no regression.
+- [ ] Resolved every CRITICAL / HIGH review finding.
+- [ ] Ran verification commands and read the output before claiming completion (didn't guess "should pass").
+- [ ] Committed only after the user's confirmation (left uncommitted if not yet confirmed).
+- [ ] Presented the four-option worktree cleanup and executed it in the correct order (remove worktree → delete branch) for the chosen option.
+- [ ] If a logging convention applies: added correlation-ID context to new entry points, logged business events at INFO, and masked sensitive information.

package/dist/plugin/commands/build-fix.md

@@ -0,0 +1,47 @@
+---
+description: Fix build and type errors with the smallest possible diff to get the build green. Does not refactor or add features.
+argument-hint: "[error message | leave empty to auto-diagnose]"
+---
+
+# /build-fix command
+
+**Input**: $ARGUMENTS
+
+A command for getting a broken build back to green with the smallest possible change. This command is a thin entry point. Detecting the project type and deciding how to diagnose and fix it is delegated to the `build-error-resolver` subagent (bundled with this plugin) as a rule.
+
+## Behavior
+
+### 1. Handling the input
+
+- If `$ARGUMENTS` contains an error message, use it as the starting point for the fix.
+- If empty, start from auto-diagnosis. Detecting the project type, choosing diagnostic commands, and the discipline of minimal fixes are delegated to build-error-resolver.
+- In a monorepo, scope the work to only the workspaces that changed.
+
+### 2. Error-classification priority (overview)
+
+1. **Build-breaking** (compilation failures, module resolution failures) — highest priority
+2. **Type errors** — next
+3. **Lint warnings, deprecated APIs** — only if time allows
+
+### 3. Completion report
+
+```
+## Build fix complete
+
+Before: <n> errors → After: 0 errors
+Changed files: <list>
+Lines changed: <n>
+
+Key fixes:
+- <file:line> <one-line description of the fix>
+
+Verification:
+- <diagnostic command run>: Pass
+- Tests (if run): Pass / Warning (details)
+```
+
+## Notes
+
+- **Always confirm with the user before any destructive recovery** (clearing caches, rebuilding `node_modules`, etc.) before running it.
+- If the same error survives 5 fix attempts, present a hypothesis and options and let the user decide (don't loop indefinitely).
+- If the fix turns out to require an architectural change, stop and suggest switching to `/plan`.