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

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

@@ -1,88 +1,96 @@
-name: mvt-analyze-code
-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."
-
-sections:
-  - type: inline
-    content: |
-      # MVT Analyze Code
-
-      ## 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.
-
-  - type: shared
-    source: sections/role-header.md
-    params:
-      role: Analyst
-      role_desc: "a Requirements 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"
-      boundaries:
-        - scope: "make architecture decisions"
-          skill: "/mvt-design"
-        - scope: "recommend technologies"
-          skill: "/mvt-design"
-        - scope: "write implementation code"
-          skill: "/mvt-implement"
-
-  - type: shared
-    source: sections/activation-load-context.md
-    params:
-      extended_context:
-        - "Scan project source directories for analysis"
-
-  - type: shared
-    source: sections/activation-load-config.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.'
-
-  - 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.
-
-  - 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`
-
-      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/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"
+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

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

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

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: 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"

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 |