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

package/sources/sections/session-update.md

@@ -1,47 +1,115 @@
-{{?read_only}}
-## State Update
-
-This skill is read-only and does NOT modify `.ai-agents/workspace/session.yaml`. No state mutation, no `skill_history` append, no `recent_actions` append.
-{{/read_only}}
-{{^read_only}}
-## State Update (Required)
-
-After execution, update `.ai-agents/workspace/session.yaml` with the following fields.
-
-### Mandatory (every skill must set)
-
-- `session.last_command`: Set to the current skill command (e.g., `"/mvt-analyze"`)
-- `skill_history`: Append entry:
-  ```yaml
-  - command: "/{skill-name}"
-    completed_at: "{current timestamp ISO 8601}"
-    summary: "{one-line summary of what was accomplished}"
-    change_id: "{active_change.id if set, otherwise empty string}"
-  ```
-  Keep max 10 entries. If exceeds, drop the oldest. The `change_id` field enables `/mvt-resume` to filter history per change when multiple changes are in flight.
-- `recent_actions`: Append one-line summary with format:
-  `[{YYYY-MM-DD HH:MM}] /{command}: {one-line summary}`
-  Keep max 5 entries. If exceeds, drop the oldest.
-{{#update_active_change}}
-
-### Conditional (set only when applicable)
-
-- `active_change.id`: Set when this skill creates a new change
-- `active_change.title`: Set when this skill creates a new change
-- `active_change.created_at`: Set when this skill creates a new change
-{{/update_active_change}}
-{{#update_initialized_at}}
-
-### Conditional (set only when applicable)
-
-- `session.initialized_at`: Set to current timestamp when this skill initializes the project
-{{/update_initialized_at}}
-
-### Forbidden
-
-- Do NOT update fields not listed above
-- Do NOT overwrite `active_change` unless this skill creates a new change
-- Do NOT modify `skill_history` entries other than appending a new one
-- Do NOT modify `recent_changes` -- it is owned by `/mvt-plan-dev` and `/mvt-update-plan`
-- Do NOT modify `active_change.plan_path` or `active_change.has_plan` -- these are owned by `/mvt-plan-dev`
-{{/read_only}}
+{{?read_only}}
+## State Update
+
+This skill is read-only and does NOT modify `.ai-agents/workspace/session.yaml`.
+{{/read_only}}
+{{^read_only}}
+## State Update
+
+After completing the skill's main task, run the session update script **exactly once** with the following arguments:
+
+```bash
+node .ai-agents/scripts/session-update.cjs --skill <skill_command_name> --summary "<concise one-line summary>"{{#update_active_change}} --new-change "<active_change.title>" --change-id <active_change.id>{{/update_active_change}}{{#set_plan_path}} --set-plan-path ".ai-agents/workspace/artifacts/{active_change.id}/plan.yaml"{{/set_plan_path}}{{#update_change}} --update-change{{/update_change}}{{#close_change}} --close-change{{/close_change}}{{#set_change_status}} --set-change-status <status>{{/set_change_status}}{{#no_change}} --no-change{{/no_change}}{{#set_synced}} --set-synced{{/set_synced}}{{#truncate_history}} --truncate-history <count>{{/truncate_history}}{{#update_initialized_at}} --set-initialized{{/update_initialized_at}}
+
+```
+
+If the script exits with code 0, the state update was applied successfully; there is no need to read or verify the session file.
+
+### Argument values
+
+| Argument | Value source | Example |
+|----------|-------------|---------|
+| `--skill` | The exact skill command name without the leading `/` | `{{current_skill}}` |
+| `--summary` | A concise one-line description of what this invocation accomplished, in the configured `interaction_language` | `"Identified auth requirements and created change chg-001"` |
+{{#update_active_change}}
+| `--new-change` | The title of the new change being created (same value written to `active_change.title`) | `"User authentication system"` |
+| `--change-id` | The unique identifier of the new change (same value written to `active_change.id`) | `chg-001` |
+{{/update_active_change}}
+{{#set_plan_path}}
+| `--set-plan-path` | The path to the newly created plan.yaml | `".ai-agents/workspace/artifacts/chg-001/plan.yaml"` |
+{{/set_plan_path}}
+{{#update_change}}
+| `--update-change` | Flag only, no value. Upserts the current `active_change` into `changes[]`. | — |
+{{/update_change}}
+{{#close_change}}
+| `--close-change` | Flag only, no value. Snapshots `active_change` into `changes[]` with `status: done`, then clears `active_change`. | — |
+{{/close_change}}
+{{#set_change_status}}
+| `--set-change-status` | The status to set on the `changes[]` entry matching `active_change.id`. Values: `active`, `done`, `abandoned`. | `done` |
+{{/set_change_status}}
+{{#no_change}}
+| `--no-change` | Flag only, no value. Forces `history[].change_id` to empty string (skips `active_change.id` fallback). | — |
+{{/no_change}}
+{{#set_synced}}
+| `--set-synced` | Flag only, no value. Sets `session.last_synced_at` to current time. | — |
+{{/set_synced}}
+{{#truncate_history}}
+| `--truncate-history` | Number of most recent history entries to keep (read from `config.yaml > preferences.history_limits.history`, default 20); older entries are discarded. | `20` |
+{{/truncate_history}}
+{{#update_initialized_at}}
+| `--set-initialized` | Flag only, no value. Set when this skill initializes the project for the first time. | — |
+{{/update_initialized_at}}
+
+{{#update_active_change}}
+### Parameter semantics
+
+| Argument | When to use | Effect on `session.yaml` |
+|----------|-------------|--------------------------|
+| `--new-change` + `--change-id` | Skill creates or identifies a new change | Sets `active_change.id`, `.title`, `.created_at`. Auto-snapshots old `active_change` into `changes[]` if non-empty. Requires both arguments together. |
+{{#set_plan_path}}
+| `--set-plan-path` | Skill creates a new `plan.yaml` for the active change | Sets `active_change.plan_path`. Must be used together with `--update-change`. |
+{{/set_plan_path}}
+{{#update_change}}
+| `--update-change` | Skill creates or modifies a plan (i.e., after `plan.yaml` is written/updated) | Upserts current `active_change` into `changes[]` (with `status: active`), sets `updated_at`, sorts ascending, truncates to configured limit. |
+{{/update_change}}
+{{#close_change}}
+| `--close-change` | All plan tasks are completed | Snapshots `active_change` into `changes[]` with `status: done`, then clears all `active_change` fields. |
+{{/close_change}}
+{{#set_change_status}}
+| `--set-change-status` | Explicitly mark a change as `done` or `abandoned` | Sets `status` on the `changes[]` entry whose `id` matches `active_change.id`. |
+{{/set_change_status}}
+{{#no_change}}
+| `--no-change` | Skill should not be associated with any change | Forces `history[].change_id` to empty string, skipping the `active_change.id` fallback. |
+{{/no_change}}
+{{#set_synced}}
+| `--set-synced` | Skill synchronizes context files | Sets `session.last_synced_at` to the current time. |
+{{/set_synced}}
+{{#truncate_history}}
+| `--truncate-history` | Maintenance: trim old history entries | Keeps the most recent N entries in `history[]`, discards older ones. |
+{{/truncate_history}}
+{{#update_initialized_at}}
+| `--set-initialized` | Skill initializes the project for the first time | Sets `session.initialized_at` (idempotent — only writes if empty). |
+{{/update_initialized_at}}
+{{/update_active_change}}
+{{^update_active_change}}
+### Parameter semantics
+
+| Argument | When to use | Effect on `session.yaml` |
+|----------|-------------|--------------------------|
+{{#update_change}}
+| `--update-change` | Skill modifies a plan (i.e., after `plan.yaml` is updated) | Upserts current `active_change` into `changes[]` (with `status: active`), sets `updated_at`, sorts ascending, truncates to configured limit. |
+{{/update_change}}
+{{#close_change}}
+| `--close-change` | All plan tasks are completed | Snapshots `active_change` into `changes[]` with `status: done`, then clears all `active_change` fields. |
+{{/close_change}}
+{{#set_change_status}}
+| `--set-change-status` | Explicitly mark a change as `done` or `abandoned` | Sets `status` on the `changes[]` entry whose `id` matches `active_change.id`. |
+{{/set_change_status}}
+{{#no_change}}
+| `--no-change` | Skill should not be associated with any change | Forces `history[].change_id` to empty string, skipping the `active_change.id` fallback. |
+{{/no_change}}
+{{#set_synced}}
+| `--set-synced` | Skill synchronizes context files | Sets `session.last_synced_at` to the current time. |
+{{/set_synced}}
+{{#truncate_history}}
+| `--truncate-history` | Maintenance: trim old history entries | Keeps the most recent N entries in `history[]`, discards older ones. |
+{{/truncate_history}}
+{{#update_initialized_at}}
+| `--set-initialized` | Skill initializes the project for the first time | Sets `session.initialized_at` (idempotent — only writes if empty). |
+{{/update_initialized_at}}
+{{/update_active_change}}
+
+### Failure handling
+
+If the script fails (non-zero exit), do NOT abort the skill's main task. Continue execution and add a brief note at the end of your response that the session could not be updated.
+{{/read_only}}

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

@@ -10,7 +10,7 @@
 - Extract business rules and constraints
 - Note assumptions made
 
-### Step 2.5: Assess Complexity (Quick Path Detection)
+### Step 3: Assess Complexity (Quick Path Detection)
 - **What**: evaluate whether this requirement qualifies as a simple change suitable for the quick development path via `/mvt-quick-dev`.
 - **How**: check each criterion in the table below. ALL criteria must pass for the quick path to be offered.
 
@@ -40,30 +40,30 @@
     - Scope: ✗ touches auth middleware, user model, login UI, OAuth callback handler, config (5+ files)
     - No new concepts: ✗ introduces external IdP and OAuth callback contract
     - No integration concerns: ✗ new external dependency (Google IdP)
-    → Proceed with standard analysis flow (Steps 3-5).
+    → Proceed with standard analysis flow (Steps 4-6).
 
 - **Branches**:
 
   | Condition | Action |
   |-----------|--------|
   | ALL criteria pass | Ask user: "This appears to be a simple change (1-3 files, no architectural impact). Use /mvt-quick-dev for faster execution? (y / n / show-criteria)" |
-  | ANY criterion fails | Proceed with standard analysis flow (Steps 3-5) |
+  | ANY criterion fails | Proceed with standard analysis flow (Steps 4-6) |
   | Ambiguous (2-3 criteria unclear) | Proceed with standard analysis; do NOT offer quick path |
 
 - **On user choice**:
   - "y" -- Do NOT write an analysis artifact. Summarize the requirement understanding in conversation and recommend `/mvt-quick-dev` directly. Set `active_change` if one doesn't exist, so `/mvt-quick-dev` can reference the current work context.
-  - "n" -- Continue with full analysis flow (Steps 3-5).
+  - "n" -- Continue with full analysis flow (Steps 4-6).
   - "show-criteria" -- Display the assessment results (pass/fail per criterion), then re-prompt with y/n.
 
-### Step 3: Detect Ambiguities
+### Step 4: Detect Ambiguities
 - Check for unclear requirements
 - Check for missing information
 - Check for conflicting requirements
 
-### Step 4: Generate Clarification Questions
+### Step 5: Generate Clarification Questions
 - If ambiguities found -> List each with specific question, prioritized by impact
 - If no ambiguities -> Skip this step
 
-### Step 5: Update Workspace
+### Step 6: Update Workspace
 1. Generate change-id: `{YYYYMMDD}-{slug}` format (e.g., `20260425-user-authentication`)
 2. Write artifact: `.ai-agents/workspace/artifacts/{change-id}/analysis.md`

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

@@ -71,6 +71,7 @@ sections:
   - type: shared
     source: sections/session-update.md
     params:
+      current_skill: mvt-analyze
       update_active_change: true
 
   - type: shared

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

@@ -1,96 +1,110 @@
-name: mvt-analyze-code
-output: .claude/skills/mvt-analyze-code/SKILL.md
-
-frontmatter:
-  name: mvt-analyze-code
-  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
-    content: |
-      # MVT Analyze Code
-
-      ## Purpose
-
-      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 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: "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"
-        - scope: "recommend technologies"
-          skill: "/mvt-design"
-        - 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:
-      checks:
-        - order: "1"
-          field: "session.initialized_at"
-          level: "WARN"
-          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
-      - Output is written to `.ai-agents/knowledge/project/_generated/project-context.md`
-
-  - type: file
-    source: ./business.md
-
-  - type: inline
-    content: |
-      ## 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`
-
-  - type: shared
-    source: sections/session-update.md
-
-  - type: shared
-    source: sections/footer-next-steps.md
-    params:
-      current_skill: mvt-analyze-code
+name: mvt-analyze-code
+output: .claude/skills/mvt-analyze-code/SKILL.md
+
+frontmatter:
+  name: mvt-analyze-code
+  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
+    content: |
+      # MVT Analyze Code
+
+      ## Purpose
+
+      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 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: "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"
+        - scope: "recommend technologies"
+          skill: "/mvt-design"
+        - 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:
+      checks:
+        - order: "1"
+          field: "session.initialized_at"
+          level: "WARN"
+          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: |
+      ## Operation Mode: Independent
+
+      This is an independent operation — no workflow prerequisites required.
+      - Does NOT create a change-id.
+      - Output is written to `.ai-agents/knowledge/project/_generated/project-context.md`.
+
+  - type: file
+    source: ./business.md
+
+  - type: inline
+    content: |
+      ## 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`
+
+  - type: shared
+    source: sections/session-update.md
+    params:
+      current_skill: mvt-analyze-code
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-analyze-code
+      conditional_suggestions:
+        conditions:
+          - condition: "project-context.md generated, no active change"
+            primary: mvt-analyze
+            primary_desc: "Analyze requirements for a new feature"
+          - condition: "project-context.md generated, active change exists"
+            primary: mvt-design
+            primary_desc: "Design with the updated project context"
+          - condition: "analysis revealed outdated knowledge"
+            primary: mvt-manage-context
+            primary_desc: "Update knowledge entries"

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

@@ -0,0 +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.
+
+## 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

@@ -0,0 +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: 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 |