@uoyo/mvtt 2.0.0 → 2.2.0

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

@@ -21,6 +21,7 @@
   | Recently modified source files | Last-resort, last 24h mtime |
 
 - For each target file, locate or plan its corresponding test file path using the project's test layout convention (mirror under `tests/`, sibling `*.test.ts`, etc.).
+  - If the selected source is `git diff --name-only main...HEAD` or `Recently modified source files`, present the resolved target list and ask for scope confirmation before Step 7 writes any test file. Do not write tests from a low-confidence fallback without confirmation.
 
 ### Step 3: Identify Project Scope and Load Project-Specific Knowledge
 
@@ -35,7 +36,7 @@ This step applies only when the workspace has multiple projects (`projects.lengt
   2. Every entry under `skills.mvt-test.knowledge.{P}` -- load each entry's referenced files.
   3. Skip any key absent from the registry (no project-specific knowledge is valid; do not warn).
 - **Multi-project scenario**: if files span multiple projects, load each project's knowledge sequentially. The skill operates with the union of all loaded project-specific knowledge plus the `_all` knowledge already loaded at activation.
-- **Unmatched files**: if a file path does not match any project's `path` or `source_paths`, surface a note and treat it as belonging to the first project in `projects[]` (fallback). This may indicate a configuration gap in `project-context.yaml`.
+- **Unmatched files**: if a file path does not match any project's `path` or `source_paths`, surface a note and ask the user to choose the project scope. Do not silently fall back to the first project.
 
 ### Step 4: Identify Test Scenarios
 - **What**: produce a Scenario Table covering happy path, edge, negative, and security cases.
@@ -91,16 +92,13 @@ This step applies only when the workspace has multiple projects (`projects.lengt
 - Record each finding with: scenario id, expected vs observed, severity (Critical / Warning), and recommend `/mvt-fix`.
 
 ### Step 10: Write Artifact
-- **Path and template**: as defined in the **Artifact Structure** section below.
-- **Required content** (mapped to template headings):
-  - `Scope` -- target files, fallbacks applied.
-  - `Test Framework & Layout` -- chosen framework, file layout convention.
-  - `Test Scenarios` -- the Scenario Table from Step 4.
-  - `Test Cases` -- the row-level table from Step 6.
-  - `Granularity Decisions` -- summary from Step 5, including any "needs setup" gaps.
-  - `Coverage Analysis` -- only when `--coverage`; otherwise omit the heading.
-  - `Implementation Issues Found` -- from Step 9; empty list is fine.
-  - `Suggested Run Commands` -- one or two commands the user can copy-paste.
+- **Scope of this step**: this gate concerns ONLY the test-design record artifact (`test-design.md`). The actual test files were already written to the project tree in Step 7 and are NOT affected by the choice below.
+- **Confirm before writing**: when an `active_change` exists (so an artifact would be written), present the test-design summary in the conversation first (target scope, scenario/case counts, coverage gaps, any implementation issues), then ask the user whether to persist it: `Write the test-design artifact to {path}? (y/n)`.
+  - If the user declines (n), do NOT write any file under `artifacts/`. Keep the full test design in the conversation only, and note that no artifact was persisted. Then continue to Step 11.
+  - If the user confirms (y), write the artifact as described below.
+  - When no `active_change` exists, there is no artifact to write — skip the prompt and keep the full test design in the conversation only (no artifact).
+- **Path and template**: as defined in the **Artifact Structure** section below; this applies only when an `active_change` exists. Follow the HTML comments in the template for what each section should contain; strip comments from the final artifact.
+- **Required coverage**: cover only content that is applicable to this test effort. Preserve enough information for the user to understand the target scope, chosen framework/layout, scenarios and runnable test cases, granularity choices, coverage gaps when `--coverage` is set, implementation issues when found, and practical run commands when tests are generated. Do not create empty or artificial sections just because an item is named here; if the template omits or renames a section, place applicable content in the closest relevant section.
 - The actual test files go to the project tree; the artifact is a record.
 
 ### Step 11: State Update
@@ -117,3 +115,5 @@ Apply the State Update rules defined in the **State Update** section below.
 | Flaky test detected during writing | Add deterministic seeding/clock; if not possible, mark as `flaky-suspected` and surface in artifact |
 | User asks to "skip edge cases" | Refuse: edge cases are a non-negotiable boundary of this skill; explain and continue |
 | `--coverage` set but coverage tool not configured in project | Generate the gap list from scenarios alone; suggest tool setup; do not invoke a non-existent coverage runner |
+| User declines to write the artifact at Step 10 | Do not write any file under `artifacts/`; keep the test design in the conversation only and note that no artifact was persisted. Test files already written to the project tree (Step 7) are unaffected |
+| `active_change` is missing entirely | Write the test files to the project tree as usual, but keep the test-design record in the conversation only; do not write any artifact (no ad-hoc artifact path) |

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

@@ -31,9 +31,9 @@ sections:
         - scope: "modify the code being tested"
           skill: "/mvt-fix"
         - scope: "make architecture decisions"
-          skill: "(Test against existing design)"
+          guidance: "test against existing design"
         - scope: "skip edge cases or negative tests"
-          skill: "(Never)"
+          guidance: "never"
 
   - type: inline
     content: |
@@ -46,23 +46,14 @@ sections:
       | `/mvt-test --coverage` | Generate tests with coverage analysis |
 
   - type: shared
-    source: sections/activation-load-context.md
+    source: sections/activation-protocol.md
     params:
+      activation_reads:
+        - session.yaml
       extended_context:
         - "Implementation files to be tested"
-
-  - type: shared
-    source: sections/activation-load-config.md
-
-  - type: shared
-    source: sections/language-constraint.md
-
-  - type: shared
-    source: sections/output-format-constraint.md
-
-  - type: shared
-    source: sections/activation-preflight.md
-    params:
+        - ".ai-agents/workspace/artifacts/{active_change.id}/design.md -- error paths / data flow that negative-path scenarios trace to (skip if absent)"
+      has_preflight: true
       checks:
         - order: "1"
           field: "session.initialized_at"
@@ -73,6 +64,12 @@ sections:
           level: "WARN"
           message: "No implementation found. Run `/mvt-implement` first."
 
+  - type: shared
+    source: sections/language-constraint.md
+
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: inline
     content: |
       ## Test Case Types
@@ -93,8 +90,8 @@ sections:
       ## Artifact Structure
       Read the document structure template from: `.ai-agents/skills/_templates/test-output.md`
       If a custom version exists at `.ai-agents/skills/_templates/custom/test-output.md`, use the custom version instead.
-      The template defines section headings only. Generate content for each section based on test design results.
-      Write the artifact to: `.ai-agents/workspace/artifacts/{change-id}/tests/test-design.md`
+      The template defines section structure and guidance comments. Generate applicable content based on test design results.
+      Write the artifact to: `.ai-agents/workspace/artifacts/{change-id}/test-design.md`
 
   - type: shared
     source: sections/session-update.md

package/sources/skills/mvt-update-plan/business.md

@@ -29,7 +29,9 @@ The mechanical work — mutating the task, recomputing `current_tasks` via the p
 rules, validating the result, and writing back atomically — is performed by a
 deterministic script. Do NOT hand-edit `plan.yaml` or reason through the
 `current_tasks` selection yourself; call the script with the resolved arguments
-from Step 1–2:
+from Step 1–2. See the **Script Usage Rule** section for the command template,
+or read `.ai-agents/scripts/plan-update.md` for argument value sources,
+parameter semantics, and output interpretation.
 
 ```bash
 node .ai-agents/scripts/plan-update.cjs --plan "<active_change.plan_path>" --task <task_id> --status <new_status> --projects "<comma,separated,project,names>" [--artifacts "<comma,separated,paths>"] [--notes "<note text>"]
@@ -37,30 +39,7 @@ node .ai-agents/scripts/plan-update.cjs --plan "<active_change.plan_path>" --tas
 
 Include `--artifacts` only if artifacts were provided, and `--notes` only if a note was provided; omit each flag otherwise.
 
-| Argument | Value source |
-|----------|-------------|
-| `--plan` | `active_change.plan_path` resolved from session.yaml |
-| `--task` | the `task_id` resolved in Step 1 |
-| `--status` | the `new_status` resolved in Step 1 (`pending`/`in_progress`/`done`/`blocked`/`skipped`) |
-| `--projects` | comma-separated project names read from `project-context.yaml > projects[].name` |
-| `--artifacts` | optional; comma-separated paths to append (the script de-duplicates) |
-| `--notes` | optional; overwrites the task's `notes` |
-
-The script performs, deterministically:
-
-1. **Apply**: sets the task status; appends + de-duplicates `--artifacts` (handles `artifacts: null`); overwrites `--notes`; sets `completed_at` to now when status is `done`, else `null`; refreshes `plan.updated_at`.
-2. **Recompute `current_tasks`** (per-project independent advancement): for each project, finds the `in_progress` task or advances the first `pending` task whose `depends_on` are all in `resolvedIds` (done + skipped; blocked does NOT satisfy). Detects `project_switch` when advancement crosses a project boundary. Plan done -> `current_tasks = {}`.
-3. **Validate** the mutated plan (unique ids, valid `depends_on` references, DAG/no-cycle per project, one `in_progress` per project, every task has acceptance, `completed_at` consistency, `current_tasks` validity, project naming constraint, task project membership).
-4. **Write atomically** (temp + rename) only if validation passes.
-
-**Interpreting the result:**
-
-- **Exit 0**: success. stdout is a single-line JSON object:
-  ```json
-  {"ok":true,"task":{"id":"t1","title":"...","old_status":"in_progress","new_status":"done"},"current_tasks":{"default":"t2"},"plan_status":"in_progress","progress":{"done":1,"total":4},"warning":null,"project_switch":null}
-  ```
-  Use these fields directly to render the Output Format block. The file is already written — do NOT read it back to verify. If `warning` is non-null, surface it. If `project_switch` is non-null, note the project boundary crossing.
-- **Exit 1**: failure. stderr carries the error (invalid status, task not found, validation failure, parse/write error). The file was **not** modified. Report the error to the user and do not fabricate a success summary.
+**Interpreting the result:** See `.ai-agents/scripts/plan-update.md` "Output interpretation" for the exit-0 / exit-1 protocol. On exit 0, use the JSON fields directly to render the Output Format block. On exit 1, report stderr and do not fabricate a success summary.
 
 ### Step 4: Output
 
@@ -91,15 +70,25 @@ After the Step 3 script reports `plan_status: "done"`:
    > - **(defer)** Mark child done but don't advance yet
 
 4. On **y**:
-   - `epic-update.cjs --epic <active_epic.epic_path> --complete-child <active_change.id>`
-   - `session-update.cjs --skill mvt-update-plan --summary "..." --close-change`
+  - Call the Epic Update Script in `--complete-child` mode using the command below:
+     ```bash
+     node .ai-agents/scripts/epic-update.cjs --epic "<active_epic.epic_path>" --complete-child <active_change.id>
+     ```
+  - If the epic-update command fails, STOP and do not call `session-update.cjs`; report stderr and keep the active change open.
+  - If epic-update succeeds, call `session-update.cjs --skill mvt-update-plan --summary "..." --close-change`.
+  - If session-update fails after epic-update succeeded, report the divergence explicitly: the child was marked done in `epic.yaml`, but `session.active_change` was not closed. Tell the user to rerun `/mvt-update-plan` or manually recover session state before continuing.
    - Display: next child info from epic-update stdout. Suggest `/mvt-analyze` to start the next sub-change.
 
 5. On **n**: No action. Display reminder: "Change remains open. Run other skills (e.g., `/mvt-review`, `/mvt-test`, `/mvt-fix`) as needed; run `/mvt-update-plan` again when ready to advance the epic."
 
 6. On **defer**:
-   - `epic-update.cjs --epic <active_epic.epic_path> --set-child-status <active_change.id> done`
-   - `session-update.cjs --skill mvt-update-plan --summary "..." --close-change`
+  - Call the Epic Update Script in `--set-child-status` mode using the command below:
+     ```bash
+     node .ai-agents/scripts/epic-update.cjs --epic "<active_epic.epic_path>" --set-child-status <active_change.id> --child-status done
+     ```
+  - If the epic-update command fails, STOP and do not call `session-update.cjs`; report stderr and keep the active change open.
+  - If epic-update succeeds, call `session-update.cjs --skill mvt-update-plan --summary "..." --close-change`.
+  - If session-update fails after epic-update succeeded, report the divergence explicitly: the child was marked done in `epic.yaml`, but `session.active_change` was not closed. Tell the user to rerun `/mvt-update-plan` or manually recover session state before continuing.
    - Display: "Child marked done, current_change unchanged."
 
 ## Edge Cases & Errors

package/sources/skills/mvt-update-plan/manifest.yaml

@@ -35,32 +35,28 @@ sections:
           skill: "/mvt-implement"
 
   - type: shared
-    source: sections/activation-load-context.md
+    source: sections/activation-protocol.md
     params:
+      activation_reads:
+        - session.yaml
       extended_context:
         - "{active_change.plan_path} -- The plan to update (resolved from session.yaml)"
-
-  - type: shared
-    source: sections/activation-load-config.md
-
-  - type: shared
-    source: sections/language-constraint.md
-
-  - type: shared
-    source: sections/output-format-constraint.md
-
-  - type: shared
-    source: sections/activation-preflight.md
-    params:
+      has_preflight: true
       checks:
         - order: "1"
           field: "session.initialized_at"
           level: "WARN"
-          message: 'Session not initialized. Run `/mvt-init` first.'
+          message: "Session not initialized. Run `/mvt-init` first."
         - order: "2"
           field: "active_change.plan_path"
           level: "BLOCK"
-          message: 'No active plan. Run `/mvt-plan-dev` to create one.'
+          message: "No active plan. Run `/mvt-plan-dev` to create one."
+
+  - type: shared
+    source: sections/language-constraint.md
+
+  - type: shared
+    source: sections/output-format-constraint.md
 
   - type: inline
     content: |
@@ -108,6 +104,12 @@ sections:
       current_skill: mvt-update-plan
       update_change: true
 
+  - type: shared
+    source: sections/script-usage-rule.md
+    params:
+      uses_plan_update: true
+      epic_update_inline_modes_only: true
+
   - type: shared
     source: sections/footer-next-steps.md
     params:

package/sources/templates/analyze-output/body.md

@@ -1,15 +1,56 @@
 # Requirements Analysis: {Feature Name}
 
+<!--
+  This template defines the structure of analysis.md.
+  Each section below includes a guidance comment explaining what to write.
+  Replace {Feature Name} with the actual feature/change name.
+  Remove these HTML comments in the final artifact.
+-->
+
 ## Feature Overview
+<!--
+  One paragraph: what the requirement asks for, the scope of this analysis,
+  and the source of the requirements (file path or "conversation only").
+  Keep it concise — the details go in the sections below.
+-->
 
 ## Actors
+<!--
+  List all actors and stakeholders involved in the feature: user roles,
+  system actors, and external services. One line per actor with its role.
+  If only one actor is involved, state it explicitly.
+-->
 
 ## Requirements
+<!--
+  The extracted features and functionality, grouped logically.
+  Each requirement: what it does + any assumptions made during extraction.
+  This is the core of the analysis — be specific and actionable.
+-->
 
 ## Domain Concepts
+<!--
+  Key domain entities, terms, and abstractions introduced or affected.
+  Present as a glossary where helpful: | Term | Meaning |.
+  Include models, value objects, DTOs, and configuration concepts.
+-->
 
 ## Business Rules
+<!--
+  Extracted business rules and constraints: validation rules, computation
+  rules, state transitions, and access restrictions. One rule per bullet
+  with a clear statement of the constraint.
+-->
 
 ## Ambiguities & Questions
+<!--
+  Unclear, missing, or conflicting requirements detected during analysis.
+  Each item: the ambiguity + a specific clarification question for the user.
+  If no ambiguities were found, write "None detected".
+-->
 
 ## Change Tracking
+<!--
+  Optional. If this analysis feeds a tracked change, note the change-id and
+  a one-line status. Otherwise, omit this section entirely.
+-->

package/sources/templates/decompose-output/body.md

@@ -1,13 +1,49 @@
 # Epic Decomposition: {Epic Title}
 
+<!--
+  This template defines the structure of epic.md (the narrative companion
+  to epic.yaml). Each section below includes a guidance comment explaining
+  what to write. Replace {Epic Title} with the actual epic name.
+  Remove these HTML comments in the final artifact.
+-->
+
 ## Vision
+<!--
+  One-sentence summary of the overall epic goal. This is the single
+  cohesive outcome the decomposition aims to deliver.
+-->
 
 ## Scope & Out of Scope
+<!--
+  What the epic delivers (in scope) vs. what it explicitly excludes
+  (out of scope). Two short lists or a two-column table. Boundaries here
+  prevent scope creep into the child stories.
+-->
 
 ## Cross-cutting Concerns
+<!--
+  Themes spanning multiple children: auth, logging, error handling, data
+  migration, shared infrastructure, etc. Each concern: which children it
+  affects. These are not standalone children — they are shared obligations.
+-->
 
 ## Child Stories
+<!--
+  Markdown table mirroring epic.yaml children[]. Columns:
+  | # | Child | Scope | Status | Depends On |
+  One row per child story. Status is `active` for the first child and
+  `pending` for the rest. Depends On lists change_ids (empty for roots).
+-->
 
 ## Dependency Map
+<!--
+  Mermaid flowchart showing child dependencies (the DAG). Each node is a
+  child change_id; edges point from dependency to dependent. This must
+  match the depends_on relationships in epic.yaml and contain no cycles.
+-->
 
 ## Open Questions
+<!--
+  Ambiguities or decisions deferred during decomposition. Each item: the
+  question + which child it affects (if any). If none, write "None".
+-->

package/sources/templates/design-output/body.md

@@ -1,17 +1,65 @@
 # Architecture Design: {Feature Name}
 
+<!--
+  This template defines the structure of design.md.
+  Each section below includes a guidance comment explaining what to write.
+  Replace {Feature Name} with the actual feature/change name.
+  Remove these HTML comments in the final artifact.
+-->
+
 ## Overview
+<!--
+  The problem statement: what is being designed and why. Summarise the
+  requirement context (from analysis.md or conversation) and the design
+  goal in one short paragraph.
+-->
 
 ## Architecture Decision Records
+<!--
+  Every ADR from the design process. Each ADR: context, decision, status
+  (proposed/accepted/superseded), and consequences. Never zero ADRs — if
+  none were needed, produce minimal one-line ADRs. In --plan mode, ADRs
+  collapse to one-line `decision: <text>`.
+-->
 
 ## Module Design
+<!--
+  Table of modules from the design: | Module | Path | Responsibility |
+  Dependencies |. Each module's boundary, what it owns, and what it
+  depends on. This drives the File Structure and implementation ordering.
+-->
 
 ## Key Interfaces
+<!--
+  Explicit signatures and endpoints: function signatures, class contracts,
+  HTTP endpoints (method + path), event contracts. These are the public
+  contracts that /mvt-implement must match exactly.
+-->
 
 ## Data Flow
+<!--
+  Sequences describing how data moves through the system, including error
+  paths. Use prose or mermaid sequence diagrams. Cover the main flow and
+  each declared error path.
+-->
 
 ## File Structure
+<!--
+  Mapping of modules to file/directory paths in this repo. Show the
+  intended file layout (create/modify/delete) so /mvt-implement and
+  /mvt-plan-dev can locate targets without re-deriving paths.
+-->
 
 ## Implementation Guidelines
+<!--
+  Ordering hints for /mvt-implement and /mvt-plan-dev: which modules to
+  build first, shared dependencies to establish early, and any sequencing
+  constraints. Not a task list — just guidance.
+-->
 
 ## Change Tracking
+<!--
+  List of files expected to be created/modified/deleted by this design.
+  This is the footprint estimate; /mvt-implement records the actual
+  footprint. If > ~5 files or > 1 new module, /mvt-plan-dev is recommended.
+-->

package/sources/templates/implement-output/body.md

@@ -1,11 +1,56 @@
 # Implementation: {Feature Name}
 
-## Implementation Plan
+<!--
+  This template defines the structure of implementation.md.
+  Each section below includes a guidance comment explaining what to write.
+  Replace {Feature Name} with the actual feature/change name.
+  Remove these HTML comments in the final artifact.
+-->
 
-## Changes
+## Implementation Summary
+<!--
+  One paragraph: what was built, the scope of this implementation, and
+  which design or plan task it fulfils. Keep it concise — the details go
+  in the sections below.
+-->
 
-## Implementation Details
+## Files Touched
+<!--
+  Table with columns: Path | Action (create/modify/delete) | Intent (one line)
+  List every file written, modified, or deleted during this implementation.
+  This is the authoritative record of the change footprint.
+-->
 
 ## Design Compliance
+<!--
+  Summary of Step 5 design-compliance checks. For each check, state:
+  passed / deviated / not-applicable, with a one-line reason.
+  mvt-review will read this section and independently verify the claims.
+-->
+
+## Deviations from Design
+<!--
+  List any deviations from design.md (files added/removed, interface changes,
+  module placement changes). Each entry: what changed + why.
+  An empty list (write "None") is acceptable and expected for clean implementations.
+-->
+
+## Self-Check Results
+<!--
+  Record Step 6 outcomes: type-checker status (pass/fail/not-configured),
+  any suggested test commands, and UI verification status if applicable.
+  Do NOT claim "tested" if only a type-check was run.
+-->
+
+## Open TODOs
+<!--
+  Anything deferred to /mvt-review, /mvt-test, or a follow-up change.
+  Each item: what is pending + who/which skill should handle it.
+  Write "None" if nothing is deferred.
+-->
 
 ## Change Tracking
+<!--
+  Optional. If this change is tracked in plan.yaml, note the task id(s)
+  and a one-line status. Otherwise, omit this section entirely.
+-->

package/sources/templates/project-context/body.md

@@ -1,13 +1,58 @@
 # Project: {project name}
 
+<!--
+  This template defines the structure of project-context.md — the
+  project semantic document generated by /mvt-analyze-code.
+  Each section below includes a guidance comment explaining what to write.
+  Replace {project name} with the actual project name.
+  Remove these HTML comments in the final artifact.
+
+  Multi-project note: when the workspace has multiple projects, each
+  project's content is written under its own `# Project: {name}` heading
+  within the single file. If a section has no relevant content, include
+  the heading with "(No relevant content detected)".
+-->
+
 ## Overview
+<!--
+  One paragraph: what the project is, its purpose, and its tech stack.
+  Inferred from the codebase structure and entry points.
+-->
 
 ## Core Terms
+<!--
+  Glossary of domain-specific terminology found in the code: class and
+  interface names representing domain concepts, abbreviations and their
+  expansions, domain jargon from comments and docstrings.
+  Present as a table: | Term | Meaning |.
+-->
 
 ## Module Structure
+<!--
+  Top-level modules and their responsibilities. For each module: path,
+  responsibility, and dependencies on other modules. Include domain
+  entities (models, schemas, types, interfaces) classified by type
+  (domain model, value object, DTO, configuration).
+-->
 
 ## Layer Structure
+<!--
+  Architectural layers and their boundaries: which layer imports which,
+  and any forbidden cross-layer imports. This feeds the forbidden-import
+  checks in /mvt-implement and /mvt-review.
+-->
 
 ## Key Business Rules
+<!--
+  Business logic and constraints extracted from code: validation rules
+  (assertions, guards), computation rules (formulas, algorithms), state
+  transition rules (workflow steps, status changes), and constraint rules
+  (limits, quotas, access restrictions).
+-->
 
 ## API Overview
+<!--
+  Public interfaces: HTTP endpoints (method + path), public methods of
+  service classes, event publishers/subscribers, and CLI commands if
+  applicable. This is the external contract surface of the project.
+-->

package/sources/templates/review-output/body.md

@@ -1,11 +1,70 @@
 # Code Review Report
 
+<!--
+  This template defines the structure of review.md.
+  Each section below includes a guidance comment explaining what to write.
+  Remove these HTML comments in the final artifact.
+-->
+
+## Review Scope
+<!--
+  The file list reviewed, the review depth (full / per-module / aspect
+  filter), and any fallbacks applied (e.g., "design.md missing -> Group A
+  skipped"). This establishes what was and was not covered.
+-->
+
 ## Summary
+<!--
+  Counts per severity (Critical / Warning / Suggestion) plus a one-paragraph
+  overall verdict: Approve / Approve with comments / Request changes / Block.
+  Verdict rule: Critical > 0 -> Request changes; Critical = 0 & Warnings > 5
+  -> Approve with comments; Critical = 0 & Warnings <= 5 & Suggestions only
+  -> Approve. Code-only review (design.md missing) caps at Approve with comments.
+-->
 
 ## Critical Issues
+<!--
+  One entry per Critical finding. Each finding: file, line range, severity,
+  observation, recommendation. Critical = bug, security flaw, broken
+  contract, data loss risk, or layer violation that breaks isolation.
+  Merge duplicate findings (same root cause, multiple files) into one entry.
+-->
 
 ## Warnings
+<!--
+  One entry per Warning finding. Warning = likely problem or significant
+  quality issue that is not a bug today but is high-risk or a maintainability
+  hazard (e.g., function 200 lines, duplicated logic 3x, missing tests for a
+  documented business rule). Same finding format as Critical Issues.
+-->
 
 ## Suggestions
+<!--
+  One entry per Suggestion finding. Suggestion = improvement, polish, or
+  taste preference (e.g., clearer variable name, split a small helper,
+  minor docstring gap). Same finding format as Critical Issues.
+-->
+
+## Skipped Checks
+<!--
+  Review groups skipped because their inputs were missing (e.g., Group A
+  skipped when design.md is absent, Group E skipped when no test files in
+  scope). Each entry: the group name + the reason it was skipped.
+  If no groups were skipped, write "None".
+-->
+
+## Recommended Next Skill
+<!--
+  One-line recommendation based on findings: `/mvt-fix` for Critical
+  issues, `/mvt-test` if Group E (tests) gaps, `/mvt-refactor` if Group B
+  (quality) is dominant, `/mvt-implement` if review is clean and work
+  remains. Tailor to the actual finding distribution.
+-->
 
 ## Highlights
+<!--
+  Positive observations worth noting: well-structured code, good test
+  coverage, clean abstractions, or anything done particularly well.
+  Balances the review and reinforces good practices. Optional — omit if
+  nothing stands out.
+-->