@uoyo/mvtt 2.0.0 → 2.1.0

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,14 +70,20 @@ 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>`
+  - 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>
+     ```
    - `session-update.cjs --skill mvt-update-plan --summary "..." --close-change`
    - 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`
+  - 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
+     ```
    - `session-update.cjs --skill mvt-update-plan --summary "..." --close-change`
    - Display: "Child marked done, current_change unchanged."
 

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

@@ -43,12 +43,6 @@ sections:
   - 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:
@@ -62,6 +56,12 @@ sections:
           level: "BLOCK"
           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: |
       ## Operation Mode: Shortcut
@@ -108,6 +108,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.
+-->

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

@@ -1,7 +1,79 @@
 # Test Design: {Feature Name}
 
+<!--
+  This template defines the structure of test-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.
+-->
+
+## Scope
+<!--
+  The target files under test and any fallbacks applied (e.g., resolved
+  from implementation.md Files Touched, or git diff, or user argument).
+  Establishes what this test design covers.
+-->
+
+## Test Framework & Layout
+<!--
+  The chosen test framework (inferred from project manifests or confirmed
+  with user) and the file layout convention used (mirror under tests/,
+  sibling *.test.ts, etc.). One short paragraph or a small table.
+-->
+
+## Test Scenarios
+<!--
+  The Scenario Table from the scenario-identification step. Columns:
+  | ID | Scenario | Type (happy/edge/negative/security/performance) | Rule-traced-to |.
+  Covers happy paths, boundaries, invalid inputs, business rules from
+  project-context.md, and error paths declared in design.md data flow.
+-->
+
 ## Test Cases
+<!--
+  The row-level test case table from the design step. Columns:
+  | ID | Scenario | Granularity | Preconditions | Inputs | Actions | Expected | Rule-traced-to |.
+  Each row maps to one concrete, runnable test. One scenario maps to one
+  granularity (unit / integration / E2E).
+-->
 
 ## Test Code
+<!--
+  The generated test files: file paths and a brief description of what
+  each file covers. The actual test source goes into the project tree;
+  this section is a record of what was written and where. Include any
+  setup/fixture notes that explain non-obvious test infrastructure.
+-->
+
+## Granularity Decisions
+<!--
+  Summary of how scenarios were assigned to unit / integration / E2E,
+  including any "needs setup" gaps (e.g., integration scenarios flagged
+  because the project lacks an integration test setup). One short
+  paragraph or a small table.
+-->
 
 ## Coverage Analysis
+<!--
+  Only when the --coverage flag is set; otherwise omit this heading
+  entirely. Map test cases back to target files/functions and business
+  rules from project-context.md; list gaps (untested functions, untested
+  rules, untested error paths) and recommend additional test cases for
+  each gap. Do not auto-generate gap tests unless the user confirms.
+-->
+
+## Implementation Issues Found
+<!--
+  Bugs discovered during scenario design or test writing (failing test
+  reveals a real bug, not a test bug). Each finding: scenario id, expected
+  vs observed, severity (Critical / Warning), and a recommendation to run
+  /mvt-fix. Do NOT modify production code from this skill. If none found,
+  write "None".
+-->
+
+## Suggested Run Commands
+<!--
+  One or two commands the user can copy-paste to execute the generated
+  tests (e.g., `npx vitest run path/to/test.test.ts`). Keep it minimal
+  and project-appropriate.
+-->