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

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

@@ -1,11 +1,22 @@
 ## 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`.
-  2. For each candidate, verify `.ai-agents/workspace/artifacts/{change-id}/` exists AND contains at least one of `analysis.md` or `design.md`. Drop entries with only `plan.yaml`.
-  3. (Fallback) If `changes[]` is empty, scan `.ai-agents/workspace/artifacts/*/` directly; offer those with `analysis.md` or `design.md`, marked `unindexed`.
+  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:
      - **Indexed changes**: exclude any `changes[]` entry with `status: abandoned`. For `status: done` entries, Step 1.2's directory existence check already filters out those whose artifacts have been moved to `artifacts/_archived/` by `/mvt-cleanup`.
      - **Fallback scan**: when scanning `artifacts/*/` directly, skip any path under `artifacts/_archived/` (the unified archive directory managed by `/mvt-cleanup`).
@@ -23,66 +34,95 @@
 
 - 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").
-   - The summary is what enables matching in Step 3 -- section titles may be in any language and may not match conventional names (Terms / Modules / etc.).
+   - The summary is what enables matching in Step 5 -- section titles may be in any language and may not match conventional names (Terms / Modules / etc.).
 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 4d.
+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 and Classify Artifact Content
+### Step 4: Extract Artifact Content
 
-- **What**: from each selected change-id, extract atomic knowledge items and classify them against the section map from Step 2.
+- **What**: from each selected change-id, extract atomic knowledge items (do not classify yet).
 - **How**:
-  1. For each selected change-id, read available artifacts (`analysis.md`, `implementation.md`).
+  1. For each selected change-id, read available artifacts (`analysis.md`, `implementation.md`). Do NOT read `design.md` -- design artifacts are not aggregated by this skill.
   2. Extract atomic items. Typical sources:
      - `analysis.md` -> domain terms, actors, business rules, constraints
      - `implementation.md` -> files added/changed (informs `.yaml` source_paths), realized vs deviated design points
-  3. For each item, match to a section from the Step 2 map:
+
+### 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.
+
+1. For each extracted item, apply the normalization rules below (the governing principle lives in the Document Profile; this table lists concrete patterns, non-exhaustive):
+
+   | Pattern | Example | Normalization |
+   |---------|---------|---------------|
+   | ADR reference with section number | `(ADR-06, §12.4)` | Remove the reference; keep the substantive content it annotates |
+   | Bare ADR reference | `per ADR-06`, `(ADR-06)` | Remove entirely |
+   | Section number reference | `§12.4`, `§3.2.1` | Remove entirely |
+   | Design rule label prefix | `B-1:`, `D-7:`, `C-3:` | Remove the prefix; keep the rule text |
+   | Parenthesized design label | `(D-7)`, `(B-4)` | Remove entirely |
+   | Cross-artifact link phrase | `see §X`, `refer to ADR-N` | Remove the link phrase |
+   | Other reference pointing outside project-context.md | Any pattern not listed above | Apply the governing principle: if understanding requires an external document, strip the reference marker |
+
+   **Critical**: strip only the *reference marker*, never the *substantive content* it annotates.
+
+2. After normalization, re-evaluate each item:
+   - Still contains substantive content -> keep for classification in Step 5.
+   - 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 6: Classify Artifact Content
+
+- **What**: classify each normalized item against the section map from Step 2.
+- **How**:
+  1. For each item, match to a section from the Step 2 map:
      - Match by semantic similarity to **section title + 1-line summary**, not by exact string.
      - Confidence levels:
        - **mapped**: exactly one section matches with high confidence
        - **ambiguous**: 2+ sections plausibly match
        - **orphan**: no section matches; propose a new section name
-  4. For each item, also detect change type relative to current section content:
+  2. For each item, also detect change type relative to current section content:
      - `new` -- target section does not contain this entity
      - `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 4: Render the Update Plan (Four Tables)
+### Step 7: Render the Update Plan (Four Tables)
 
-#### 4a. Section-mapped items
+#### 6a. Section-mapped items
 | # | change-id | item | type | target section | classification |
 |---|-----------|------|------|----------------|----------------|
 
-#### 4b. Conflicts requiring resolution (every `modify` item)
+#### 6b. Conflicts requiring resolution (every `modify` item)
 | # | item | section | current value | proposed value (from {change-id}) |
 |---|------|---------|---------------|-----------------------------------|
 
-#### 4c. Ambiguous and orphan items
+#### 6c. Ambiguous and orphan items
 | # | item | reason | candidate sections (or proposed new section) |
 |---|------|--------|----------------------------------------------|
 
-#### 4d. Implied yaml changes
+#### 6d. Implied yaml changes
 | # | yaml field | current | proposed |
 |---|------------|---------|----------|
 
-### Step 5: User Confirmation (Per-Table)
+### Step 8: User Confirmation (Per-Table)
 
-- **4a**: default = accept all. User input: indices to drop, or `e <n>` to edit a single item's target section.
-- **4b**: **explicit per-row decision required**. Format `<index>:<keep|replace|edit>`. Example: `1:replace,2:keep,3:edit`. No default.
-- **4c**: per row, user picks an existing section, types a new section name, or `skip`.
-- **4d**: default = accept; user can drop indices.
+- **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.
+- **6c**: per row, user picks an existing section, types a new section name, or `skip`.
+- **6d**: default = accept; user can drop indices.
 
 Then ask: **"Run optional read-only code verification before applying? (y/n)"**
 
-### Step 6: (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`.
 
@@ -101,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 7 with Step 5 selections.
+If user skips verification: proceed directly to Step 10 with Step 7 selections.
 
-### Step 7: 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`.
@@ -114,15 +154,17 @@ If user skips verification: proceed directly to Step 7 with Step 5 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. **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 4d.
+  1. Apply accepted entries from Table 6d.
   2. Add new `source_paths` to matching project entry; add new modules to `modules[]`.
   3. **Never delete** an existing yaml entry in this skill.
 
 - **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 8: Report
+### Step 11: Report
 
 1. **Applied summary** -- counts: items added / modified / skipped / orphaned-into-new-section
 2. **Files changed** -- paths + byte deltas
@@ -136,9 +178,10 @@ If user skips verification: proceed directly to Step 7 with Step 5 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 9: 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
 
@@ -149,7 +192,7 @@ Apply the State Update rules defined in the **State Update** section below.
 | Selected change-id has only `plan.yaml` | Filtered in Step 1; will not appear |
 | `modify` with `replace` but the existing line cannot be located deterministically | Fall back to append + flag as duplicate-needs-manual-edit; do NOT silently overwrite the wrong line |
 | `.md.bak` already exists | Overwrite (only the most recent backup matters) |
-| User aborts at Step 5 | Do not write; report "no changes applied" |
-| Step 6 verification finds zero matches for everything | Strong warning; require explicit confirm before proceeding (artifacts likely describe planned, not delivered, work) |
-| Two artifacts contradict each other (design says layer A, implementation says layer B) | Surface in Table 4b as cross-artifact conflict; user picks |
-| change-id was archived between Step 1 and Step 7 | Skip with note; do not error the run |
+| User aborts at Step 7 | Do not write; report "no changes applied" |
+| Step 8 verification finds zero matches for everything | Strong warning; require explicit confirm before proceeding (artifacts likely describe planned, not delivered, work) |
+| Two artifacts contradict each other (analysis claims rule X, implementation realizes rule Y) | Surface in Table 6b as cross-artifact conflict; user picks |
+| change-id was archived between Step 1 and Step 9 | Skip with note; do not error the run |

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

@@ -60,6 +60,9 @@ sections:
   - type: shared
     source: sections/output-language-constraint.md
 
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: shared
     source: sections/activation-preflight.md
     params:
@@ -73,6 +76,9 @@ sections:
           level: "BLOCK"
           message: "project-context.md not found. Run `/mvt-analyze-code` to create the initial document; this skill only handles incremental updates."
 
+  - type: shared
+    source: sections/project-context-profile.md
+
   - type: file
     source: ./business.md
 

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-test/manifest.yaml

@@ -57,6 +57,9 @@ sections:
   - type: shared
     source: sections/output-language-constraint.md
 
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: shared
     source: sections/activation-preflight.md
     params:

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
 
@@ -23,54 +23,85 @@ Resolution rules:
 2. Parse YAML; if parse fails or schema is invalid -> stop and report. Do not attempt to repair silently.
 3. Verify the target `task_id` exists in `tasks[]`. If not, list valid ids and stop.
 
-### Step 3: Apply the Update
+### Step 3: Apply the Update, Recompute, Validate, and Write (via script)
 
-Mutate the in-memory plan:
+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_tasks` selection yourself; call the script with the resolved arguments
+from Step 1–2:
 
-1. Find the target task; capture `old_status` for the report.
-2. Set `tasks[i].status = new_status`.
-3. If `artifacts` provided -> append to `tasks[i].artifacts` (de-duplicate).
-4. If `notes` provided -> overwrite `tasks[i].notes`.
-5. Update `plan.updated_at` to current ISO 8601 timestamp.
+```bash
+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>"]
+```
 
-### Step 4: Recompute current_task
+Include `--artifacts` only if artifacts were provided, and `--notes` only if a note was provided; omit each flag otherwise.
 
-Selection logic, in order:
+| Argument | Value source |
+|----------|-------------|
+| `--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` |
 
-1. If any task has status `in_progress` AND it is **not** the task we just changed to a terminal status (done/blocked/skipped) -> `current_task` = that task's id.
-2. Otherwise pick the first task (by array order) where:
-   - `status == pending`
-   - All ids in `depends_on` reference tasks with status `done`
-3. If no such task exists AND every task is `done` -> set `plan.status = done`, `current_task = null`.
-4. If no such task exists but some tasks are still `pending` (because their dependencies are not done -- e.g., everything reachable is blocked) -> set `current_task = null`, leave `plan.status = in_progress`. Surface a warning in the output ("All remaining tasks are blocked by dependencies; resolve a blocker before continuing").
+The script performs, deterministically:
 
-If the selected next task is currently `pending` -> promote it to `in_progress` (so the plan accurately reflects the active focus). Skip this promotion if `plan.status` just transitioned to `done`.
+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_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.
 
-### Step 5: Validate and Write
+**Interpreting the result:**
 
-1. Run the plan validator on the mutated structure.
-2. If validation fails -> abort the write, report the validation errors, leave the original file untouched.
-3. Otherwise, write back to `active_change.plan_path`.
+- **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_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. 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 6: Update Session State
-
-Apply the State Update rules defined in the **State Update** section below, AND the update-plan-specific updates:
-
-- Refresh the matching entry in `changes[]`: `updated_at` -> current ISO 8601 timestamp.
-- Do NOT touch `active_change.plan_path`.
-
-### Step 7: Output
+### Step 4: Output
 
 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 |
@@ -79,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:
@@ -46,6 +46,9 @@ sections:
   - type: shared
     source: sections/output-language-constraint.md
 
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: shared
     source: sections/activation-preflight.md
     params:
@@ -91,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}
@@ -116,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