@uoyo/mvtt 2.0.0-beta.4 → 2.0.0

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

@@ -87,9 +87,24 @@
   | Multi-module | Touches >1 module or shared utility | List impacted modules, read each call site before editing, group by commit if possible |
   | Cross-architecture | Requires layering change, new dependency, or interface redesign | STOP -- recommend `/mvt-design` (or `/mvt-refactor` if behavior is preserved); do NOT implement here |
 
-- Identify regression risk: which existing tests cover this code? If none, decide whether to add a regression test in Step 7.
+- Identify regression risk: which existing tests cover this code? If none, decide whether to add a regression test in Step 8.
 
-### Step 6: User Confirmation
+### Step 6: 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 prior steps (from review findings, bug detection, or self-contained diagnosis) 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-fix.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 affected 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 7: User Confirmation
 - **When to confirm before applying**:
   - Multi-module class or above.
   - The fix changes a public/exported symbol or a configuration default.
@@ -99,14 +114,14 @@
   - One-liner / single-file class AND fix is purely additive or correctional AND reproduction was verified.
 - **Confirmation prompt format**: present `Root cause: ...`, `Proposed change: <files + summary>`, `Risk: <regression scope>`, then ask `Apply? (y / n / show-diff)`.
 
-### Step 7: Apply the Fix
+### Step 8: Apply the Fix
 - For source 1a (review.md): apply fixes per finding; re-run the review's relevant checks (not reproduction) to confirm each fix addresses its finding.
 - Make the targeted code change.
 - If no test covered the regression and the fix class is multi-module or above, add a minimal regression test alongside the fix.
 - Re-run the original repro (if any) to confirm resolution.
 - If repro still fails -> revert, return to Step 3 with the new evidence.
 
-### Step 8: Write Fix Notes
+### Step 9: Write Fix Notes
 - **Path**: `.ai-agents/workspace/artifacts/{change-id}/fix-notes.md` if an `active_change` exists; otherwise inline in the conversation only (no artifact -- shortcut operation).
 - **Structure** (each section is a single paragraph or list):
   - `Symptom` -- what the user saw / reported.
@@ -118,7 +133,7 @@
   - `Regression risk` -- scope of behavior potentially affected, plus what tests guard it.
   - `Follow-ups` -- TODOs, deferred refactors, related issues.
 
-### Step 9: State Update
+### Step 10: State Update
 Apply the State Update rules defined in the **State Update** section below.
 
 ## Edge Cases & Errors
@@ -128,6 +143,6 @@ Apply the State Update rules defined in the **State Update** section below.
 | Bug is intermittent / racy | Mark reproduction as "flaky", state confidence level explicitly, prefer adding instrumentation over speculative fix |
 | Fix would require breaking a downstream API | STOP -- escalate to `/mvt-design` or `/mvt-refactor`; do not silently break contracts |
 | Root cause is in a third-party dependency | Document the upstream issue, apply a minimal local workaround clearly labeled as temporary |
-| User aborts at Step 6 | Do not write fix notes; record the diagnosis as a comment in the conversation only |
+| User aborts at Step 7 | Do not write fix notes; record the diagnosis as a comment in the conversation only |
 | Fix relies on changes the user has uncommitted in another branch | Surface the conflict before editing; do not overwrite |
 | `active_change` is missing entirely | Apply fix without writing artifact (shortcut mode), summarize result in conversation |

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

@@ -45,7 +45,7 @@ sections:
     source: sections/activation-load-config.md
 
   - type: shared
-    source: sections/output-language-constraint.md
+    source: sections/language-constraint.md
 
   - type: shared
     source: sections/output-format-constraint.md
@@ -64,7 +64,7 @@ sections:
       ## Operation Mode: Shortcut
 
       This skill operates as a shortcut — it can execute at any time without checking workflow prerequisites.
-      - Do NOT update `progress` (this is a shortcut operation, not a workflow phase).
+      - Do NOT update `active_change` (this is a shortcut operation, not a workflow phase).
 
   - type: file
     source: ./business.md

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

@@ -11,8 +11,9 @@
 
   | Condition | Recommendation |
   |-----------|---------------|
-  | `session.yaml` missing or `initialized_at` empty | `/mvt-init` -- Initialize the project |
+  | `.ai-agents/workspace/session.yaml` missing or `initialized_at` empty | `/mvt-init` -- Initialize the project |
   | Initialized AND `project-context.md` does not exist | `/mvt-analyze-code` -- Analyze existing code |
+  | `active_epic.id` non-empty AND `active_change.id` empty (epic-pending) | `/mvt-analyze` -- Start the next sub-change in the epic |
   | No requirements (no `analysis.md` for active change AND no completed `/mvt-analyze` in `history`) | `/mvt-analyze` -- Analyze requirements |
   | No requirements, but user describes a simple change directly | `/mvt-quick-dev` -- Implement a simple change quickly |
   | Requirements present, no `design.md` | `/mvt-design` -- Design architecture |
@@ -25,14 +26,11 @@
 
 ### Step 3: Display Skills Catalog
 Read `registry.yaml` > `skills` section.
-Group skills by `category` field and display as tables:
-- `workflow` -> "Workflow Skills (sequential phases)"
-- `shortcut` -> "Shortcut Skills (anytime, no prerequisites)"
-- `project` -> "Project Management Skills"
-- `utility` -> "Utility Skills"
+Display all skills as a single flat table (no grouping; the section comment headers in `registry.yaml` already group them by role for human readers):
+- Header row: `Skill | Description`
 
 For each skill, show: `/{skill-name}` | `description` field from registry.
-Sort within each group by declaration order in registry.
+Sort by declaration order in registry.
 
 ### Step 4: Show Workflow Diagram
 Display the standard workflow with current position highlighted:
@@ -45,6 +43,9 @@ flowchart LR
     E --> F[review] --> G[test]
 
     C -.->|simple change| Q[quick-dev]
+    C -.->|epic scale| DC[decompose]
+    DC --> C2[analyze<br/>epic-child]
+    C2 --> D
 ```
 
 Color-code based on current progress: green (done), yellow (current/recommended), gray (pending). The "current" node is whichever skill the Step 2 table recommended; "done" is determined by the same evidence the Step 2 table consumed.
@@ -56,7 +57,7 @@ Color-code based on current progress: green (done), yellow (current/recommended)
   | Question pattern | Response |
   |------------------|----------|
   | "What should I do next?" / no specific question | Repeat the Step 2 recommendation in one line, followed by a one-clause reason citing the matched condition |
-  | "What does `/mvt-X` do?" / asks about a specific skill | Read the skill's metadata from `registry.yaml`, show: name, description, category, dependencies, knowledge entries (if any), template (if any). If the skill has a `path`, mention "see SKILL.md for the full procedure" -- do NOT inline the full SKILL.md content (too large) |
+  | "What does `/mvt-X` do?" / asks about a specific skill | Read the skill's metadata from `registry.yaml`, show: name, description, knowledge entries (if any), template (if any). Mention "see the skill's SKILL.md for the full procedure" -- do NOT inline the full SKILL.md content (too large) |
   | "Compare `/mvt-X` and `/mvt-Y`" | Pull descriptions from registry; if both are workflow skills, mention their relative position in the diagram |
   | Asks about something not in registry | Reply: "No skill matches that. Available skills: see catalog above." Do not invent skills |
 
@@ -69,4 +70,5 @@ Color-code based on current progress: green (done), yellow (current/recommended)
 | `changes[]` references a `plan_path` that no longer exists | Ignore for help purposes; do not warn -- `/mvt-status` is the right place for that |
 | User invokes `/mvt-help` while inside an active change with Critical review findings | Step 2's recommendation is `/mvt-fix`; surface this prominently above the catalog |
 | User asks about a custom skill (registry entry with `custom: true`) | Treat identically to built-ins; the only difference is showing `custom: true` in the metadata view |
-| Workflow diagram cannot be rendered (mermaid unsupported in environment) | Fall back to a textual flow: `init -> analyze-code -> analyze -> design -> [plan-dev] -> implement -> review -> test` |
+| Workflow diagram cannot be rendered (mermaid unsupported in environment) | Fall back to a textual flow: `init -> analyze-code -> analyze -> [decompose (epic) -> analyze (epic-child)] -> design -> [plan-dev] -> implement -> review -> test` |
+| Epic-pending state (`active_epic` non-empty, `active_change` empty) | Step 2's recommendation is `/mvt-analyze` to start the next sub-change; the decompose path is shown in the workflow diagram |

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

@@ -24,10 +24,8 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
-  - type: inline
-    content: |
-      ### Step 4: Pre-flight Checks
-      - No blocking checks required.
+  - type: shared
+    source: sections/language-constraint.md
 
   - type: file
     source: ./business.md

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

@@ -5,7 +5,7 @@
   - The actual source files referenced in the design's `File Structure` and `Change Tracking` sections.
 - **Fallback**:
   - If `design.md` is missing, surface a WARN and ask the user whether to (a) run `/mvt-design` first or (b) proceed using their conversational description as the design (mark artifact with "Source: conversation only").
-  - If `coding-standards.md` is missing, fall back to language/framework defaults inferred from `project-context.yaml`.
+  - If coding standards are not loaded by activation, fall back to language/framework defaults inferred from `project-context.yaml`.
 
 ### Step 2: Plan the Implementation
 - **What**: produce an ordered file list with the smallest possible commit boundary per group.
@@ -14,7 +14,7 @@
   2. Topologically order files by dependency: domain entities -> repositories/adapters -> use-case/services -> controllers/UI.
   3. Group consecutive files that share a single conceptual change into one commit boundary.
   4. For each file, decide: `create | modify | delete`, and write a one-line intent.
-- **Plan-aware behavior**: if `plan.yaml` is present, treat `current_task`'s `artifacts.files` (cross-reference `plan.tasks[*].artifacts.files`) as a **starting-scope hint, not a hard ceiling**. The source of truth for scope remains `design.md`'s `Change Tracking` (per Step 2.1). When `artifacts.files` is `null` or empty, derive scope entirely from `Change Tracking`. If implementation reveals files beyond this hint are genuinely required, do NOT silently expand — surface them via Step 3 confirmation and never absorb files that clearly belong to a different task.
+- **Plan-aware behavior**: if `plan.yaml` is present, identify the active task from `current_tasks` (the entry matching the current project, or the sole entry in single-project mode), then treat that task's `artifacts.files` (cross-reference `plan.tasks[*].artifacts.files`) as a **starting-scope hint, not a hard ceiling**. The source of truth for scope remains `design.md`'s `Change Tracking` (per Step 2.1). When `artifacts.files` is `null` or empty, derive scope entirely from `Change Tracking`. If implementation reveals files beyond this hint are genuinely required, do NOT silently expand — surface them via Step 3 confirmation and never absorb files that clearly belong to a different task.
 - **Output of this step**: an in-conversation list shown to user as a preview, with no write yet.
 
 ### Step 3: Confirm Scope (when needed)
@@ -23,7 +23,7 @@
   - The plan introduces a new public API (exported symbol, HTTP endpoint, CLI flag).
   - The plan deletes existing code (delete count > 0).
   - The plan deviates from `design.md` (e.g., adds files not in `Change Tracking` or skips files listed there).
-  - The plan touches files beyond `current_task`'s `artifacts.files` hint (state which files are added and why, in one line each).
+  - The plan touches files beyond the active task's `artifacts.files` hint (state which files are added and why, in one line each).
 - **Otherwise**: proceed silently.
 - **On deviation from design**: explain the deviation reason in one line; if the deviation is structural (new module, layer change, interface break), STOP and recommend re-running `/mvt-design`.
 
@@ -31,7 +31,7 @@
 - **What**: write/modify the planned files, one commit-group at a time.
 - **How**:
   1. For each commit-group: write all files, then move on. Do not interleave groups.
-  2. Follow `coding-standards.md`. Match the surrounding code style if standards are silent.
+  2. Follow the coding standards loaded by activation (if any). Match the surrounding code style if standards are silent.
   3. Respect module/layer rules from `project-context.md`. Forbidden imports must NOT appear; use the abstractions defined in `design.md`'s `Key Interfaces`.
   4. Add error handling at system boundaries only (HTTP, DB, external API, file IO, message bus). Do NOT add try/catch around internal calls "just in case".
   5. Inline comments only for: non-obvious algorithmic choices, deliberate workarounds with a reason, interface contracts not expressible in code. Never narrate WHAT the code does.
@@ -75,9 +75,50 @@
   - `Open TODOs` -- anything deferred for `/mvt-review`, `/mvt-test`, or follow-up changes.
 - The actual source code goes to the project tree; the artifact is a record, not the code itself.
 
-### Step 8: Plan-Aware Progress Hint (if applicable)
-- If `plan.yaml` exists and a single `current_task` covers this implementation, suggest the user run `/mvt-update-plan <task-id> done` (or `blocked` with reason).
-- If the files actually touched differ from `current_task`'s `artifacts.files` (extra files added during Step 3, or planned files left untouched), explicitly remind the user to run `/mvt-update-plan` so the plan's `artifacts.files` reflects reality for `/mvt-resume` and future sessions.
+### Step 8: Deliverables Handoff (if applicable)
+
+**SKIP this step entirely** (go directly to Step 9) if ANY of the following is true:
+- No `plan.yaml` exists for the active change (`active_change.plan_path` is empty or the file does not exist).
+- No task in `plan.tasks[]` has a `depends_on` entry that includes the current task id (i.e., the current task has zero downstream dependents).
+
+> These are hard guards. Do NOT prompt the user about deliverables unless BOTH guards pass.
+
+- **Prompt the user**:
+  - If `task.deliverables` already exists (re-implementation / rescope): "Implementation changed, and downstream task(s) {ids} depend on it. Update deliverables? (y/n)"
+  - If this is the first time (no `deliverables` field on the task): "Downstream task(s) {ids} will consume this task's output. Generate deliverables? (default y)"
+- **On confirmation**, append a deliverables subsection under the task's existing `## Task: {id}` section in `implementation.md` (if multi-task plan) or as a dedicated section (if single-task). Use this soft skeleton:
+
+  ```markdown
+  ### Deliverables
+
+  #### Public Interface
+  {Describe exported symbols, function signatures, endpoint contracts that downstream tasks rely on.}
+
+  #### Data Shapes
+  {Describe data structures, types, schemas that flow between this task and downstream consumers.}
+
+  #### Usage Constraints
+  {Document invariants, preconditions, or side effects that downstream tasks must respect.}
+  ```
+
+- **After writing deliverables**, call `plan-update.cjs` with both flags in a single invocation:
+  ```bash
+  node .ai-agents/scripts/plan-update.cjs \
+    --plan "<active_change.plan_path>" \
+    --task <current_task_id> \
+    --status <current_status> \
+    --deliverables-pointer current \
+    --mark-deliverable-stale <downstream_task_id1>[,<downstream_task_id2>,...] \
+    --projects <project_list>
+  ```
+  `<project_list>` is the comma-separated project names from `plan.yaml > current_tasks` keys. In a single-project workspace this is `default`. The `--projects` flag ensures per-project validation runs correctly in multi-project plans.
+  The `--status` must be the task's current status (typically `in_progress` at this point, since Step 9 has not yet run). Pass ALL downstream dependent task ids as a comma-separated list to `--mark-deliverable-stale` so that `/mvt-resume` and `/mvt-status` can surface the stale warning.
+- **On user decline**: do not write deliverables and do not call `plan-update.cjs` with the deliverables flags. The downstream tasks will not receive stale warnings, which is acceptable if the user considers the contract unchanged.
+- **Error handling**: if `plan-update.cjs` rejects (e.g., malformed freshness), surface stderr and leave `implementation.md` as written. The deliverables content is the source of truth; the pointer can be retried via `/mvt-update-plan`.
+
+### Step 9: Plan-Aware Progress Hint (if applicable)
+- If `plan.yaml` exists and `current_tasks` identifies the active task for this implementation, suggest the user run `/mvt-update-plan <task-id> done` (or `blocked` with reason).
+- If the files actually touched differ from the active task's `artifacts.files` (extra files added during Step 3, or planned files left untouched), explicitly remind the user to run `/mvt-update-plan` so the plan's `artifacts.files` reflects reality for `/mvt-resume` and future sessions.
 - Do NOT modify `plan.yaml` directly from this skill; it is owned by `/mvt-update-plan`.
 - Do NOT modify `changes` directly; it is owned by `/mvt-plan-dev` / `/mvt-update-plan`.
 
@@ -91,4 +132,6 @@
 | User aborts at Step 3 confirmation | Do not write any source files or artifact |
 | File listed in `Change Tracking` no longer exists in the working tree | Surface, ask user whether design is stale or file was deleted in a parallel change |
 | Implementation must touch a file outside the active project (other repo / submodule) | STOP -- this is out of scope for `/mvt-implement`; surface and ask user to plan it as a separate change |
-| Plan task is `blocked` or `done` already | Refuse to implement that task; ask user to pick another `current_task` or run `/mvt-update-plan` |
+| Plan task is `blocked` or `done` already | Refuse to implement that task; ask user to pick another task from `current_tasks` or run `/mvt-update-plan` |
+| Deliverables already exist and user declines to update | Leave existing deliverables in place; do not call `plan-update.cjs` with deliverables flags |
+| `plan-update.cjs` rejects deliverables pointer | Surface error; leave `implementation.md` as written (content is source of truth, pointer can be retried) |

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

@@ -41,7 +41,7 @@ sections:
     source: sections/activation-load-config.md
 
   - type: shared
-    source: sections/output-language-constraint.md
+    source: sections/language-constraint.md
 
   - type: shared
     source: sections/output-format-constraint.md

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
@@ -57,7 +56,7 @@ sections:
     source: sections/activation-load-config.md
 
   - type: shared
-    source: sections/output-language-constraint.md
+    source: sections/language-constraint.md
 
   - type: shared
     source: sections/output-format-constraint.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

@@ -47,16 +47,11 @@ sections:
     source: sections/activation-load-config.md
 
   - type: shared
-    source: sections/output-language-constraint.md
+    source: sections/language-constraint.md
 
   - 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-plan-dev/manifest.yaml

@@ -46,7 +46,7 @@ sections:
     source: sections/activation-load-config.md
 
   - type: shared
-    source: sections/output-language-constraint.md
+    source: sections/language-constraint.md
 
   - type: shared
     source: sections/output-format-constraint.md