@uoyo/mvtt 2.0.0-beta.4 → 2.0.0-beta.6

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

@@ -89,6 +89,8 @@ For each project:
 - Name, path, type
 - Tech stack (language, framework, build tool, test framework)
 
+**Project naming constraint**: each project name must match `[a-zA-Z0-9][a-zA-Z0-9_-]*` (no leading underscore). Validate all detected names against this constraint; if a name violates it (e.g., auto-detected as `_internal`), prompt the user to provide a valid alternative before proceeding.
+
 Wait for user to confirm or adjust:
 - `yes` -- Accept all
 - Provide corrections -- User specifies which fields to change
@@ -112,6 +114,7 @@ For each target file, check if it already exists:
      - name: "{project_name}"
        path: "{relative_path}"
        type: "{project_type}"
+       source_paths: []
        tech_stack:
          primary_language: "{language}"
          secondary_languages: [{...}]
@@ -119,6 +122,7 @@ For each target file, check if it already exists:
          build_tool: "{build_tool}"
          test_framework: "{test_framework}"
    ```
+   `source_paths` is populated by `/mvt-analyze-code` based on analyzed code structure. On initial `/mvt-init`, leave as empty array.
    For multi-project repos, include one entry per detected project.
 
 #### 5.3 Post-write validation
@@ -126,34 +130,40 @@ For each target file, check if it already exists:
 After writing all files, validate:
 - `project-context.yaml` is valid YAML with `projects[]` containing at least one entry
 - Each project entry has required fields: `name`, `path`, `type`, `tech_stack.primary_language`
-- `session.yaml` is structurally intact and contains: `session` (with `initialized_at`, `last_synced_at`), `active_change` (with `plan_path`), `changes` (array), `history`
 
 If any validation fails → report the specific error and offer to retry or skip.
 
-### Step 6: Refresh Mode Handling (--refresh only)
+### Step 6: Refresh Mode Handling (Interactive)
+
+When `mvt-init` is executed and existing MVTT artifacts are detected:
+
+1. **Prompt user**: "Existing MVTT configuration found. Refresh to re-scan project structure? (y/n)"
+   - If `n` -> stop, no changes made.
+   - If `y` -> proceed with refresh.
+
+2. **Re-scan** project structure using Steps 1-3 above.
 
-When `--refresh` is specified:
+3. **Compare** new vs existing `projects[]`. If project changes detected (added/removed/renamed sub-projects):
+   - Show diff: "+N added / -N removed / ~N renamed"
+   - Confirm before writing.
 
-1. **Preserve** the following from existing files:
+4. **Preserve** the following from existing files:
    - `session.yaml` > `history`
    - `project-context.yaml` > any user-added custom fields (fields not in the standard schema)
    - `config.yaml` > `preferences` section
 
-2. **Update** only auto-detectable fields:
+5. **Update** only auto-detectable fields:
    - `tech_stack` (re-scan and update)
    - `type` (re-infer)
+   - `source_paths` (re-scan)
 
-3. **Diff and confirm**: Show a summary of what will change vs what will be preserved. Ask for confirmation before writing.
+6. **After writing** -> prompt: "Project structure updated. Recommend running `/mvt-analyze-code` to sync semantic context."
 
-4. **Old format migration**: If existing `project-context.yaml` uses old format (has top-level `project`, `requirements`, `architecture`, `environment` keys):
-   - Wrap `project.*` as `projects[0]` with `name="default"`, `path="."`
-   - Discard `requirements`, `architecture` sections -- suggest running `/mvt-analyze-code` to regenerate
-   - Discard `environment` section
-   - Discard any `pattern` related fields
+7. **Orphan knowledge entries**: After refresh, if any knowledge entries in `registry.yaml` reference a project name not in the updated `projects[]`, prompt: "N orphan knowledge entries found for project(s) not in projects list: {names}. Consider `/mvt-manage-context remove` to clean up."
 
 ### Step 7: Determine Project State (drives next-step recommendation)
 
-After Step 5 writes are committed, classify the project state to select the appropriate next_suggestions branch from registry.yaml:
+After Step 5 writes are committed, classify the project state to select the appropriate recommendation branch in the **Suggested Next Steps** section below:
 
 | Condition | Detection logic |
 |-----------|-----------------|
@@ -161,4 +171,4 @@ After Step 5 writes are committed, classify the project state to select the appr
 | `empty_project` | Step 1 found no source files AND no package manager file (truly empty or docs-only repo) -- the recommended next step is `/mvt-manage-context` to manually capture context |
 | `default` | Neither condition matched (rare -- fallback path) |
 
-Pass the resolved condition to the output template so the suggested next steps section renders the matching branch from `registry.yaml > skills.mvt-init.next_suggestions.conditional[]`.
+Use the resolved condition to render the matching branch in the **Suggested Next Steps** section (Conditional Recommendations).

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

@@ -43,8 +43,7 @@ sections:
 
       | Variant | Description |
       |---------|-------------|
-      | `/mvt-init` | Standard initialization (scan + detect + write index) |
-      | `/mvt-init --refresh` | Re-scan existing project -- preserve user state, update auto-detectable fields, show diff before writing |
+      | `/mvt-init` | Standard initialization or interactive refresh (scan + detect + write index; re-scan on existing project with user confirmation) |
 
   - type: shared
     source: sections/activation-load-context.md

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

@@ -19,6 +19,21 @@ For interactive menu, present the five options and wait for user choice, then en
 
 Switch to the matching section below.
 
+### Map-Aware Knowledge Structure
+
+The registry uses project-keyed knowledge maps. Every knowledge block (top-level `knowledge` and each `skills.<name>.knowledge`) is a map where keys are project names or the reserved `_all` key (all projects). All subcommands must operate on this map structure.
+
+**Two-question routing table (add subcommand)**:
+
+| Question 1: Scope | Question 2: Breadth | Registry key path |
+|--------------------|---------------------|-------------------|
+| global | all skills | `knowledge._all` |
+| project-specific | all skills | `knowledge.{projectName}` |
+| global | specific skill | `skills.{name}.knowledge._all` |
+| project-specific | specific skill | `skills.{name}.knowledge.{projectName}` |
+
+**`_all` promotion confirmation**: routing to `knowledge._all` or `skills.{name}.knowledge._all` means the entry will be loaded by every skill across every project (or every project for that skill). When the add flow routes to `_all`, prompt: "This knowledge will be loaded by ALL skills across ALL projects. Confirm? (y/n)" -- default to **n** for project-specific entries, default to **y** only when the user explicitly chose scope=global.
+
 ---
 
 ## Subcommand: add
@@ -36,24 +51,31 @@ Classify the content into one of:
 
 The skill should suggest a type based on content keywords; the user confirms or overrides.
 
-### 2.3 AI Routing -- Score every skill
+### 2.3 AI Routing -- Two-question routing + skill scoring
 
-1. Read `.ai-agents/registry.yaml` > `skills.*` -- collect every skill's `name` and `description`.
-2. For each skill, score relevance to the content on a 0-100 scale:
+1. **Question 1: Scope** -- Ask: "Is this knowledge global (applies to all projects) or project-specific?"
+   - `global` -> keys under `_all`
+   - `project-specific` -> ask which project (list from `project-context.yaml > projects[].name`); key under `{projectName}`
+2. **Question 2: Breadth** -- Ask: "Should this knowledge be loaded by all skills or a specific skill?"
+   - `all skills` -> top-level `knowledge` map
+   - `specific skill` -> AI-score each skill for relevance (see below)
+3. Read `.ai-agents/registry.yaml` > `skills.*` -- collect every skill's `name` and `description`.
+4. For each skill, score relevance to the content on a 0-100 scale:
    - 90-100: directly aligned (e.g., review rules + `mvt-review`)
    - 70-89: strongly relevant
    - 50-69: tangentially relevant
    - 0-49: weak match
-3. Read `.ai-agents/config.yaml` > `preferences.context_routing.relevance_threshold` (default 70 if missing).
-4. Display **all** skills sorted by score descending. Do not truncate -- the user sees the full list with scores.
+5. Read `.ai-agents/config.yaml` > `preferences.context_routing.relevance_threshold` (default 70 if missing).
+6. Display **all** skills sorted by score descending. Do not truncate -- the user sees the full list with scores.
    - Skills at or above threshold: pre-checked, shown with `[High]` / `[Med]` markers (or stars in emoji mode).
    - Skills below threshold: collapsed under an "expand" prompt; not pre-checked.
+7. Combine the two questions with the scoring to determine the registry key path per the routing table above.
 
 ### 2.4 Accept user input
 Accept any of:
 - `Enter` (empty input) -- confirm pre-checked selection
 - Comma-separated indices (e.g. `1,3,5`) -- custom skill selection
-- `s` -- promote to **shared** (write to `registry.yaml > knowledge.shared`)
+- `s` -- promote to **global** (write to `registry.yaml > knowledge._all`)
 - `c` -- promote to **core** (write to `.ai-agents/knowledge/core/user/{filename}` + append entry to `core/manifest.yaml` with `origin: user`)
 - `n` -- **none** (file-only; not auto-loaded)
 - `m` -- **manual** mode (display the full skill list including below-threshold for direct picking)
@@ -63,8 +85,8 @@ Accept any of:
 
 | User choice | File destination | Registry / manifest update |
 |------------|-----------------|----------------------------|
-| Per-skill (any subset) | `.ai-agents/knowledge/{type}/{filename}` (`type` = `principle` or `project`) | For each chosen skill: append entry to `registry.yaml > skills.{name}.knowledge[]` with `type: static`, `source: knowledge/{type}/`, `files: [{filename}]` |
-| `s` (shared) | `.ai-agents/knowledge/{type}/{filename}` | Append to `registry.yaml > knowledge.shared[]` with the same `type: static` shape |
+| Per-skill (any subset) | `.ai-agents/knowledge/{type}/{filename}` (`type` = `principle` or `project`) | For each chosen skill: append entry to `registry.yaml > skills.{name}.knowledge.{projectKey}[]` with `type: static`, `source: knowledge/{type}/`, `files: [{filename}]`. `projectKey` = `_all` if scope=global, or `{projectName}` if project-specific. |
+| `s` (shared / global + all skills) | `.ai-agents/knowledge/{type}/{filename}` | Append to `registry.yaml > knowledge._all[]` with the same `type: static` shape |
 | `c` (core) | `.ai-agents/knowledge/core/user/{filename}` | Append to `core/manifest.yaml > files[]` with `path: user/{filename}`, `origin: user`, `auto_load: true` |
 | `n` (none) | `.ai-agents/knowledge/{type}/{filename}` | No registry/manifest change |
 
@@ -93,8 +115,10 @@ Use the `add / move / rename` output format from the manifest. Show:
 Show the entry's file path, all binding references (shared / per-skill / core), and ask user to confirm.
 
 ### 3.3 Drop references
-- `registry.yaml > knowledge.shared[]` -- remove entries whose path matches
-- `registry.yaml > skills.*.knowledge[]` -- remove every per-skill entry whose path matches
+- `registry.yaml > knowledge._all[]` -- remove entries whose path matches
+- `registry.yaml > knowledge.{projectName}[]` -- traverse ALL project keys, remove entries whose path matches
+- `registry.yaml > skills.*.knowledge._all[]` -- remove every per-skill _all entry whose path matches
+- `registry.yaml > skills.*.knowledge.{projectName}[]` -- traverse ALL project keys for each skill, remove entries whose path matches
 - `core/manifest.yaml > files[]` -- if the file lives under `core/user/`, remove the matching entry
 
 ### 3.4 Delete file
@@ -115,7 +139,10 @@ Use the `remove` output format. Show every reference dropped.
 Display where the entry is currently bound (shared / per-skill / core / none).
 
 ### 4.3 Prompt for new binding
-Use the same UI as `add` step 2.4 (Enter / indices / `s` / `c` / `n`).
+Use the same two-question routing as `add` step 2.3 (Scope + Breadth -> registry key path). Support cross-key movement:
+- `_all` -> `{projectName}` (narrow from global to project-specific)
+- `{projectName}` -> `_all` (promote to global; apply `_all` promotion confirmation)
+- `{projectName1}` -> `{projectName2}` (move between projects)
 
 ### 4.4 Apply changes
 - Update registry / manifest references atomically:
@@ -151,14 +178,14 @@ Use the `add / move / rename` output format.
 ## Subcommand: list
 
 ### 6.1 Read sources
-- `.ai-agents/registry.yaml` > `knowledge.shared[]` and `skills.*.knowledge[]`
+- `.ai-agents/registry.yaml` > `knowledge._all[]`, `knowledge.{projectName}[]`, `skills.*.knowledge._all[]`, `skills.*.knowledge.{projectName}[]` -- traverse ALL project keys
 - `.ai-agents/knowledge/core/manifest.yaml` > `files[]`
 - Walk `.ai-agents/knowledge/{principle,project}/` for files not referenced anywhere (Unbound)
 
 ### 6.2 Group and render
-Use the `list` output format. Each row should answer: where is the file, and which skills load it?
+Use the `list` output format. Group by **project x skill** (3D table). Each row should answer: where is the file, which project(s) does it serve, and which skills load it?
 
-For Per-Skill rows, list every skill that binds to the file (a single file can be bound to multiple skills).
+Flag **orphan entries** -- entries under a project key not in `projects[].name` from `project-context.yaml`.
 
 ### 6.3 Health hints
 At the bottom of the list, optionally surface:

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

@@ -52,11 +52,6 @@ sections:
   - type: shared
     source: sections/output-format-constraint.md
 
-  - type: inline
-    content: |
-      ### Step 4: Pre-flight Checks
-      - No blocking checks required.
-
   - type: file
     source: ./business.md
 
@@ -92,7 +87,8 @@ sections:
       ### Removed entry: `{id}`
       - File: `.ai-agents/knowledge/{path}` (deleted)
       - References dropped from:
-        - `registry.yaml > knowledge.shared` (if applicable)
+        - `registry.yaml > knowledge._all` (if applicable)
+        - `registry.yaml > knowledge.{projectName}` (if applicable)
         - `registry.yaml > skills.{name}.knowledge` x N (if applicable)
         - `core/manifest.yaml > files[]` (if applicable)
       ```

package/sources/skills/mvt-plan-dev/business.md

@@ -15,7 +15,7 @@ If no analysis or design artifacts exist and the user provides no description, p
 If `active_change.plan_path is non-empty` AND `.ai-agents/workspace/artifacts/{active_change.id}/plan.yaml` already exists:
 
 - Read the existing plan.
-- Show a summary (task count, status counts, current_task).
+- Show a summary (task count, status counts, current_tasks).
 - Ask: "A plan already exists. Choose: (1) regenerate from scratch (existing tasks discarded), (2) cancel and use `/mvt-update-plan` to evolve it, (3) abort."
 - Only continue with generation on choice (1).
 
@@ -31,6 +31,7 @@ Decompose the change with the following constraints. These constraints are AI-fr
 | Explicit dependencies | If task B requires output from task A, list `A` in B's `depends_on`. Avoid hidden ordering. Tasks that can run in parallel should have no dependency between them. |
 | No cycles | Dependency graph must be a DAG. Validation will reject cycles. |
 | Skill hint | Set `skill_hint` to the skill best suited to execute the task (without `/` prefix): `mvt-implement`, `mvt-test`, `mvt-fix`, `mvt-design`, `mvt-review`, `mvt-refactor`, etc. |
+| Project attribution | Each task must have a `project` array listing which projects it belongs to. In a single-project workspace (`projects.length == 1`), set `project: ["default"]` (or the sole project's name). In a multi-project workspace, auto-infer from the task's file paths matching `projects[].path` and `projects[].source_paths`; if ambiguous, prompt the user. Cross-project tasks list multiple project names. |
 
 ### Step 4: Assemble plan.yaml
 
@@ -43,7 +44,8 @@ title: "Feature Name"
 created_at: "2026-05-31T11:30:00"
 updated_at: "2026-05-31T11:30:00"
 status: in_progress
-current_task: "t1-foundation-layer"
+current_tasks:
+  default: "t1-foundation-layer"
 
 tasks:
   - id: "t1-foundation-layer"
@@ -51,6 +53,8 @@ tasks:
     status: in_progress
     completed_at: null
     depends_on: []
+    project:
+      - default
     skill_hint: mvt-implement
     artifacts:
       files:
@@ -68,6 +72,8 @@ tasks:
     status: pending
     completed_at: null
     depends_on: ["t1-foundation-layer"]
+    project:
+      - default
     skill_hint: mvt-implement
     artifacts: null
     notes: >
@@ -87,7 +93,7 @@ tasks:
 - `created_at`: current ISO 8601 timestamp
 - `updated_at`: same as `created_at` initially
 - `status: in_progress`
-- `current_task`: the `id` of the first executable task (a task with `depends_on: []`), set to `in_progress`
+- `current_tasks`: a map of project name to task id. For single-project workspaces: `{ default: "<first_task_id>" }`. For multi-project: one key per project, each pointing to that project's first executable task.
 
 #### Task fields
 
@@ -98,6 +104,7 @@ For each task, populate:
 - **`status`**: first executable task → `in_progress`; all others → `pending`.
 - **`completed_at`**: `null` for all tasks on initial creation (set by `/mvt-update-plan` when marking `done`).
 - **`depends_on`**: array of task ids. Empty array `[]` means no dependencies.
+- **`project`**: array of project names this task belongs to. In single-project workspaces, use `["default"]` (or the sole project's name). Cross-project tasks list multiple names. Auto-infer from file paths matching `projects[].path` and `projects[].source_paths`; if ambiguous, prompt the user.
 - **`skill_hint`**: the skill name (without `/`) that will execute this task.
 - **`artifacts`**: structured object. On initial plan creation, set to `null` or pre-populate with planned target files if known:
   ```yaml
@@ -118,11 +125,12 @@ Before writing, validate the assembled YAML:
 
 1. **Unique IDs** — no two tasks share the same `id`
 2. **Valid references** — every `depends_on` entry references an existing task `id`
-3. **No cycles** — the dependency graph is a DAG
-4. **current_task validity** — references a task with status `pending` or `in_progress`
+3. **No cycles** — the dependency graph is a DAG (per-project subgraph when multi-project)
+4. **current_tasks validity** — each value references a task with status `pending` or `in_progress`
 5. **Acceptance required** — every task has at least one acceptance criterion
-6. **Single in_progress** — at most one task has status `in_progress`
+6. **Per-project in_progress** — at most one `in_progress` task per project (not globally)
 7. **completed_at consistency** — must be `null` for all non-done tasks
+8. **Project attribution** — every task has a `project` array with at least one valid project name
 
 If validation fails, revise the plan and re-validate (do NOT write a broken plan).
 
@@ -148,9 +156,9 @@ Render an inline summary (no external template). Structure:
 
 ### Task Breakdown
 
-| # | id | title | status | skill | depends_on |
-|---|----|----|--------|-------|------------|
-| 1 | {id} | {title} | {status} | {skill_hint} | {deps_or_"—"} |
+| # | id | title | status | skill | project | depends_on |
+|---|----|----|--------|-------|---------|------------|
+| 1 | {id} | {title} | {status} | {skill_hint} | {project_list} | {deps_or_"—"} |
 | ... |
 
 ```

package/sources/skills/mvt-quick-dev/business.md

@@ -46,7 +46,22 @@
   5. Cross-reference `project-context.md` layer rules (if available) -- flag any change that would violate layer constraints.
 - **Output of this step**: a target list (`path | action | one-line intent`).
 
-### Step 4: Plan the Change
+### Step 4: Identify Project Scope and Load Project-Specific Knowledge
+
+This step applies only when the workspace has multiple projects (`projects.length > 1` in `project-context.yaml`). In single-project workspaces, all relevant knowledge was loaded at activation; skip this step entirely.
+
+- **Project identification**: match the file paths resolved in Step 3 against `projects[].path` and `projects[].source_paths`:
+  - A file whose path starts with a project's `path` prefix belongs to that project.
+  - A file under a project's `source_paths` entry also belongs to that project.
+  - Collect the set of unique project names from all matched files. This is the **active project scope** for this invocation.
+- **On-demand knowledge loading**: for each project P in the active project scope, read `.ai-agents/registry.yaml` and load:
+  1. Every entry under `knowledge.{P}` -- load each entry's referenced files (resolve relative to `.ai-agents/{source}`).
+  2. Every entry under `skills.mvt-quick-dev.knowledge.{P}` -- load each entry's referenced files.
+  3. Skip any key absent from the registry (no project-specific knowledge is valid; do not warn).
+- **Multi-project scenario**: if files span multiple projects, load each project's knowledge sequentially. The skill operates with the union of all loaded project-specific knowledge plus the `_all` knowledge already loaded at activation.
+- **Unmatched files**: if a file path does not match any project's `path` or `source_paths`, surface a note and treat it as belonging to the first project in `projects[]` (fallback). This may indicate a configuration gap in `project-context.yaml`.
+
+### Step 5: Plan the Change
 - **What**: produce an ordered file list before writing any code.
 - **How**:
   1. For each target from Step 3, decide: `create | modify | delete`, and write a one-line intent.
@@ -60,31 +75,31 @@
   | Plan exceeds 3 files | Escalate to Complex -- STOP, recommend standard workflow |
   | Plan introduces an unplanned module | Escalate to Complex -- STOP, recommend standard workflow |
 
-### Step 5: Implement
+### Step 6: Implement
 - **What**: write/modify the planned files.
 - **How**:
-  1. Apply changes one file at a time, in the order determined by Step 4.
-  2. Follow `coding-standards.md` if available; match surrounding code style otherwise.
+  1. Apply changes one file at a time, in the order determined by Step 5.
+  2. Follow the coding standards loaded by activation (if any); match surrounding code style otherwise.
   3. Respect module/layer rules from `project-context.md`. Forbidden imports must NOT appear.
   4. Add error handling at system boundaries only (HTTP, DB, external API, file IO, message bus). Do NOT add try/catch around internal calls.
   5. Inline comments only for non-obvious algorithmic choices or deliberate workarounds with a reason.
   6. Do NOT introduce abstractions, helpers, or feature flags beyond what the task requires.
 
-### Step 6: Quick Verify
+### Step 7: Quick Verify
 - **What**: light-weight verification before reporting completion.
 - **How**:
   1. If a type-checker is configured for the project (`tsc`, `mypy`, `cargo check`, etc.), run it on changed files only. Surface failures.
   2. If existing tests cover the changed code, suggest the test command but do not auto-run unless user explicitly approved.
   3. For frontend/UI changes, note that user should verify in browser; do NOT claim "tested" based on type-check alone.
 
-### Step 7: Summarize in Conversation
+### Step 8: Summarize in Conversation
 - **What**: present the result without writing any artifact file.
 - **How**: output a brief summary containing:
   - Files touched: `path | action`
   - Verification status: type-check result, test suggestion
 - **No artifact is written. No document is generated.** This is a conversation-only skill.
 
-### Step 8: State Update
+### Step 9: State Update
 Apply the State Update rules defined in the **State Update** section below.
 
 ## Edge Cases & Errors

package/sources/skills/mvt-quick-dev/manifest.yaml

@@ -39,7 +39,6 @@ sections:
     params:
       extended_context:
         - ".ai-agents/knowledge/project/_generated/project-context.md -- Module/layer map (optional)"
-        - ".ai-agents/knowledge/principle/coding-standards.md -- Coding standards (optional)"
         - "Target source files (load based on change description)"
 
   - type: shared

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

@@ -16,12 +16,27 @@
   3. State the current behavior in plain language; include any non-obvious side effects or invariants you can see in the code.
 - **Output of this step**: a target table (`file | range | role`) and a "current behavior" paragraph; both are shown to user before continuing.
 
-### Step 3: Classify Refactoring Type
+### Step 3: Identify Project Scope and Load Project-Specific Knowledge
+
+This step applies only when the workspace has multiple projects (`projects.length > 1` in `project-context.yaml`). In single-project workspaces, all relevant knowledge was loaded at activation; skip this step entirely.
+
+- **Project identification**: match the file paths resolved in Step 2 against `projects[].path` and `projects[].source_paths`:
+  - A file whose path starts with a project's `path` prefix belongs to that project.
+  - A file under a project's `source_paths` entry also belongs to that project.
+  - Collect the set of unique project names from all matched files. This is the **active project scope** for this invocation.
+- **On-demand knowledge loading**: for each project P in the active project scope, read `.ai-agents/registry.yaml` and load:
+  1. Every entry under `knowledge.{P}` -- load each entry's referenced files (resolve relative to `.ai-agents/{source}`).
+  2. Every entry under `skills.mvt-refactor.knowledge.{P}` -- load each entry's referenced files.
+  3. Skip any key absent from the registry (no project-specific knowledge is valid; do not warn).
+- **Multi-project scenario**: if files span multiple projects, load each project's knowledge sequentially. The skill operates with the union of all loaded project-specific knowledge plus the `_all` knowledge already loaded at activation.
+- **Unmatched files**: if a file path does not match any project's `path` or `source_paths`, surface a note and treat it as belonging to the first project in `projects[]` (fallback). This may indicate a configuration gap in `project-context.yaml`.
+
+### Step 4: Classify Refactoring Type
 - **What**: pick the smallest type that covers the requested change. Use the Refactoring Types table above for risk levels.
 - **How**: assign one primary type per refactoring task. Multiple types in one run are allowed but each must be tracked separately in the artifact.
 - If the request requires `Change Interface/API` AND the symbol is exported beyond the project (public API, library entry point, IPC boundary): STOP -- this is no longer a refactoring task; recommend `/mvt-design`.
 
-### Step 4: Risk Assessment
+### Step 5: Risk Assessment
 - **What**: assign a final risk score and decide whether explicit confirmation is needed.
 - **How**: combine refactoring type and impact factors.
 
@@ -34,11 +49,11 @@
   | User has uncommitted changes overlapping the target | +1 |
 
 - Final risk = type's base level + factors:
-  - Low + 0..1 -> proceed silently in Step 7.
-  - Medium OR Low + 2 -> require explicit confirmation in Step 6.
-  - High OR (Medium + 2) -> require explicit confirmation AND a behavior-preservation strategy from Step 5.
+  - Low + 0..1 -> proceed silently in Step 8.
+  - Medium OR Low + 2 -> require explicit confirmation in Step 7.
+  - High OR (Medium + 2) -> require explicit confirmation AND a behavior-preservation strategy from Step 6.
 
-### Step 5: Choose Behavior-Preservation Strategy
+### Step 6: Choose Behavior-Preservation Strategy
 - **What**: pick a verification path BEFORE editing.
 - **How**: choose the row that matches your test reality.
 
@@ -50,34 +65,34 @@
 
 - Document the chosen strategy in the artifact regardless of risk level.
 
-### Step 6: Confirm with User (when required)
-- **Trigger**: per the Step 4 thresholds, or any High-risk type.
+### Step 7: Confirm with User (when required)
+- **Trigger**: per the Step 5 thresholds, or any High-risk type.
 - **Format**: present a single screen with:
   - Target summary (Step 2's table, condensed to file count + symbol).
   - Refactoring type and risk level.
   - Number of callers and a list of the top 5 affected files.
-  - Behavior-preservation strategy (Step 5).
+  - Behavior-preservation strategy (Step 6).
   - One yes/no prompt: `Proceed with this refactor? (y / n / show-plan)`.
 
-### Step 7: Plan and Execute Incrementally
+### Step 8: Plan and Execute Incrementally
 - **What**: apply the change in the smallest reversible steps.
 - **How**:
   1. Break the refactor into ordered sub-steps (e.g., Rename: 1) update declaration, 2) update callers, 3) update tests, 4) update docs).
   2. After each sub-step:
      - Compile / type-check the affected files.
-     - If a test command was identified in Step 5, run it (or surface it for user to run if running tests is not allowed in this environment).
+     - If a test command was identified in Step 6, run it (or surface it for user to run if running tests is not allowed in this environment).
      - On failure: revert the sub-step, surface the cause, do NOT continue.
   3. Do not interleave behavior changes (bug fixes, feature toggles) with the refactor. If you spot one, note it for follow-up; do not silently include it.
   4. Do not modify code outside the planned target unless required for compilation/type correctness; record any such "incidental" edits.
 
-### Step 8: Verify Behavior Preservation
+### Step 9: Verify Behavior Preservation
 - **What**: prove (within the chosen strategy) that observable behavior is unchanged.
 - **How**:
   - With tests: all pre-existing tests pass; new characterization tests pass; assert pass count is unchanged or increased.
   - Without tests: list the call sites you visually verified, plus the manual behavior checks you recommend the user run.
-- If anything regresses: revert the most recent sub-step, surface the regression, return to Step 7. Do not declare success.
+- If anything regresses: revert the most recent sub-step, surface the regression, return to Step 8. Do not declare success.
 
-### Step 9: Write Refactor Notes
+### Step 10: Write Refactor Notes
 - **Path**: `.ai-agents/workspace/artifacts/{change-id}/refactor-notes.md` if `active_change` exists; otherwise inline summary in conversation only (shortcut mode).
 - **Required content**:
   - `Target` -- file/symbol list, current-behavior paragraph.
@@ -88,7 +103,7 @@
   - `Verification Result` -- tests run, pass/fail counts; or manual checks recommended.
   - `Follow-ups` -- deferred behavior changes spotted during refactoring.
 
-### Step 10: State Update
+### Step 11: State Update
 Apply the State Update rules defined in the **State Update** section below.
 
 ## Edge Cases & Errors
@@ -98,8 +113,8 @@ Apply the State Update rules defined in the **State Update** section below.
 | Target spans multiple repos / submodules | STOP -- out of scope; recommend a coordinated change rather than a single refactor |
 | Refactor uncovers a real bug | Pause refactor, document the bug, recommend `/mvt-fix` -- do NOT fix during the refactor |
 | Refactor target is dead code | Confirm with user before deleting; offer alternative of marking deprecated first |
-| Symbol is referenced via reflection / dynamic dispatch / string lookup | Increase risk by +2; require strategy 5(a) (characterization test) before proceeding |
+| Symbol is referenced via reflection / dynamic dispatch / string lookup | Increase risk by +2; require strategy 6(a) (characterization test) before proceeding |
 | User has uncommitted changes overlapping the target | Show diff, recommend committing/stashing first, ask for explicit confirmation if user wants to proceed anyway |
 | Type/test failures persist after revert | Surface a clear summary; suggest user re-run the original test baseline to detect a pre-existing failure unrelated to the refactor |
-| User aborts at Step 6 | Do not modify any file; report "no changes" |
+| User aborts at Step 7 | Do not modify any file; report "no changes" |
 | Active change is mid-implementation (not yet `done`) | Warn that refactoring during implementation can confuse review/test phases; require explicit confirmation |

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

@@ -68,11 +68,6 @@ sections:
   - type: shared
     source: sections/output-format-constraint.md
 
-  - type: inline
-    content: |
-      ### Step 4: Pre-flight Checks
-      - No blocking checks required (shortcut operation).
-
   - type: inline
     content: |
       ## Operation Mode: Shortcut

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

@@ -2,12 +2,23 @@
 
 ### Step 1: Read Session State
 
-Extract from the already-loaded session context:
-- `active_change` -- the current change-id (if any), plan_path
+Read `.ai-agents/workspace/session.yaml`. If the file is missing or empty, jump to Step 8 with the "no session" branch.
+
+Extract:
+- `active_change` -- the current change-id (if any), plan_path, epic_id
+- `active_epic` -- the current epic (if any): id, title, epic_path
 - `changes` -- list of changes with active plans
 - `history` -- last 20 entries (skill name, timestamp, change_id)
 
-If session.yaml is missing or empty, jump to Step 8 with the "no session" branch.
+### Step 1a: Check Epic State
+
+After extracting session data in Step 1, check for epic state:
+
+| Condition | Action |
+|-----------|--------|
+| `active_change.id` non-empty AND `active_change.epic_id` non-empty | Set `within_epic = true`. Continue to Step 2 (normal plan-based resume). In Step 7, include an Epic Context section. |
+| `active_change.id` empty AND `active_epic.id` non-empty (epic-pending) | Read `epic.yaml` via `active_epic.epic_path`. If unreadable, warn and jump to Step 8 with the "epic-pending but epic.yaml missing" edge case. Otherwise, identify the child referenced by `epic.yaml.current_change` as the resume target. Skip Steps 2-6 and go directly to Step 7 with a simplified report containing: (1) **Epic State** -- epic title, id, status, progress (done/total); (2) **Current Sub-change** -- title, scope, depends_on status of each dependency; (3) **Resume Point** -- "Resuming epic: {title}. Next sub-change: {current_change_title}. Run `/mvt-analyze` to start."; (4) **Recommended Next Step** -- `/mvt-analyze` -- Start the next sub-change in the epic. |
+| Neither | Continue to Step 2 (normal flow). |
 
 ### Step 2: Discover Pending Plans
 
@@ -56,18 +67,23 @@ For each artifact, capture: file path, mtime, size (in tokens estimate = chars /
 
 ### Step 5: Determine Resume Point
 
-Read the plan's `current_task`. The resume point = that task. Next-step recommendation = the task's `skill_hint` (or infer from task title if skill_hint is absent).
+Read the plan's `current_tasks` map. The resume point = the task(s) referenced by `current_tasks`. Next-step recommendation = the relevant task's `skill_hint` (or infer from task title if skill_hint is absent).
+
+For multi-project workspaces, if `current_tasks` has entries for multiple projects, display each project's current task separately.
 
 Also filter `history` to entries matching `change_id == selected_change_id` (entries with empty change_id are excluded from this filtered view).
 
+If the plan-update script output from a previous session included a `project_switch` notification, surface it: "Last session crossed from {from} to {to} project."
+
 ### Step 6: Load Plan Progress
 
 Generate the **Plan Progress** section:
 
 - Read all tasks from plan.yaml.
-- Build a compact status table: `| # | id | title | status | skill_hint |`
-- Highlight `current_task` row (prefix with `>>` or bold).
+- Build a compact status table: `| # | id | title | status | project | skill_hint |`
+- Highlight `current_tasks` rows (prefix with `>>` or bold).
 - Count summary: `Done: {d}, In Progress: {ip}, Pending: {p}, Blocked: {b}, Skipped: {s}`
+- If any task has `deliverables.freshness == "stale"`, append a warning: "Stale deliverables: {task_ids} -- downstream tasks may be out of date. Run `/mvt-implement` to refresh."
 
 And the **Current Task Detail** section:
 
@@ -82,11 +98,12 @@ And the **Current Task Detail** section:
 Render via the `resume-output.md` template. Sections to fill:
 
 1. **Active Task** -- name, change-id, started_at (from selected plan)
-2. **Plan Progress** -- task table + counts + current task detail
-3. **Recent Skill History** -- last 5 entries from history (filtered to selected change if applicable)
-4. **Recent Artifacts** -- the top 5 artifacts collected in Step 4 (path, mtime, size)
-5. **Resume Point** -- a one-paragraph natural-language summary of "where we are"
-6. **Recommended Next Step** -- the mapped next skill from Step 5, with justification
+2. **Epic Context** (if `within_epic` is true) -- epic title, id, progress (done/total children), current position within the epic. Resolve the parent epic path: compare `active_change.epic_id` to `active_epic.id`. If they match, use `active_epic.epic_path`. If they do not match, search `session.epics[]` for an entry with `id == active_change.epic_id` and use its `epic_path`. If neither path exists, render the plan resume and add a bounded warning: "Epic context could not be loaded (epic_id: {active_change.epic_id})." Read `epic.yaml` via the resolved path and render: "This change is part of epic: **{epic_title}** ({done}/{total} sub-changes done). Current: {active_child_title}."
+3. **Plan Progress** -- task table + counts + current task detail
+4. **Recent Skill History** -- last 5 entries from history (filtered to selected change if applicable)
+5. **Recent Artifacts** -- the top 5 artifacts collected in Step 4 (path, mtime, size)
+6. **Resume Point** -- a one-paragraph natural-language summary of "where we are"
+7. **Recommended Next Step** -- the mapped next skill from Step 5, with justification
 
 ### Step 8: Edge Cases
 
@@ -94,4 +111,7 @@ Render via the `resume-output.md` template. Sections to fill:
 - **No active plans**: report "No active plans found. Start a new change with `/mvt-analyze` or run `/mvt-status` to check project state."
 - **Selected change but referenced artifacts missing**: warn "Artifact directory `{path}` not found -- task state may be stale. Verify with `/mvt-status` or run `/mvt-cleanup`."
 - **Plan exists but plan.yaml is invalid** (parse error or schema violation): warn "plan.yaml is corrupted or invalid. Run `/mvt-plan-dev` to regenerate, or `/mvt-status` to inspect."
-- **Stale task warning**: If plan's `current_task` has status `in_progress` but the plan's `updated_at` is more than 5 days old, append a notice: "Current task has been in_progress for {N} days without updates. Consider running `/mvt-update-plan` to refresh status."
+- **Stale task warning**: If plan's `current_tasks` entries reference tasks with status `in_progress` but the plan's `updated_at` is more than 5 days old, append a notice: "Current task has been in_progress for {N} days without updates. Consider running `/mvt-update-plan` to refresh status."
+- **Stale deliverables warning**: If any task has `deliverables.freshness == "stale"`, warn: "Task(s) {ids} have stale deliverables. Downstream tasks may reference outdated contracts. Run `/mvt-implement` to refresh."
+- **Epic-pending but epic.yaml missing**: warn "Epic state references `epic_path` but file not found at `{path}`. Run `/mvt-status` to inspect or `/mvt-cleanup` to archive stale entries."
+- **Epic-pending but current_change empty or invalid**: warn "Epic `current_change` is empty or points to a non-existent child. Run `/mvt-status` to inspect the epic state."

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

@@ -30,8 +30,8 @@ sections:
         - rule: "Exactly one in_progress plan found -> Auto-select it and proceed"
         - rule: "No plans found -> Report no active plans, suggest `/mvt-analyze` or `/mvt-plan-dev`"
         - rule: "active_change is empty AND history is empty AND no plans -> Recommend `/mvt-init` or `/mvt-status`"
-        - rule: "Plan exists and has current_task -> Use current_task's skill_hint as next-step recommendation"
-        - rule: "Plan's current_task has been in_progress for >5 days -> Surface stale warning"
+        - rule: "Plan exists and has current_tasks -> Use current_tasks entry's skill_hint as next-step recommendation"
+        - rule: "Plan's current_tasks entry has been in_progress for >5 days -> Surface stale warning"
         - rule: "Last skill was interrupted -> Surface the context, suggest retry"
       boundaries:
         - scope: "read git state (branch, diff, commits)"
@@ -70,7 +70,7 @@ sections:
       current_skill: mvt-resume
       conditional_suggestions:
         conditions:
-          - condition: "plan has current_task with skill_hint"
+          - condition: "plan has current_tasks entry with skill_hint"
             primary: mvt-implement
             primary_desc: "Continue with the next planned task (use skill_hint)"
           - condition: "no active plans found"