@uoyo/mvtt 2.0.0-beta.0 → 2.0.0-beta.2

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

@@ -1,74 +1,63 @@
-name: mvt-check-context
-output: .claude/skills/mvt-check-context/SKILL.md
-
-frontmatter:
-  name: mvt-check-context
-  description: "Analyze context token load and give optimization recommendations. Use when user wants to check how much context MVTT loads, identify large files, or optimize workspace size for better performance."
-
-sections:
-  - type: inline
-    content: |
-      # MVT Context Check
-
-      ## Purpose
-
-      Analyze the total context information that MVTT loads at runtime, estimate token consumption, assess health status, and provide actionable optimization recommendations.
-
-  - type: shared
-    source: sections/role-header.md
-    params:
-      role: Conductor
-      role_desc: "a Workflow Coordinator"
-      decision_rules:
-        - rule: "Total tokens < 5,000 -> Report as \"Good\""
-        - rule: "Total tokens 5,000-15,000 -> Report as \"Moderate\""
-        - rule: "Total tokens 15,000-30,000 -> Report as \"High\", suggest optimizations"
-        - rule: "Total tokens > 30,000 -> Report as \"Overloaded\", strongly recommend cleanup"
-      boundaries:
-        - scope: "modify any files"
-          skill: "(Only analyze and recommend)"
-        - scope: "clean up artifacts"
-          skill: "/mvt-cleanup"
-        - scope: "modify context"
-          skill: "/mvt-add-context"
-
-  - type: shared
-    source: sections/activation-load-context.md
-    params:
-      extended_context:
-        - ".ai-agents/config.yaml -- Framework configuration (to be scanned for size)"
-
-  - type: shared
-    source: sections/activation-load-config.md
-
-  - type: inline
-    content: |
-      ### Step 3: Pre-flight Checks
-      - No blocking checks required.
-
-      ### Step 4: Execute
-      Proceed to Execution Flow below.
-
-  - type: file
-    source: ./business.md
-
-  - type: inline
-    content: |
-      ## Output Format
-
-      Read and use the output template from: `.ai-agents/skills/_templates/context-check-output.md`
-
-      If a custom version exists at `.ai-agents/skills/_templates/custom/context-check-output.md`, use the custom version instead.
-
-      Fill the template with analysis results.
-
-      Every response MUST end with a Suggested Next Steps section.
-
-  - type: shared
-    source: sections/footer-next-steps.md
-    params:
-      next_primary: mvt-cleanup
-      next_primary_desc: "Clean up old artifacts to reduce context size"
-      next_alternatives:
-        - skill: mvt-add-context
-          when: "Update project context if information is outdated"
+name: mvt-check-context
+output: .claude/skills/mvt-check-context/SKILL.md
+
+frontmatter:
+  name: mvt-check-context
+  description: "Analyze context token load and provide optimization recommendations. This skill should be used when user wants to check how much context MVTT loads, identify large files, or optimize workspace size for better performance."
+
+sections:
+  - type: inline
+    content: |
+      # MVT Context Check
+
+      ## Purpose
+
+      Analyze the total context information that MVTT loads at runtime, estimate token consumption, assess health status, and provide actionable optimization recommendations.
+
+  - type: shared
+    source: sections/role-header.md
+    params:
+      role: Conductor
+      role_desc: "a Workflow Coordinator"
+      decision_rules:
+        - rule: "Total tokens < 5,000 -> Report as \"Good\""
+        - rule: "Total tokens 5,000-15,000 -> Report as \"Moderate\""
+        - rule: "Total tokens 15,000-30,000 -> Report as \"High\", suggest optimizations"
+        - rule: "Total tokens > 30,000 -> Report as \"Overloaded\", strongly recommend cleanup"
+      boundaries:
+        - scope: "modify any files"
+          skill: "(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
+    params:
+      extended_context:
+        - ".ai-agents/config.yaml -- Framework configuration (to be scanned for size)"
+
+  - type: shared
+    source: sections/activation-load-config.md
+
+  - type: shared
+    source: sections/output-language-constraint.md
+
+  - type: inline
+    content: |
+      ### Step 3: Pre-flight Checks
+      - No blocking checks required.
+
+  - type: file
+    source: ./business.md
+
+  - type: shared
+    source: sections/session-update.md
+    params:
+      read_only: true
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-check-context

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

@@ -1,31 +1,80 @@
-## Execution Flow
-
-### Step 1: Scan Workspace State
-- Read all files under `.ai-agents/workspace/artifacts/{change-id}/`
-- Read `.ai-agents/workspace/session.yaml`
-- Count total artifact files
-- Estimate token footprint for each file (~characters / 4)
-
-### Step 2: Identify Cleanup Candidates
-- Apply cleanup rules to identify candidates
-- Calculate current size and projected savings for each
-
-### Step 3: Present Cleanup Plan
-Show user what will be cleaned:
-
-| Item | Current Size | Action | Result |
-|------|-------------|--------|--------|
-| {artifact} | ~{tokens} tokens | {action} | ~{reduced} tokens |
-| **Total** | **{total}** | | **{new_total} ({savings} saved)** |
-
-If `--dry-run` flag is set -> Stop here. Do not proceed.
-
-### Step 4: Execute (after user confirmation)
-- Summarize identified artifacts (keep key decisions, remove details)
-- Update `session.yaml` to reflect cleanup
-- Output summary of actions taken
-
-### Step 5: Update Workspace
-1. Update `.ai-agents/workspace/session.yaml`:
-   - Set `session.last_command: "/mvt-cleanup"`
-   - Append one-line summary to `recent_actions` (keep max 3)
+## Execution Flow
+
+### Step 1: Load Inputs
+- **Fallback**: if `session.yaml` is missing, refuse to clean -- without state we can't tell what is in-progress vs completed; recommend `/mvt-init` and stop.
+
+### Step 2: Inventory Artifacts
+- **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.
+  2. For each file: characters, estimated tokens (`chars / 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`.
+     - `in-recent-changes` if it appears in `session.recent_changes[]` (any status).
+     - `unindexed` if neither condition holds and it sits under `artifacts/`.
+     - `legacy-pattern` if the directory is `knowledge/patterns/` or matches other legacy markers.
+
+### Step 3: Apply Cleanup Rules
+- **What**: compute Cleanup Candidates from the inventory.
+- **How**: run the rules table (defined in the shared section above) plus the additions below. A single change-id may match multiple rows; collect all proposed actions.
+
+  | Source | Rule | Proposed action |
+  |--------|------|-----------------|
+  | `recent_changes[]` entry with `status: completed` AND any task in plan is older than the active change's start | Summarize: collapse multi-file artifacts into a single `summary.md`, keep the plan.yaml verbatim, archive the rest under `artifacts/{id}/_archive/` |
+  | Change-id directory marked `unindexed` | List for user review (do NOT auto-archive -- could be in-flight work the user just hasn't registered) |
+  | `skill_history` entries beyond the most recent 10 | Collapse into a single summary entry inside session.yaml (rule from Cleanup Rules table) |
+  | Directory `knowledge/patterns/` exists | Flag for deletion (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.
+
+### Step 4: Present Cleanup Plan
+- Render the plan as a table:
+
+  | Item | Category | Current Size | Action | Result |
+  |------|----------|-------------|--------|--------|
+  | {change-id or path} | {completed | unindexed | stale-history | legacy} | ~{tokens} | {summarize | archive | review-only | delete} | ~{reduced tokens} |
+  | **Total** | | **{total}** | | **{new_total} ({savings} saved)** |
+
+- Below the table, list any items marked `review-only` (unindexed) with a one-line note: user must decide manually.
+- If `--dry-run` is set, STOP here. Print "(dry run -- no changes applied)" and exit cleanly.
+
+### Step 5: Confirm Before Destructive Steps
+- **Always require confirmation** if the plan includes any of:
+  - File deletion (legacy patterns, empty dirs).
+  - `summarize` action (collapses multi-file content).
+  - `archive` action (moves files into `_archive/`).
+- Confirmation format: a single prompt `Apply cleanup plan? (y / n / show-details)`. `show-details` prints the per-file actions, then re-asks.
+- Do NOT silently delete. Do NOT skip confirmation when `--dry-run` is absent.
+
+### Step 6: Execute the Plan
+- **What**: apply the confirmed actions.
+- **How**:
+  1. **Summarize action**: read the full set of files in the change-id directory; produce a `summary.md` with: title, change-id, status, key decisions (list each ADR/decision title), final outcomes, list of original files. Then move originals to `_archive/`.
+  2. **Archive action**: move files into `_archive/` under the same change-id directory, preserving relative paths.
+  3. **Delete action**: remove only the items explicitly marked for deletion in the confirmed plan; never recurse beyond what was listed.
+  4. **Stale skill_history collapse**: rewrite `session.yaml`'s `skill_history` keeping the most recent 10 detailed entries plus one rolled-up entry summarizing the older ones (count + earliest/latest date).
+  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).
+
+### Step 7: Report Result
+- Print the actually-applied actions (may differ from the plan if Step 6 stopped early).
+- Show new totals: files cleaned, tokens saved.
+- Recommend `/mvt-check-context` to validate the post-cleanup state if savings exceed ~5k tokens.
+
+### Step 8: (session update handled by shared section)
+- This skill mutates `session.skill_history` directly in Step 6 (collapse). The standard `skill_history` append from the shared section still applies; the collapse runs BEFORE the append so the new entry is preserved at full detail.
+
+## Edge Cases & Errors
+
+| Case | Handling |
+|------|----------|
+| `active_change.id` directory matches a "stale completed" rule | Skip cleanup of the active change; never archive in-progress work |
+| `--dry-run` set | Stop after Step 4; do not request confirmation; do not modify any file |
+| Plan would archive ALL artifacts (workspace becomes empty) | Require an extra confirmation: `This will archive every artifact. Continue? (y/n)` |
+| User aborts at Step 5 confirmation | Report "no changes applied" |
+| `_archive/` already exists with content from a prior run | Preserve existing `_archive/` content; new archives are added alongside |
+| File targeted for action no longer exists (concurrent removal) | Skip with a note; do not error out the whole run |
+| Unindexed change-id directory contains only `plan.yaml` | List as review-only; suggest user runs `/mvt-update-plan` or registers it via `/mvt-plan-dev` instead of cleaning |
+| `session.yaml.bak` present from a previous failed run | Overwrite during Step 6 collapse (only the most recent backup is useful) |

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

@@ -1,93 +1,85 @@
-name: mvt-cleanup
-output: .claude/skills/mvt-cleanup/SKILL.md
-
-frontmatter:
-  name: mvt-cleanup
-  description: "Clean up workspace artifacts, summarize old changes, and maintain workspace health. Use when workspace has accumulated old artifacts or to reduce context token footprint."
-
-sections:
-  - type: inline
-    content: |
-      # MVT Cleanup
-
-      ## Purpose
-
-      Clean up workspace artifacts, summarize completed changes, and maintain workspace health. Reduces token footprint by archiving old artifacts and removing stale data.
-
-  - type: shared
-    source: sections/role-header.md
-    params:
-      role: Conductor
-      role_desc: "a Workflow Coordinator"
-      decision_rules:
-        - rule: "No arguments -> Interactive cleanup (review items before action)"
-        - rule: "`--dry-run` flag -> Show what would be cleaned without taking action"
-        - rule: "Completed changes found -> Summarize and archive"
-        - rule: "Orphaned artifacts found -> List for user review"
-        - rule: "Stale session data found -> Summarize into single entry"
-      boundaries:
-        - scope: "analyze requirements"
-          skill: "/mvt-analyze"
-        - scope: "design architecture"
-          skill: "/mvt-design"
-        - scope: "write implementation code"
-          skill: "/mvt-implement"
-
-  - type: inline
-    content: |
-      ## Variants
-
-      | Variant | Description |
-      |---------|-------------|
-      | `/mvt-cleanup` | Interactive cleanup (review before action) |
-      | `/mvt-cleanup --dry-run` | Preview what would be cleaned |
-
-  - type: shared
-    source: sections/activation-load-context.md
-    params:
-      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:
-      checks:
-        - order: "1"
-          field: "project not initialized"
-          level: "REQUIRED"
-          message: "Project must be initialized (session.yaml exists)"
-
-  - type: inline
-    content: |
-      ### Step 4: Execute
-      Proceed to Execution Flow below.
-
-      ## Cleanup Rules
-
-      | Category | Rule | Action |
-      |----------|------|--------|
-      | Completed changes | Change with `status: completed` older than current task | Summarize -> archive |
-      | Orphaned artifacts | Files in `artifacts/` not referenced by any active change | List for user review |
-      | Stale session data | Session history entries older than 5 phases ago | Summarize into single entry |
-
-  - type: file
-    source: ./business.md
-
-  - type: inline
-    content: |
-      ## Output Format
-
-      Read and use the output template from: `.ai-agents/skills/_templates/cleanup-output.md`
-
-      If a custom version exists at `.ai-agents/skills/_templates/custom/cleanup-output.md`, use the custom version instead.
-
-      Every response MUST end with a Suggested Next Steps section.
-
-  - type: shared
-    source: sections/footer-next-steps.md
-    params:
-      next_primary: mvt-status
-      next_primary_desc: "Verify workspace state"
+name: mvt-cleanup
+output: .claude/skills/mvt-cleanup/SKILL.md
+
+frontmatter:
+  name: mvt-cleanup
+  description: "Clean up workspace artifacts, summarize completed changes, and maintain workspace health. This skill should be used when workspace has accumulated old artifacts, token footprint needs reduction, or to archive completed change records."
+
+sections:
+  - type: inline
+    content: |
+      # MVT Cleanup
+
+      ## Purpose
+
+      Clean up workspace artifacts, summarize completed changes, and maintain workspace health. Reduces token footprint by archiving old artifacts and removing stale data.
+
+  - type: shared
+    source: sections/role-header.md
+    params:
+      role: Conductor
+      role_desc: "a Workflow Coordinator"
+      decision_rules:
+        - rule: "No arguments -> Interactive cleanup (review items before action)"
+        - rule: "`--dry-run` flag -> Show what would be cleaned without taking action"
+        - rule: "Completed changes found -> Summarize and archive"
+        - rule: "Orphaned artifacts found -> List for user review"
+        - rule: "Stale session data found -> Summarize into single entry"
+      boundaries:
+        - scope: "analyze requirements"
+          skill: "/mvt-analyze"
+        - scope: "design architecture"
+          skill: "/mvt-design"
+        - scope: "write implementation code"
+          skill: "/mvt-implement"
+
+  - type: inline
+    content: |
+      ## Variants
+
+      | Variant | Description |
+      |---------|-------------|
+      | `/mvt-cleanup` | Interactive cleanup (review before action) |
+      | `/mvt-cleanup --dry-run` | Preview what would be cleaned |
+
+  - type: shared
+    source: sections/activation-load-context.md
+    params:
+      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/output-language-constraint.md
+
+  - type: shared
+    source: sections/activation-preflight.md
+    params:
+      checks:
+        - order: "1"
+          field: "project not initialized"
+          level: "REQUIRED"
+          message: "Project must be initialized (session.yaml exists)"
+
+  - type: inline
+    content: |
+      ## Cleanup Rules
+
+      | Category | Rule | Action |
+      |----------|------|--------|
+      | Completed changes | Change with `status: completed` older than current task | Summarize -> archive |
+      | Orphaned artifacts | Files in `artifacts/` not referenced by any active change | List for user review |
+      | Stale session data | Session history entries older than 5 phases ago | Summarize into single entry |
+
+  - type: file
+    source: ./business.md
+
+  - type: shared
+    source: sections/session-update.md
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-cleanup

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

@@ -1,26 +1,94 @@
-## Execution Flow
-
-### Interactive Menu (Default)
-1. Read current settings from `config.yaml`
-2. Display configuration menu with categories and current values
-3. Wait for user to select a category (1-5)
-4. Show category detail view with editable settings
-5. Apply changes after user confirmation
-
-### Direct Set (`set {key} {value}`)
-1. Validate key exists -- if not, show available keys
-2. Validate value type -- if wrong, show expected type
-3. Preview the change (old -> new)
-4. Ask user to confirm
-5. Apply and write `config.yaml`
-
-### Guided Wizard (`wizard`)
-1. Step 1: Language Preference
-2. Step 2: Output Style (emojis, data format)
-3. Step 3: Architecture Pattern
-4. Summary Preview -> User confirms -> Apply all changes
-
-### Reset (`reset`)
-1. Show all settings that will be reset
-2. Ask user confirmation
-3. Write default values to `config.yaml`
+## Execution Flow
+
+### Step 1: Load Inputs
+- **Recommended**:
+  - `.ai-agents/knowledge/core/manifest.yaml` -- only when computing token estimates for 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
+- 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.
+
+### 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.
+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`, `zh-CN`), reject other locale strings -- ask 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.shared`, 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).
+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.
+
+  | Stage | Key | Notes |
+  |-------|-----|-------|
+  | 1 | `preferences.interaction_language` | Default `en-US`. Show allowed list |
+  | 2 | `preferences.document_output_language` | Default = whatever was just set in stage 1; user may override. Reuse stage-1 value when user accepts default |
+  | 3 | `preferences.output.no_emojis` | Default `true` |
+  | 4 | `preferences.output.data_format` | Default `yaml`; allowed: `yaml`, `json` |
+  | 5 | `preferences.context_routing.relevance_threshold` | Default `70`; allowed: 0-100 |
+
+- 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.
+
+### 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.shared` 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.
+
+### Step 8: (session update handled by shared section)
+
+## Knowledge Inspection (sub-flow used by Interactive Menu and Show All)
+- **View**: list shared knowledge ids from `registry.yaml > knowledge.shared`, 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.
+
+## Edge Cases & Errors
+
+| Case | Handling |
+|------|----------|
+| `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) |
+| Concurrent edit detected (mtime changed during preview->write) | Abort write, surface a message, ask user to re-run |
+| `set knowledge.shared <list>` 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 |