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

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

@@ -4,7 +4,7 @@
 - **Required**:
   - The set of files to review (see Step 2 for resolution).
 - **Fallback**:
-  - If `design.md`/`implementation.md` are missing, downgrade to "code-only review": skip the design-compliance checks (Step 4 row group A) and note the limitation in the artifact.
+  - If `design.md`/`implementation.md` are missing, downgrade to "code-only review": skip the design-compliance checks (Step 5 row group A) and note the limitation in the artifact.
   - If `project-context.md` is missing, skip layer-compliance checks and note the limitation.
 
 ### Step 2: Resolve Review Target
@@ -22,12 +22,27 @@
 - If the resolved list is empty, STOP and ask the user to specify the target.
 - If the list exceeds ~30 files, ask the user to scope down OR confirm a high-level (per-module) review depth.
 
-### Step 3: Determine Review Depth
-- **Default**: full review across all axes (Step 4).
+### 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-review.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: Determine Review Depth
+- **Default**: full review across all axes (Step 5).
 - `--aspect <name>`: narrow to a single axis. Supported aspects: `architecture`, `quality`, `errors`, `edge-cases`, `security`, `naming`, `tests`. Other aspects -> ask user to clarify.
 - For files >300 lines, do a structural pass first (interfaces, exports, key paths) before line-level review; do not attempt line-by-line on huge files.
 
-### Step 4: Run Review Checks
+### Step 5: Run Review Checks
 - **What**: produce findings, each tagged with severity, location, and a concrete remedy.
 - **How**: walk the checklist below. Skip any group whose inputs were missing per Step 1 fallback notes.
 
@@ -39,7 +54,7 @@
 
   **Group B -- Code Quality**
   - Functions are small and focused; flag functions > ~50 lines or with > ~3 nested control levels.
-  - Naming is clear, consistent with `naming-conventions.md`, and matches surrounding code.
+  - Naming is clear, consistent with the naming conventions loaded by activation (if any), and matches surrounding code.
   - No duplication: same logic appearing >= 3 times warrants extraction.
   - No premature abstraction: a single-use helper / interface / wrapper is a finding.
   - No dead code, unused imports, commented-out blocks left behind.
@@ -68,7 +83,7 @@
   - Auth/authz checks present on every protected endpoint or operation.
   - SQL/NoSQL/HTML rendered through parameterized / escaped APIs.
 
-### Step 5: Categorize and De-duplicate Findings
+### Step 6: Categorize and De-duplicate Findings
 - **Severity**: assign each finding using the table below.
 
   | Level | Definition | Examples |
@@ -80,7 +95,7 @@
 - Merge duplicate findings (same root cause appearing in multiple files) into one entry with a list of locations.
 - Each finding must include: file, line range, severity, observation, recommendation.
 
-### Step 6: Write Artifact
+### Step 7: Write Artifact
 - **Path and template**: as defined in the **Artifact Structure** section below. If no `active_change` exists, use `.ai-agents/workspace/artifacts/_ad-hoc-review-{YYYY-MM-DD-HHMM}/review.md`.
 - **Required content** (mapped to template headings):
   - `Review Scope` -- file list, depth, aspect filter, fallbacks applied (e.g., "design.md missing -> Group A skipped").
@@ -91,13 +106,13 @@
   - `Skipped Checks` -- groups skipped because inputs were missing, with reason.
   - `Recommended Next Skill` -- e.g., `/mvt-fix` for Critical, `/mvt-test` if Group E gaps, `/mvt-refactor` if Group B is dominant.
 
-### Step 7: Verdict Rule
+### Step 8: Verdict Rule
 - Critical > 0 -> verdict is `Request changes`. Suggest `/mvt-fix`.
 - Critical = 0, Warnings > 5 -> verdict is `Approve with comments`.
 - Critical = 0, Warnings <= 5, Suggestions only -> verdict is `Approve`.
 - Code-only review (design.md missing) -> verdict cannot be higher than `Approve with comments` (call it out explicitly).
 
-### 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-status/business.md

@@ -11,16 +11,16 @@
 ### Step 2: Build Activity Timeline
 - **What**: produce the most-recent-first list of history entries with derived metadata.
 - **How**:
-  1. Read `history` from `session.yaml`.
+  1. Read `.ai-agents/workspace/session.yaml`, extract `history`.
   2. For each entry, attach: relative time (e.g., "2h ago"), `change_id` (if present), and the originating skill name.
   3. Limit to the last 10 entries for the rendered table; keep full count separately for the summary line.
 
 ### Step 3: Discover All Plans (Multi-Change Dashboard)
 - **What**: produce the canonical plan list across the workspace.
 - **How**:
-  1. Iterate `changes[]` from `session.yaml`. For each entry with a `plan_path`, attempt to read the plan file.
+  1. From the session data loaded above, iterate `changes[]`. For each entry with a `plan_path`, attempt to read the plan file.
   2. Glob `.ai-agents/workspace/artifacts/*/plan.yaml` to find any plans not registered in `changes` (mark them `unindexed`). **Exclude paths under `artifacts/_archived/`** — those are completed changes archived by `/mvt-cleanup`.
-  3. For each plan, extract: `change_id`, `title`, `status`, `current_task`, task progress (`done/total`), `updated_at`, `skill_hint` (from current task if present).
+  3. For each plan, extract: `change_id`, `title`, `status`, `current_tasks`, task progress (`done/total`), `updated_at`, `skill_hint` (from current task if present).
   4. If a plan file is present but malformed, include a row with `(corrupt)` in the status column and mark the file path; do not abort.
 - **Branches**:
 
@@ -38,19 +38,44 @@
   2. **Projects** -- table: name | type | tech stack (truncated). Cap at 10 rows; collapse the rest into `+N more`.
   3. **Semantic Context** -- one line: `project-context.md present` / `missing -- run /mvt-analyze-code`.
   4. **Active Change** -- if `active_change` exists: id, title, start time. Else: `none`.
+  4a. **Epic Progress** -- if `active_epic.id` is non-empty:
+     - Read `epic.yaml` via `active_epic.epic_path`. If the file is missing or unreadable, render `(epic.yaml not found at {path})` and skip this section.
+     - Compute progress: count children with `status` in `["done", "abandoned"]` as completed; total = `children.length`.
+     - Render:
+
+       ```markdown
+       ## Epic: {epic_title} ({epic_id})
+       Progress: {done}/{total} done -- Status: {status}
+
+       | Sub-change | Status | depends_on | Internal Progress |
+       |------------|--------|------------|-------------------|
+       | {title} | {status} | {deps or --} | {plan progress or --} |
+       ```
+
+     - For each child in `epic.yaml.children[]`:
+       - `depends_on`: comma-separated list of change_ids, or `--` if empty.
+       - `Internal Progress`: for a child with `status: active`, attempt to read its plan.yaml from `.ai-agents/workspace/artifacts/{change_id}/plan.yaml`. If found, show `{done_count}/{total_count} tasks`. If not found, show `--`. For non-active children, show `--`.
+     - Below the table, render a context line:
+       - If `active_change.id` is non-empty (within-epic active change): "Current: **{active_child_title}**. Run `/mvt-resume` to continue."
+       - If `active_change.id` is empty (epic-pending state): "Next sub-change: **{current_change_title}**. Run `/mvt-analyze` to start."
   5. **Changes Overview** -- table from Step 3 (skip if no plans). Render with these columns:
 
-     | change-id | title | status | progress | current_task | updated_at |
-     |-----------|-------|--------|----------|--------------|------------|
+     | change-id | title | status | progress | current_tasks | project | updated_at |
+     |-----------|-------|--------|----------|---------------|---------|------------|
+
+     For `current_tasks`, display as a compact representation: if single-project, show the task id only; if multi-project, show `web: t2, api: t1` format. The `project` column lists the distinct projects across all tasks in the plan.
+
+     If any task has `deliverables.freshness == "stale"`, append a warning row: "Stale deliverables: {task_ids} -- run `/mvt-implement` to refresh"
   6. **Skill History** -- last 5 rows of the timeline from Step 2.
 
 - Hard cap: total rendered output should not exceed ~120 lines. If it would, truncate Skill History first; never truncate the active change or Changes Overview header rows.
 
 ### Step 5: Suggest Next Step
 - Resolution order (first match wins):
-  1. `active_change` has a plan in `in_progress`, `current_task` is set -> suggest the task's `skill_hint` (or, if missing, recommend `/mvt-update-plan` to set `current_task`).
-  2. `project-context.md` is missing -> suggest `/mvt-analyze-code`.
-  3. No `active_change` or no active plan -> suggest `/mvt-analyze` to start a new feature OR `/mvt-help` to browse the catalog.
+  1. `active_change` has a plan in `in_progress`, `current_tasks` has entries -> suggest the relevant task's `skill_hint` (or, if missing, recommend `/mvt-update-plan` to set `current_tasks`).
+  2. `active_epic.id` non-empty AND `active_change.id` empty (epic-pending state) -> suggest `/mvt-analyze` -- Start the next sub-change in the epic.
+  3. `project-context.md` is missing -> suggest `/mvt-analyze-code`.
+  4. No `active_change` or no active plan -> suggest `/mvt-analyze` to start a new feature OR `/mvt-help` to browse the catalog.
 - The suggestion must be a single line: skill command + one-clause reason.
 
 ## Edge Cases & Errors
@@ -60,8 +85,11 @@
 | `session.yaml` missing entirely | Render a minimal report (Projects section if available) and recommend `/mvt-init` |
 | `session.yaml` corrupt (parse error) | Surface error with file path, render Projects only, recommend `/mvt-init` to reinitialize |
 | `changes[]` references a `plan_path` that no longer exists | Include in Changes Overview with `(missing)` marker; do not delete the index entry from this skill |
-| Plan file's `current_task` references a task id not in `tasks[]` | Render `current_task` as `(invalid: <id>)`; do not attempt to fix |
+| Plan file's `current_tasks` references a task id not in `tasks[]` | Render `current_tasks` entry as `(invalid: <id>)`; do not attempt to fix |
 | Plan file's `status` is not one of the known values | Render the raw value verbatim; flag in skip-checks of the report |
 | Both `changes[]` and the artifact glob find the same plan | Deduplicate by `change_id`; prefer the indexed entry's metadata |
 | Multiple `in_progress` plans | All rendered in Changes Overview; Step 5's suggestion picks the most recently updated; mention the count in the suggestion line |
 | Workspace contains zero projects | Render header only with a single suggestion: `/mvt-init` |
+| `active_epic.epic_path` points to missing `epic.yaml` | Render `(epic.yaml not found at {path})` in Epic Progress section; skip the section |
+| `epic.yaml` parse error | Surface one-line error with file path, skip Epic Progress section; do not attempt repair |
+| `epic.yaml.current_change` points to non-existent child | Show `(invalid: {id})` in the child table context line |

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

@@ -25,7 +25,7 @@ sections:
         - rule: "If workflow in progress -> Highlight recent skill history and next recommended step"
         - rule: "If project-context.md missing -> Suggest `/mvt-analyze-code` to generate semantic context"
         - rule: "If one or more plans exist -> Show Changes Overview table with progress for all plans"
-        - rule: "If an in_progress plan has a current_task -> Suggest the matching skill_hint as next step"
+        - rule: "If an in_progress plan has current_tasks -> Suggest the matching skill_hint as next step"
       boundaries:
         - scope: "analyze requirements"
           skill: "/mvt-analyze"
@@ -63,7 +63,7 @@ sections:
       current_skill: mvt-status
       conditional_suggestions:
         conditions:
-          - condition: "active change with current_task"
+          - condition: "active change with current_tasks"
             primary: mvt-resume
             primary_desc: "Resume work on the current task"
           - condition: "project-context.md missing"

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

@@ -1,9 +1,20 @@
 ## Execution Flow
 
-### Step 1: Identify Completed Changes
+### Step 1: Per-Project Routing (4-Level Fallback Chain)
+
+Before processing any change, determine which project(s) the sync targets. Use this 4-level fallback chain:
+
+1. **`task.project` exists** (when syncing within a plan-driven context): route to that project for per-project technical knowledge lookups (project-context.md always uses the flat path). If the task has multiple projects, route to each independently.
+2. **Artifact file paths match** a unique project's `source_paths` or `path` from `project-context.yaml`: route to that project.
+3. **Current operation's file path reverse-lookup**: match the file path against `projects[].path` and `projects[].source_paths` -> route to that project.
+4. **List candidate projects for user selection**: if none of the above resolved a unique project, list the project names and ask the user.
+
+**Cross-project changes** (task spanning multiple projects): route to each project for per-project technical knowledge lookups. The merge target for `project-context.md` is always the single flat file; per-project knowledge (quadrant 3/4) is routed per project.
+
+### Step 2: Identify Completed Changes
 - **What**: produce a candidate list of change-ids whose artifacts will be aggregated.
 - **How**:
-  1. Read `session.yaml`. Collect `changes[]` entries with `status: done`.
+  1. Read `.ai-agents/workspace/session.yaml`. Collect `changes[]` entries with `status: done`.
   2. For each candidate, verify `.ai-agents/workspace/artifacts/{change-id}/` exists AND contains at least one of `analysis.md` or `implementation.md`. Drop entries with only `plan.yaml`, or with only `design.md` (design artifacts are not aggregated -- see Step 3).
   3. (Fallback) If `changes[]` is empty, scan `.ai-agents/workspace/artifacts/*/` directly; offer those with `analysis.md` or `implementation.md`, marked `unindexed`.
   4. Exclude already-archived or irrelevant changes:
@@ -23,12 +34,13 @@
 
 - Cancel / empty selection -> stop with "no changes applied".
 
-### Step 2: Read Current Project Context (Adaptive Structure Discovery)
+### Step 3: Read Current Project Context (Adaptive Structure Discovery)
 
 This step establishes the **target structure** that aggregated content must fit into. The structure is NOT assumed -- it is derived from the current document.
 
-1. Read `.ai-agents/knowledge/project/_generated/project-context.md`.
-   - Already required by preflight; if discovered missing here, STOP and recommend `/mvt-analyze-code`.
+1. Read the project-context file: always read `.ai-agents/knowledge/project/_generated/project-context.md` (flat path, regardless of project count).
+   - **Multi-project**: the file contains `# Project: {name}` sections; use the routing result from Step 1 to identify which project section(s) are relevant for the current sync operation.
+   - If the file does not exist, STOP and recommend `/mvt-analyze-code`.
 2. Parse the current `.md` into a section map:
    - Each top-level `##` heading -> one section anchor.
    - Record: section title (verbatim), byte range, and a 1-line semantic summary derived from the section's content (e.g., "lists domain terms with definitions" or "describes module dependencies").
@@ -36,7 +48,7 @@ This step establishes the **target structure** that aggregated content must fit
 3. If the document has zero `##` sections (single block) -> STOP. Recommend `/mvt-analyze-code` to establish a sectioned baseline first.
 4. Read `.ai-agents/workspace/project-context.yaml`. Record current `projects[].source_paths`, `modules`, and `tech_stack` for diff comparison in Step 5d.
 
-### Step 3: Extract Artifact Content
+### Step 4: Extract Artifact Content
 
 - **What**: from each selected change-id, extract atomic knowledge items (do not classify yet).
 - **How**:
@@ -45,7 +57,7 @@ This step establishes the **target structure** that aggregated content must fit
      - `analysis.md` -> domain terms, actors, business rules, constraints
      - `implementation.md` -> files added/changed (informs `.yaml` source_paths), realized vs deviated design points
 
-### Step 4: Normalize Extracted Content
+### Step 5: Normalize Extracted Content
 
 Before classifying extracted items against the section map, normalize each item per the **Document Profile: project-context.md** section loaded above. This step strips intra-artifact cross-references -- meaningful in their source document but noise in project-context.md -- before they enter the merge pipeline.
 
@@ -68,7 +80,7 @@ Before classifying extracted items against the section map, normalize each item
    - Was entirely a cross-reference with no independent semantic value -> drop it (it is a pointer, not knowledge).
 3. Any normalization that removes content from a `modify` item (where the item modifies an existing entry) must be flagged in the update plan (Step 6, Table 6b) so the user can verify the substantive meaning was preserved.
 
-### Step 5: Classify Artifact Content
+### Step 6: Classify Artifact Content
 
 - **What**: classify each normalized item against the section map from Step 2.
 - **How**:
@@ -83,7 +95,7 @@ Before classifying extracted items against the section map, normalize each item
      - `modify` -- target section mentions the entity but artifact provides a different value
      - `redundant` -- already present, no change (will be filtered out, not shown to user)
 
-### Step 6: Render the Update Plan (Four Tables)
+### Step 7: Render the Update Plan (Four Tables)
 
 #### 6a. Section-mapped items
 | # | change-id | item | type | target section | classification |
@@ -101,7 +113,7 @@ Before classifying extracted items against the section map, normalize each item
 | # | yaml field | current | proposed |
 |---|------------|---------|----------|
 
-### Step 7: User Confirmation (Per-Table)
+### Step 8: User Confirmation (Per-Table)
 
 - **6a**: default = accept all. User input: indices to drop, or `e <n>` to edit a single item's target section.
 - **6b**: **explicit per-row decision required**. Format `<index>:<keep|replace|edit>`. Example: `1:replace,2:keep,3:edit`. No default.
@@ -110,7 +122,7 @@ Before classifying extracted items against the section map, normalize each item
 
 Then ask: **"Run optional read-only code verification before applying? (y/n)"**
 
-### Step 8: (Optional) Read-only Code Verification
+### Step 9: (Optional) Read-only Code Verification
 
 This step catches artifacts claiming entities never actually delivered. It is **read-only** -- it never writes anything to `.md` or `.yaml`.
 
@@ -129,9 +141,9 @@ If user opts in:
 
 3. Re-render the apply list with `verified` / `unverified` markers; final confirmation.
 
-If user skips verification: proceed directly to Step 9 with Step 7 selections.
+If user skips verification: proceed directly to Step 10 with Step 7 selections.
 
-### Step 9: Apply Updates (Merge Mode)
+### Step 10: Apply Updates (Merge Mode)
 
 - **Pre-write**:
   1. Backup: `project-context.md` -> `project-context.md.bak`; `project-context.yaml` -> `project-context.yaml.bak`. Overwrite any prior `.bak`.
@@ -142,7 +154,8 @@ If user skips verification: proceed directly to Step 9 with Step 7 selections.
   2. Each `modify` item with `replace`: replace the matching line in place. Smallest possible diff.
   3. Each `orphan` item with new-section choice: append a new `##` section at end of file.
   4. **Never delete** any existing line. **Never reorder** existing sections.
-  5. All merged content must already be normalized per Step 4 rules. Do not re-introduce stripped references during inline replacement or append operations.
+  5. **Multi-project files**: use `# Project: {name}` headings to scope merges to the correct project section. New items for project X go into its `# Project: X` section; do not mix cross-project content.
+  6. All merged content must already be normalized per Step 4 rules. Do not re-introduce stripped references during inline replacement or append operations.
 
 - **Update `project-context.yaml`** (structured merge):
   1. Apply accepted entries from Table 6d.
@@ -151,7 +164,7 @@ If user skips verification: proceed directly to Step 9 with Step 7 selections.
 
 - **Atomicity**: temp + rename per file. If `.md` write succeeds but `.yaml` fails (or vice versa) -> restore the failed one from `.bak`, keep the other; report partial success.
 
-### Step 10: Report
+### Step 11: Report
 
 1. **Applied summary** -- counts: items added / modified / skipped / orphaned-into-new-section
 2. **Files changed** -- paths + byte deltas
@@ -165,9 +178,10 @@ If user skips verification: proceed directly to Step 9 with Step 7 selections.
    - Aggregated >= 1 change -> "Run `/mvt-cleanup` to archive these completed changes."
    - Verification flagged code-only entities -> "Run `/mvt-analyze-code` to capture missing entities."
 
-### Step 11: State Update
+### Step 12: State Update
 Apply the State Update rules defined in the **State Update** section below.
 - The `--set-synced` parameter updates `session.last_synced_at`.
+- Pass `--projects` to plan-update.cjs when updating a plan that has project attribution.
 
 ## Edge Cases & Errors
 

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

@@ -88,7 +88,7 @@
 |------|----------|
 | User selects a `#` that doesn't exist in inventory | Re-display the table, ask again |
 | `customize` validation fails repeatedly | After two failed attempts, suggest user export to a file and edit manually, then re-import via `customize` with `free-form patch` |
-| Custom file exists but registry no longer references the template (`Orphan-custom`) | Allow `view` and `reset`; refuse `customize` (stale target); recommend running `/mvt-init --refresh` or removing the file manually |
+| Custom file exists but registry no longer references the template (`Orphan-custom`) | Allow `view` and `reset`; refuse `customize` (stale target); recommend running `/mvt-init` (interactive refresh) or removing the file manually |
 | Default file is missing (`Missing`) | Refuse all actions for that row; suggest reinstall (`mvtt install`) |
 | User aborts at any confirmation prompt | Do not modify any file; report "no changes" |
 | External process modified the file between preview and write | Detect via mtime check just before write; abort and re-run preview |

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

@@ -41,11 +41,6 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
-  - type: inline
-    content: |
-      ### Step 4: Pre-flight Checks
-      - No blocking checks required.
-
   - type: file
     source: ./business.md
 

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

@@ -22,7 +22,22 @@
 
 - For each target file, locate or plan its corresponding test file path using the project's test layout convention (mirror under `tests/`, sibling `*.test.ts`, etc.).
 
-### Step 3: Identify Test Scenarios
+### 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-test.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: Identify Test Scenarios
 - **What**: produce a Scenario Table covering happy path, edge, negative, and security cases.
 - **How**:
   1. For each public function / endpoint in scope, list at least: 1 happy path, 1 boundary, 1 invalid input.
@@ -33,7 +48,7 @@
      - Security -> include only when requirements mention auth, data sensitivity, or external input boundaries.
      - Performance -> include only when requirements explicitly state SLAs.
 
-### Step 4: Choose Test Granularity
+### Step 5: Choose Test Granularity
 - **What**: assign each scenario to unit / integration / E2E.
 - **How**: use the rule below; one scenario maps to one granularity.
 
@@ -46,49 +61,49 @@
 - A single scenario should not be tested at multiple granularities unless explicitly required (avoid wasteful duplication).
 - Flag scenarios that need integration but the project lacks an integration test setup -> note in artifact, suggest setup, do not invent a fixture.
 
-### Step 5: Design Test Cases
+### Step 6: Design Test Cases
 - **What**: turn each scenario into a concrete test case row.
 - **How**: each row must include `id | scenario | granularity | preconditions | inputs | actions | expected | rule-traced-to`.
 - Prioritize: every business rule trace must be present; happy paths first, then edges, then negatives, then security/performance.
 - For external dependencies, decide mock/stub/fake per project conventions; document the choice.
 
-### Step 6: Write Test Code
+### Step 7: Write Test Code
 - **What**: emit test files using project conventions.
 - **How**:
   1. Match the project's existing test framework, file layout, and naming.
   2. Test names describe the scenario in business language ("rejects login when password is expired"), not the function name.
   3. Each test follows arrange / act / assert structure with no hidden setup.
-  4. Use mocks/stubs only at boundaries identified in Step 4; do NOT mock the unit under test.
-  5. Do not modify the production code being tested -- if implementation has a bug, surface it (Step 8) and recommend `/mvt-fix`.
+  4. Use mocks/stubs only at boundaries identified in Step 5; do NOT mock the unit under test.
+  5. Do not modify the production code being tested -- if implementation has a bug, surface it (Step 9) and recommend `/mvt-fix`.
   6. Avoid `skip` / `only` / commented-out tests in the final output.
 
-### Step 7: Coverage Analysis (only when `--coverage` flag set)
+### Step 8: Coverage Analysis (only when `--coverage` flag set)
 - **What**: produce a coverage map and gap list.
 - **How**:
-  1. Map each test case (Step 5) back to: a target file/function, and (if available) a business rule from `project-context.md`.
+  1. Map each test case (Step 6) back to: a target file/function, and (if available) a business rule from `project-context.md`.
   2. Identify gaps: target functions with no test, business rules with no test, error paths from `design.md` with no test.
   3. Read coverage thresholds from `.ai-agents/config.yaml` if present; otherwise default targets: line >= 80%, branch >= 70%, business-rule == 100%.
   4. Recommend additional test cases for each gap; do not auto-generate them in this run unless user confirms.
 
-### Step 8: Surface Implementation Issues (if any)
+### Step 9: Surface Implementation Issues (if any)
 - During scenario design or test writing you may discover the implementation is wrong (failing test reveals a real bug, not a test bug).
 - **Do not** modify production code from this skill.
 - Record each finding with: scenario id, expected vs observed, severity (Critical / Warning), and recommend `/mvt-fix`.
 
-### Step 9: Write Artifact
+### Step 10: Write Artifact
 - **Path and template**: as defined in the **Artifact Structure** section below.
 - **Required content** (mapped to template headings):
   - `Scope` -- target files, fallbacks applied.
   - `Test Framework & Layout` -- chosen framework, file layout convention.
-  - `Test Scenarios` -- the Scenario Table from Step 3.
-  - `Test Cases` -- the row-level table from Step 5.
-  - `Granularity Decisions` -- summary from Step 4, including any "needs setup" gaps.
+  - `Test Scenarios` -- the Scenario Table from Step 4.
+  - `Test Cases` -- the row-level table from Step 6.
+  - `Granularity Decisions` -- summary from Step 5, including any "needs setup" gaps.
   - `Coverage Analysis` -- only when `--coverage`; otherwise omit the heading.
-  - `Implementation Issues Found` -- from Step 8; empty list is fine.
+  - `Implementation Issues Found` -- from Step 9; empty list is fine.
   - `Suggested Run Commands` -- one or two commands the user can copy-paste.
 - The actual test files go to the project tree; the artifact is a record.
 
-### Step 10: State Update
+### Step 11: State Update
 Apply the State Update rules defined in the **State Update** section below.
 
 ## Edge Cases & Errors

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

@@ -14,8 +14,8 @@ Resolution rules:
 - If `task_id` is omitted AND exactly one task currently has status `in_progress` -> default to that task.
 - If `task_id` is omitted AND zero or multiple tasks are in_progress -> ask the user to specify.
 - If the user reply is the natural-language form `done` / `blocked: <reason>` (from a workflow skill's soft-prompt) -> map to:
-  - `done` -> task = plan.current_task, new_status = done
-  - `blocked: <reason>` -> task = plan.current_task, new_status = blocked, notes = `<reason>`
+  - `done` -> task = the entry in `plan.current_tasks` matching the current project (or the sole entry if single-project), new_status = done
+  - `blocked: <reason>` -> task = the entry in `plan.current_tasks` matching the current project (or the sole entry if single-project), new_status = blocked, notes = `<reason>`
 
 ### Step 2: Load and Validate Existing Plan
 
@@ -25,14 +25,14 @@ Resolution rules:
 
 ### Step 3: Apply the Update, Recompute, Validate, and Write (via script)
 
-The mechanical work — mutating the task, recomputing `current_task` via the DAG
+The mechanical work — mutating the task, recomputing `current_tasks` via the per-project DAG
 rules, validating the result, and writing back atomically — is performed by a
 deterministic script. Do NOT hand-edit `plan.yaml` or reason through the
-`current_task` selection yourself; call the script with the resolved arguments
+`current_tasks` selection yourself; call the script with the resolved arguments
 from Step 1–2:
 
 ```bash
-node .ai-agents/scripts/plan-update.cjs --plan "<active_change.plan_path>" --task <task_id> --status <new_status> [--artifacts "<comma,separated,paths>"] [--notes "<note text>"]
+node .ai-agents/scripts/plan-update.cjs --plan "<active_change.plan_path>" --task <task_id> --status <new_status> --projects "<comma,separated,project,names>" [--artifacts "<comma,separated,paths>"] [--notes "<note text>"]
 ```
 
 Include `--artifacts` only if artifacts were provided, and `--notes` only if a note was provided; omit each flag otherwise.
@@ -42,23 +42,24 @@ Include `--artifacts` only if artifacts were provided, and `--notes` only if a n
 | `--plan` | `active_change.plan_path` resolved from session.yaml |
 | `--task` | the `task_id` resolved in Step 1 |
 | `--status` | the `new_status` resolved in Step 1 (`pending`/`in_progress`/`done`/`blocked`/`skipped`) |
+| `--projects` | comma-separated project names read from `project-context.yaml > projects[].name` |
 | `--artifacts` | optional; comma-separated paths to append (the script de-duplicates) |
 | `--notes` | optional; overwrites the task's `notes` |
 
 The script performs, deterministically:
 
 1. **Apply**: sets the task status; appends + de-duplicates `--artifacts` (handles `artifacts: null`); overwrites `--notes`; sets `completed_at` to now when status is `done`, else `null`; refreshes `plan.updated_at`.
-2. **Recompute `current_task`** (same rules as before): an `in_progress` task that is not the one just moved to terminal wins; else the first `pending` task whose `depends_on` are all `done` (promoted to `in_progress`); else if all tasks are `done` set `plan.status = done` and `current_task = null`; else `current_task = null` with a blocked-by-dependencies warning.
-3. **Validate** the mutated plan (unique ids, valid `depends_on` references, DAG/no-cycle, ≤1 `in_progress`, every task has acceptance, `completed_at` consistency, `current_task` validity).
+2. **Recompute `current_tasks`** (per-project independent advancement): for each project, finds the `in_progress` task or advances the first `pending` task whose `depends_on` are all in `resolvedIds` (done + skipped; blocked does NOT satisfy). Detects `project_switch` when advancement crosses a project boundary. Plan done -> `current_tasks = {}`.
+3. **Validate** the mutated plan (unique ids, valid `depends_on` references, DAG/no-cycle per project, one `in_progress` per project, every task has acceptance, `completed_at` consistency, `current_tasks` validity, project naming constraint, task project membership).
 4. **Write atomically** (temp + rename) only if validation passes.
 
 **Interpreting the result:**
 
 - **Exit 0**: success. stdout is a single-line JSON object:
   ```json
-  {"ok":true,"task":{"id":"t1","title":"...","old_status":"in_progress","new_status":"done"},"current_task":"t2","plan_status":"in_progress","progress":{"done":1,"total":4},"warning":null}
+  {"ok":true,"task":{"id":"t1","title":"...","old_status":"in_progress","new_status":"done"},"current_tasks":{"default":"t2"},"plan_status":"in_progress","progress":{"done":1,"total":4},"warning":null,"project_switch":null}
   ```
-  Use these fields directly to render the Output Format block. The file is already written — do NOT read it back to verify. If `warning` is non-null, surface it.
+  Use these fields directly to render the Output Format block. The file is already written — do NOT read it back to verify. If `warning` is non-null, surface it. If `project_switch` is non-null, note the project boundary crossing.
 - **Exit 1**: failure. stderr carries the error (invalid status, task not found, validation failure, parse/write error). The file was **not** modified. Report the error to the user and do not fabricate a success summary.
 
 ### Step 4: Output
@@ -67,12 +68,40 @@ Emit the Plan Update summary block defined in the Output Format section. Include
 
 - The task that changed (id, title, old -> new status).
 - A compact table of all tasks with their current status.
-- The new `current_task` (or "(plan complete)" if `plan.status == done`).
+- The new `current_tasks` map (or "(plan complete)" if `plan.status == done`).
+- If `project_switch` was emitted in the script output, note: "Project switch: {from} -> {to}".
 - A one-line "Next" hint:
-  - If a new `current_task` is set -> recommend the skill matching its `skill_hint`.
+  - If `current_tasks` has entries -> recommend the skill matching the relevant task's `skill_hint`.
   - If plan complete -> recommend `/mvt-cleanup` or starting a new change via `/mvt-analyze`.
   - If all remaining tasks are blocked -> recommend resolving the blocker (point at the `notes` of the blocked task).
 
+### Step 5: Epic Advancement Check
+
+After the Step 3 script reports `plan_status: "done"`:
+
+1. Read `session.active_change.epic_id` from session.yaml.
+2. If empty -> skip this step (standard change, no epic context).
+3. If non-empty -> prompt user:
+
+   > This change belongs to epic: **{epic_title}** ({epic_id}).
+   > All plan tasks are complete.
+   >
+   > - **(y)** Mark child done and advance to next sub-change
+   > - **(n)** Keep change open (continue review/test/sync)
+   > - **(defer)** Mark child done but don't advance yet
+
+4. On **y**:
+   - `epic-update.cjs --epic <active_epic.epic_path> --complete-child <active_change.id>`
+   - `session-update.cjs --skill mvt-update-plan --summary "..." --close-change`
+   - Display: next child info from epic-update stdout. Suggest `/mvt-analyze` to start the next sub-change.
+
+5. On **n**: No action. Display reminder: "Change remains open. Run other skills (e.g., `/mvt-review`, `/mvt-test`, `/mvt-fix`) as needed; run `/mvt-update-plan` again when ready to advance the epic."
+
+6. On **defer**:
+   - `epic-update.cjs --epic <active_epic.epic_path> --set-child-status <active_change.id> done`
+   - `session-update.cjs --skill mvt-update-plan --summary "..." --close-change`
+   - Display: "Child marked done, current_change unchanged."
+
 ## Edge Cases & Errors
 
 | Case | Handling |
@@ -81,5 +110,5 @@ Emit the Plan Update summary block defined in the Output Format section. Include
 | Task id provided does not exist in `plan.yaml` | Abort with error listing valid task ids |
 | Transition to `done` but `depends_on` tasks are not all `done` | Warn but allow: "Task marked done despite unfinished dependencies — verify correctness" |
 | All tasks are `done` but user marks another as `in_progress` | Reject: plan is already complete; suggest creating a new change |
-| Circular dependency detected in `depends_on` | Report the cycle and refuse to auto-advance `current_task`; suggest manual fix |
+| Circular dependency detected in `depends_on` | Report the cycle and refuse to auto-advance `current_tasks`; suggest manual fix |
 | `plan.yaml` write fails (permission denied, invalid YAML state) | Abort; do not update session; report the write error |

package/sources/skills/mvt-update-plan/manifest.yaml

@@ -3,7 +3,7 @@ output: .claude/skills/mvt-update-plan/SKILL.md
 
 frontmatter:
   name: mvt-update-plan
-  description: "Update a single task in the active change's plan.yaml: change status, attach artifacts, leave notes, and auto-advance current_task. This skill should be used after a workflow skill finishes work that maps to a plan task, or whenever the user wants to mark a task as done, blocked, or skipped."
+  description: "Update a single task in the active change's plan.yaml: change status, attach artifacts, leave notes, and auto-advance current_tasks. This skill should be used after a workflow skill finishes work that maps to a plan task, or whenever the user wants to mark a task as done, blocked, or skipped."
 
 sections:
   - type: inline
@@ -12,7 +12,7 @@ sections:
 
       ## Purpose
 
-      Apply incremental updates to the active plan.yaml: mark a task done/blocked/skipped, attach the artifacts produced, and let the skill auto-advance `current_task` to the next executable task. AI may invoke this skill on the user's behalf when the user replies to a soft-prompt with `done` / `blocked: <reason>`.
+      Apply incremental updates to the active plan.yaml: mark a task done/blocked/skipped, attach the artifacts produced, and let the skill auto-advance `current_tasks` to the next executable task. AI may invoke this skill on the user's behalf when the user replies to a soft-prompt with `done` / `blocked: <reason>`.
 
   - type: shared
     source: sections/role-header.md
@@ -20,10 +20,10 @@ sections:
       role: Architect
       role_desc: "a Development Planner"
       decision_rules:
-        - rule: "Task id provided AND target status valid -> Apply update, advance current_task, write back"
+        - rule: "Task id provided AND target status valid -> Apply update, advance current_tasks, write back"
         - rule: "Task id missing AND only one task is in_progress -> Default to that task"
-        - rule: "Target status would create an invalid current_task -> Recompute current_task automatically"
-        - rule: "All tasks become done -> Set plan.status = done, current_task = null"
+        - rule: "Target status would create an invalid current_tasks -> Recompute current_tasks automatically"
+        - rule: "All tasks become done -> Set plan.status = done, current_tasks = {}"
         - rule: "active_change.plan_path is empty -> Stop and suggest /mvt-plan-dev"
 
       boundaries:
@@ -94,7 +94,7 @@ sections:
       | ... |
 
       Progress: {done_count}/{total_count}
-      Current task: {new_current_task_id_or_"(plan complete)"}
+      Current tasks: {new_current_tasks_map_or_"(plan complete)"}
 
       ### Next
       {one-line guidance: continue to next task, resolve blocker, or run /mvt-cleanup}
@@ -119,7 +119,7 @@ sections:
             primary_desc: "All tasks complete -- clean up artifacts and prepare to start the next change"
           - condition: "default"
             primary: mvt-implement
-            primary_desc: "Continue with the next current_task"
+            primary_desc: "Continue with the next task from current_tasks"
         alternatives:
           - skill: mvt-resume
             desc: "Refresh context after task transitions"

package/sources/templates/decompose-output/body.md

@@ -0,0 +1,13 @@
+# Epic Decomposition: {Epic Title}
+
+## Vision
+
+## Scope & Out of Scope
+
+## Cross-cutting Concerns
+
+## Child Stories
+
+## Dependency Map
+
+## Open Questions

package/sources/templates/decompose-output/manifest.yaml

@@ -0,0 +1,11 @@
+name: decompose-output
+output: .ai-agents/skills/_templates/decompose-output.md
+
+frontmatter:
+  id: decompose-output
+  version: "1.0"
+  skill: mvt-decompose
+
+sections:
+  - type: file
+    source: ./body.md