@uoyo/mvtt 2.0.0-beta.6 → 2.1.0

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

@@ -44,12 +44,6 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
-  - type: shared
-    source: sections/output-language-constraint.md
-
-  - type: shared
-    source: sections/output-format-constraint.md
-
   - type: shared
     source: sections/activation-preflight.md
     params:
@@ -59,6 +53,12 @@ sections:
           level: "WARN"
           message: 'Session not initialized. Run `/mvt-init` first.'
 
+  - type: shared
+    source: sections/language-constraint.md
+
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: inline
     content: |
       ## Operation Mode: Shortcut

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

@@ -2,12 +2,19 @@
 
 ### Step 1: Load Inputs
 - **Recommended**:
-  - `.ai-agents/knowledge/project/_generated/project-context.md` -- existence check only, to detect whether semantic context has been generated.
+  - `.ai-agents/knowledge/project/_generated/project-context.md` -- existence check only, to detect whether semantic context has been generated. This generated semantic context (`.md`) is distinct from the structural project index (`.ai-agents/workspace/project-context.yaml`) loaded during activation.
 - **Fallback**: any missing optional file is treated as "feature absent" for assessment purposes; do not abort. If `registry.yaml` itself is missing, surface the error and recommend `mvtt install`.
 
 ### Step 2: Assess User Position
 - **What**: pick exactly one recommended next skill based on the current workspace state.
 - **How**: walk the table top-to-bottom; the first row whose condition holds wins.
+- **Evidence conventions**:
+  - Active change artifacts resolve under `.ai-agents/workspace/artifacts/{active_change.id}/`.
+  - `analysis.md`, `design.md`, `implementation.md`, `review.md`, and `test-design.md` refer to files in the active change artifact directory unless stated otherwise.
+  - Completed skill history matches `session.yaml > history[].skill` exactly, using the `/mvt-` prefix and case-sensitive skill name. When `active_change.id` is non-empty, prefer history rows whose `change_id` matches the active change; use unmatched history only as fallback context.
+  - `Change Tracking lists > 5 files` means `design.md > ## Change Tracking` names more than five affected files.
+  - A `review.md` has Critical findings when its severity summary or Critical Issues section reports one or more Critical findings.
+- **Runtime recommendation**: store the winning row as the primary runtime recommendation. Use that same recommendation in Current Status, "What should I do next?" answers, and as the first Suggested Next Steps item.
 
   | Condition | Recommendation |
   |-----------|---------------|
@@ -20,13 +27,13 @@
   | `design.md` exists, change is large (Change Tracking lists > 5 files OR ADR includes breaking change OR > 1 new module) | `/mvt-plan-dev` -- Decompose into tracked plan |
   | `design.md` (or `plan.yaml`) ready, no `implementation.md` | `/mvt-implement` -- Implement the design |
   | `implementation.md` exists, no `review.md` | `/mvt-review` -- Review the code |
+  | `review.md` has Critical findings | `/mvt-fix` -- Fix critical issues before continuing; surface prominently above the catalog |
   | `review.md` exists with no Critical findings, no `test-design.md` | `/mvt-test` -- Write tests |
-  | `review.md` has Critical findings | `/mvt-fix` -- Fix critical issues before continuing |
   | All of the above complete | `/mvt-cleanup` -- Tidy artifacts, OR start a new feature with `/mvt-analyze` |
 
 ### Step 3: Display Skills Catalog
 Read `registry.yaml` > `skills` section.
-Display all skills as a single flat table (no grouping; the section comment headers in `registry.yaml` already group them by role for human readers):
+Display all skills as a single flat table:
 - Header row: `Skill | Description`
 
 For each skill, show: `/{skill-name}` | `description` field from registry.
@@ -46,9 +53,13 @@ flowchart LR
     C -.->|epic scale| DC[decompose]
     DC --> C2[analyze<br/>epic-child]
     C2 --> D
+
+    classDef done fill:#c6efce,stroke:#2e7d32,color:#2e7d32
+    classDef current fill:#ffeb9c,stroke:#f59e0b,color:#b45309
+    classDef pending fill:#f0f0f0,stroke:#9ca3af,color:#6b7280
 ```
 
-Color-code based on current progress: green (done), yellow (current/recommended), gray (pending). The "current" node is whichever skill the Step 2 table recommended; "done" is determined by the same evidence the Step 2 table consumed.
+Apply `:::done`, `:::current`, and `:::pending` to nodes based on current progress: green/done, yellow/current recommendation, gray/pending. The "current" node is whichever skill the Step 2 table recommended; "done" is determined by the same evidence the Step 2 table consumed.
 
 ### Step 5: Respond to User Questions
 - **What**: handle the user's free-form question after the catalog is rendered.
@@ -56,10 +67,10 @@ Color-code based on current progress: green (done), yellow (current/recommended)
 
   | Question pattern | Response |
   |------------------|----------|
-  | "What should I do next?" / no specific question | Repeat the Step 2 recommendation in one line, followed by a one-clause reason citing the matched condition |
-  | "What does `/mvt-X` do?" / asks about a specific skill | Read the skill's metadata from `registry.yaml`, show: name, description, knowledge entries (if any), template (if any). Mention "see the skill's SKILL.md for the full procedure" -- do NOT inline the full SKILL.md content (too large) |
+  | "What should I do next?" / no specific question | Repeat the primary runtime recommendation in one line, followed by a reason explaining why the matched current state fact applies |
+  | "What does `/mvt-X` do?" / asks about a specific skill | Read the skill's metadata from `registry.yaml`; show name and description. If `template` exists, mention it. If `custom: true` is set, note it. If `knowledge` exists on that skill entry, show it; otherwise omit knowledge. Mention "see the skill's SKILL.md for the full procedure" -- do NOT inline the full SKILL.md content (too large) |
   | "Compare `/mvt-X` and `/mvt-Y`" | Pull descriptions from registry; if both are workflow skills, mention their relative position in the diagram |
-  | Asks about something not in registry | Reply: "No skill matches that. Available skills: see catalog above." Do not invent skills |
+  | Asks about something not in registry | Do not invent skills. Use simple keyword overlap against skill names and descriptions in `registry.yaml`; if there are close matches, show up to two "closest matches" with one-line reasons. If no close matches exist, say no skill matches and point to the catalog. |
 
 ## Edge Cases & Errors
 
@@ -68,7 +79,6 @@ Color-code based on current progress: green (done), yellow (current/recommended)
 | `registry.yaml` missing | STOP at Step 1; recommend `mvtt install`; show no catalog |
 | `session.yaml` missing | Render catalog (Step 3) and diagram (Step 4) without the "current position" highlight; Step 2 recommends `/mvt-init` |
 | `changes[]` references a `plan_path` that no longer exists | Ignore for help purposes; do not warn -- `/mvt-status` is the right place for that |
-| User invokes `/mvt-help` while inside an active change with Critical review findings | Step 2's recommendation is `/mvt-fix`; surface this prominently above the catalog |
 | User asks about a custom skill (registry entry with `custom: true`) | Treat identically to built-ins; the only difference is showing `custom: true` in the metadata view |
-| Workflow diagram cannot be rendered (mermaid unsupported in environment) | Fall back to a textual flow: `init -> analyze-code -> analyze -> [decompose (epic) -> analyze (epic-child)] -> design -> [plan-dev] -> implement -> review -> test` |
+| Workflow diagram cannot be rendered (mermaid unsupported in environment) | Fall back to a textual flow: `init -> analyze-code -> analyze -> [decompose (epic) -> analyze (epic-child)] -> design -> [plan-dev] -> implement -> review -> test`; mark nodes with `[done]`, `[current]`, or `[pending]` using the same evidence rules |
 | Epic-pending state (`active_epic` non-empty, `active_change` empty) | Step 2's recommendation is `/mvt-analyze` to start the next sub-change; the decompose path is shown in the workflow diagram |

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

@@ -24,6 +24,9 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
+  - type: shared
+    source: sections/language-constraint.md
+
   - type: file
     source: ./business.md
 
@@ -37,15 +40,15 @@ sections:
       ## MVT Help
 
       ### Current Status
-      - **Project**: {name} ({initialized/not initialized})
+      - **Project**: {project names from `project-context.yaml > projects[]`, comma-separated} ({initialized/not initialized from `session.yaml > session.initialized_at`})
       - **Last Skill**: {last command from history}
-      - **Recommended Next**: `/mvt-{next}` -- {description}
+      - **Recommended Next**: {primary runtime recommendation from Step 2}
 
       ### Workflow
       {Mermaid flowchart with current position highlighted}
 
       ### Available Skills
-      {Skills tables grouped by category, as defined in Step 3}
+      {Single flat skills table, sorted by registry declaration order}
       ```
 
   - type: shared
@@ -57,14 +60,3 @@ sections:
     source: sections/footer-next-steps.md
     params:
       current_skill: mvt-help
-      conditional_suggestions:
-        conditions:
-          - condition: "project not initialized"
-            primary: mvt-init
-            primary_desc: "Initialize the project"
-          - condition: "project initialized, no active change"
-            primary: mvt-analyze
-            primary_desc: "Start analyzing requirements for a new feature"
-          - condition: "active change in progress"
-            primary: mvt-resume
-            primary_desc: "Resume work on the active change"

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

@@ -11,10 +11,12 @@
 - **What**: produce an ordered file list with the smallest possible commit boundary per group.
 - **How**:
   1. Take `Change Tracking` from `design.md` as the source of truth for which files are in scope.
-  2. Topologically order files by dependency: domain entities -> repositories/adapters -> use-case/services -> controllers/UI.
-  3. Group consecutive files that share a single conceptual change into one commit boundary.
-  4. For each file, decide: `create | modify | delete`, and write a one-line intent.
-- **Plan-aware behavior**: if `plan.yaml` is present, identify the active task from `current_tasks` (the entry matching the current project, or the sole entry in single-project mode), then treat that task's `artifacts.files` (cross-reference `plan.tasks[*].artifacts.files`) as a **starting-scope hint, not a hard ceiling**. The source of truth for scope remains `design.md`'s `Change Tracking` (per Step 2.1). When `artifacts.files` is `null` or empty, derive scope entirely from `Change Tracking`. If implementation reveals files beyond this hint are genuinely required, do NOT silently expand — surface them via Step 3 confirmation and never absorb files that clearly belong to a different task.
+  2. Derive dependencies from `Module Design`, `Key Interfaces`, and `Data Flow`.
+  3. Order files dependency-first: shared types/contracts -> dependency-free internals -> dependents -> entry points/controllers/routes/UI shells.
+  4. For async/event flows: event schemas first; then producers and consumers after shared contracts. Put producers before consumers only when consumers import producer-side types.
+  5. Group consecutive files that share a single conceptual change into one commit boundary.
+  6. For each file, decide: `create | modify | delete`, and write a one-line intent.
+- **Plan-aware behavior**: if `plan.yaml` exists, resolve one active task before planning. Candidate task ids come from deduplicated `current_tasks`; if one remains, use it. If several remain, prefer an explicit user task id, then match current paths against each candidate's `artifacts.files` and project paths; if still ambiguous, ask the user. Treat the resolved task's `artifacts.files` as a starting-scope hint only; `design.md` Change Tracking remains authoritative. Confirm Step 3 before touching files beyond the hint, and never absorb files that belong to another task.
 - **Output of this step**: an in-conversation list shown to user as a preview, with no write yet.
 
 ### Step 3: Confirm Scope (when needed)
@@ -39,18 +41,19 @@
 
 ### Step 5: Verify Design Compliance
 - **What**: confirm the implementation matches the design before writing the artifact.
-- **How**: run the checks below. Each is either Auto (mechanical / scriptable / type-checker) or Manual (read the design + diff).
+- **How**: run the checks below and record the result in `implementation.md > Design Compliance`. `mvt-review` will use this section as an input and independently verify claimed passes or undocumented deviations.
 
-  | Check | Mode | Action on failure |
-  |-------|------|-------------------|
-  | Files touched == Change Tracking ± deviation noted | Auto (compare lists) | Update artifact's deviation log OR revert extras |
-  | Each file lives in the module/layer assigned by `Module Design` | Auto (path match against design table) | Move file or mark deliberate exception with rationale |
-  | Public interfaces match `Key Interfaces` (signatures, endpoints) | Auto (grep for declarations) | Adjust to match OR raise as deliberate change requiring `/mvt-design` re-run |
-  | Forbidden cross-layer imports absent | Auto (grep import paths against `project-context.md` rules) | BLOCK -- must fix before artifact write |
-  | Error handling lives only at boundaries listed in design | Manual (read code) | Refactor or document why an interior catch was needed |
-  | No new external deps not listed in `design.md` ADRs | Auto (diff package manifests) | Either remove or add an ADR via `/mvt-design` |
+  | Check | Mode | Failure level | Action on failure |
+  |-------|------|---------------|-------------------|
+  | Files touched == Change Tracking ± deviation noted | Auto (mechanical list compare) | WARN-and-document | Update `Deviations from Design` OR revert extras |
+  | Each file lives in the module/layer assigned by `Module Design` | Semi-auto (path heuristic; downgrade to Manual if design tables lack path/module mapping) | WARN-and-document | Move file or mark deliberate exception with rationale |
+  | Public interfaces match `Key Interfaces` (signatures, endpoints) | Semi-auto (grep can find declarations; signature compatibility is Manual) | BLOCK | Adjust to match OR stop and require `/mvt-design` re-run for a deliberate contract change |
+  | Forbidden cross-layer imports absent | Auto (mechanical grep against `project-context.md` rules) | BLOCK | Fix before artifact write |
+  | Error handling lives only at boundaries listed in design | Manual (read code) | FIX-in-place | Refactor or document why an interior catch was needed |
+  | No new external deps not listed in `design.md` ADRs | Auto (mechanical manifest diff; Manual if no manifest exists) | BLOCK | Remove the dependency OR stop and add an ADR via `/mvt-design` |
 
 - **On any BLOCK failure**: stop, fix, re-run Step 5. Do not proceed to Step 6.
+- **If `design.md` is missing**: skip only the checks that require design (`Change Tracking`, `Module Design`, `Key Interfaces`, boundary error-handling list, external-dependency ADRs). Still run forbidden import checks when `project-context.md` contains layer or import rules.
 
 ### Step 6: Run Quick Self-Check
 - **What**: light-weight verification before handing off to `/mvt-review` or `/mvt-test`.
@@ -60,20 +63,11 @@
   3. UI/frontend changes: per project rules, ask user to verify in browser; do NOT claim "tested" if you only ran type-check.
 
 ### Step 7: Write Artifact
-- **Path and template**: as defined in the **Artifact Structure** section below. The artifact filename is ALWAYS `implementation.md` — one file per change, never per task. Do NOT invent task-suffixed names like `implementation-t1.md`.
-- **Multi-task plans (single-file accumulation)**: when `plan.yaml` drives the change and you implement tasks across separate invocations, all task implementations accumulate into the **same** `implementation.md`:
-  1. If `implementation.md` does not yet exist -> create it from the template.
-  2. If it already exists -> read it, then **append** a new `## Task: {current_task_id} — {task_title}` section for this task. Do NOT overwrite prior tasks' sections.
-  3. Under that task section, place this invocation's required content (the headings below). Keep earlier tasks' sections intact.
-  4. For single-task or plan-less changes, write the content at the top level without a per-task wrapper (existing behavior).
-- **Required content** (mapped to template headings):
-  - `Implementation Summary` -- one paragraph: what was built, scope.
-  - `Files Touched` -- table: path | create/modify/delete | one-line intent.
-  - `Design Compliance` -- summary of Step 5 checks (passed / deviated, with reasons).
-  - `Deviations from Design` -- empty list is acceptable; otherwise list each deviation with rationale.
-  - `Self-Check Results` -- type-check status, suggested test commands (Step 6).
-  - `Open TODOs` -- anything deferred for `/mvt-review`, `/mvt-test`, or follow-up changes.
-- The actual source code goes to the project tree; the artifact is a record, not the code itself.
+- **Path**: `.ai-agents/workspace/artifacts/{change-id}/implementation.md` — always this filename, one file per change. Never per-task suffixed names.
+- **Template**: load from the **Artifact Structure** section below. Follow the HTML comments for what each section should contain; strip comments from the final artifact.
+- **Multi-task accumulation**: if `plan.yaml` drives implementation across separate invocations, append a `## Task: {id} — {title}` section per task — never overwrite a *different* task's section. If `## Task: {id}` for the *same* task already exists (re-implementation after `blocked` or rescope), replace that section's content in place — preserve any `### Deliverables` subsection within it. Single-task or plan-less: write at top level without a task wrapper.
+- **Required coverage**: cover only content that is applicable to this implementation. Preserve enough information for downstream skills to understand what changed, files touched, design compliance, deviations, validation results, and open TODOs. 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 artifact is a record, not the code. Reference file paths and summarise intent — do NOT paste source listings.
 
 ### Step 8: Deliverables Handoff (if applicable)
 
@@ -101,18 +95,16 @@
   {Document invariants, preconditions, or side effects that downstream tasks must respect.}
   ```
 
-- **After writing deliverables**, call `plan-update.cjs` with both flags in a single invocation:
+- **After writing deliverables**, call `plan-update.cjs` with both deliverables flags in a single invocation. Use the command below as authoritative:
   ```bash
   node .ai-agents/scripts/plan-update.cjs \
     --plan "<active_change.plan_path>" \
     --task <current_task_id> \
-    --status <current_status> \
     --deliverables-pointer current \
-    --mark-deliverable-stale <downstream_task_id1>[,<downstream_task_id2>,...] \
-    --projects <project_list>
+    --mark-deliverable-stale <downstream_task_id1>[,<downstream_task_id2>,...]
   ```
-  `<project_list>` is the comma-separated project names from `plan.yaml > current_tasks` keys. In a single-project workspace this is `default`. The `--projects` flag ensures per-project validation runs correctly in multi-project plans.
-  The `--status` must be the task's current status (typically `in_progress` at this point, since Step 9 has not yet run). Pass ALL downstream dependent task ids as a comma-separated list to `--mark-deliverable-stale` so that `/mvt-resume` and `/mvt-status` can surface the stale warning.
+  Use this exact metadata-only command. Do NOT add `--status`, hand-edit `plan.yaml`, choose `current_tasks`, or read `.cjs`/`.js` source.
+  Pass ALL downstream dependent task ids as a comma-separated list to `--mark-deliverable-stale` so that `/mvt-resume` and `/mvt-status` can surface the stale warning.
 - **On user decline**: do not write deliverables and do not call `plan-update.cjs` with the deliverables flags. The downstream tasks will not receive stale warnings, which is acceptable if the user considers the contract unchanged.
 - **Error handling**: if `plan-update.cjs` rejects (e.g., malformed freshness), surface stderr and leave `implementation.md` as written. The deliverables content is the source of truth; the pointer can be retried via `/mvt-update-plan`.
 
@@ -126,7 +118,7 @@
 
 | Case | Handling |
 |------|----------|
-| `design.md` missing | WARN, ask user; if they proceed, mark artifact "Source: conversation only" and skip Step 5 design-match checks |
+| `design.md` missing | WARN, ask user; if they proceed, mark artifact "Source: conversation only"; in Step 5 skip checks that require design.md but still run forbidden import checks from `project-context.md` when rules exist |
 | Implementation reveals the design is infeasible | STOP at Step 4, document the blocker in conversation, recommend `/mvt-design` re-run -- do not silently improvise an alternative |
 | Type-checker fails on pre-existing errors unrelated to the change | Note in artifact, do not attempt blanket fixes outside scope |
 | User aborts at Step 3 confirmation | Do not write any source files or artifact |
@@ -135,3 +127,4 @@
 | Plan task is `blocked` or `done` already | Refuse to implement that task; ask user to pick another task from `current_tasks` or run `/mvt-update-plan` |
 | Deliverables already exist and user declines to update | Leave existing deliverables in place; do not call `plan-update.cjs` with deliverables flags |
 | `plan-update.cjs` rejects deliverables pointer | Surface error; leave `implementation.md` as written (content is source of truth, pointer can be retried) |
+| Re-implementing a task whose `## Task: {id}` section already exists in `implementation.md` | Replace that section's content in place; preserve any `### Deliverables` subsection within it. Do NOT create a second `## Task: {id}` section |

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

@@ -40,12 +40,6 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
-  - type: shared
-    source: sections/output-language-constraint.md
-
-  - type: shared
-    source: sections/output-format-constraint.md
-
   - type: shared
     source: sections/activation-preflight.md
     params:
@@ -58,10 +52,12 @@ sections:
           field: "projects[] in project-context.yaml"
           level: "BLOCK"
           message: "Project not initialized. Run `/mvt-init` first."
-        - order: "3"
-          field: "modules in project-context.md"
-          level: "WARN"
-          message: "No architecture defined. Run `/mvt-design` first. (allow user to proceed)"
+
+  - type: shared
+    source: sections/language-constraint.md
+
+  - type: shared
+    source: sections/output-format-constraint.md
 
   - type: file
     source: ./business.md
@@ -69,10 +65,8 @@ sections:
   - type: inline
     content: |
       ## Artifact Structure
-      Read the document structure template from: `.ai-agents/skills/_templates/implement-output.md`
-      If a custom version exists at `.ai-agents/skills/_templates/custom/implement-output.md`, use the custom version instead.
-      The template defines section headings only. Generate content for each section based on implementation results.
-      Write the artifact to: `.ai-agents/workspace/artifacts/{change-id}/implementation.md`
+      Template location: `.ai-agents/skills/_templates/implement-output.md`
+      Custom override: `.ai-agents/skills/_templates/custom/implement-output.md` (takes precedence if present)
 
   - type: shared
     source: sections/session-update.md

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

@@ -55,12 +55,6 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
-  - type: shared
-    source: sections/output-language-constraint.md
-
-  - type: shared
-    source: sections/output-format-constraint.md
-
   - type: shared
     source: sections/activation-preflight.md
     params:
@@ -70,6 +64,12 @@ sections:
           level: "INFO"
           message: "This is a first-time init, proceed normally."
 
+  - type: shared
+    source: sections/language-constraint.md
+
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: file
     source: ./business.md
 

package/sources/skills/mvt-manage-context/manifest.yaml

@@ -47,7 +47,7 @@ sections:
     source: sections/activation-load-config.md
 
   - type: shared
-    source: sections/output-language-constraint.md
+    source: sections/language-constraint.md
 
   - type: shared
     source: sections/output-format-constraint.md

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

@@ -21,17 +21,27 @@ If `active_change.plan_path is non-empty` AND `.ai-agents/workspace/artifacts/{a
 
 ### Step 3: Decompose Into Tasks
 
-Decompose the change with the following constraints. These constraints are AI-friendly granularity rules — too coarse leaves a task uncompletable in a single skill invocation; too fine turns the plan into noise.
+Decompose the change with the following constraints. These constraints are AI-friendly decomposition rules.
+
+**Granularity guidance** — read from `preferences.planning.granularity` in `.ai-agents/config.yaml`. Default: `medium`.
+
+| Level | Decomposition style |
+|-------|---------------------|
+| `coarse` | Prefer fewer, larger tasks — combine related work into broader task boundaries |
+| `medium` | Balanced — each task maps to one focused skill invocation |
+| `fine` | Prefer more, smaller tasks — split work into narrower, focused units |
+
+This is **qualitative AI guidance**, not a hard task count constraint. A complex change may produce many tasks; a simple one may produce few — both are valid at any granularity level.
 
 | Rule | Detail |
 |------|--------|
-| Count | Aim for 3–10 tasks at the top level. If the change clearly needs more, stop and propose phasing into multiple plans (one per phase). |
 | Single responsibility | Each task should map to one focused skill invocation (e.g., one `/mvt-implement` for one feature slice). |
 | Independently verifiable | Each task must have at least one acceptance criterion that a human or test can check. |
 | Explicit dependencies | If task B requires output from task A, list `A` in B's `depends_on`. Avoid hidden ordering. Tasks that can run in parallel should have no dependency between them. |
 | No cycles | Dependency graph must be a DAG. Validation will reject cycles. |
 | Skill hint | Set `skill_hint` to the skill best suited to execute the task (without `/` prefix): `mvt-implement`, `mvt-test`, `mvt-fix`, `mvt-design`, `mvt-review`, `mvt-refactor`, etc. |
 | Project attribution | Each task must have a `project` array listing which projects it belongs to. In a single-project workspace (`projects.length == 1`), set `project: ["default"]` (or the sole project's name). In a multi-project workspace, auto-infer from the task's file paths matching `projects[].path` and `projects[].source_paths`; if ambiguous, prompt the user. Cross-project tasks list multiple project names. |
+| Invalid value handling | If `granularity` contains a value other than `coarse`, `medium`, `fine`, warn the user and fall back to `medium`. |
 
 ### Step 4: Assemble plan.yaml
 

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

@@ -22,7 +22,7 @@ sections:
       decision_rules:
         - rule: "active_change is set AND plan_path is empty -> Generate a fresh plan.yaml"
         - rule: "active_change is set AND plan_path is non-empty -> Confirm before regenerating; default to /mvt-update-plan"
-        - rule: "Tasks would exceed 10 -> Stop, propose phasing the change into multiple plans"
+        - rule: "Plan grows beyond practical manageability -> Stop, propose phasing the change into multiple plans"
         - rule: "Dependencies form a cycle -> Reject and ask the user to resolve"
         - rule: "active_change is empty -> Stop and request /mvt-analyze first"
       boundaries:
@@ -45,12 +45,6 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
-  - type: shared
-    source: sections/output-language-constraint.md
-
-  - type: shared
-    source: sections/output-format-constraint.md
-
   - type: shared
     source: sections/activation-preflight.md
     params:
@@ -64,6 +58,12 @@ sections:
           level: "BLOCK"
           message: 'No active change. Run `/mvt-analyze` to create one before planning.'
 
+  - type: shared
+    source: sections/language-constraint.md
+
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: file
     source: ./business.md
 

package/sources/skills/mvt-quick-dev/manifest.yaml

@@ -45,7 +45,7 @@ sections:
     source: sections/activation-load-config.md
 
   - type: shared
-    source: sections/output-language-constraint.md
+    source: sections/language-constraint.md
 
   - type: shared
     source: sections/output-format-constraint.md

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

@@ -63,7 +63,7 @@ sections:
     source: sections/activation-load-config.md
 
   - type: shared
-    source: sections/output-language-constraint.md
+    source: sections/language-constraint.md
 
   - type: shared
     source: sections/output-format-constraint.md

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

@@ -56,6 +56,9 @@ sections:
           level: "WARN"
           message: "Session not initialized. Run `/mvt-init` first."
 
+  - type: shared
+    source: sections/language-constraint.md
+
   - type: file
     source: ./business.md
 

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

@@ -47,6 +47,7 @@ This step applies only when the workspace has multiple projects (`projects.lengt
 - **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)
+  - If `implementation.md > Design Compliance` exists, use it as the implementer's self-check claim set. Independently verify claimed passes and investigate any skipped, deviated, or undocumented item; do not repeat every mechanical self-check when the claim is already supported.
   - 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.
@@ -96,15 +97,8 @@ This step applies only when the workspace has multiple projects (`projects.lengt
 - Each finding must include: file, line range, severity, observation, recommendation.
 
 ### Step 7: Write Artifact
-- **Path and template**: as defined in the **Artifact Structure** section below. If no `active_change` exists, use `.ai-agents/workspace/artifacts/_ad-hoc-review-{YYYY-MM-DD-HHMM}/review.md`.
-- **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.
+- **Path and template**: as defined in the **Artifact Structure** section below. If no `active_change` exists, use `.ai-agents/workspace/artifacts/_ad-hoc-review-{YYYY-MM-DD-HHMM}/review.md`. 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 review. Preserve enough information for the user to understand what was reviewed, the verdict, material findings, skipped checks, and the recommended next step. 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.
 
 ### Step 8: Verdict Rule
 - Critical > 0 -> verdict is `Request changes`. Suggest `/mvt-fix`.

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

@@ -59,12 +59,6 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
-  - type: shared
-    source: sections/output-language-constraint.md
-
-  - type: shared
-    source: sections/output-format-constraint.md
-
   - type: shared
     source: sections/activation-preflight.md
     params:
@@ -78,6 +72,12 @@ sections:
           level: "WARN"
           message: "No code to review. Run `/mvt-implement` first or specify files."
 
+  - type: shared
+    source: sections/language-constraint.md
+
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: file
     source: ./business.md
 
@@ -86,7 +86,7 @@ sections:
       ## Artifact Structure
       Read the document structure template from: `.ai-agents/skills/_templates/review-output.md`
       If a custom version exists at `.ai-agents/skills/_templates/custom/review-output.md`, use the custom version instead.
-      The template defines section headings only. Generate content for each section based on review results.
+      The template defines section structure and guidance comments. Generate applicable content based on review results.
       Write the artifact to: `.ai-agents/workspace/artifacts/{change-id}/review.md`
 
   - type: shared

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

@@ -26,7 +26,7 @@
 
   | Condition | Action |
   |-----------|--------|
-  | No plans found anywhere | Skip the Changes Overview section entirely; render "No active changes." |
+  | No plans found anywhere | Skip the Changes Overview section entirely; render "No active plans." |
   | One plan found | Render Changes Overview with one row |
   | Multiple plans found | Render Changes Overview sorted: `in_progress` desc by `updated_at` first, then `done` desc by `updated_at`, then `abandoned` last |
   | Any plan over the cap (more than ~12 rows) | Show top 10 rows; print a `+N older changes hidden -- see artifacts/` line |
@@ -34,7 +34,7 @@
 ### Step 4: Build the Status Report
 - Render in this order, omitting any section whose inputs were unavailable:
 
-  1. **Header** -- one-line summary: project name (from `project-context.yaml`), framework version, last synced timestamp.
+  1. **Header** -- one-line summary: project name (from `project-context.yaml`), last synced timestamp.
   2. **Projects** -- table: name | type | tech stack (truncated). Cap at 10 rows; collapse the rest into `+N more`.
   3. **Semantic Context** -- one line: `project-context.md present` / `missing -- run /mvt-analyze-code`.
   4. **Active Change** -- if `active_change` exists: id, title, start time. Else: `none`.
@@ -64,20 +64,10 @@
      |-----------|-------|--------|----------|---------------|---------|------------|
 
      For `current_tasks`, display as a compact representation: if single-project, show the task id only; if multi-project, show `web: t2, api: t1` format. The `project` column lists the distinct projects across all tasks in the plan.
-
-     If any task has `deliverables.freshness == "stale"`, append a warning row: "Stale deliverables: {task_ids} -- run `/mvt-implement` to refresh"
   6. **Skill History** -- last 5 rows of the timeline from Step 2.
 
 - Hard cap: total rendered output should not exceed ~120 lines. If it would, truncate Skill History first; never truncate the active change or Changes Overview header rows.
 
-### Step 5: Suggest Next Step
-- Resolution order (first match wins):
-  1. `active_change` has a plan in `in_progress`, `current_tasks` has entries -> suggest the relevant task's `skill_hint` (or, if missing, recommend `/mvt-update-plan` to set `current_tasks`).
-  2. `active_epic.id` non-empty AND `active_change.id` empty (epic-pending state) -> suggest `/mvt-analyze` -- Start the next sub-change in the epic.
-  3. `project-context.md` is missing -> suggest `/mvt-analyze-code`.
-  4. No `active_change` or no active plan -> suggest `/mvt-analyze` to start a new feature OR `/mvt-help` to browse the catalog.
-- The suggestion must be a single line: skill command + one-clause reason.
-
 ## Edge Cases & Errors
 
 | Case | Handling |

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

@@ -49,6 +49,9 @@ sections:
           level: "WARN"
           message: "Session not initialized. Run `/mvt-init` first."
 
+  - type: shared
+    source: sections/language-constraint.md
+
   - type: file
     source: ./business.md
 

package/sources/skills/mvt-sync-context/business.md

@@ -181,7 +181,7 @@ If user skips verification: proceed directly to Step 10 with Step 7 selections.
 ### Step 12: State Update
 Apply the State Update rules defined in the **State Update** section below.
 - The `--set-synced` parameter updates `session.last_synced_at`.
-- Pass `--projects` to plan-update.cjs when updating a plan that has project attribution.
+- When updating a plan that has project attribution, pass `--projects` to `plan-update.cjs`; read `.ai-agents/scripts/plan-update.md` only if the workflow needs flags or value sources not rendered in this skill. Do NOT hand-edit `plan.yaml` or read `.cjs`/`.js` source.
 
 ## Edge Cases & Errors
 

package/sources/skills/mvt-sync-context/manifest.yaml

@@ -57,12 +57,6 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
-  - type: shared
-    source: sections/output-language-constraint.md
-
-  - type: shared
-    source: sections/output-format-constraint.md
-
   - type: shared
     source: sections/activation-preflight.md
     params:
@@ -76,6 +70,12 @@ sections:
           level: "BLOCK"
           message: "project-context.md not found. Run `/mvt-analyze-code` to create the initial document; this skill only handles incremental updates."
 
+  - type: shared
+    source: sections/language-constraint.md
+
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: shared
     source: sections/project-context-profile.md
 

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

@@ -41,6 +41,9 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
+  - type: shared
+    source: sections/language-constraint.md
+
   - type: file
     source: ./business.md
 

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

@@ -91,16 +91,8 @@ 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.
+- **Path and template**: as defined in the **Artifact Structure** section below. 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