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

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

@@ -1,35 +1,82 @@
-## Execution Flow
-
-### Step 1: Scan Codebase
-- Scan source directories (src/, lib/, app/, etc.)
-- Identify entry points
-- Map module/directory structure
-
-### Step 2: Extract Entities
-- Find domain entities and models
-- Identify value objects
-- Map relationships between entities
-
-### Step 3: Extract Services
-- Find service classes and modules
-- Identify API endpoints
-- Map dependency graph between services
-
-### Step 4: Analyze Architecture
-- Detect architecture pattern (DDD, Clean Architecture, MVC, etc.)
-- Assess confidence level
-- Identify layer boundaries
-
-### Step 5: Infer Requirements
-- Generate feature list from code functionality
-- Identify business rules from logic
-- Document inferred requirements with confidence levels
-
-### Step 6: Update Workspace
-1. Update `.ai-agents/workspace/project-context.yaml`:
-   - Write detected architecture to `architecture` section
-   - Write discovered modules, entities, services
-2. Write artifact: `.ai-agents/workspace/artifacts/code-analysis/{timestamp}-analysis.md`
-3. Update `.ai-agents/workspace/session.yaml`:
-   - Set `session.last_command: "/mvt-analyze-code"`
-   - Append one-line summary to `recent_actions` (keep max 3)
+## Execution Flow
+
+### Step 1: Determine Analysis Target
+
+Identify which project(s) to analyze:
+
+| Variant | Target |
+|---------|--------|
+| `/mvt-analyze-code` | Analyze the first project in `project-context.yaml` (or the only one) |
+| `/mvt-analyze-code --all` | Analyze all projects listed in `project-context.yaml` |
+| `/mvt-analyze-code {name}` | Analyze the project matching the given name |
+
+For each target project:
+1. Read its `path` from `project-context.yaml`
+2. Use `path` as the source directory for analysis
+
+### Step 2: Load Template
+
+Determine the output template for project-context.md:
+
+1. Check `.ai-agents/skills/_templates/custom/project-context.md` -- if exists, use it
+2. Otherwise, use `.ai-agents/skills/_templates/project-context.md` (default)
+3. Read the template to understand the required section structure
+4. The template defines section headings only -- generate content freely for each section based on code analysis
+
+### Step 3: Scan Code Structure
+
+For the target project directory:
+
+- Map directory structure (one level below source root)
+- Identify entry points (main files, index files, router files)
+- Detect module boundaries (top-level directories under source root)
+
+### Step 4: Extract Modules and Entities
+
+- Identify top-level modules and their responsibilities
+- For each module, determine: path, responsibility, dependencies on other modules
+- Identify domain entities (models, schemas, types, interfaces)
+- Classify entities by type: domain model, value object, DTO, configuration
+
+### Step 5: Extract Core Terms
+
+Scan code for domain-specific terminology:
+
+- Class and interface names that represent domain concepts
+- Abbreviations and their expansions
+- Domain jargon used in comments and docstrings
+- Present as a glossary table: | Term | Meaning |
+
+### Step 6: Extract Business Rules
+
+Identify key business logic and constraints:
+
+- Validation rules (assertions, guards, precondition checks)
+- Computation rules (formulas, algorithms, calculation logic)
+- State transition rules (workflow steps, status changes)
+- Constraint rules (limits, quotas, access restrictions)
+
+### Step 7: Extract API Overview
+
+Identify public interfaces:
+
+- HTTP endpoints (routes, handlers) with method and path
+- Public methods of service classes
+- Event publishers and subscribers
+- CLI commands (if applicable)
+
+### Step 8: Generate Output
+
+1. For each analyzed project, generate a section in the template format:
+   - Use `# Project: {name}` as the top-level heading
+   - Fill each template section with analysis results
+   - If a section has no relevant content, include the heading with "(No relevant content detected)"
+
+2. Write the output to `.ai-agents/knowledge/project/_generated/project-context.md`:
+   - If analyzing a single project, write that project's section
+   - If analyzing multiple projects (`--all`), write all sections separated by `---`
+   - If the file already exists, merge with existing content:
+     - Replace sections for re-analyzed projects
+     - Preserve sections for projects NOT in this analysis run
+
+3. Do NOT update `project-context.yaml` -- it is the lean index, managed by `/mvt-init` and `/mvt-sync-context` only

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

@@ -3,7 +3,7 @@ output: .claude/skills/mvt-analyze-code/SKILL.md
 
 frontmatter:
   name: mvt-analyze-code
-  description: "Reverse-analyze existing code to generate context and infer requirements. Use when user wants to understand an existing codebase, generate documentation for legacy code, or onboard to a new project."
+  description: "Analyze existing code to generate project-context.md with terms, modules, layers, and business rules. This skill should be used when user wants to understand an existing codebase, generate documentation for legacy code, onboard to a new project, or extract requirements from source code."
 
 sections:
   - type: inline
@@ -12,18 +12,18 @@ sections:
 
       ## Purpose
 
-      Reverse-analyze existing code to generate context, discover architecture, and infer requirements. Unlike `/mvt-analyze` which works from requirements documents, this skill works from source code. This is an independent operation that does not create a change-id.
+      Analyze existing code to generate the project-context.md file, which describes the project's terms, modules, layer structure, business rules, and API overview. This is an independent operation that does not create a change-id.
 
   - type: shared
     source: sections/role-header.md
     params:
       role: Analyst
-      role_desc: "a Requirements Analysis Expert"
+      role_desc: "a Code Analysis Expert"
       decision_rules:
         - rule: "Source code exists -> Proceed with codebase scanning"
         - rule: "No source code found -> Warn user and suggest checking project path"
-        - rule: "Ambiguous architecture -> Present detected pattern with confidence level"
-        - rule: "Multiple frameworks detected -> List all and ask user to confirm primary"
+        - rule: "Multiple frameworks detected -> List all and prompt for primary confirmation"
+        - rule: "Custom template exists -> Use it instead of default template"
       boundaries:
         - scope: "make architecture decisions"
           skill: "/mvt-design"
@@ -32,15 +32,30 @@ sections:
         - scope: "write implementation code"
           skill: "/mvt-implement"
 
+  - type: inline
+    content: |
+      ## Variants
+
+      | Variant | Description |
+      |---------|-------------|
+      | `/mvt-analyze-code` | Analyze the first (or only) project |
+      | `/mvt-analyze-code --all` | Analyze all projects in the workspace |
+      | `/mvt-analyze-code {name}` | Analyze a specific project by name |
+
   - type: shared
     source: sections/activation-load-context.md
     params:
       extended_context:
         - "Scan project source directories for analysis"
+        - ".ai-agents/skills/_templates/project-context.md -- Default template for output structure"
+        - ".ai-agents/skills/_templates/custom/project-context.md -- Custom template (if exists)"
 
   - type: shared
     source: sections/activation-load-config.md
 
+  - type: shared
+    source: sections/output-language-constraint.md
+
   - type: shared
     source: sections/activation-preflight.md
     params:
@@ -48,41 +63,34 @@ sections:
         - 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: "No projects registered. Run `/mvt-init` first."
 
   - type: inline
     content: |
       ### Independent Operation Rules
       - This is an independent operation -- no workflow prerequisites required
       - Does NOT create a change-id
-      - Artifacts stored under `.ai-agents/workspace/artifacts/code-analysis/` instead of a change-id directory
-
-      ### Step 4: Execute
-      Proceed to Execution Flow below.
+      - Output is written to `.ai-agents/knowledge/project/_generated/project-context.md`
 
   - type: file
     source: ./business.md
 
   - type: inline
     content: |
-      ## Output Format
-
-      Read and use the output template from: `.ai-agents/skills/_templates/analyze-code-output.md`
+      ## Artifact Structure
+      Read the document structure template from: `.ai-agents/skills/_templates/project-context.md`
+      If a custom version exists at `.ai-agents/skills/_templates/custom/project-context.md`, use the custom version instead.
+      The template defines section headings only. Generate content for each section based on code analysis results.
+      Write the artifact to: `.ai-agents/knowledge/project/_generated/project-context.md`
 
-      If a custom version exists at `.ai-agents/skills/_templates/custom/analyze-code-output.md`, use the custom version instead.
-
-      Fill the template placeholders with the analysis results.
-
-      Every response MUST end with a Suggested Next Steps section.
+  - type: shared
+    source: sections/session-update.md
 
   - type: shared
     source: sections/footer-next-steps.md
     params:
-      next_primary: mvt-analyze
-      next_primary_desc: "Add requirements on top of discovered structure"
-      next_alternatives:
-        - skill: mvt-design
-          when: "Design new features for existing architecture"
-      always_show:
-        - skill: mvt-status
-          desc: "Check current project state"
+      current_skill: mvt-analyze-code

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

@@ -1,42 +1,89 @@
-## Execution Flow
-
-### Step 1: Scan Context Files
-Scan all files that MVTT may load during operation:
-
-**Core files** (always loaded):
-- `.ai-agents/workspace/session.yaml`
-- `.ai-agents/workspace/project-context.yaml`
-- `.ai-agents/config.yaml`
-
-**Knowledge files** (loaded per config):
-- `.ai-agents/knowledge/core/`
-- `.ai-agents/knowledge/patterns/{active}/`
-- `.ai-agents/knowledge/principle/`
-- `.ai-agents/knowledge/project/`
-
-**Artifact files**:
-- `.ai-agents/workspace/artifacts/` (all subdirectories)
-
-**Skill files**:
-- `.claude/skills/mvt-*/SKILL.md` (all skill definitions)
-
-### Step 2: Estimate Token Consumption
-- Calculate approximate tokens for each file: `characters / 4`
-- Group by category:
-  - Core (session + context + config)
-  - Knowledge (knowledge/)
-  - Artifacts (artifacts/)
-  - Skills (skills/)
-- Sum totals per category and overall
-
-### Step 3: Assess and Recommend
-- Determine health status based on total tokens
-- Identify Top 5 largest files
-- Generate optimization recommendations:
-  - Oversized project-context.yaml -> Suggest trimming
-  - Too many old artifacts -> Suggest `/mvt-cleanup`
-  - Unused knowledge files -> Suggest removal or lazy_load
-  - Redundant information -> Suggest consolidation
-- Each recommendation should be specific and actionable
-
-### Step 4: Generate Report
+## Execution Flow
+
+### Step 1: Load Inputs
+- **Recommended**:
+  - `.ai-agents/knowledge/core/manifest.yaml` -- to filter `core/_framework/` (excluded) from `core/user/` (in-scope).
+- **Fallback**: missing `core/manifest.yaml` -> treat all `core/*` files as user-origin (over-counts; flag in report).
+
+### Step 2: Determine In-Scope Files
+This skill measures only files the **user** can reduce or relocate. Framework-fixed overhead is excluded.
+
+**In scope (user-actionable):**
+- Index: `.ai-agents/workspace/project-context.yaml`.
+- Semantic context: `.ai-agents/knowledge/project/_generated/project-context.md`.
+- Shared knowledge: every entry in `registry.yaml > knowledge.shared`. For the `core` entry, scan only files marked as user-origin per `core/manifest.yaml` (or whose path begins with `user/`); skip files under `core/_framework/`.
+- Per-skill knowledge: every entry in `registry.yaml > skills.*.knowledge`, grouped by skill.
+- Artifacts: all files under `.ai-agents/workspace/artifacts/` recursively.
+
+**Out of scope (do NOT scan):**
+- `.claude/skills/mvt-*/SKILL.md` -- framework-shipped, not user-editable.
+- `.ai-agents/knowledge/core/_framework/**` -- framework-shipped.
+- `.ai-agents/config.yaml`, `.ai-agents/workspace/session.yaml`, `.ai-agents/registry.yaml` -- small, required, and addressed via `/mvt-config` or `/mvt-manage-context`, not here.
+
+### Step 3: Estimate Token Consumption
+- **What**: produce a per-file tokens estimate and per-category subtotals.
+- **How**:
+  1. For each in-scope file: tokens ~= `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.
+  5. Identify the Top 5 largest single files across the whole in-scope set.
+
+### Step 4: Apply Thresholds and Health Status
+- **What**: assign each file/category a status of `healthy | borderline | oversized`.
+- **How**: read thresholds from `.ai-agents/config.yaml > preferences.context_thresholds.*` if present; otherwise use the defaults below.
+
+  | Subject | healthy | borderline | oversized |
+  |---------|---------|------------|-----------|
+  | Total in-scope tokens | <= 12000 | 12001-25000 | > 25000 |
+  | Single file tokens | <= 3000 | 3001-6000 | > 6000 |
+  | `project-context.md` tokens | <= 4000 | 4001-8000 | > 8000 |
+  | Shared Knowledge total tokens | <= 6000 | 6001-12000 | > 12000 |
+  | Single change-id artifacts directory tokens | <= 3000 | 3001-8000 | > 8000 |
+
+- Overall workspace status = the worst status across all subjects above.
+
+### Step 5: Generate Recommendations
+- **What**: produce a list of specific, actionable recommendations. Each entry is `(trigger, message, suggested skill)`.
+- **How**: walk the table; emit a recommendation for every row whose trigger fires.
+
+  | Trigger | Message template | Suggested skill |
+  |---------|------------------|-----------------|
+  | `project-context.md` is `oversized` | "project-context.md is {N} tokens. Regenerate with leaner sections." | `/mvt-analyze-code` |
+  | `project-context.md` is `borderline` AND last `/mvt-analyze-code` ran > 30 days ago | "project-context.md is {N} tokens and may be stale. Consider regenerating." | `/mvt-analyze-code` |
+  | Total artifacts tokens > artifacts threshold OR > 3 completed changes still in `artifacts/` | "Workspace has {N} tokens of historical artifacts. Archive completed changes." | `/mvt-cleanup` |
+  | A specific change-id directory is `oversized` | "artifacts/{id} alone is {N} tokens. Summarize this change." | `/mvt-cleanup` |
+  | Shared Knowledge total is `oversized` | "Shared knowledge totals {N} tokens (loaded by every skill). Move skill-specific entries to per-skill." | `/mvt-manage-context move` |
+  | 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 |
+
+- **Constraints on recommendations**:
+  - Never recommend changes to framework files (`_framework/`, `mvt-*/SKILL.md`).
+  - Never recommend deletion without an `/mvt-manage-context` or `/mvt-cleanup` command -- those skills own the actual mutation.
+  - If no triggers fire, return a single line: "Workspace context is healthy ({N} tokens total)."
+
+### Step 6: Generate Report
+- Render the report in this order:
+  1. **Summary** -- one line: total tokens + overall status.
+  2. **Per-Category Breakdown** -- table: `category | files | tokens | status`.
+  3. **Top 5 Largest Files** -- table: `path | tokens | category | status`.
+  4. **Per-Skill Knowledge Cost** -- table: `skill | tokens` (sorted desc); include shared knowledge as a separate row labeled `(shared, loaded every time)`.
+  5. **Recommendations** -- numbered list from Step 5; if empty, render the healthy line.
+  6. **Excluded Scope Note** -- one paragraph reminding the user that framework files (`_framework/`, `mvt-*/SKILL.md`, `config.yaml`, `session.yaml`, `registry.yaml`) were not measured here.
+- The report is conversation output; this skill does NOT write any artifact.
+
+### Step 7: (session update handled by shared section)
+
+## Edge Cases & Errors
+
+| Case | Handling |
+|------|----------|
+| `registry.yaml` references a knowledge id whose source path is empty / missing | Include in Step 5 recommendations; do NOT count missing files toward token totals |
+| `core/manifest.yaml` cannot be parsed | Treat the whole `core/` tree as in-scope (over-counts); add a note in the report |
+| Workspace has zero artifacts | Skip the artifacts category in Step 6; do not error |
+| Workspace exceeds the artifacts threshold AND the user just ran `/mvt-cleanup` (within last hour per `skill_history`) | Surface but downgrade to a one-line note ("recently cleaned -- remaining {N} tokens are likely active work") |
+| User passes a path argument | This skill ignores arguments; print a one-line note and run as normal (do not narrow scope to a single file -- that is `/mvt-status` territory) |
+| Token estimate disagrees with model's actual consumption | This is expected; the `chars/4` heuristic is an approximation. State this caveat in the Summary line |
+| Two skills declare the same knowledge id | Count the file once for storage but report it under both skills in the Per-Skill table; flag the duplication in Step 5 |

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

@@ -3,7 +3,7 @@ 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."
+  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
@@ -30,7 +30,7 @@ sections:
         - scope: "clean up artifacts"
           skill: "/mvt-cleanup"
         - scope: "modify context"
-          skill: "/mvt-add-context"
+          skill: "/mvt-manage-context"
 
   - type: shared
     source: sections/activation-load-context.md
@@ -41,34 +41,23 @@ sections:
   - 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.
 
-      ### 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/session-update.md
+    params:
+      read_only: true
 
   - 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"
+      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) |