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

package/sources/skills/mvt-bug-detect/business.md

@@ -1,101 +1,99 @@
-## Execution Flow
-
-### Step 1: Receive & Complete Input
-- Read the user-provided bug description (free text, possibly with stack trace, error message, or reproduction steps).
-- Assess input completeness using the table below:
-
-  | Input Situation | Action |
-  |-----------------|--------|
-  | No input provided | Present a structured template and wait. Template fields: **Error message**, **Reproduction steps**, **Expected behavior**, **Actual behavior**, **Environment** |
-  | Only error message | Ask: trigger conditions, runtime environment, recent changes |
-  | Only behavioral description (no error) | Ask: any error message available, whether it reproduces reliably, affected scope |
-  | Stack trace present | Sufficient — proceed to Step 2 |
-  | Reproduction steps + error message | Sufficient — proceed to Step 2 |
-
-- When asking for clarification, be specific. Do NOT ask "can you provide more details?" — instead, name the exact missing dimension (e.g., "What error message do you see when this happens?").
-
-### Step 2: Signal Extraction & Localization
-- Extract concrete signals from the bug description: error message text, stack trace frames, file paths, function/class names, input data.
-- For each signal, locate matching code (Grep / Glob).
-- Build a candidate file list with one-line justification per file.
-- Read recent git state (`git diff HEAD`, `git log -n 10 --oneline`) to surface recent changes that may correlate with the issue.
-
-### Step 3: Reproduction Verification
-
-| Condition | Action |
-|-----------|--------|
-| Reproduction steps provided → successfully reproduced | Mark as `Verified`, capture observed vs expected behavior |
-| Reproduction steps provided → cannot reproduce | Mark as `Unverified`, continue with static analysis only |
-| No reproduction steps, but signals are concrete (stack trace + paths) | Continue with static analysis, mark as `Static-only` |
-| No reproduction steps, signals are vague | STOP — ask user for: minimal reproduction, exact error, environment, last-known-good version |
-
-### Step 4: Root Cause Analysis
-- Generate 1-5 candidate root cause hypotheses based on the dominant signal:
-
-  | Dominant Signal | Hypothesis Sources |
-  |-----------------|--------------------|
-  | Stack trace | Top frame in user code, recently changed code in any frame, null/undefined origin, type mismatch at boundary |
-  | Error message | Exact-string search in repo, typed exception class hierarchy, library docs for that error |
-  | Recent git diff | Files changed in last N commits intersecting with localized files, commit messages mentioning related modules |
-  | Behavioral description (no error) | Module boundary mismatches, off-by-one / null-handling, async/race, state leakage, configuration drift |
-
-- Each hypothesis must be written as: `<claim> -- evidence: <pointer> -- check: <how to verify>`.
-- Verify hypotheses from cheapest check to most expensive. Eliminate hypotheses that fail their checks.
-- If ALL hypotheses are eliminated — STOP, surface findings, request more info from user. Do NOT fabricate new hypotheses silently.
-
-### Step 5: Impact Assessment & Classification
-
-**Bug Confirmation Status:**
-
-| Status | Meaning |
-|--------|---------|
-| Confirmed | Root cause verified, bug definitely exists |
-| Likely | Evidence is strong but cannot fully rule out other possibilities |
-| NotABug | Actual behavior matches expected behavior / business rules — not a bug |
-| Inconclusive | Insufficient evidence, requires human judgment |
-
-**Severity:**
-
-| Level | Definition |
-|-------|------------|
-| Critical | Data loss, security vulnerability, core functionality broken |
-| High | Major feature broken but temporary workaround exists |
-| Medium | Minor feature broken or usability issue |
-| Low | Edge case issue, no significant impact on main flow |
-
-**Impact Scope:**
-- List affected modules/files with one-line description each.
-- List affected user scenarios / business flows.
-- Search for similar patterns elsewhere in the codebase (same root cause may exist in other locations).
-
-### Step 6: Present Diagnosis
-- Output the diagnosis in conversation using this format:
-
-  ```
-  Bug Detection Result
-  ─────────────────────
-  Status:      <Confirmed | Likely | NotABug | Inconclusive>
-  Severity:    <Critical | High | Medium | Low>
-  Root Cause:  <one paragraph>
-  Confidence:  <reasoning for the status judgment>
-  Impact:      <affected modules and scenarios>
-  Affected:    <file list with line ranges>
-  Similar:     <other locations that may have the same root cause>
-  ─────────────────────
-  ```
-
-- For `NotABug`: explain why the current behavior is expected, and suggest `/mvt-analyze` if the requirement itself needs revision.
-- For `Inconclusive`: summarize what was found and what remains unknown, so the user or `/mvt-fix` can act with full awareness.
-
-### Step 7: (session update handled by shared section)
-
-## Edge Cases & Errors
-
-| Case | Handling |
-|------|----------|
-| Bug is intermittent / racy | Mark reproduction as "flaky", state confidence level explicitly, suggest adding instrumentation rather than speculative analysis |
-| Root cause is in a third-party dependency | Document the upstream issue, note that local workaround would be the only fix option |
-| Bug description describes expected behavior (NotABug) | Explain clearly with evidence from code/business rules, do NOT proceed to suggest fixes |
-| Multiple independent bugs described in one input | Analyze each separately, present multiple diagnosis blocks |
-| User provides a URL or external reference | Note it but do NOT fetch external resources; work only with local code and the description text |
-| `active_change` is missing | Run without change context (shortcut mode); omit change-id references in output |
+## Execution Flow
+
+### Step 1: Receive & Complete Input
+- Read the user-provided bug description (free text, possibly with stack trace, error message, or reproduction steps).
+- Assess input completeness using the table below:
+
+  | Input Situation | Action |
+  |-----------------|--------|
+  | No input provided | Present a structured template and wait. Template fields: **Error message**, **Reproduction steps**, **Expected behavior**, **Actual behavior**, **Environment** |
+  | Only error message | Ask: trigger conditions, runtime environment, recent changes |
+  | Only behavioral description (no error) | Ask: any error message available, whether it reproduces reliably, affected scope |
+  | Stack trace present | Sufficient — proceed to Step 2 |
+  | Reproduction steps + error message | Sufficient — proceed to Step 2 |
+
+- When asking for clarification, be specific. Do NOT ask "can you provide more details?" — instead, name the exact missing dimension (e.g., "What error message do you see when this happens?").
+
+### Step 2: Signal Extraction & Localization
+- Extract concrete signals from the bug description: error message text, stack trace frames, file paths, function/class names, input data.
+- For each signal, locate matching code (Grep / Glob).
+- Build a candidate file list with one-line justification per file.
+- Read recent git state (`git diff HEAD`, `git log -n 10 --oneline`) to surface recent changes that may correlate with the issue.
+
+### Step 3: Reproduction Verification
+
+| Condition | Action |
+|-----------|--------|
+| Reproduction steps provided → successfully reproduced | Mark as `Verified`, capture observed vs expected behavior |
+| Reproduction steps provided → cannot reproduce | Mark as `Unverified`, continue with static analysis only |
+| No reproduction steps, but signals are concrete (stack trace + paths) | Continue with static analysis, mark as `Static-only` |
+| No reproduction steps, signals are vague | STOP — ask user for: minimal reproduction, exact error, environment, last-known-good version |
+
+### Step 4: Root Cause Analysis
+- Generate 1-5 candidate root cause hypotheses based on the dominant signal:
+
+  | Dominant Signal | Hypothesis Sources |
+  |-----------------|--------------------|
+  | Stack trace | Top frame in user code, recently changed code in any frame, null/undefined origin, type mismatch at boundary |
+  | Error message | Exact-string search in repo, typed exception class hierarchy, library docs for that error |
+  | Recent git diff | Files changed in last N commits intersecting with localized files, commit messages mentioning related modules |
+  | Behavioral description (no error) | Module boundary mismatches, off-by-one / null-handling, async/race, state leakage, configuration drift |
+
+- Each hypothesis must be written as: `<claim> -- evidence: <pointer> -- check: <how to verify>`.
+- Verify hypotheses from cheapest check to most expensive. Eliminate hypotheses that fail their checks.
+- If ALL hypotheses are eliminated — STOP, surface findings, request more info from user. Do NOT fabricate new hypotheses silently.
+
+### Step 5: Impact Assessment & Classification
+
+**Bug Confirmation Status:**
+
+| Status | Meaning |
+|--------|---------|
+| Confirmed | Root cause verified, bug definitely exists |
+| Likely | Evidence is strong but cannot fully rule out other possibilities |
+| NotABug | Actual behavior matches expected behavior / business rules — not a bug |
+| Inconclusive | Insufficient evidence, requires human judgment |
+
+**Severity:**
+
+| Level | Definition |
+|-------|------------|
+| Critical | Data loss, security vulnerability, core functionality broken |
+| High | Major feature broken but temporary workaround exists |
+| Medium | Minor feature broken or usability issue |
+| Low | Edge case issue, no significant impact on main flow |
+
+**Impact Scope:**
+- List affected modules/files with one-line description each.
+- List affected user scenarios / business flows.
+- Search for similar patterns elsewhere in the codebase (same root cause may exist in other locations).
+
+### Step 6: Present Diagnosis
+- Output the diagnosis in conversation using this format:
+
+  ```
+  Bug Detection Result
+  ─────────────────────
+  Status:      <Confirmed | Likely | NotABug | Inconclusive>
+  Severity:    <Critical | High | Medium | Low>
+  Root Cause:  <one paragraph>
+  Confidence:  <reasoning for the status judgment>
+  Impact:      <affected modules and scenarios>
+  Affected:    <file list with line ranges>
+  Similar:     <other locations that may have the same root cause>
+  ─────────────────────
+  ```
+
+- For `NotABug`: explain why the current behavior is expected, and suggest `/mvt-analyze` if the requirement itself needs revision.
+- For `Inconclusive`: summarize what was found and what remains unknown, so the user or `/mvt-fix` can act with full awareness.
+
+## Edge Cases & Errors
+
+| Case | Handling |
+|------|----------|
+| Bug is intermittent / racy | Mark reproduction as "flaky", state confidence level explicitly, suggest adding instrumentation rather than speculative analysis |
+| Root cause is in a third-party dependency | Document the upstream issue, note that local workaround would be the only fix option |
+| Bug description describes expected behavior (NotABug) | Explain clearly with evidence from code/business rules, do NOT proceed to suggest fixes |
+| Multiple independent bugs described in one input | Analyze each separately, present multiple diagnosis blocks |
+| User provides a URL or external reference | Note it but do NOT fetch external resources; work only with local code and the description text |
+| `active_change` is missing | Run without change context (shortcut mode); omit change-id references in output |

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

@@ -1,84 +1,84 @@
-name: mvt-bug-detect
-output: .claude/skills/mvt-bug-detect/SKILL.md
-
-frontmatter:
-  name: mvt-bug-detect
-  description: "Analyze and detect bugs by investigating root cause, assessing severity and impact scope. Produces a structured diagnosis in conversation without applying fixes. This skill should be used when user suspects a bug, wants to understand a problem before fixing, or needs impact analysis."
-
-sections:
-  - type: inline
-    content: |
-      # MVT Bug Detect
-
-      ## Purpose
-
-      Investigate suspected bugs: confirm whether the bug exists, identify root cause, assess severity and impact scope, and produce a structured diagnosis. This skill does NOT apply fixes — it provides analysis to help the user understand the problem and decide on next steps.
-
-  - type: shared
-    source: sections/role-header.md
-    params:
-      role: Analyst
-      role_desc: "a Bug Investigation Specialist"
-      decision_rules:
-        - rule: "Bug description provided -> Analyze and investigate"
-        - rule: "Input too vague -> Prompt for specific details with structured template"
-        - rule: "No input -> Provide input template and wait"
-        - rule: "Root cause confirmed -> Assess impact and produce diagnosis"
-        - rule: "Multiple possible causes -> List hypotheses with evidence, verify each"
-        - rule: "Bug does not exist (expected behavior) -> Report clearly, suggest /mvt-analyze if requirement gap"
-        - rule: "Evidence insufficient -> Report findings, request more info, do NOT fabricate hypotheses"
-      boundaries:
-        - scope: "apply fixes"
-          skill: "/mvt-fix"
-        - scope: "design architecture"
-          skill: "/mvt-design"
-        - scope: "review code quality"
-          skill: "/mvt-review"
-
-  - type: shared
-    source: sections/activation-load-context.md
-    params:
-      extended_context:
-        - "Related source files (load based on bug description signals)"
-
-  - type: shared
-    source: sections/activation-load-config.md
-
-  - type: shared
-    source: sections/output-language-constraint.md
-
-  - type: inline
-    content: |
-      ### Shortcut Operation Rules
-      - Can execute at any time without checking workflow prerequisites
-      - Do NOT update `progress` (this is a shortcut operation, not a workflow phase)
-      - Do NOT write any artifact — diagnosis is presented in conversation only
-      - Do NOT modify any source code — this skill is read-only analysis
-
-  - type: file
-    source: ./business.md
-
-  - type: shared
-    source: sections/session-update.md
-
-  - type: shared
-    source: sections/footer-next-steps.md
-    params:
-      current_skill: mvt-bug-detect
-      conditional_suggestions:
-        conditions:
-          - condition: "bug confirmed, fix is straightforward"
-            primary: "mvt-fix"
-            primary_desc: "Fix this bug"
-          - condition: "bug confirmed, fix requires architecture change"
-            primary: "mvt-design"
-            primary_desc: "Design architectural solution first"
-            alternatives:
-              - skill: "mvt-fix"
-                desc: "Apply a minimal workaround"
-          - condition: "not a bug (expected behavior)"
-            primary: "mvt-analyze"
-            primary_desc: "Re-analyze the underlying requirement"
-          - condition: "inconclusive, needs deeper code understanding"
-            primary: "mvt-analyze-code"
-            primary_desc: "Deep-dive into the codebase"
+name: mvt-bug-detect
+output: .claude/skills/mvt-bug-detect/SKILL.md
+
+frontmatter:
+  name: mvt-bug-detect
+  description: "Analyze and detect bugs by investigating root cause, assessing severity and impact scope. Produces a structured diagnosis in conversation without applying fixes. This skill should be used when user suspects a bug, wants to understand a problem before fixing, or needs impact analysis."
+
+sections:
+  - type: inline
+    content: |
+      # MVT Bug Detect
+
+      ## Purpose
+
+      Investigate suspected bugs: confirm whether the bug exists, identify root cause, assess severity and impact scope, and produce a structured diagnosis. This skill does NOT apply fixes — it provides analysis to help the user understand the problem and decide on next steps.
+
+  - type: shared
+    source: sections/role-header.md
+    params:
+      role: Analyst
+      role_desc: "a Bug Investigation Specialist"
+      decision_rules:
+        - rule: "Bug description provided -> Analyze and investigate"
+        - rule: "Input too vague -> Prompt for specific details with structured template"
+        - rule: "No input -> Provide input template and wait"
+        - rule: "Root cause confirmed -> Assess impact and produce diagnosis"
+        - rule: "Multiple possible causes -> List hypotheses with evidence, verify each"
+        - rule: "Bug does not exist (expected behavior) -> Report clearly, suggest /mvt-analyze if requirement gap"
+        - rule: "Evidence insufficient -> Report findings, request more info, do NOT fabricate hypotheses"
+      boundaries:
+        - scope: "apply fixes"
+          skill: "/mvt-fix"
+        - scope: "design architecture"
+          skill: "/mvt-design"
+        - scope: "review code quality"
+          skill: "/mvt-review"
+
+  - type: shared
+    source: sections/activation-load-context.md
+    params:
+      extended_context:
+        - "Related source files (load based on bug description signals)"
+
+  - type: shared
+    source: sections/activation-load-config.md
+
+  - type: inline
+    content: |
+      ## Operation Mode: Shortcut
+
+      This skill operates as a shortcut — it can execute at any time without checking workflow prerequisites.
+      - Do NOT update `active_change` fields (this is a shortcut operation, not a workflow phase).
+      - Do NOT write any artifact — diagnosis is presented in conversation only.
+      - Do NOT modify any source code — this skill is read-only analysis.
+
+  - type: file
+    source: ./business.md
+
+  - type: shared
+    source: sections/session-update.md
+    params:
+      current_skill: mvt-bug-detect
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-bug-detect
+      conditional_suggestions:
+        conditions:
+          - condition: "bug confirmed, fix is straightforward"
+            primary: "mvt-fix"
+            primary_desc: "Fix this bug"
+          - condition: "bug confirmed, fix requires architecture change"
+            primary: "mvt-design"
+            primary_desc: "Design architectural solution first"
+            alternatives:
+              - skill: "mvt-fix"
+                desc: "Apply a minimal workaround"
+          - condition: "not a bug (expected behavior)"
+            primary: "mvt-analyze"
+            primary_desc: "Re-analyze the underlying requirement"
+          - condition: "inconclusive, needs deeper code understanding"
+            primary: "mvt-analyze-code"
+            primary_desc: "Deep-dive into the codebase"

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

@@ -13,7 +13,7 @@ This skill measures only files the **user** can reduce or relocate. Framework-fi
 - 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.
+- Artifacts: all files under `.ai-agents/workspace/artifacts/` recursively. **Exclude the `_archived/` subdirectory** — it contains completed changes archived by `/mvt-cleanup` and should not count toward the active workspace token budget.
 
 **Out of scope (do NOT scan):**
 - `.claude/skills/mvt-*/SKILL.md` -- framework-shipped, not user-editable.
@@ -51,7 +51,7 @@ This skill measures only files the **user** can reduce or relocate. Framework-fi
   |---------|------------------|-----------------|
   | `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` |
+  | Total artifacts tokens > artifacts threshold OR > 3 completed changes still in `artifacts/` (excluding `_archived/`) | "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` |
@@ -74,8 +74,6 @@ This skill measures only files the **user** can reduce or relocate. Framework-fi
   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 |
@@ -83,7 +81,7 @@ This skill measures only files the **user** can reduce or relocate. Framework-fi
 | `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") |
+| Workspace exceeds the artifacts threshold AND the user just ran `/mvt-cleanup` (within last hour per `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

@@ -20,10 +20,9 @@ sections:
       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"
+        - 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)"
@@ -41,12 +40,9 @@ 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
+      ### Step 4: Pre-flight Checks
       - No blocking checks required.
 
   - type: file
@@ -61,3 +57,14 @@ sections:
     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"