@uoyo/mvtt 2.0.0-beta.6 → 2.1.0

package/sources/sections/session-update.md

@@ -6,148 +6,62 @@ This skill is read-only and does NOT modify `.ai-agents/workspace/session.yaml`.
 {{^read_only}}
 ## State Update
 
-After completing the skill's main task, run the session update script **exactly once** with the following arguments:
+After the skill's main task, run the session update script **exactly once**:
 
 ```bash
-node .ai-agents/scripts/session-update.cjs --skill <skill_command_name> --summary "<concise one-line summary>"{{#update_active_change}} --new-change "<active_change.title>" --change-id <active_change.id>{{#link_subchange_to_epic}} --epic-id <active_epic.id>{{/link_subchange_to_epic}}{{/update_active_change}}{{#set_plan_path}} --set-plan-path ".ai-agents/workspace/artifacts/{active_change.id}/plan.yaml"{{/set_plan_path}}{{#update_change}} --update-change{{/update_change}}{{#close_change}} --close-change{{/close_change}}{{#set_change_status}} --set-change-status <status>{{/set_change_status}}{{#new_epic}} --new-epic "<epic_title>" --epic-id <epic_id>{{/new_epic}}{{#set_epic_path}} --set-epic-path <epic_path>{{/set_epic_path}}{{#set_epic_status}} --set-epic-status <status>{{/set_epic_status}}{{#close_epic}} --close-epic{{/close_epic}}{{#no_change}} --no-change{{/no_change}}{{#set_synced}} --set-synced{{/set_synced}}{{#truncate_history}} --truncate-history <count>{{/truncate_history}}{{#update_initialized_at}} --set-initialized{{/update_initialized_at}}
+node .ai-agents/scripts/session-update.cjs --skill {{current_skill}} --summary "<concise one-line summary>"{{#update_active_change}} --new-change "<active_change.title>" --change-id <active_change.id>{{#link_subchange_to_epic}} --epic-id <active_epic.id>{{/link_subchange_to_epic}}{{/update_active_change}}{{#set_plan_path}} --set-plan-path ".ai-agents/workspace/artifacts/{active_change.id}/plan.yaml"{{/set_plan_path}}{{#update_change}} --update-change{{/update_change}}{{#close_change}} --close-change{{/close_change}}{{#set_change_status}} --set-change-status <status>{{/set_change_status}}{{#new_epic}} --new-epic "<epic_title>" --epic-id <epic_id>{{/new_epic}}{{#set_epic_path}} --set-epic-path <epic_path>{{/set_epic_path}}{{#set_epic_status}} --set-epic-status <status>{{/set_epic_status}}{{#close_epic}} --close-epic{{/close_epic}}{{#no_change}} --no-change{{/no_change}}{{#set_synced}} --set-synced{{/set_synced}}{{#truncate_history}} --truncate-history <count>{{/truncate_history}}{{#update_initialized_at}} --set-initialized{{/update_initialized_at}}
 
 ```
 
-If the script exits with code 0, the state update was applied successfully; there is no need to read or verify the session file.
+Write `--summary` as one concise line in the configured `interaction_language`.
 
-### Argument values
+### Critical flag semantics
 
-| Argument | Value source | Example |
-|----------|-------------|---------|
-| `--skill` | The exact skill command name without the leading `/` | `{{current_skill}}` |
-| `--summary` | A concise one-line description of what this invocation accomplished, in the configured `interaction_language` | `"Identified auth requirements and created change chg-001"` |
+- Use only the flags rendered in the command above; do not invent extra session-update flags.
 {{#update_active_change}}
-| `--new-change` | The title of the new change being created (same value written to `active_change.title`) | `"User authentication system"` |
-| `--change-id` | The unique identifier of the new change (same value written to `active_change.id`) | `chg-001` |
+- `--new-change` and `--change-id` are required together; they set `active_change.{id,title,created_at}` and snapshot any prior active change into `changes[]`.
 {{/update_active_change}}
-{{#set_plan_path}}
-| `--set-plan-path` | The path to the newly created plan.yaml | `".ai-agents/workspace/artifacts/chg-001/plan.yaml"` |
-{{/set_plan_path}}
-{{#update_change}}
-| `--update-change` | Flag only, no value. Upserts the current `active_change` into `changes[]`. | — |
-{{/update_change}}
+{{#set_plan_path}}{{#update_change}}
+- `--set-plan-path` must be used with `--update-change`; together they persist the active change's `plan_path` into `changes[]`.
+{{/update_change}}{{/set_plan_path}}
+{{#update_change}}{{^set_plan_path}}
+- `--update-change` upserts the current `active_change` into `changes[]`, refreshes `updated_at`, and preserves the configured change-history limit.
+{{/set_plan_path}}{{/update_change}}
 {{#close_change}}
-| `--close-change` | Flag only, no value. Snapshots `active_change` into `changes[]` with `status: done`, then clears `active_change`. | — |
+- `--close-change` snapshots `active_change` into `changes[]` with `status: done`, then clears all active-change fields.
 {{/close_change}}
 {{#set_change_status}}
-| `--set-change-status` | The status to set on the `changes[]` entry matching `active_change.id`. Values: `active`, `done`, `abandoned`. | `done` |
+- `--set-change-status` sets the matching `changes[]` entry to `active`, `done`, or `abandoned`.
 {{/set_change_status}}
 {{#no_change}}
-| `--no-change` | Flag only, no value. Forces `history[].change_id` to empty string (skips `active_change.id` fallback). | — |
+- `--no-change` forces `history[].change_id` to empty instead of falling back to `active_change.id`.
 {{/no_change}}
 {{#set_synced}}
-| `--set-synced` | Flag only, no value. Sets `session.last_synced_at` to current time. | — |
+- `--set-synced` refreshes `session.last_synced_at`.
 {{/set_synced}}
 {{#truncate_history}}
-| `--truncate-history` | Number of most recent history entries to keep (read from `config.yaml > preferences.history_limits.history`, default 20); older entries are discarded. | `20` |
+- `--truncate-history` keeps the most recent N `history[]` entries; use the configured history limit.
 {{/truncate_history}}
 {{#update_initialized_at}}
-| `--set-initialized` | Flag only, no value. Set when this skill initializes the project for the first time. | — |
+- `--set-initialized` sets `session.initialized_at` only when it is empty.
 {{/update_initialized_at}}
 {{#new_epic}}
-| `--new-epic` | The title of the new epic being created (same value written to `active_epic.title`) | `"ecommerce platform"` |
-| `--epic-id` | The unique identifier of the new epic. Required when using `--new-epic`. Format: `epic-{YYYYMMDD}-{slug}`. | `"epic-20260608-ecommerce-platform"` |
+- `--new-epic` requires `--epic-id`; together they set `active_epic.{id,title,created_at}` and snapshot any prior active epic into `epics[]`.
 {{/new_epic}}
 {{#set_epic_path}}
-| `--set-epic-path` | The path to the written `epic.yaml` file. Sets `active_epic.epic_path`. | `".ai-agents/workspace/artifacts/epic-20260608-ecommerce-platform/epic.yaml"` |
+- `--set-epic-path` records the written `epic.yaml` path on `active_epic.epic_path`.
 {{/set_epic_path}}
 {{#set_epic_status}}
-| `--set-epic-status` | The status to set on the `epics[]` entry matching `active_epic.id`. Values: `in_progress`, `done`, `abandoned`. | `done` |
+- `--set-epic-status` sets the matching `epics[]` entry to `in_progress`, `done`, or `abandoned`.
 {{/set_epic_status}}
 {{#close_epic}}
-| `--close-epic` | Flag only, no value. Snapshots `active_epic` into `epics[]` with `status: done`, then clears all `active_epic` fields. | — |
+- `--close-epic` snapshots `active_epic` into `epics[]` with `status: done`, then clears all active-epic fields.
 {{/close_epic}}
 {{#link_subchange_to_epic}}
-| `--epic-id` (with `--new-change`) | The parent epic id that this new sub-change belongs to. Only valid when used together with `--new-change`. | `"epic-20260608-ecommerce-platform"` |
+- `--epic-id` with `--new-change` links the new active change to its parent epic; do not use it outside `--new-epic` or `--new-change`.
 {{/link_subchange_to_epic}}
 
-{{#update_active_change}}
-### Parameter semantics
-
-| Argument | When to use | Effect on `session.yaml` |
-|----------|-------------|--------------------------|
-| `--new-change` + `--change-id` | Skill creates or identifies a new change | Sets `active_change.id`, `.title`, `.created_at`. Auto-snapshots old `active_change` into `changes[]` if non-empty. Requires both arguments together. |
-{{#link_subchange_to_epic}}
-| `--epic-id` (with `--new-change`) | Skill creates a new sub-change inside an existing epic (epic-child mode) | Writes `active_change.epic_id` so the new sub-change is linked to the parent epic. Only valid when used together with `--new-change`. |
-{{/link_subchange_to_epic}}
-{{#set_plan_path}}
-| `--set-plan-path` | Skill creates a new `plan.yaml` for the active change | Sets `active_change.plan_path`. Must be used together with `--update-change`. |
-{{/set_plan_path}}
-{{#update_change}}
-| `--update-change` | Skill creates or modifies a plan (i.e., after `plan.yaml` is written/updated) | Upserts current `active_change` into `changes[]` (with `status: active`), sets `updated_at`, sorts ascending, truncates to configured limit. |
-{{/update_change}}
-{{#close_change}}
-| `--close-change` | All plan tasks are completed | Snapshots `active_change` into `changes[]` with `status: done`, then clears all `active_change` fields. |
-{{/close_change}}
-{{#set_change_status}}
-| `--set-change-status` | Explicitly mark a change as `done` or `abandoned` | Sets `status` on the `changes[]` entry whose `id` matches `active_change.id`. |
-{{/set_change_status}}
-{{#set_epic_path}}
-| `--set-epic-path` | Skill writes or moves the `epic.yaml` file (e.g., after `/mvt-decompose` writes the artifacts) | Sets `active_epic.epic_path`. |
-{{/set_epic_path}}
-{{#set_epic_status}}
-| `--set-epic-status` | Skill marks the active epic as `done` or `abandoned` (rarely used directly — `epic-update.cjs` usually drives this) | Sets `status` on the `epics[]` entry whose `id` matches `active_epic.id`. |
-{{/set_epic_status}}
-{{#close_epic}}
-| `--close-epic` | Skill closes the active epic (e.g., after archiving a completed epic) | Snapshots `active_epic` into `epics[]` with `status: done`, then clears all `active_epic` fields. |
-{{/close_epic}}
-{{#no_change}}
-| `--no-change` | Skill should not be associated with any change | Forces `history[].change_id` to empty string, skipping the `active_change.id` fallback. |
-{{/no_change}}
-{{#set_synced}}
-| `--set-synced` | Skill synchronizes context files | Sets `session.last_synced_at` to the current time. |
-{{/set_synced}}
-{{#truncate_history}}
-| `--truncate-history` | Maintenance: trim old history entries | Keeps the most recent N entries in `history[]`, discards older ones. |
-{{/truncate_history}}
-{{#update_initialized_at}}
-| `--set-initialized` | Skill initializes the project for the first time | Sets `session.initialized_at` (idempotent — only writes if empty). |
-{{/update_initialized_at}}
-{{/update_active_change}}
-{{^update_active_change}}
-### Parameter semantics
-
-| Argument | When to use | Effect on `session.yaml` |
-|----------|-------------|--------------------------|
-{{#new_epic}}
-| `--new-epic` + `--epic-id` | Skill creates a new epic (e.g., `/mvt-decompose`) | Sets `active_epic.{id,title,created_at}`. Auto-snapshots old `active_epic` into `epics[]` if non-empty. Requires both arguments together. |
-{{/new_epic}}
-{{#update_change}}
-| `--update-change` | Skill modifies a plan (i.e., after `plan.yaml` is updated) | Upserts current `active_change` into `changes[]` (with `status: active`), sets `updated_at`, sorts ascending, truncates to configured limit. |
-{{/update_change}}
-{{#close_change}}
-| `--close-change` | All plan tasks are completed | Snapshots `active_change` into `changes[]` with `status: done`, then clears all `active_change` fields. |
-{{/close_change}}
-{{#set_change_status}}
-| `--set-change-status` | Explicitly mark a change as `done` or `abandoned` | Sets `status` on the `changes[]` entry whose `id` matches `active_change.id`. |
-{{/set_change_status}}
-{{#set_epic_path}}
-| `--set-epic-path` | Skill writes or moves the `epic.yaml` file (e.g., after `/mvt-decompose` writes the artifacts) | Sets `active_epic.epic_path`. |
-{{/set_epic_path}}
-{{#set_epic_status}}
-| `--set-epic-status` | Skill marks the active epic as `done` or `abandoned` (rarely used directly — `epic-update.cjs` usually drives this) | Sets `status` on the `epics[]` entry whose `id` matches `active_epic.id`. |
-{{/set_epic_status}}
-{{#close_epic}}
-| `--close-epic` | Skill closes the active epic (e.g., after archiving a completed epic) | Snapshots `active_epic` into `epics[]` with `status: done`, then clears all `active_epic` fields. |
-{{/close_epic}}
-{{#no_change}}
-| `--no-change` | Skill should not be associated with any change | Forces `history[].change_id` to empty string, skipping the `active_change.id` fallback. |
-{{/no_change}}
-{{#set_synced}}
-| `--set-synced` | Skill synchronizes context files | Sets `session.last_synced_at` to the current time. |
-{{/set_synced}}
-{{#truncate_history}}
-| `--truncate-history` | Maintenance: trim old history entries | Keeps the most recent N entries in `history[]`, discards older ones. |
-{{/truncate_history}}
-{{#update_initialized_at}}
-| `--set-initialized` | Skill initializes the project for the first time | Sets `session.initialized_at` (idempotent — only writes if empty). |
-{{/update_initialized_at}}
-{{/update_active_change}}
+If the script exits with code 0, the state update was applied successfully; do not read or verify the session file.
 
 ### Failure handling
 

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

@@ -8,7 +8,7 @@ In this state the user is starting a new sub-change within an existing epic. Rea
 |----------|-------------|----------|
 | A | Empty | Auto-use `current_change` child's scope from `epic.yaml` as the requirement input. Proceed to Step 3. |
 | B | Supplements current child | Merge user message with `current_change` child's scope. Proceed to Step 3. |
-| C | Points to different child | Locate target in `children[]`. If `depends_on` has unfinished prerequisites → warn and ask to confirm forced reorder (y/n). If deps satisfied → confirm switch (y/n). On confirmed reorder: call `epic-update.cjs --epic <epic_path> --switch-active <target_id>`. If target not in `children[]` → offer to treat as independent change (exit epic-child mode) or `--add-child`. |
+| C | Points to different child | Locate target in `children[]`. If `depends_on` has unfinished prerequisites → warn and ask to confirm forced reorder (y/n). If deps satisfied → confirm switch (y/n). On confirmed reorder: call the Epic Update Script in `--switch-active` mode with `node .ai-agents/scripts/epic-update.cjs --epic <epic_path> --switch-active <target_id>`. If target not in `children[]` → offer to treat as independent change (exit epic-child mode) or use `--add-child` mode to append it as a new child. Read `.ai-agents/scripts/epic-update.md` only if a required mode or flag is not rendered here. Do NOT hand-edit `epic.yaml`, advance `current_change`, or read `.cjs`/`.js` source. |
 
 ## Execution Flow
 

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

@@ -41,12 +41,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:
@@ -60,6 +54,12 @@ sections:
           level: "WARN"
           message: 'Project not initialized. Run `/mvt-init` first.'
 
+  - type: shared
+    source: sections/language-constraint.md
+
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: file
     source: ./business.md
 
@@ -68,7 +68,7 @@ sections:
       ## Artifact Structure
       Read the document structure template from: `.ai-agents/skills/_templates/analyze-output.md`
       If a custom version exists at `.ai-agents/skills/_templates/custom/analyze-output.md`, use the custom version instead.
-      The template defines section headings only. Generate content for each section based on analysis results.
+      The template defines section structure and guidance comments. Generate applicable content based on analysis results.
       Write the artifact to: `.ai-agents/workspace/artifacts/{change-id}/analysis.md`
 
   - type: shared

package/sources/skills/mvt-analyze-code/manifest.yaml

@@ -53,12 +53,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:
@@ -72,6 +66,12 @@ sections:
           level: "WARN"
           message: "No projects registered. Run `/mvt-init` first."
 
+  - type: shared
+    source: sections/language-constraint.md
+
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: inline
     content: |
       ## Operation Mode: Independent
@@ -88,7 +88,7 @@ sections:
       ## Artifact Structure
       Read the document structure template from: `.ai-agents/skills/_templates/project-context.md`
       If a custom version exists at `.ai-agents/skills/_templates/custom/project-context.md`, use the custom version instead.
-      The template defines section headings only. Generate content for each section based on code analysis results.
+      The template defines section structure and guidance comments. Generate applicable content based on code analysis results.
       Write the artifact to: `.ai-agents/knowledge/project/_generated/project-context.md`
 
   - type: shared

package/sources/skills/mvt-bug-detect/manifest.yaml

@@ -44,6 +44,9 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
+  - type: shared
+    source: sections/language-constraint.md
+
   - type: inline
     content: |
       ## Operation Mode: Shortcut

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

@@ -40,6 +40,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-cleanup/business.md

@@ -104,6 +104,15 @@ N is read from `config.yaml > preferences.history_limits.history` (default 20).
 ### Step 10: State Update
 Apply the State Update rules defined in the **State Update** section below.
 
+**Pre-filled example** (closed active_change + history truncation):
+```bash
+node .ai-agents/scripts/session-update.cjs \
+  --skill mvt-cleanup \
+  --close-change \
+  --truncate-history 10
+```
+Replace `10` with the actual `config.yaml > preferences.history_limits.history` value. If only truncating history (active_change still in progress), omit `--close-change`.
+
 ## Edge Cases & Errors
 
 | Case | Handling |

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

@@ -51,12 +51,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:
@@ -66,6 +60,12 @@ sections:
           level: "REQUIRED"
           message: "Project must be initialized (session.yaml exists)"
 
+  - type: shared
+    source: sections/language-constraint.md
+
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: file
     source: ./business.md
 

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

@@ -61,6 +61,7 @@
   | 4 | `preferences.output.data_format` | Default `yaml`; allowed: `yaml`, `json` |
   | 5 | `preferences.context_routing.relevance_threshold` | Default `70`; allowed: 0-100 |
   | 6 | `preferences.history_limits.*` | Show each limit with current value; accept new int or Enter to keep |
+  | 7 | `preferences.planning.granularity` | Default `medium`; allowed: `coarse`, `medium`, `fine` |
 
 - After all stages, render a Summary Preview table: `key | from | to`, then a single confirmation prompt to apply ALL changes atomically.
 - If the user aborts at the summary, discard all in-progress values; do not write anything.

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

@@ -56,6 +56,9 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
+  - type: shared
+    source: sections/language-constraint.md
+
   - type: inline
     content: |
       ## Configuration Keys
@@ -71,6 +74,7 @@ sections:
       | `preferences.context_routing.relevance_threshold` | int | `70` | AI routing threshold for `/mvt-manage-context add` (0-100) |
       | `preferences.history_limits.history` | int | `20` | Max history entries (1-100) |
       | `preferences.history_limits.changes` | int | `20` | Max changes entries (1-100) |
+      | `preferences.planning.granularity` | enum | `medium` | Task decomposition granularity for `/mvt-plan-dev`. Qualitative AI guidance, not hard limits. Values: `coarse` (fewer, larger tasks), `medium` (balanced), `fine` (more, smaller tasks) |
 
       ### Knowledge Settings
 

package/sources/skills/mvt-create-skill/business.md

@@ -212,7 +212,7 @@ Copy the following sections verbatim from this document (the assembled SKILL.md
 |---------|----------------------|-----------------|
 | Activation Protocol | `## Activation Protocol` | Add `extended_context` entries if the skill needs additional context sources; otherwise copy as-is |
 | Load Config | Load Config step within Activation Protocol | Copy as-is |
-| Output Language Constraint | Output Language Constraint step within Activation Protocol | Copy as-is |
+| Language Constraint | Language Constraint step within Activation Protocol | Copy as-is |
 | Pre-flight Checks | Pre-flight Checks step within Activation Protocol | Replace `checks` table with skill-specific checks; if none required, use a single INFO row |
 | State Update | `## State Update` | Replace `/{name}` with the new skill's command; include `active_change` conditional block only if the skill creates changes; include `Shortcut Operation Rules` if the user opted for shortcut semantics during Step 5 design |
 | Suggested Next Steps | `## Suggested Next Steps` | Replace `current_skill` with the new skill name; replace conditional suggestions with skill-appropriate ones |

package/sources/skills/mvt-create-skill/manifest.yaml

@@ -48,7 +48,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-decompose/business.md

@@ -54,16 +54,11 @@
 - **On confirmation**: proceed to Step 6.
 
 ### Step 6: Write Artifacts
-Write two artifacts using the `decompose-output` template for `epic.md`:
+Write two artifacts:
 
 1. **epic.md** (narrative) -- `.ai-agents/workspace/artifacts/{epic_id}/epic.md`
-   - Uses the `decompose-output` template.
-   - **Child Stories**: Markdown table mirroring `epic.yaml.children[]`
-
-     | # | Child | Scope | Status | Depends On |
-     |---|-------|-------|--------|------------|
-
-   - **Dependency Map**: Mermaid flowchart showing child dependencies
+   - Uses the `decompose-output` template. Follow the HTML comments in the template for what each section should contain (including the Child Stories table format and the Dependency Map mermaid flowchart); strip comments from the final artifact.
+  - **Required coverage**: cover only content that is applicable to this decomposition. Preserve enough information for the user to understand the epic vision, boundaries, cross-cutting concerns, child stories, dependencies, and unresolved questions. 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.
 
 2. **epic.yaml** (structured) -- `.ai-agents/workspace/artifacts/{epic_id}/epic.yaml`
    - Follows the schema defined in Artifact Structure
@@ -78,11 +73,25 @@ Write two artifacts using the `decompose-output` template for `epic.md`:
 - [ ] `current_change` matches the active child's `change_id`
 - [ ] Each child has non-empty `title` and `scope`
 
-**Optional safety net**: after writing, call `epic-update.cjs --validate` to verify:
+**Optional safety net**: after writing, validate the epic using the Epic Update Script command below:
 ```bash
 node .ai-agents/scripts/epic-update.cjs --validate .ai-agents/workspace/artifacts/{epic_id}/epic.yaml
 ```
 
+If the epic needs children added later (e.g. a missed sub-change discovered during analysis), use `--add-child`:
+```bash
+node .ai-agents/scripts/epic-update.cjs --epic .ai-agents/workspace/artifacts/{epic_id}/epic.yaml \
+  --add-child <new_child_id> --child-title "<title>" --child-scope "<scope>"
+```
+
+To advance the epic after a child change completes, use `--complete-child`:
+```bash
+node .ai-agents/scripts/epic-update.cjs --epic .ai-agents/workspace/artifacts/{epic_id}/epic.yaml \
+  --complete-child <completed_child_id>
+```
+
+For post-write epic mutations, use the rendered `epic-update.cjs` commands. Do NOT hand-edit `epic.yaml`, advance `current_change`, or read `.cjs`/`.js` source.
+
 ### Step 7: Update Session
 Run the session update command (see State Update section) to:
 1. Create a new `active_epic` in session.yaml

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

@@ -38,12 +38,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:
@@ -61,6 +55,12 @@ sections:
           level: "WARN"
           message: 'An active change already exists. Decomposing will create a new epic alongside it. Continue? (y/n)'
 
+  - type: shared
+    source: sections/language-constraint.md
+
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: file
     source: ./business.md
 
@@ -71,7 +71,7 @@ sections:
       **epic.md** (narrative):
       Read the document structure template from: `.ai-agents/skills/_templates/decompose-output.md`
       If a custom version exists at `.ai-agents/skills/_templates/custom/decompose-output.md`, use the custom version instead.
-      The template defines section headings only. Generate content for each section based on decomposition results.
+      The template defines section structure and guidance comments. Generate applicable content based on decomposition results.
       Write to: `.ai-agents/workspace/artifacts/{epic_id}/epic.md`
 
       **epic.yaml** (structured):

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

@@ -5,7 +5,7 @@
   - Existing design artifacts of related prior changes (`artifacts/*/design.md`) -- to stay consistent.
 - **Fallback**:
   - If `analysis.md` is missing, surface a WARN and accept the user's free-text intent as the requirement input.
-  - If `project-context.md` is missing, proceed but mark the design as "context-light" and skip the layer-compliance check in Step 4.
+  - If `project-context.md` is missing, proceed but mark the design as "context-light" and skip the layer-compliance check in Step 3.
 
 ### Step 2: Frame the Problem
 - **What**: produce a one-paragraph problem statement plus a list of explicit architectural concerns (3-7 items).
@@ -15,36 +15,35 @@
   3. Drop any concern that is not actually exercised by the requirements -- do not invent NFRs.
 - **Output of this step**: a Concerns Table with columns `concern | source-of-evidence | priority(must/should/nice)`.
 
-### Step 3: Choose Architecture Style
-- **What**: select the smallest viable architecture style for this change. Escalate only when concerns force it.
-- **How**: pick the row that matches the dominant concerns; multiple changes within the same project should normally pick the same style unless requirements force otherwise.
-
-  | Style | Use when | Avoid when |
-  |-------|----------|------------|
-  | Plain CRUD / 3-layer | Single resource flow, no domain rules beyond validation | Complex business invariants, multi-step workflows |
-  | Service-oriented within a module | Multiple use cases sharing entities, transactions across them | Cross-team boundaries, independent deployment needs |
-  | Domain-driven (aggregates, domain services) | Rich business rules, invariants, multiple actors per workflow | Simple read-mostly resources |
-  | Event-driven / async | Long-running flows, decoupled side-effects, retry/back-pressure | Strong synchronous contracts, immediate-consistency reads |
-  | Multi-service / boundary split | Independent scaling or deployment, separate teams | Single team, single deployment pipeline -- DEFER |
-
-- If the requirements suggest "multi-service" but project is currently single-service: STOP and ask user to confirm scope expansion before designing across services.
-
-### Step 4: Design Module Structure
+### Step 3: Design Module Structure
 - **What**: list modules (new and modified), their responsibilities, owned entities, and interfaces.
 - **How**:
-  1. Map each Concern (Step 2) to one owning module.
-  2. For every module, write: name, responsibility (one sentence), owned entities, public interface (function/class signatures or HTTP endpoints), dependencies on other modules.
-  3. Validate dependency direction against `project-context.md` layer rules (e.g., domain -> infra forbidden). If violation found, redesign or flag it as an explicit ADR (Step 6).
-  4. Use the existing module names from `project-context.md` whenever possible -- introduce a new module only when no existing one fits.
+  1. Follow existing project architecture first: `project-context.md`, accepted ADRs, framework constraints, and domain rules override the examples below.
+  2. Start simple. Add a boundary, abstraction, async flow, dependency, or new module only when a must/should concern requires it.
+  3. For each must/should Concern (Step 2), choose the smallest response that satisfies it. Use the table as examples, not a closed list; if no row fits, derive a response from the concern itself.
+
+     | Concern signal (example) | Smallest architectural response | Module consequence |
+     |---------------------------|----------------------------------|--------------------|
+     | Simple data lifecycle | CRUD-oriented service/repository shape | Resource module with validation and persistence boundary |
+     | Rich business invariant | Domain model or aggregate boundary | Entity or aggregate module owns invariant enforcement |
+     | Shared multi-step workflow | Application service or use-case coordinator | Workflow module coordinates existing modules |
+     | Async side effect or retry need | Event handler or queue boundary | Producer/consumer or handler module; mark event boundary |
+     | Independent deployment, scaling, or team ownership | Service boundary candidate | STOP if it implies a new deployable service, runtime, or cross-service contract |
+
+  4. Output the concern mapping as `concern | response | owning module | boundary impact`.
+  5. For every module, write: name, responsibility (one sentence), owned entities, public interface (function/class signatures or HTTP endpoints), dependencies on other modules.
+  6. Reuse existing module names from `project-context.md` whenever possible. Add a new module only when no existing module fits.
+  7. Validate dependency direction against `project-context.md` layer rules (e.g., domain -> infra forbidden). If violation found, redesign or flag it as an explicit ADR (Step 5).
 - **Branches**:
 
   | Condition | Action |
   |-----------|--------|
   | Layer-compliance check passes | Proceed |
   | Single layer violation, fix is local | Adjust module placement, document in change tracking |
-  | Systemic violation (style mismatch with existing project) | STOP, raise ADR (Step 6) and ask user to confirm direction before continuing |
+  | Architectural response implies a new deployable service, runtime, or cross-service contract | STOP, ask user to confirm scope expansion before designing across boundaries |
+  | Systemic violation (mismatch with existing project architecture) | STOP, raise ADR (Step 5) and ask user to confirm direction before continuing |
 
-### Step 5: Define Data Flow
+### Step 4: Define Data Flow
 - **What**: for each primary use case, produce a sequence of module interactions.
 - **How**:
   1. For each use case (from Step 2 / analysis.md), list the trigger, the modules involved, the call order, and the persistence/event boundaries.
@@ -52,7 +51,7 @@
   3. Mark transactional boundaries explicitly (`-- transaction begin/end`).
   4. Identify error paths for each flow: what happens if step N fails? Document fallback behavior (retry, compensating action, user-visible error).
 
-### Step 6: Document Decisions (ADRs)
+### Step 5: Document Decisions (ADRs)
 - **What**: capture every non-obvious choice as an Architecture Decision Record.
 - **How**: write one ADR per decision with these fields:
 
@@ -66,39 +65,31 @@
   | Consequences | Positive and negative impacts; which downstream skills/modules pay the cost |
 
 - Decisions that MUST be ADRs (do not skip):
-  - Choice of architecture style (Step 3) when more than one row was viable.
+  - Any architectural response that changes module boundaries, deployment/runtime boundaries, persistence boundaries, async/event boundaries, or public contracts.
   - Any layer-rule violation accepted as a deliberate exception.
   - Introduction of a new external dependency (DB, queue, library category).
   - Breaking change to an existing public interface.
 
-### Step 7: User Confirmation Before Write
+### Step 6: User Confirmation Before Write
 - **When to confirm before writing the artifact**:
-  - Step 3 escalated to multi-service.
-  - Step 4 raised a systemic layer violation.
-  - Step 6 contains any ADR with `status: proposed` for a breaking change.
+  - Step 3 identified a new deployable service, runtime, or cross-service contract.
+  - Step 3 raised a systemic layer violation.
+  - Step 5 contains any ADR with `status: proposed` for a breaking change.
   - The design adds a new external dependency.
 - **When to write silently**:
   - Single-module addition that fits existing layers, no ADR escalations, no breaking change.
-- **Confirmation format**: present a one-screen summary -- style chosen, modules added/changed, ADRs requiring review, a single yes/no prompt. Do not dump the full artifact.
-
-### Step 8: Write Artifact
-- **Path and template**: as defined in the **Artifact Structure** section below.
-- **Required sections** (filled per template headings, but content must include):
-  - `Overview` -- the problem statement (Step 2).
-  - `Architecture Decision Records` -- every ADR from Step 6.
-  - `Module Design` -- table of modules from Step 4.
-  - `Key Interfaces` -- explicit signatures/endpoints.
-  - `Data Flow` -- sequences from Step 5, including error paths.
-  - `File Structure` -- mapping of modules to file/directory paths in this repo.
-  - `Implementation Guidelines` -- ordering hints for `/mvt-implement` and `/mvt-plan-dev`.
-  - `Change Tracking` -- list of files expected to be created/modified/deleted.
+- **Confirmation format**: present a one-screen summary -- module boundary changes, deployment/runtime boundary changes, ADRs requiring review, external dependencies, and a single yes/no prompt. Do not dump the full artifact.
+
+### Step 7: Write Artifact
+- **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 design. Preserve enough information for downstream skills to understand the problem, decisions made, module/interface/data-flow impacts, expected file changes, and implementation guidance. 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.
 - Do NOT modify `project-context.yaml` or `project-context.md` here.
 
-### Step 9: Suggest Plan Decomposition
+### Step 8: Suggest Plan Decomposition
 - If `Change Tracking` lists more than ~5 files OR Module Design adds more than 1 new module OR ADRs include any breaking change, recommend `/mvt-plan-dev` as the next step.
 - Otherwise recommend `/mvt-implement` directly.
 
-### Step 10: State Update
+### Step 9: State Update
 Apply the State Update rules defined in the **State Update** section below.
 
 ## Edge Cases & Errors

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

@@ -52,12 +52,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:
@@ -79,6 +73,12 @@ sections:
           level: "WARN"
           message: "No requirements found. Run `/mvt-analyze` 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
 
@@ -87,7 +87,7 @@ sections:
       ## Artifact Structure
       Read the document structure template from: `.ai-agents/skills/_templates/design-output.md`
       If a custom version exists at `.ai-agents/skills/_templates/custom/design-output.md`, use the custom version instead.
-      The template defines section headings only. Generate content for each section based on design results.
+      The template defines section structure and guidance comments. Generate applicable content based on design results.
       Write the artifact to: `.ai-agents/workspace/artifacts/{change-id}/design.md`
 
   - type: shared