@uoyo/mvtt 2.1.0 → 2.2.1

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

@@ -23,7 +23,7 @@ This skill measures only files the **user** can reduce or relocate. Framework-fi
 ### Step 3: Estimate Token Consumption
 - **What**: produce a per-file tokens estimate and per-category subtotals, with **per-project breakdown**.
 - **How**:
-  1. For each in-scope file: tokens ~= `characters / 4`.
+  1. For each in-scope file: compute characters mechanically and estimate tokens as `ceil(characters / 4)`.
   2. Group by category: `Index`, `Semantic Context`, `Shared Knowledge`, `Per-Skill Knowledge`, `Artifacts`.
   3. For Shared Knowledge, compute total once -- this is per-skill overhead (loaded by every skill invocation).
   4. For Per-Skill Knowledge, compute totals per skill so users can see which skill is heaviest.
@@ -63,7 +63,7 @@ This skill measures only files the **user** can reduce or relocate. Framework-fi
   | A single Shared Knowledge file is `oversized` | "{path} is {N} tokens. Split or move to per-skill." | `/mvt-manage-context move` |
   | Per-skill Knowledge entry exists in `registry.yaml` but its referenced files are missing | "{skill} declares knowledge `{id}` but `{path}` is missing." | `/mvt-manage-context remove` (or restore the file) |
   | A knowledge file exists on disk but no `registry.yaml` entry references it | "{path} is unused (not loaded by any skill)." | `/mvt-manage-context remove` |
-  | Two knowledge entries reference identical content (same hash) | "{a} and {b} are duplicates. Consolidate." | manual edit |
+  | Two knowledge entries reference identical content (same SHA-256 hash computed from file bytes) | "{a} and {b} are duplicates. Consolidate." | manual edit |
 
 - **Constraints on recommendations**:
   - Never recommend changes to framework files (`_framework/`, `mvt-*/SKILL.md`).

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

@@ -25,20 +25,17 @@ sections:
         - rule: "Total tokens > 25,000 -> Report as \"Oversized\", strongly recommend cleanup"
       boundaries:
         - scope: "modify any files"
-          skill: "(Only analyze and recommend)"
+          guidance: "Only analyze and recommend"
         - scope: "clean up artifacts"
           skill: "/mvt-cleanup"
         - scope: "modify context"
           skill: "/mvt-manage-context"
 
   - type: shared
-    source: sections/activation-load-context.md
+    source: sections/activation-protocol.md
     params:
       extended_context:
-        - ".ai-agents/config.yaml -- Framework configuration (to be scanned for size)"
-
-  - type: shared
-    source: sections/activation-load-config.md
+        - ".ai-agents/config.yaml -- Framework configuration (read thresholds and preferences; do not count config itself as context payload)"
 
   - type: shared
     source: sections/language-constraint.md

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

@@ -16,7 +16,7 @@ This check ensures `/mvt-sync-context` has processed a change's knowledge before
 - **What**: produce a per-change-id inventory with size and last-modified data.
 - **How**:
   1. Walk `.ai-agents/workspace/artifacts/` and group files by their parent change-id directory. **Exclude the `_archived/` subdirectory** from the walk — it contains previously archived changes and is not subject to re-inventory.
-  2. For each file: characters, estimated tokens (`chars / 4`), last-modified (mtime).
+  2. For each file: characters, estimated tokens (`ceil(characters / 4)`), last-modified (mtime).
   3. For each change-id directory, sum tokens and file count.
   4. Mark each change-id as `active | in-recent-changes | unindexed | legacy-pattern`:
      - `active` if it matches `session.active_change.id`.
@@ -30,12 +30,12 @@ This check ensures `/mvt-sync-context` has processed a change's knowledge before
 
   | Source | Rule | Proposed action |
   |--------|------|-----------------|
-  | `changes[]` entry with `status: done` AND any task in plan is older than the active change's start | Summarize: generate a `summary.md` from the change's artifacts, then move the **entire** `artifacts/{id}/` directory (including `summary.md`) to `artifacts/_archived/{id}/` |
+  | `changes[]` entry with `status: done` AND `artifacts/{id}/` exists AND (any task in plan is older than the active change's start **OR** plan metadata is missing, unreadable, or absent for this change) | Summarize: generate a `summary.md` from the change's artifacts, then move the **entire** `artifacts/{id}/` directory (including `summary.md`) to `artifacts/_archived/{id}/` |
   | `changes[]` entry with `status: done` AND `epic_id` non-empty AND parent epic status is NOT `done` | **Epic integrity warning**: mark the candidate as `epic-unsafe` -- archiving a sub-change whose parent epic is still in-progress may leave the epic in an inconsistent state. Default to `n` (skip) in the cleanup plan. User may override to force-archive. |
   | Artifact directory under `artifacts/` whose id starts with `epic-` AND contains `epic.yaml` with `status: done` | **Batch archive candidate**: mark for batch suggestion in Step 7 -- read `epic.yaml.children[]` for child change-ids to offer as batch archive options alongside the epic |
   | Change-id directory marked `unindexed` | List for user review (do NOT auto-archive -- could be in-flight work the user just hasn't registered) |
-  | `history` entries beyond the most recent N (from `config.yaml > preferences.history_limits.history`, default 20) | Truncate via `session-update.cjs --truncate-history <N>` |
-  | Directory `knowledge/patterns/` exists | Flag for deletion (legacy pattern data; no replacement) |
+  | `history` entries beyond the most recent N (from `config.yaml > preferences.history_limits.history`, default 10) | Truncate via `session-update.cjs --truncate-history <N>` |
+  | Directory `knowledge/patterns/` exists | Archive to `.ai-agents/knowledge/_archived/legacy-patterns/` after confirmation (legacy pattern data; no replacement) |
   | Empty change-id directories (zero files inside) | Propose deletion of the directory itself |
 
 - For each candidate, compute: `current size (tokens)` -> `projected size (tokens)`, expected savings.
@@ -79,10 +79,12 @@ This check ensures `/mvt-sync-context` has processed a change's knowledge before
 
      Per ADR-8: archive = abandon references; no post-archive `epic_id` integrity maintenance. Child changes that are also `status: done` are eligible for batch archiving; in-progress or pending children are excluded with a note.
 
-  3. **Delete action**: remove only the items explicitly marked for deletion in the confirmed plan; never recurse beyond what was listed.
-  4. **Stale history truncation**: call `session-update.cjs --truncate-history <N>` where N is from `config.yaml > preferences.history_limits.history` (default 20).
-  5. All file mutations atomic where possible (write-temp + rename, copy-then-delete for moves).
-  6. If any single action fails, STOP further actions; report what completed, what failed, and leave a recoverable state (do not partially overwrite a file with truncated content).
+  3. **Archive legacy-pattern action**: move `knowledge/patterns/` to `.ai-agents/knowledge/_archived/legacy-patterns/`. If that destination exists, preserve existing content and ask for a timestamped suffix. Do not hard-delete this directory.
+  4. **Delete action**: remove only the items explicitly marked for deletion in the confirmed plan; never recurse beyond what was listed.
+  5. **Stale history truncation**: call `session-update.cjs --truncate-history <N>` where N is from `config.yaml > preferences.history_limits.history` (default 10).
+  6. All file mutations atomic where possible (write-temp + rename, copy-then-delete for moves).
+  7. If any single action fails, STOP further actions; report what completed, what failed, and leave a recoverable state (do not partially overwrite a file with truncated content).
+  8. **Index synchronization**: after all archive moves finish, re-glob `artifacts/_archived/` for the actual moved change-id and epic-id directories from this run. The `--remove-change` id set MUST equal the set of change-id directories actually moved into `_archived/`; the `--remove-epic` id set MUST equal the set of epic directories actually moved. If the sets differ from the planned ids, use the actual moved-dir set and report the mismatch.
 
 ### Step 8: Report Result
 - Print the actually-applied actions (may differ from the plan if Step 7 stopped early).
@@ -95,23 +97,48 @@ Based on the actual cleanup actions performed, choose the appropriate session-up
 
 | Actual cleanup action | session-update parameters |
 |----------------------|---------------------------|
-| Closed `active_change` (all plan tasks completed) | `--close-change --truncate-history <N>` |
-| Only truncated history / archived old changes (active_change still in progress) | `--truncate-history <N>` (**do NOT** pass `--close-change`) |
+| Closed `active_change` (all plan tasks completed) **+** archived old done changes | `--close-change --remove-change <ids> --truncate-history <N>` |
+| Closed `active_change` only (no old changes archived) | `--close-change --truncate-history <N>` |
+| Archived old changes only (active_change still in progress) | `--remove-change <ids> --truncate-history <N>` |
+| Archived epic + its children (batch archive) | `--remove-epic <epic_id> --remove-change <child1>,<child2> --truncate-history <N>` |
 | `--dry-run` mode (no modifications made) | **Do NOT call** session-update script; only record history |
 
-N is read from `config.yaml > preferences.history_limits.history` (default 20).
+N is read from `config.yaml > preferences.history_limits.history` (default 10). `<ids>` is a comma-separated list from the actual moved-dir set collected in Step 7.8.
 
 ### Step 10: State Update
 Apply the State Update rules defined in the **State Update** section below.
 
-**Pre-filled example** (closed active_change + history truncation):
+**Pre-filled examples** (one per Step 9 row):
+
 ```bash
+# Row 1: closed active_change + archived old done changes
+node .ai-agents/scripts/session-update.cjs \
+  --skill mvt-cleanup \
+  --close-change \
+  --remove-change <archived_change_ids> \
+  --truncate-history 10
+
+# Row 2: closed active_change only
 node .ai-agents/scripts/session-update.cjs \
   --skill mvt-cleanup \
   --close-change \
   --truncate-history 10
+
+# Row 3: archived old changes only
+node .ai-agents/scripts/session-update.cjs \
+  --skill mvt-cleanup \
+  --remove-change <archived_change_ids> \
+  --truncate-history 10
+
+# Row 4: batch archive (epic + its children)
+node .ai-agents/scripts/session-update.cjs \
+  --skill mvt-cleanup \
+  --remove-epic <archived_epic_id> \
+  --remove-change <archived_child_ids> \
+  --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`.
+
+Replace `10` with the actual `config.yaml > preferences.history_limits.history` value, and `<archived_change_ids>` / `<archived_child_ids>` with the comma-separated id list collected in Step 7.8, `<archived_epic_id>` with the batch-archived epic id. Drop any `--remove-*` flag whose id list is empty.
 
 ## Edge Cases & Errors
 

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

@@ -43,20 +43,17 @@ sections:
       | `/mvt-cleanup --dry-run` | Preview what would be cleaned |
 
   - type: shared
-    source: sections/activation-load-context.md
+    source: sections/activation-protocol.md
     params:
+      activation_reads:
+        - session.yaml
       extended_context:
         - "Scan all files under `.ai-agents/workspace/artifacts/` (all change-id directories)"
-
-  - type: shared
-    source: sections/activation-load-config.md
-
-  - type: shared
-    source: sections/activation-preflight.md
-    params:
+      has_preflight: true
       checks:
         - order: "1"
           field: "project not initialized"
+          condition: "session.yaml missing OR session.initialized_at is empty"
           level: "REQUIRED"
           message: "Project must be initialized (session.yaml exists)"
 
@@ -75,6 +72,8 @@ sections:
       current_skill: mvt-cleanup
       truncate_history: true
       close_change: true
+      remove_change: true
+      remove_epic: true
 
   - type: shared
     source: sections/footer-next-steps.md

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

@@ -1,57 +1,62 @@
 ## Execution Flow
 
+`/mvt-config` takes no arguments. Every invocation opens the Interactive Menu (Step 2); all actions -- viewing settings, editing a key, and guided setup -- are reached from there. There is no `set` / `show` / `wizard` / `reset` invocation form.
+
 ### Step 1: Load Inputs
+- **Required**:
+  - `.ai-agents/config.yaml` -- the configuration to inspect and edit.
 - **Recommended**:
-  - `.ai-agents/knowledge/core/manifest.yaml` -- only when computing token estimates for shared knowledge view.
+  - `.ai-agents/knowledge/core/manifest.yaml` -- only when computing token estimates for the shared knowledge view.
 - **Fallback**: if `config.yaml` is missing, surface the error and recommend `mvtt install` or `/mvt-init`. Do not silently create a fresh config from this skill.
 
-### Step 2: Dispatch by Mode
-- **What**: pick the operating mode from the user's invocation.
-- **How**:
-
-  | Invocation | Mode | Go to |
-  |------------|------|-------|
-  | `/mvt-config` (no args) | Interactive Menu | Step 3 |
-  | `/mvt-config show` | Show All | Step 4 |
-  | `/mvt-config set {key} {value}` | Direct Set | Step 5 |
-  | `/mvt-config wizard` | Guided Wizard | Step 6 |
-  | `/mvt-config reset` | Reset | Step 7 |
-  | Anything else | Refuse, print Variants table, stop | -- |
-
-### Step 3: Interactive Menu
-1. Read current `config.yaml` and render a numbered menu grouped by category (User Preferences, Knowledge Settings, etc.) with current values inline.
-2. Wait for user to select a category number (or `q` to quit).
-3. Show the category detail view: keys with current values, type, default, allowed values.
-4. Let user pick a key to edit; reuse Step 5 (Direct Set) sub-flow for validation, preview, confirmation, write.
-5. After write, return to the top-level menu until user quits.
-6. No write happens unless the Step 5 sub-flow confirms.
-
-### Step 4: Show All
+### Step 2: Interactive Menu (entry point)
+1. Read current `config.yaml`.
+2. Render the top-level menu with these actions:
+
+   | # | Action | Goes to |
+   |---|--------|---------|
+   | 1 | View all settings | Step 3 |
+   | 2 | Edit a setting | Step 4 |
+   | 3 | Guided setup (walk through common settings) | Step 5 |
+   | `q` | Quit | -- exit, no write |
+
+3. Wait for the user's selection. Re-render the menu after any action completes, until the user quits.
+4. On an unrecognized selection, re-print the menu and prompt again. Do not exit.
+5. No write happens unless the user confirms -- either in the Edit sub-flow (Step 4) or at the Guided-setup summary (Step 5).
+
+### Step 3: View All
 - Print every key with `current value | type | default`. Mark values that differ from default with a `*`.
-- Print the Configuration Keys reference table (provided in shared section above) below the values, for context.
-- No write.
+- Print the Configuration Keys reference table (provided in the shared section above) below the values, for context.
+- No write. Return to the top-level menu (Step 2).
 
-### Step 5: Direct Set (`set {key} {value}`)
-1. **Validate key exists**:
-   - The key must match one of the rows in the Configuration Keys table. If not, print "Unknown key: <name>", list available keys, exit without writing.
+### Step 4: Edit a Setting
+1. Render a numbered list of editable keys grouped by category (User Preferences, etc.) with current values inline.
+2. Wait for the user to select a key (or `b` to go back to the top-level menu).
+3. Show the key detail: current value, type, default, allowed values.
+4. Run the **Edit sub-flow** (below) for the selected key.
+5. After the sub-flow completes (write or cancel), return to the editable-key list, then to the top-level menu.
+
+#### Edit sub-flow (validate -> preview -> confirm -> write)
+Used by Step 4 and by each stage of Step 5.
+
+1. **Validate key exists**: the key must match one of the rows in the Configuration Keys table. If not, report it and return without writing.
 2. **Validate value type and constraints**:
 
    | Type | Validation |
    |------|------------|
-   | `enum` | Value MUST be in the allowed list. Reject with the allowed list shown. For `language` enums (`en-US` = English, `zh-CN` = 简体中文), reject other locale strings -- ask user to pick from the allowed list (do not fuzzy-match) |
+   | `enum` | Value MUST be in the allowed list. Reject with the allowed list shown. For `language` enums (`en-US` = English, `zh-CN` = 简体中文), reject other locale strings -- ask the user to pick from the allowed list (do not fuzzy-match) |
    | `bool` | Accept exactly `true` / `false` (case-insensitive). Reject `yes`/`1`/`y` |
    | `int` | Parse as integer; check range when range is documented (e.g., `relevance_threshold` must be 0-100) |
-   | `list` | Parse as comma-separated tokens; for knowledge map entries (`_all` and project keys), every token must be a registered knowledge id |
 
 3. **Preview**: render `key: <current> -> <new>` on a single line.
-4. **Confirm**: prompt `Apply this change? (y/n)`. Skip the prompt only if invocation included an explicit non-interactive flag (none currently exists, so always prompt).
+4. **Confirm**: prompt `Apply this change? (y/n)`. On `n`, discard and return.
 5. **Write atomically**:
    - Read the current file, mutate only the targeted key, preserve all other content and formatting (do NOT rewrite the whole file from a template -- the user may have comments).
    - Write to a temp file in the same directory, then rename. On any error, do not touch the original.
 6. Report the new value and a one-line "what this affects" hint (e.g., "applies to subsequent skill invocations").
 
-### Step 6: Guided Wizard
-- Walk the user through these stages in order. Each stage uses the Step 5 validation rules. Defer the actual write to the end.
+### Step 5: Guided Setup
+- Selected from the top-level menu. Walk the user through these stages in order. Each stage uses the Edit sub-flow's validation rules. Defer the actual write to the end.
 
   | Stage | Key | Notes |
   |-------|-----|-------|
@@ -65,17 +70,9 @@
 
 - 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.
+- After applying (or aborting), return to the top-level menu (Step 2).
 
-### Step 7: Reset
-1. Build the diff between current `config.yaml` and framework defaults: list every key that will revert.
-2. Render the diff as `key | current | will-become-default`.
-3. Require explicit confirmation: `Reset all settings to defaults? (y/n)`.
-4. Backup current `config.yaml` to `config.yaml.bak` before writing.
-5. Write defaults atomically.
-6. Report the keys that changed.
-- Do NOT reset knowledge map entries (`_all`, project keys) to defaults if the user has added entries via `/mvt-manage-context` -- preserve user-added knowledge ids; only reset preferences. Surface this exception in the diff.
-
-## Knowledge Inspection (sub-flow used by Interactive Menu and Show All)
+## Knowledge Inspection (sub-flow used by View All and Edit a Setting)
 - **View**: list global knowledge ids from `registry.yaml > knowledge._all` and project-specific ids from `knowledge.{projectName}`, then per-skill knowledge ids grouped by skill (`registry.yaml > skills.*.knowledge`). Show token estimates from each entry's manifest if available.
 - **Modify**: this skill does NOT mutate knowledge settings; defer to `/mvt-manage-context`. Print the suggested command (`/mvt-manage-context move`, `/mvt-manage-context add`, etc.) instead of doing the work here.
 
@@ -85,10 +82,8 @@
 |------|----------|
 | `config.yaml` missing | STOP; recommend `mvtt install` or `/mvt-init` |
 | `config.yaml` exists but unparseable YAML | Surface error with line number; refuse to write; recommend manual fix or `mvtt install --refresh` |
-| User runs `set` with a deprecated key (`preferences.language`) | Print migration hint: `Run mvtt update --migrate-config` to split into the two language fields. Do not mutate the deprecated key |
-| Wizard stage receives an empty value | Treat as "accept default for this stage", continue |
-| User aborts mid-wizard | No partial write; the temp values are discarded |
-| `.bak` from previous reset already exists | Overwrite (only the most recent backup is useful) |
+| Editing a deprecated key (`preferences.language`) | Print migration hint: `Run mvtt update --migrate-config` to split into the two language fields. Do not mutate the deprecated key |
+| Guided-setup stage receives an empty value | Treat as "accept default for this stage", continue |
+| User aborts mid guided-setup | No partial write; the temp values are discarded |
 | Concurrent edit detected (mtime changed during preview->write) | Abort write, surface a message, ask user to re-run |
-| `set knowledge._all <list>` (or project key) includes unknown id | Reject with the list of valid ids from `registry.yaml` |
-| `reset` invoked but `config.yaml` already matches defaults | Report "nothing to reset", do not write |
+| User asks to edit `knowledge._all` or any knowledge map key | Refuse and route to `/mvt-manage-context`; this skill inspects knowledge settings but does not mutate them |

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

@@ -12,7 +12,7 @@ sections:
 
       ## Purpose
 
-      Manage MVTT framework configuration interactively. Provide guided setup, direct key-value setting, and a setup wizard for common configurations.
+      Manage MVTT framework configuration through an interactive menu: view all settings, edit an individual key, or run a guided setup for common configurations.
 
   - type: shared
     source: sections/role-header.md
@@ -20,13 +20,12 @@ sections:
       role: Conductor
       role_desc: "a Workflow Coordinator"
       decision_rules:
-        - rule: "No arguments -> Show interactive configuration menu"
-        - rule: "`show` argument -> Display all current settings"
-        - rule: "`set {key} {value}` -> Validate and apply the specific setting"
-        - rule: "`wizard` argument -> Start guided setup flow"
-        - rule: "`reset` argument -> Reset all settings to defaults after confirmation"
-        - rule: "Invalid key -> Show available keys and exit"
-        - rule: "Invalid value type -> Show expected type and exit"
+        - rule: "Any invocation -> Open the interactive configuration menu (this skill takes no arguments)"
+        - rule: "Menu: View all settings -> Display every key with current value, type, default"
+        - rule: "Menu: Edit a setting -> Pick a key, validate, preview, confirm, write"
+        - rule: "Menu: Guided setup -> Walk common settings in order, apply atomically at the end"
+        - rule: "Invalid key -> Show available keys and return to the menu"
+        - rule: "Invalid value type -> Show expected type and re-prompt"
       boundaries:
         - scope: "analyze requirements"
           skill: "/mvt-analyze"
@@ -37,25 +36,22 @@ sections:
 
   - type: inline
     content: |
-      ## Variants
+      ## Usage
 
-      | Variant | Description |
-      |---------|-------------|
-      | `/mvt-config` | Show interactive configuration menu |
-      | `/mvt-config show` | Display all current settings |
-      | `/mvt-config set {key} {value}` | Set a specific configuration value |
-      | `/mvt-config wizard` | Start guided setup wizard |
-      | `/mvt-config reset` | Reset all settings to defaults |
+      `/mvt-config` takes no arguments. It always opens an interactive menu; all actions are reached from there.
+
+      | Menu action | Description |
+      |-------------|-------------|
+      | View all settings | Display every configuration key with its current value, type, and default |
+      | Edit a setting | Pick a key, then validate, preview, confirm, and write the change |
+      | Guided setup | Walk through common settings in order and apply them atomically |
 
   - type: shared
-    source: sections/activation-load-context.md
+    source: sections/activation-protocol.md
     params:
       extended_context:
         - ".ai-agents/config.yaml -- Current configuration (this skill's primary target)"
 
-  - type: shared
-    source: sections/activation-load-config.md
-
   - type: shared
     source: sections/language-constraint.md
 
@@ -72,15 +68,14 @@ sections:
       | `preferences.output.no_emojis` | bool | `true` | Disable emojis in output |
       | `preferences.output.data_format` | enum | `yaml` | Data output format (yaml, json) |
       | `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.history_limits.history` | int | `10` | Max history entries (1-100) |
+      | `preferences.history_limits.changes` | int | `10` | Max changes entries (1-100) |
+      | `preferences.context_thresholds.*` | map | built-in thresholds | Optional context health thresholds read by `/mvt-check-context`; omitted keys use built-in defaults |
       | `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
 
-      | Key | Type | Default | Description |
-      |-----|------|---------|-------------|
-      | `knowledge._all` | list | `[core, project-context]` | Global knowledge entries in registry.yaml under `_all` key, loaded by all skills across all projects |
+      Knowledge routing is managed by `/mvt-manage-context`, not by `/mvt-config`. Requests to change `knowledge.*` keys must be refused and routed there.
 
   - type: file
     source: ./business.md

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

@@ -45,7 +45,7 @@ Collect core metadata. Each field has an explicit constraint -- do not accept va
 
 | Field | Constraint | Notes |
 |-------|------------|-------|
-| Name | Lowercase, kebab-case, no spaces. Prefix `mvt-` for framework skills; project-specific prefixes (e.g., `app-`, `proj-`) are also acceptable | Reject if conflicts with an existing entry in `registry.yaml` |
+| Name | Lowercase, kebab-case, no spaces, must match `^[a-z][a-z0-9-]*$`. Prefix `mvt-` for framework skills; project-specific prefixes (e.g., `app-`, `proj-`) are also acceptable | Reject if invalid or if it conflicts with an existing entry in `registry.yaml` |
 | Agent role | One of: `conductor`, `analyst`, `architect`, `developer`, `reviewer`, `tester` | Maps the skill to an existing role family |
 | Purpose | One sentence | Will become the SKILL.md `## Purpose` section |
 | Category | One of: `workflow`, `shortcut`, `project`, `utility` | Drives how `/mvt-help` groups it |
@@ -77,7 +77,7 @@ If the user is unsure on any field, propose a default and ask for confirmation r
   |--------|----------|
   | Input parameters | What does the skill need from the user / workspace? |
   | Execution mode | Interactive / automated / hybrid |
-  | Pre-flight checks | List, with severity (BLOCK / WARN); defer to `activation-preflight.md` shared section |
+  | Pre-flight checks | List, with severity (BLOCK / WARN); these populate the Pre-flight part of the Activation Protocol copied into the generated SKILL.md |
   | Decision rules (in role-header) | 3-7 imperative rules covering the major branches |
   | Boundaries | What is in-scope vs delegated to other skills |
   | Execution Flow steps | Bulleted titles only (full content comes in Step 6) |
@@ -86,7 +86,7 @@ If the user is unsure on any field, propose a default and ask for confirmation r
 ### Step 6: Generate Skill Files
 1. Create skill directory: `.claude/skills/{name}/`.
 2. Generate a complete `SKILL.md` file (see Generated SKILL.md Structure below). This file must be fully self-contained — there is no assembler or build step to resolve shared section references. All content must be inlined directly into the SKILL.md.
-3. For standard sections (Activation Protocol, Load Config, Language Constraint, Pre-flight, State Update, Next Steps), copy them verbatim from this document's own SKILL.md and substitute only the skill-specific values (role, decision rules, boundaries, pre-flight checks, next-skill suggestions). Do NOT paraphrase standard sections — copy character-for-character to ensure consistency.
+3. For standard sections (Activation Protocol, Language Constraint, Output Format Constraint, State Update, Next Steps), read the existing shared section files under `.ai-agents/sections/` or the corresponding installed skill section and substitute only the skill-specific values (role, decision rules, boundaries, pre-flight checks, next-skill suggestions). Do NOT reproduce these sections from memory; use the checked-in source text as the canonical template.
 4. For skill-specific sections (frontmatter, Purpose, Execution Flow, Edge Cases & Errors), generate fresh content following the skeleton below.
    - `## Execution Flow`
    - `### Step 1: Load Inputs` -- list required and recommended files, plus fallback rules.
@@ -100,16 +100,21 @@ If the user is unsure on any field, propose a default and ask for confirmation r
 7. SKILL.md word budget: aim for the body to be under ~5k words. Push reference material to `references/`.
 
 ### Step 7: Register in Registry (MANDATORY)
-Append the skill entry to `.ai-agents/registry.yaml` > `skills` section:
+Create a pre-write backup of `.ai-agents/registry.yaml`, then add the skill entry to `.ai-agents/registry.yaml` > `skills` section using structured YAML serialization (not hand-written string concatenation):
 
 ```yaml
   {name}:
     description: "{third-person description with trigger keywords}"
     custom: true
+    template: "_templates/{name}-output.md"   # include ONLY if an output template was created in Step 6; omit this key otherwise
 ```
 
+- If an output template was created in Step 6, set `template:` to its path so `/mvt-template` can discover it; otherwise omit the key entirely.
 - The `custom: true` field is **required** for user-created skills; without it, framework updates will overwrite the entry.
-- Validate the YAML still parses after the append; if not, abort and surface the parse error.
+- Refuse to overwrite an existing skill key.
+- Escape `description` through the YAML serializer; never interpolate raw user text into YAML.
+- Validate the YAML still parses after the write; if not, restore the backup and surface the parse error.
+- Post-write, assert the skills entry count increased by exactly 1 and no existing sibling skill entry changed.
 
 ### Step 8: Validation
 Walk this checklist; any failed item must be fixed before declaring success.
@@ -150,7 +155,7 @@ Apply the State Update rules defined in the **State Update** section below.
 | Skill duplicates an existing skill's responsibility | Surface the overlap (cite the existing skill's description); propose merging or sub-classing as a variant rather than creating a duplicate |
 | User provides a non-third-person description ("Use this skill when you need...") | Rewrite to third-person before saving; show the rewrite for confirmation |
 | Generated SKILL.md is missing a standard section (e.g., State Update, Next Steps) | Abort generation; inform user which section is missing; read an existing SKILL.md for the correct structure |
-| `registry.yaml` parse fails after append | Restore from a pre-append backup; surface the error; do not leave the registry corrupt |
+| `registry.yaml` parse fails after write | Restore from the pre-write backup; surface the error; do not leave the registry corrupt |
 
 ## Generated SKILL.md Structure
 
@@ -210,11 +215,10 @@ Copy the following sections verbatim from this document (the assembled SKILL.md
 
 | Section | Source in this document | What to replace |
 |---------|----------------------|-----------------|
-| 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 |
-| 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 |
+| Activation Protocol | `## Activation Protocol` (the whole Load + Resolve block) | Copy the entire block as-is. The block already covers context loading, project scope, knowledge, config preferences, and pre-flight. Adjust only two skill-specific parts: under Load, the Extended Context entries (add the files/directives this skill needs, or drop the Extended Context bullet if none); under Resolve > Pre-flight, the checks table (skill-specific checks, or a single INFO row if none required) |
+| Language Constraint | `## Language Constraint` | Copy as-is (separate section, not part of Activation Protocol) |
+| Output Format Constraint | `## Output Format Constraint` | Copy as-is (separate section); include only if the skill writes persisted markdown |
 | 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 |
 
-**Important**: Do NOT paraphrase or rewrite the standard sections. Copy them character-for-character from this document and only substitute the skill-specific values. This ensures consistency across all MVTT skills.
+**Important**: Do NOT paraphrase or rewrite the standard sections. Load them from the checked-in shared section sources or a selected installed exemplar and only substitute the skill-specific values. This ensures consistency across all MVTT skills.

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

@@ -28,25 +28,22 @@ sections:
         - rule: "Usage patterns unclear -> Ask for concrete examples before proceeding"
       boundaries:
         - scope: "generate skills that deviate from MVTT SKILL.md standard structure"
-          skill: "the standard structure as documented"
+          guidance: "follow the standard structure as documented"
         - scope: "use arbitrary prefixes without validating naming conventions"
-          skill: "`mvt-` or a project-specific prefix like `app-`, `proj-`"
+          guidance: "use `mvt-` or a project-specific prefix like `app-`, `proj-`"
         - scope: "create skills without registering in registry.yaml"
-          skill: "`custom: true` in registry.yaml"
+          guidance: "register with `custom: true` in registry.yaml"
         - scope: "write vague or first-person descriptions"
-          skill: "third-person with effective trigger keywords"
+          guidance: "write third-person with effective trigger keywords"
         - scope: "exceed ~5k words in SKILL.md body"
-          skill: "references/ for detailed content"
+          guidance: "push detailed content to references/"
 
   - type: shared
-    source: sections/activation-load-context.md
+    source: sections/activation-protocol.md
     params:
       extended_context:
         - "Load one existing SKILL.md as structural reference (e.g., `.claude/skills/mvt-status/SKILL.md`)"
 
-  - type: shared
-    source: sections/activation-load-config.md
-
   - type: shared
     source: sections/language-constraint.md
 

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

@@ -56,6 +56,8 @@
 ### Step 6: Write Artifacts
 Write two artifacts:
 
+Before writing, derive `epic_id` and check whether `.ai-agents/workspace/artifacts/{epic_id}/` already exists. If it exists, do NOT overwrite it; warn the user and ask for a disambiguating slug, then re-run the preview from Step 5 with the new id.
+
 1. **epic.md** (narrative) -- `.ai-agents/workspace/artifacts/{epic_id}/epic.md`
    - 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.
@@ -67,6 +69,7 @@ Write two artifacts:
 
 **Self-validation checklist** (verify before writing):
 - [ ] All `change_id` values are unique
+- [ ] `.ai-agents/workspace/artifacts/{epic_id}/` does not already exist
 - [ ] All `depends_on` references exist in `children[]`
 - [ ] No cycles in the dependency graph
 - [ ] Exactly one child has `status: active`

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

@@ -33,27 +33,25 @@ sections:
           skill: "/mvt-analyze"
 
   - type: shared
-    source: sections/activation-load-context.md
-
-  - type: shared
-    source: sections/activation-load-config.md
-
-  - type: shared
-    source: sections/activation-preflight.md
+    source: sections/activation-protocol.md
     params:
+      activation_reads:
+        - session.yaml
+      has_preflight: true
       checks:
         - order: "1"
           field: "session.initialized_at"
           level: "WARN"
-          message: 'Session not initialized. Run `/mvt-init` first.'
+          message: "Session not initialized. Run `/mvt-init` first."
         - order: "2"
           field: "projects[] in project-context.yaml"
           level: "WARN"
-          message: 'Project not initialized. Run `/mvt-init` first.'
+          message: "Project not initialized. Run `/mvt-init` first."
         - order: "3"
           field: "active_change.id"
+          condition: "active_change.id is non-empty"
           level: "WARN"
-          message: 'An active change already exists. Decomposing will create a new epic alongside it. Continue? (y/n)'
+          message: "An active change already exists. Decomposing will create a new epic alongside it. Continue? (y/n)"
 
   - type: shared
     source: sections/language-constraint.md

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

@@ -86,7 +86,7 @@
 - Do NOT modify `project-context.yaml` or `project-context.md` here.
 
 ### 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.
+- 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 9: State Update

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

@@ -44,17 +44,15 @@ sections:
       | `/mvt-design --plan` | High-level implementation plan only: skip Step 5 (data flow detail) and Step 6 (full ADR fields). ADRs collapse to one-line `decision: <text>`. Step 8 writes `design.md` with abbreviated content and a top-line `Mode: plan` indicator. If the request is actually small (1 file), downgrade to a 5-line summary in chat and do NOT write `design.md`. |
 
   - type: shared
-    source: sections/activation-load-context.md
+    source: sections/activation-protocol.md
     params:
+      activation_reads:
+        - session.yaml
       extended_context:
         - ".ai-agents/workspace/artifacts/{active_change.id}/analysis.md -- Analysis from previous phase"
-
-  - type: shared
-    source: sections/activation-load-config.md
-
-  - type: shared
-    source: sections/activation-preflight.md
-    params:
+        - ".ai-agents/knowledge/project/_generated/project-context.md -- Current semantic project context"
+        - ".ai-agents/workspace/artifacts/*/design.md -- Prior design artifacts for related changes (load only relevant matches)"
+      has_preflight: true
       checks:
         - order: "1"
           field: "session.initialized_at"