@uoyo/mvtt 2.0.0-beta.1 → 2.0.0-beta.3

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

@@ -1,63 +1,70 @@
-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
+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 <= 12,000 -> Report as \"Healthy\""
+        - rule: "Total tokens 12,001-25,000 -> Report as \"Borderline\", suggest optimizations"
+        - rule: "Total tokens > 25,000 -> Report as \"Oversized\", 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: inline
+    content: |
+      ### Step 4: 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
+      conditional_suggestions:
+        conditions:
+          - condition: "context oversized or borderline"
+            primary: mvt-cleanup
+            primary_desc: "Archive old artifacts to reduce context"
+            alternatives:
+              - skill: mvt-manage-context
+                desc: "Move per-skill knowledge to reduce shared load"
+          - condition: "context healthy"
+            primary: mvt-status
+            primary_desc: "Check overall project status"

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

@@ -3,33 +3,42 @@
 ### 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
+### Step 2: Pre-Archive Sync Check
+
+For each `changes[]` entry with `status: done`:
+1. Compare `session.last_synced_at` with the change's `updated_at`.
+2. If `last_synced_at` is empty OR `last_synced_at` < `updated_at`, mark the change as **⚠️ unsynced**.
+3. Collect all unsynced change-ids into a warning list for display in Step 6.
+
+This check ensures `/mvt-sync-context` has processed a change's knowledge before cleanup archives it. Once archived, the original artifact files (`analysis.md`, `design.md`, `implementation.md`) are no longer accessible to sync-context.
+
+### Step 3: 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.
+  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).
   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).
+     - `in-recent-changes` if it appears in `session.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
+### Step 4: 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.
+- **How**: run the rules table 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/` |
+  | `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}/` |
   | 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) |
+  | `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) |
   | 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
+### Step 5: Present Cleanup Plan
 - Render the plan as a table:
 
   | Item | Category | Current Size | Action | Result |
@@ -40,41 +49,58 @@
 - 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
+### Step 6: 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.
+  - `archive` action (moves entire change-id directory into `artifacts/_archived/`).
+- If the Step 2 warning list is non-empty, prepend it to the confirmation prompt:
+  > ⚠️ The following changes have NOT been synced by `/mvt-sync-context`. Archiving them will permanently lose their knowledge for aggregation:
+  > - {change-id}: {title}
+  > Options: `y` = archive anyway, `n` = cancel, `sync-first` = abort and run `/mvt-sync-context` first, `show-details` = per-file breakdown.
+- If no unsynced warnings, use the standard prompt: `Apply cleanup plan? (y / n / show-details)`. `show-details` prints the per-file actions, then re-asks.
+- User chooses `sync-first` → stop cleanup, print "Run `/mvt-sync-context` first, then re-run `/mvt-cleanup`." and exit.
 - Do NOT silently delete. Do NOT skip confirmation when `--dry-run` is absent.
 
-### Step 6: Execute the Plan
+### Step 7: 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.
+  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. Write `summary.md` into the change-id directory, then move the **entire** `artifacts/{id}/` directory to `artifacts/_archived/{id}/` (summary.md travels with it).
+  2. **Archive action** (no summarize): move the **entire** `artifacts/{id}/` directory to `artifacts/_archived/{id}/`. No internal path restructuring needed.
   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).
+  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).
 
-### Step 7: Report Result
-- Print the actually-applied actions (may differ from the plan if Step 6 stopped early).
+### Step 8: Report Result
+- Print the actually-applied actions (may differ from the plan if Step 7 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.
+### Step 9: Session Update Parameter Selection
+
+Based on the actual cleanup actions performed, choose the appropriate session-update parameter combination:
+
+| 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`) |
+| `--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).
+
+### Step 10: State Update
+Apply the State Update rules defined in the **State Update** section below.
 
 ## 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 |
+| `--dry-run` set | Stop after Step 5; 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 |
+| User aborts at Step 6 confirmation | Report "no changes applied" |
+| `artifacts/_archived/{id}/` already exists from a prior run | Preserve existing content; merge or skip with a note — do not overwrite |
 | 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) |
+| `session.yaml.bak` present from a previous failed run | Overwrite during Step 7 collapse (only the most recent backup is useful) |

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

@@ -63,23 +63,28 @@ sections:
           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
+    params:
+      current_skill: mvt-cleanup
+      truncate_history: true
+      close_change: true
 
   - type: shared
     source: sections/footer-next-steps.md
     params:
       current_skill: mvt-cleanup
+      conditional_suggestions:
+        conditions:
+          - condition: "cleanup freed significant tokens"
+            primary: mvt-check-context
+            primary_desc: "Validate post-cleanup context health"
+          - condition: "active change still in progress"
+            primary: mvt-resume
+            primary_desc: "Resume work on the active change"
+          - condition: "no active changes remain"
+            primary: mvt-analyze
+            primary_desc: "Start a new feature"

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

@@ -60,6 +60,7 @@
   | 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 |
+  | 6 | `preferences.history_limits.*` | Show each limit with current value; accept new int or Enter to keep |
 
 - 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.
@@ -73,8 +74,6 @@
 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.

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

@@ -1,96 +1,103 @@
-name: mvt-config
-output: .claude/skills/mvt-config/SKILL.md
-
-frontmatter:
-  name: mvt-config
-  description: "Manage MVTT framework configuration interactively. This skill should be used when user wants to change language, output format, or other framework settings."
-
-sections:
-  - type: inline
-    content: |
-      # MVT Config
-
-      ## Purpose
-
-      Manage MVTT framework configuration interactively. Provide guided setup, direct key-value setting, and a setup wizard for common configurations.
-
-  - type: shared
-    source: sections/role-header.md
-    params:
-      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"
-      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-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 |
-
-  - type: shared
-    source: sections/activation-load-context.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/output-language-constraint.md
-
-  - type: inline
-    content: |
-      ### Step 3: Pre-flight Checks
-      - No blocking checks required (config is always accessible)
-
-      ## Configuration Keys
-
-      ### User Preferences
-
-      | Key | Type | Default | Description |
-      |-----|------|---------|-------------|
-      | `preferences.interaction_language` | enum | `en-US` | Language for interactive output: chat replies, prompts, tables (en-US, zh-CN) |
-      | `preferences.document_output_language` | enum | `en-US` | Language for persisted documents: artifacts, project-context.md (falls back to interaction_language) |
-      | `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) |
-
-      ### Knowledge Settings
-
-      | Key | Type | Default | Description |
-      |-----|------|---------|-------------|
-      | `knowledge.shared` | list | `[core, project-context]` | Shared knowledge entries in registry.yaml, loaded by all skills |
-
-  - 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-config
+name: mvt-config
+output: .claude/skills/mvt-config/SKILL.md
+
+frontmatter:
+  name: mvt-config
+  description: "Manage MVTT framework configuration interactively. This skill should be used when user wants to change language, output format, or other framework settings."
+
+sections:
+  - type: inline
+    content: |
+      # MVT Config
+
+      ## Purpose
+
+      Manage MVTT framework configuration interactively. Provide guided setup, direct key-value setting, and a setup wizard for common configurations.
+
+  - type: shared
+    source: sections/role-header.md
+    params:
+      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"
+      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-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 |
+
+  - type: shared
+    source: sections/activation-load-context.md
+    params:
+      extended_context:
+        - ".ai-agents/config.yaml -- Current configuration (this skill's primary target)"
+
+  - type: shared
+    source: sections/activation-load-config.md
+
+  - type: inline
+    content: |
+      ### Step 4: Pre-flight Checks
+      - No blocking checks required (config is always accessible)
+
+      ## Configuration Keys
+
+      ### User Preferences
+
+      | Key | Type | Default | Description |
+      |-----|------|---------|-------------|
+      | `preferences.interaction_language` | enum | `en-US` | Language for interactive output: chat replies, prompts, tables (en-US, zh-CN) |
+      | `preferences.document_output_language` | enum | `en-US` | Language for persisted documents: artifacts, project-context.md (falls back to interaction_language) |
+      | `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) |
+
+      ### Knowledge Settings
+
+      | Key | Type | Default | Description |
+      |-----|------|---------|-------------|
+      | `knowledge.shared` | list | `[core, project-context]` | Shared knowledge entries in registry.yaml, loaded by all skills |
+
+  - 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-config
+      conditional_suggestions:
+        conditions:
+          - condition: "configuration updated"
+            primary: mvt-status
+            primary_desc: "Check project status with new settings"
+          - condition: "language changed"
+            primary: mvt-help
+            primary_desc: "Verify output in the new language"