@uoyo/mvtt 2.0.0-beta.0 → 2.0.0-beta.1

package/sources/skills/mvt-refactor/business.md

@@ -1,33 +1,104 @@
-## Execution Flow
-
-### Step 1: Analyze Current Code
-- Read target files
-- Understand current behavior
-- Classify refactoring type from the types table
-- Identify refactoring opportunities
-
-### Step 2: Risk Assessment
-- Assess risk level based on refactoring type
-- Identify all callers/dependents of the target code
-- Estimate impact scope (files and modules affected)
-- Check for existing tests covering the target code
-
-### Step 3: Plan Refactoring
-- Define refactoring goals
-- Identify incremental steps
-- Ensure behavior preservation strategy
-
-### Step 4: Execute Refactoring
-- Apply changes incrementally
-- Verify behavior at each step
-
-### Step 5: Verify Behavior Preservation
-- If tests exist -> Suggest running them
-- If no tests -> Describe how to verify behavior is unchanged
-- Confirm no regressions in dependent code
-
-### Step 6: Update Workspace
-1. Update `.ai-agents/workspace/session.yaml`:
-   - Set `session.last_command: "/mvt-refactor"`
-   - Append one-line summary to `recent_actions` (keep max 3)
-   - Do NOT update `progress` (shortcut operation)
+## Execution Flow
+
+### Step 1: Load Inputs
+- **Required**:
+  - User-specified target (file path, symbol name, module, or "the code I just wrote").
+- **Recommended**:
+  - Existing tests covering the target (search by file path, by symbol name, and by sibling test files).
+  - `git status` / `git diff` -- to know what is already modified before refactoring.
+- **Fallback**: if no target was specified, ask the user. Do not refactor speculatively.
+
+### Step 2: Locate and Understand Target
+- **What**: produce a precise list of files and line ranges that constitute the refactoring target, plus a one-paragraph statement of what the code currently does.
+- **How**:
+  1. Resolve the target: glob/grep for the named symbol or path.
+  2. List every caller / dependent: grep for the symbol's exported name across the project (and across packages if it is exported beyond the module).
+  3. State the current behavior in plain language; include any non-obvious side effects or invariants you can see in the code.
+- **Output of this step**: a target table (`file | range | role`) and a "current behavior" paragraph; both are shown to user before continuing.
+
+### Step 3: Classify Refactoring Type
+- **What**: pick the smallest type that covers the requested change. Use the Refactoring Types table above for risk levels.
+- **How**: assign one primary type per refactoring task. Multiple types in one run are allowed but each must be tracked separately in the artifact.
+- If the request requires `Change Interface/API` AND the symbol is exported beyond the project (public API, library entry point, IPC boundary): STOP -- this is no longer a refactoring task; recommend `/mvt-design`.
+
+### Step 4: Risk Assessment
+- **What**: assign a final risk score and decide whether explicit confirmation is needed.
+- **How**: combine refactoring type and impact factors.
+
+  | Factor | +risk |
+  |--------|-------|
+  | Touches > 10 files | +1 |
+  | Touches a public/exported symbol | +1 |
+  | No existing tests on the target | +1 |
+  | Target is in a critical path (auth, payments, persistence boundary, public API) | +1 |
+  | User has uncommitted changes overlapping the target | +1 |
+
+- Final risk = type's base level + factors:
+  - Low + 0..1 -> proceed silently in Step 7.
+  - Medium OR Low + 2 -> require explicit confirmation in Step 6.
+  - High OR (Medium + 2) -> require explicit confirmation AND a behavior-preservation strategy from Step 5.
+
+### Step 5: Choose Behavior-Preservation Strategy
+- **What**: pick a verification path BEFORE editing.
+- **How**: choose the row that matches your test reality.
+
+  | Test reality | Strategy |
+  |--------------|----------|
+  | Comprehensive tests cover the target | Run them once before changes (capture baseline), once after each step, and once at the end |
+  | Some tests exist, gaps known | Do the refactor in incremental steps; after each step, run available tests; for gaps, add a single characterization test BEFORE refactoring (capture current behavior, even if quirky) |
+  | No tests exist | Choose ONE: (a) write a minimal characterization test first, OR (b) for Low-risk refactors only, use mechanical refactoring (rename, extract) where the editor / language tooling guarantees behavior. Never attempt High-risk refactors with zero tests |
+
+- Document the chosen strategy in the artifact regardless of risk level.
+
+### Step 6: Confirm with User (when required)
+- **Trigger**: per the Step 4 thresholds, or any High-risk type.
+- **Format**: present a single screen with:
+  - Target summary (Step 2's table, condensed to file count + symbol).
+  - Refactoring type and risk level.
+  - Number of callers and a list of the top 5 affected files.
+  - Behavior-preservation strategy (Step 5).
+  - One yes/no prompt: `Proceed with this refactor? (y / n / show-plan)`.
+
+### Step 7: Plan and Execute Incrementally
+- **What**: apply the change in the smallest reversible steps.
+- **How**:
+  1. Break the refactor into ordered sub-steps (e.g., Rename: 1) update declaration, 2) update callers, 3) update tests, 4) update docs).
+  2. After each sub-step:
+     - Compile / type-check the affected files.
+     - If a test command was identified in Step 5, run it (or surface it for user to run if running tests is not allowed in this environment).
+     - On failure: revert the sub-step, surface the cause, do NOT continue.
+  3. Do not interleave behavior changes (bug fixes, feature toggles) with the refactor. If you spot one, note it for follow-up; do not silently include it.
+  4. Do not modify code outside the planned target unless required for compilation/type correctness; record any such "incidental" edits.
+
+### Step 8: Verify Behavior Preservation
+- **What**: prove (within the chosen strategy) that observable behavior is unchanged.
+- **How**:
+  - With tests: all pre-existing tests pass; new characterization tests pass; assert pass count is unchanged or increased.
+  - Without tests: list the call sites you visually verified, plus the manual behavior checks you recommend the user run.
+- If anything regresses: revert the most recent sub-step, surface the regression, return to Step 7. Do not declare success.
+
+### Step 9: Write Refactor Notes
+- **Path**: `.ai-agents/workspace/artifacts/{change-id}/refactor-notes.md` if `active_change` exists; otherwise inline summary in conversation only (shortcut mode).
+- **Required content**:
+  - `Target` -- file/symbol list, current-behavior paragraph.
+  - `Refactoring Type` and final risk level.
+  - `Behavior-Preservation Strategy` -- chosen row + tests touched / written.
+  - `Steps Applied` -- ordered sub-steps with one-line outcome each.
+  - `Incidental Edits` -- any unplanned files touched, with reason.
+  - `Verification Result` -- tests run, pass/fail counts; or manual checks recommended.
+  - `Follow-ups` -- deferred behavior changes spotted during refactoring.
+
+### Step 10: (session update handled by shared section)
+
+## Edge Cases & Errors
+
+| Case | Handling |
+|------|----------|
+| Target spans multiple repos / submodules | STOP -- out of scope; recommend a coordinated change rather than a single refactor |
+| Refactor uncovers a real bug | Pause refactor, document the bug, recommend `/mvt-fix` -- do NOT fix during the refactor |
+| Refactor target is dead code | Confirm with user before deleting; offer alternative of marking deprecated first |
+| Symbol is referenced via reflection / dynamic dispatch / string lookup | Increase risk by +2; require strategy 5(a) (characterization test) before proceeding |
+| User has uncommitted changes overlapping the target | Show diff, recommend committing/stashing first, ask for explicit confirmation if user wants to proceed anyway |
+| Type/test failures persist after revert | Surface a clear summary; suggest user re-run the original test baseline to detect a pre-existing failure unrelated to the refactor |
+| User aborts at Step 6 | Do not modify any file; report "no changes" |
+| Active change is mid-implementation (not yet `done`) | Warn that refactoring during implementation can confuse review/test phases; require explicit confirmation |

package/sources/skills/mvt-refactor/manifest.yaml

@@ -3,7 +3,7 @@ output: .claude/skills/mvt-refactor/SKILL.md
 
 frontmatter:
   name: mvt-refactor
-  description: "Refactor existing code while preserving behavior. Supports extract, rename, move, decompose, and other refactoring types. Use when user wants to improve code structure without changing functionality."
+  description: "Refactor existing code while preserving behavior. This skill should be used when user wants to improve code structure, rename symbols, extract methods or classes, or reorganize code without changing functionality."
 
 sections:
   - type: inline
@@ -21,7 +21,7 @@ sections:
       role_desc: "an Implementation Specialist"
       decision_rules:
         - rule: "Refactoring target specified -> Analyze and plan the refactoring"
-        - rule: "No target specified -> Ask user what to refactor"
+        - rule: "No target specified -> Prompt user for refactoring target"
         - rule: "Risk level is High -> Warn user and require explicit confirmation"
         - rule: "Tests exist for target code -> Recommend running them after refactoring"
         - rule: "No tests exist -> Describe how to verify behavior is unchanged"
@@ -43,26 +43,28 @@ sections:
 
       ## Refactoring Types
 
-      | Type | Description | Risk Level |
-      |------|-------------|------------|
-      | Extract Method/Class | Pull logic into new method or class | Low |
-      | Rename | Rename symbols for clarity | Low |
-      | Move | Relocate code to appropriate module/layer | Medium |
-      | Decompose Conditional | Simplify complex if/switch logic | Medium |
-      | Replace Inheritance with Composition | Change class hierarchy | High |
-      | Change Interface/API | Modify public contracts | High |
+      | Type | Risk Level | Examples |
+      |------|------------|----------|
+      | Rename | Low | Variable, function, file rename |
+      | Extract Method/Class | Low | Pull repeated logic into a helper |
+      | Inline | Low | Eliminate a thin wrapper |
+      | Move | Medium | Relocate code to appropriate module/layer |
+      | Decompose Conditional | Medium | Simplify complex if/switch logic |
+      | Replace Inheritance with Composition | High | Class-hierarchy redesign |
+      | Change Interface/API | High | Modify public contracts |
 
   - type: shared
     source: sections/activation-load-context.md
     params:
       extended_context:
-        - ".ai-agents/knowledge/patterns/{pattern.active}/ -- Active architecture pattern knowledge"
-        - ".ai-agents/knowledge/principle/coding-standards.md -- Project coding standards"
         - "Related source files to be refactored"
 
   - type: shared
     source: sections/activation-load-config.md
 
+  - type: shared
+    source: sections/output-language-constraint.md
+
   - type: inline
     content: |
       ### Step 3: Pre-flight Checks
@@ -70,32 +72,15 @@ sections:
 
       ### Shortcut Operation Rules
       - Can execute at any time without checking workflow prerequisites
-      - Do NOT update `progress` in `session.yaml` after completion
-      - Only update `session.last_command` and `recent_actions`
-
-      ### Step 4: Execute
-      Proceed to Execution Flow below.
 
   - type: file
     source: ./business.md
 
-  - type: inline
-    content: |
-      ## Output Format
 
-      Read and use the output template from: `.ai-agents/skills/_templates/refactor-output.md`
-
-      If a custom version exists at `.ai-agents/skills/_templates/custom/refactor-output.md`, use the custom version instead.
-
-      Fill the template placeholders with the refactoring results.
-
-      Every response MUST end with a Suggested Next Steps section.
+  - type: shared
+    source: sections/session-update.md
 
   - type: shared
     source: sections/footer-next-steps.md
     params:
-      next_primary: mvt-review
-      next_primary_desc: "Verify refactoring changes"
-      next_alternatives:
-        - skill: mvt-test
-          when: "Run tests to confirm behavior preservation"
+      current_skill: mvt-refactor

package/sources/skills/mvt-resume/business.md

@@ -0,0 +1,137 @@
+## Execution Flow
+
+### Step 1: Read Session State
+
+Extract from the already-loaded session context:
+- `active_change` -- the current change-id (if any), its phase, plan_path, has_plan
+- `recent_changes` -- list of changes with active plans
+- `skill_history` -- last 10 entries (skill name, timestamp, status, change_id)
+- `recent_actions` -- last 5 entries (what was done, when, outcome)
+- `last_command` and `last_skill` -- most recent invocation
+
+If session.yaml is missing or empty, jump to Step 6 with the "no session" branch.
+
+### Step 1.5: Discover Pending Plans
+
+Scan for in-progress plans using two sources:
+
+1. **Index path**: For each entry in `recent_changes[]`, read its `plan_path` if the file exists.
+2. **Fallback scan**: Glob `.ai-agents/workspace/artifacts/*/plan.yaml`, read any files not already covered by (1).
+
+For each found plan.yaml, read and filter:
+- Include only plans where `plan.status == "in_progress"`.
+- Capture: `change_id`, `title`, task progress (`done_count / total_count`), `updated_at`.
+- Sort candidates by `updated_at` descending.
+
+### Step 1.6: Select Target Change
+
+| Candidates | Behavior |
+|------------|----------|
+| 0          | Skip to Step 2 — use legacy `active_change` / `skill_history` flow (no plan context). |
+| 1          | Auto-select. Print: "Found one active plan: **{title}** ({progress}). Resuming." |
+| ≥2         | **Pause and prompt**. Display candidate table and wait for user input. |
+
+**Candidate table format** (≥2 candidates):
+
+```
+Found {N} active plans. Select which to resume:
+
+| # | change-id | title | progress | last_updated |
+|---|-----------|-------|----------|--------------|
+| 1 | {id}      | {t}   | {d}/{n}  | {relative}   |
+| ...
+
+Enter a number, a change-id, or "none" to skip plan context:
+```
+
+**Explicit argument override**: If the user invoked `/mvt-resume {change-id}`, use that change-id directly — skip the table, locate and load its plan.yaml (error if not found or not in_progress).
+
+After selection, set `selected_change_id` for use in subsequent steps. If "none" or 0 candidates, `selected_change_id = null`.
+
+### Step 2: Inspect Recent Artifacts
+
+If `selected_change_id` is set:
+- List files under `.ai-agents/workspace/artifacts/{selected_change_id}/`, sorted by mtime descending
+- Exclude `plan.yaml` from the artifact list (it gets its own section)
+- Take the top 5
+
+Else if `active_change.id` is set (no-plan fallback):
+- List files under `.ai-agents/workspace/artifacts/{active_change.id}/`, sorted by mtime descending
+- Take the top 5
+
+Otherwise:
+- List all files under `.ai-agents/workspace/artifacts/` (recursive), sorted by mtime descending
+- Take the top 5
+
+For each artifact, capture: file path, mtime, size (in tokens estimate = chars / 4), and the change-id it belongs to.
+
+### Step 3: Determine Resume Point
+
+**Plan-aware path** (when `selected_change_id` has a valid plan.yaml):
+
+Read the plan's `current_task`. The resume point = that task. Next-step recommendation = the task's `skill_hint` (or infer from task title if skill_hint is absent).
+
+Also filter `skill_history` to entries matching `change_id == selected_change_id` (entries with empty change_id are excluded from this filtered view).
+
+**Legacy path** (no plan):
+
+Pick the **resume point** by precedence:
+
+| Condition | Resume point | Phase label |
+|-----------|--------------|-------------|
+| `active_change` is set with non-empty `phase` | `{active_change.phase}` | from session |
+| `active_change` is set without phase | inferred from last skill in history | inferred |
+| `skill_history[0]` exists | last skill | last skill |
+| Nothing | `none` | new project |
+
+Map skill -> next-step recommendation:
+
+| Last skill | Suggested next |
+|-----------|----------------|
+| mvt-init | mvt-analyze-code (if has code) or mvt-analyze (if requirements available) |
+| mvt-analyze | mvt-design |
+| mvt-analyze-code | mvt-analyze (if requirements pending) or mvt-design |
+| mvt-design | mvt-plan-dev (if change is large) or mvt-implement |
+| mvt-implement | mvt-review |
+| mvt-review | mvt-fix (if findings) or mvt-test |
+| mvt-fix | mvt-review (re-review) or mvt-test |
+| mvt-test | mvt-cleanup or next change |
+| mvt-cleanup | new change via mvt-analyze |
+| (other) | mvt-status |
+
+### Step 4: Load Plan Progress (plan-aware path only)
+
+If `selected_change_id` has a plan, generate the **Plan Progress** section:
+
+- Read all tasks from plan.yaml.
+- Build a compact status table: `| # | id | title | status | skill_hint |`
+- Highlight `current_task` row (prefix with `>>` or bold).
+- Count summary: `Done: {d}, In Progress: {ip}, Pending: {p}, Blocked: {b}, Skipped: {s}`
+
+And the **Current Task Detail** section:
+
+- `title`
+- `acceptance` criteria (bulleted list)
+- `depends_on` with status of each dependency (all should be `done`)
+- `notes` (if non-empty)
+- `skill_hint` -> recommendation
+
+### Step 5: Generate Resume Report
+
+Render via the `resume-output.md` template. Sections to fill:
+
+1. **Active Task** -- name, change-id, phase, started_at (from active_change or selected plan)
+2. **Plan Progress** -- (only when plan exists) task table + counts + current task detail
+3. **Recent Skill History** -- last 5 entries from skill_history (filtered to selected change if applicable)
+4. **Recent Artifacts** -- the top 5 artifacts collected in Step 2 (path, mtime, size)
+5. **Resume Point** -- a one-paragraph natural-language summary of "where we are"
+6. **Recommended Next Step** -- the mapped next skill from Step 3, with justification
+
+### Step 6: Edge Cases
+
+- **No session**: report "No session found. Run `/mvt-init` to start a project."
+- **No active_change AND no history AND no plans**: report "No active task. Suggested entry points: `/mvt-init`, `/mvt-analyze`, `/mvt-status`."
+- **active_change set but referenced artifacts missing**: warn "Artifact directory `{path}` not found -- task state may be stale. Verify with `/mvt-status` or run `/mvt-cleanup`."
+- **Last skill ended in failure** (skill_history entry status=failed): surface the failure summary first, suggest retry of that skill rather than advancing.
+- **Plan exists but plan.yaml is invalid** (parse error or schema violation): warn "plan.yaml is corrupted or invalid. Run `/mvt-plan-dev` to regenerate, or `/mvt-status` to inspect."
+- **Stale task warning**: If plan's `current_task` has status `in_progress` but the plan's `updated_at` is more than 5 days old, append a notice: "Current task has been in_progress for {N} days without updates. Consider running `/mvt-update-plan` to refresh status."

package/sources/skills/mvt-resume/manifest.yaml

@@ -0,0 +1,71 @@
+name: mvt-resume
+output: .claude/skills/mvt-resume/SKILL.md
+
+frontmatter:
+  name: mvt-resume
+  description: "Resume an in-progress development task in a new conversation. Reads session.yaml (active_change, skill_history, recent_actions) and recent artifacts to reconstruct context. Does not read git state."
+
+sections:
+  - type: inline
+    content: |
+      # MVT Resume
+
+      ## Purpose
+
+      Reconstruct an in-progress development task in a fresh conversation by replaying state from `session.yaml`, recent artifacts, and plan.yaml (if one exists). When multiple plans are in-flight, prompt the user to select which change to resume. Use this skill at the start of a new conversation to pick up exactly where the last session left off.
+
+      ## Arguments
+
+      | Argument | Required | Description |
+      |----------|----------|-------------|
+      | `{change-id}` | No | Directly resume a specific change (skips candidate selection). Error if not found or not in_progress. |
+
+  - type: shared
+    source: sections/role-header.md
+    params:
+      role: Conductor
+      role_desc: "a Workflow Coordinator"
+      decision_rules:
+        - rule: "Multiple in_progress plans found -> Pause and display candidate table, wait for user selection"
+        - rule: "Exactly one in_progress plan found -> Auto-select it and proceed"
+        - rule: "No plans found BUT active_change is set -> Fall back to legacy skill_history-based resume"
+        - rule: "active_change is empty AND skill_history is empty AND no plans -> Recommend `/mvt-init` or `/mvt-status`"
+        - rule: "Plan exists and has current_task -> Use current_task's skill_hint as next-step recommendation"
+        - rule: "Plan's current_task has been in_progress for >5 days -> Surface stale warning"
+        - rule: "Last skill failed or was interrupted -> Surface the failure context, suggest retry"
+      boundaries:
+        - scope: "read git state (branch, diff, commits)"
+          skill: "(Out of scope -- this skill is session-state only)"
+        - scope: "modify any files"
+          skill: "(Read-only)"
+        - scope: "run analyses or tests"
+          skill: "(Use the recommended next skill)"
+
+  - type: shared
+    source: sections/activation-load-context.md
+
+  - type: shared
+    source: sections/activation-load-config.md
+
+  - type: shared
+    source: sections/output-language-constraint.md
+
+  - type: shared
+    source: sections/activation-preflight.md
+    params:
+      checks:
+        - order: "1"
+          field: "session.initialized_at"
+          level: "WARN"
+          message: "Session not initialized. Run `/mvt-init` first."
+
+  - type: file
+    source: ./business.md
+
+  - type: shared
+    source: sections/session-update.md
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-resume

package/sources/skills/mvt-review/business.md

@@ -1,49 +1,112 @@
-## Execution Flow
-
-### Step 1: Identify Review Target
-- Latest implementation files from current change
-- Files specified by user
-- Files in current change artifacts
-
-### Step 2: Load Context
-- Read target files
-- Read project-context for architecture expectations
-- Load review checklist for active pattern (if available)
-
-### Step 3: Analyze Code
-- Check architecture compliance (layer assignments, dependencies)
-- Check code quality (functions small/focused, naming, duplication)
-- Check error handling
-- Check edge cases
-- Check readability
-- If `--aspect` specified -> Focus on that aspect
-
-### Step 4: Categorize Issues
-Classify each finding by severity:
-
-| Level | Description | Action Required |
-|-------|-------------|-----------------|
-| **Critical** | Bugs, security issues, breaks functionality | Must fix before merge |
-| **Warning** | Code quality issues, potential bugs | Should fix |
-| **Suggestion** | Improvements, best practices | Nice to have |
-
-### Step 5: Update Workspace
-1. Update `.ai-agents/workspace/session.yaml`:
-   - Set `progress.review: done`
-   - Set `session.last_command: "/mvt-review"`
-   - Append one-line summary to `recent_actions` (keep max 3)
-2. Write artifact: `.ai-agents/workspace/artifacts/{change-id}/review.md`
-
-## Review Checklist
-
-### Architecture Compliance
-- [ ] Follows established architecture pattern
-- [ ] Correct layer assignment
-- [ ] Proper dependency direction
-- [ ] Module boundaries respected
-
-### Code Quality
-- [ ] Functions are small and focused
-- [ ] Naming is clear and consistent
-- [ ] No code duplication
-- [ ] Proper error handling
+## Execution Flow
+
+### Step 1: Load Inputs
+- **Required**:
+  - The set of files to review (see Step 2 for resolution).
+- **Fallback**:
+  - If `design.md`/`implementation.md` are missing, downgrade to "code-only review": skip the design-compliance checks (Step 4 row group A) and note the limitation in the artifact.
+  - If `project-context.md` is missing, skip layer-compliance checks and note the limitation.
+
+### Step 2: Resolve Review Target
+- **What**: produce a definitive file list to review.
+- **How**: pick the FIRST source that yields a non-empty list.
+
+  | Source | Condition |
+  |--------|-----------|
+  | User-provided file paths | User passed paths/globs as arguments |
+  | `--aspect` filter | User specified an aspect; intersect aspect-relevant files with the active change's `Change Tracking` |
+  | `implementation.md` -> `Files Touched` | Active change has implementation artifact |
+  | `git diff --name-only main...HEAD` | Inside a feature branch |
+  | `git diff --name-only HEAD~1` | Last-commit fallback |
+
+- If the resolved list is empty, STOP and ask the user to specify the target.
+- If the list exceeds ~30 files, ask the user to scope down OR confirm a high-level (per-module) review depth.
+
+### Step 3: Determine Review Depth
+- **Default**: full review across all axes (Step 4).
+- `--aspect <name>`: narrow to a single axis. Supported aspects: `architecture`, `quality`, `errors`, `edge-cases`, `security`, `naming`, `tests`. Other aspects -> ask user to clarify.
+- For files >300 lines, do a structural pass first (interfaces, exports, key paths) before line-level review; do not attempt line-by-line on huge files.
+
+### Step 4: Run Review Checks
+- **What**: produce findings, each tagged with severity, location, and a concrete remedy.
+- **How**: walk the checklist below. Skip any group whose inputs were missing per Step 1 fallback notes.
+
+  **Group A -- Design / Layer Compliance** (requires design.md OR project-context.md)
+  - Each file is in the module/layer assigned by design or project-context.
+  - Dependency direction respects layer rules (no upward imports, no forbidden cross-module reaches).
+  - Public interfaces match `Key Interfaces` from design.
+  - Implementation `Deviations from Design` are documented; undocumented deviations are findings.
+
+  **Group B -- Code Quality**
+  - Functions are small and focused; flag functions > ~50 lines or with > ~3 nested control levels.
+  - Naming is clear, consistent with `naming-conventions.md`, and matches surrounding code.
+  - No duplication: same logic appearing >= 3 times warrants extraction.
+  - No premature abstraction: a single-use helper / interface / wrapper is a finding.
+  - No dead code, unused imports, commented-out blocks left behind.
+
+  **Group C -- Error Handling**
+  - Error handling appears only at system boundaries (HTTP, DB, external API, file IO, queue).
+  - Interior try/catch must have an explicit reason in a one-line comment, otherwise findable.
+  - No swallowed errors (catch without rethrow / log / explicit recovery).
+  - Error types are specific where the language supports it (no bare `catch Exception` without rethrow).
+
+  **Group D -- Edge Cases**
+  - Boundary inputs handled: empty / null / max length / negative / zero / unicode.
+  - Concurrency: shared state, async ordering, idempotency where required by design.
+  - Resource lifecycle: opened resources are closed on all paths.
+  - Off-by-one: loop bounds, slice indices, pagination cursors.
+
+  **Group E -- Tests** (if test files are in scope)
+  - Each business rule from `project-context.md` has at least one test case.
+  - Tests assert behavior, not implementation details.
+  - No `skip` / `only` / commented-out tests left in.
+  - Test names describe the scenario, not the function name.
+
+  **Group F -- Security** (if user requirements mention auth/data sensitivity OR `--aspect security`)
+  - No secrets in code or test fixtures.
+  - Input validation at every external boundary.
+  - Auth/authz checks present on every protected endpoint or operation.
+  - SQL/NoSQL/HTML rendered through parameterized / escaped APIs.
+
+### Step 5: Categorize and De-duplicate Findings
+- **Severity**: assign each finding using the table below.
+
+  | Level | Definition | Examples |
+  |-------|------------|----------|
+  | **Critical** | Bug, security flaw, broken contract, data loss risk, layer violation that breaks isolation | Swallowed exception in payment path; missing auth on protected endpoint; forbidden cross-layer import |
+  | **Warning** | Likely problem or significant quality issue: not a bug today, but high-risk or maintainability hazard | Function 200 lines; duplicated logic 3x; missing tests for a documented business rule |
+  | **Suggestion** | Improvement, polish, taste preference | Variable name could be clearer; could split a small helper; minor docstring gap |
+
+- Merge duplicate findings (same root cause appearing in multiple files) into one entry with a list of locations.
+- Each finding must include: file, line range, severity, observation, recommendation.
+
+### Step 6: Write Artifact
+- **Path**: `.ai-agents/workspace/artifacts/{active_change.id}/review.md` if `active_change` exists; else `.ai-agents/workspace/artifacts/_ad-hoc-review-{YYYY-MM-DD-HHMM}/review.md`.
+- **Template**: `.ai-agents/skills/_templates/review-output.md` (custom override at `_templates/custom/...` takes precedence).
+- **Required content** (mapped to template headings):
+  - `Review Scope` -- file list, depth, aspect filter, fallbacks applied (e.g., "design.md missing -> Group A skipped").
+  - `Summary` -- counts per severity + one-paragraph overall verdict (Approve / Approve with comments / Request changes / Block).
+  - `Critical Findings` -- one entry per finding.
+  - `Warnings`.
+  - `Suggestions`.
+  - `Skipped Checks` -- groups skipped because inputs were missing, with reason.
+  - `Recommended Next Skill` -- e.g., `/mvt-fix` for Critical, `/mvt-test` if Group E gaps, `/mvt-refactor` if Group B is dominant.
+
+### Step 7: Verdict Rule
+- Critical > 0 -> verdict is `Request changes`. Suggest `/mvt-fix`.
+- Critical = 0, Warnings > 5 -> verdict is `Approve with comments`.
+- Critical = 0, Warnings <= 5, Suggestions only -> verdict is `Approve`.
+- Code-only review (design.md missing) -> verdict cannot be higher than `Approve with comments` (call it out explicitly).
+
+### Step 8: (session update handled by shared section)
+
+## Edge Cases & Errors
+
+| Case | Handling |
+|------|----------|
+| Review target is generated code (build output, lockfile, vendored dep) | Skip with a one-line note in artifact; do not flag findings |
+| All Group A inputs missing | Run as code-only review; cap verdict at `Approve with comments` |
+| User asked for review but there are zero changes | STOP, report "no diff to review", do not write artifact |
+| Findings in the same file conflict (e.g., quality says "extract", architecture says "do not introduce a new module") | Defer to architecture; record the tension in `Suggestions` |
+| Implementation explicitly documents a deviation from design (in `Deviations from Design`) | Treat as accepted -- flag only if the deviation is itself problematic |
+| Reviewer finds bugs requiring discussion before fix | Mark Critical, but do NOT auto-invoke `/mvt-fix`; leave the call to the user |