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

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

@@ -9,24 +9,24 @@
   - If `session.yaml` exists but is empty (zero keys), treat as `not initialized` -> recommend `/mvt-init`.
 
 ### Step 2: Build Activity Timeline
-- **What**: produce the most-recent-first list of skill_history entries with derived metadata.
+- **What**: produce the most-recent-first list of history entries with derived metadata.
 - **How**:
-  1. Read `skill_history` from `session.yaml`.
+  1. Read `history` from `session.yaml`.
   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 `recent_changes[]` from `session.yaml`. 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 `recent_changes` (mark them `unindexed`).
+  1. Iterate `changes[]` from `session.yaml`. 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).
   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**:
 
   | Condition | Action |
   |-----------|--------|
-  | No plans found anywhere | Skip the Changes Overview section entirely; render only legacy `active_change` summary |
+  | No plans found anywhere | Skip the Changes Overview section entirely; render "No active changes." |
   | One plan found | Render Changes Overview with one row |
   | Multiple plans found | Render Changes Overview sorted: `in_progress` desc by `updated_at` first, then `done` desc by `updated_at`, then `abandoned` last |
   | Any plan over the cap (more than ~12 rows) | Show top 10 rows; print a `+N older changes hidden -- see artifacts/` line |
@@ -37,35 +37,31 @@
   1. **Header** -- one-line summary: project name (from `project-context.yaml`), framework version, last synced timestamp.
   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, current phase, start time. Else: `none`.
+  4. **Active Change** -- if `active_change` exists: id, title, start time. Else: `none`.
   5. **Changes Overview** -- table from Step 3 (skip if no plans). Render with these columns:
 
-     | change-id | title | status | progress | current_task | last_updated |
-     |-----------|-------|--------|----------|--------------|--------------|
+     | change-id | title | status | progress | current_task | updated_at |
+     |-----------|-------|--------|----------|--------------|------------|
   6. **Skill History** -- last 5 rows of the timeline from Step 2.
-  7. **Recent Actions** -- compact list (max 5).
 
-- Hard cap: total rendered output should not exceed ~120 lines. If it would, truncate Skill History and Recent Actions first; never truncate the active change or Changes Overview header rows.
+- 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. `active_change` exists but no plan -> infer next workflow phase from `skill_history` (last completed phase determines next).
-  3. No `active_change`, but `project-context.md` is missing -> suggest `/mvt-analyze-code`.
-  4. No `active_change`, no missing context -> suggest `/mvt-analyze` to start a new feature OR `/mvt-help` to browse the catalog.
+  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.
 - The suggestion must be a single line: skill command + one-clause reason.
 
-### Step 6: (session update handled by shared section)
-
 ## Edge Cases & Errors
 
 | Case | Handling |
 |------|----------|
 | `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-sync-context` |
-| `recent_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 |
+| `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 `status` is not one of the known values | Render the raw value verbatim; flag in skip-checks of the report |
-| Both `recent_changes[]` and the artifact glob find the same plan | Deduplicate by `change_id`; prefer the indexed entry's metadata |
+| 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` |

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

@@ -40,9 +40,6 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
-  - type: shared
-    source: sections/output-language-constraint.md
-
   - type: shared
     source: sections/activation-preflight.md
     params:
@@ -64,3 +61,14 @@ sections:
     source: sections/footer-next-steps.md
     params:
       current_skill: mvt-status
+      conditional_suggestions:
+        conditions:
+          - condition: "active change with current_task"
+            primary: mvt-resume
+            primary_desc: "Resume work on the current task"
+          - condition: "project-context.md missing"
+            primary: mvt-analyze-code
+            primary_desc: "Generate semantic project context"
+          - condition: "no active change"
+            primary: mvt-analyze
+            primary_desc: "Start analyzing a new feature"

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

@@ -3,10 +3,12 @@
 ### Step 1: Identify Completed Changes
 - **What**: produce a candidate list of change-ids whose artifacts will be aggregated.
 - **How**:
-  1. Read `session.yaml`. Collect `recent_changes[]` entries with `status: completed`.
-  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 `recent_changes[]` is empty, scan `.ai-agents/workspace/artifacts/*/` directly; offer those with `analysis.md` or `design.md`, marked `unindexed`.
-  4. Exclude any change-id whose directory contains an `_archive/` subfolder (already archived).
+  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 `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`).
   5. Exclude `active_change.id` (work in flight).
 
 - **Present** the list:
@@ -30,58 +32,85 @@ This step establishes the **target structure** that aggregated content must fit
 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 3: 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`, `design.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
-     - `design.md` -> modules, layers, dependency rules, key interfaces, ADRs
      - `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 4: 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 5: 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 6: 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 7: 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 8: (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`.
 
@@ -100,9 +129,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 9 with Step 7 selections.
 
-### Step 7: Apply Updates (Merge Mode)
+### Step 9: 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`.
@@ -113,27 +142,32 @@ 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. 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 10: Report
 
 1. **Applied summary** -- counts: items added / modified / skipped / orphaned-into-new-section
 2. **Files changed** -- paths + byte deltas
 3. **Backup paths** -- so user can manually revert
-4. **Out-of-scope reminder** (always print):
+4. **Synced changes** -- list all change-ids whose knowledge was aggregated in this run:
+   > The following changes have been synced and can be safely archived: {change-id-1}, {change-id-2}, ...
+   > Last synced at: {last_synced_at} (updated by this run)
+5. **Out-of-scope reminder** (always print):
    > This skill processes additions and modifications only. Module deletions, renames, and large refactors are NOT detected here. Run `/mvt-analyze-code` periodically to rebuild from ground truth.
-5. **Suggested next**:
+6. **Suggested next**:
    - 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: (session update handled by shared section)
-- Refresh `session.last_synced_at` to current ISO timestamp.
+### Step 11: State Update
+Apply the State Update rules defined in the **State Update** section below.
+- The `--set-synced` parameter updates `session.last_synced_at`.
 
 ## Edge Cases & Errors
 
@@ -144,7 +178,7 @@ If user skips verification: proceed directly to Step 7 with Step 5 selections.
 | 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,11 +76,17 @@ 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
 
   - type: shared
     source: sections/session-update.md
+    params:
+      current_skill: mvt-sync-context
+      set_synced: true
 
   - type: shared
     source: sections/footer-next-steps.md

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

@@ -82,8 +82,6 @@
 
   3. Never write outside the project root unless an absolute path was explicitly provided by the user.
 
-### Step 5: (session update handled by shared section)
-
 ## Edge Cases & Errors
 
 | Case | Handling |

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

@@ -27,10 +27,10 @@ sections:
         - rule: "User selects \"export\" -> Output template to specified location"
         - rule: "Custom template must preserve frontmatter format"
       boundaries:
-        - scope: "modify default templates in `_templates/` root"
-          skill: "(Only create/modify in `custom/`)"
-        - scope: "modify skill logic"
-          skill: "(Only change output formatting)"
+        - scope: "modify default templates in `_templates/` root (only create/modify in `custom/`)"
+          skill: "(constraint)"
+        - scope: "modify skill logic (only change output formatting)"
+          skill: "(constraint)"
 
   - type: shared
     source: sections/activation-load-context.md
@@ -41,12 +41,9 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
-  - type: shared
-    source: sections/output-language-constraint.md
-
   - type: inline
     content: |
-      ### Step 3: Pre-flight Checks
+      ### Step 4: Pre-flight Checks
       - No blocking checks required.
 
   - type: file
@@ -61,3 +58,11 @@ sections:
     source: sections/footer-next-steps.md
     params:
       current_skill: mvt-template
+      conditional_suggestions:
+        conditions:
+          - condition: "template customized"
+            primary: mvt-status
+            primary_desc: "Check project status"
+          - condition: "template reset to default"
+            primary: mvt-help
+            primary_desc: "Review available skills and templates"

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

@@ -76,8 +76,7 @@
 - Record each finding with: scenario id, expected vs observed, severity (Critical / Warning), and recommend `/mvt-fix`.
 
 ### Step 9: Write Artifact
-- **Path**: `.ai-agents/workspace/artifacts/{active_change.id}/tests/test-design.md`.
-- **Template**: `.ai-agents/skills/_templates/test-output.md` (custom override at `_templates/custom/...` takes precedence).
+- **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.
@@ -89,7 +88,8 @@
   - `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: (session update handled by shared section)
+### Step 10: 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:
@@ -66,7 +69,7 @@ sections:
           level: "WARN"
           message: "Session not initialized. Run `/mvt-init` first."
         - order: "2"
-          field: "no implementation files"
+          field: "implementation files (user args, implementation.md, or source tree)"
           level: "WARN"
           message: "No implementation found. Run `/mvt-implement` first."
 
@@ -95,8 +98,21 @@ sections:
 
   - type: shared
     source: sections/session-update.md
+    params:
+      current_skill: mvt-test
 
   - type: shared
     source: sections/footer-next-steps.md
     params:
       current_skill: mvt-test
+      conditional_suggestions:
+        conditions:
+          - condition: "tests pass, implementation verified"
+            primary: mvt-review
+            primary_desc: "Final code review before merge"
+          - condition: "tests reveal bugs"
+            primary: mvt-fix
+            primary_desc: "Fix the issues found during testing"
+          - condition: "plan exists with remaining tasks"
+            primary: mvt-update-plan
+            primary_desc: "Mark current task done and advance to next"

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

@@ -23,43 +23,45 @@ 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_task` via the 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
+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> [--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`) |
+| `--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_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).
+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_task":"t2","plan_status":"in_progress","progress":{"done":1,"total":4},"warning":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.
+- **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 standard State Update rules (see shared section above) AND the update-plan-specific updates:
-
-- Refresh the matching entry in `recent_changes[]`: `last_updated` -> current ISO 8601 timestamp.
-- Do NOT touch `active_change.has_plan` / `active_change.plan_path`.
-
-### Step 7: Output
+### Step 4: Output
 
 Emit the Plan Update summary block defined in the Output Format section. Include:
 
@@ -70,3 +72,14 @@ Emit the Plan Update summary block defined in the Output Format section. Include
   - If a new `current_task` is set -> recommend the skill matching its `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).
+
+## Edge Cases & Errors
+
+| Case | Handling |
+|------|----------|
+| `plan.yaml` not found at `active_change.plan_path` | Abort with error: "No plan found. Run `/mvt-plan-dev` to create one." |
+| 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 |
+| `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

@@ -24,7 +24,7 @@ sections:
         - 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: "active_change.has_plan is false -> Stop and suggest /mvt-plan-dev"
+        - rule: "active_change.plan_path is empty -> Stop and suggest /mvt-plan-dev"
 
       boundaries:
         - scope: "create new tasks or restructure the plan"
@@ -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:
@@ -55,16 +58,17 @@ sections:
           level: "WARN"
           message: 'Session not initialized. Run `/mvt-init` first.'
         - order: "2"
-          field: "active_change.has_plan"
+          field: "active_change.plan_path"
           level: "BLOCK"
-          message: 'No active plan. Run `/mvt-plan-dev` to create one before updating.'
+          message: 'No active plan. Run `/mvt-plan-dev` to create one.'
 
   - type: inline
     content: |
-      ### Shortcut Operation Rules
-      - Can execute at any time when an active plan exists
-      - Performs surgical edits only -- never overwrites the whole plan structure
-      - Re-validates the resulting plan before writing; aborts on validation failure
+      ## Operation Mode: Shortcut
+
+      This skill operates as a shortcut — it can execute at any time when an active plan exists.
+      - Performs surgical edits only — never overwrites the whole plan structure.
+      - Re-validates the resulting plan before writing; aborts on validation failure.
 
   - type: file
     source: ./business.md
@@ -100,18 +104,9 @@ sections:
 
   - type: shared
     source: sections/session-update.md
-
-  - type: inline
-    content: |
-      ### Update-Plan Specific State Updates
-
-      In addition to the mandatory updates above, this skill MUST refresh `recent_changes` for the active change:
-
-      - Find the entry where `id == active_change.id`. If absent, append one (this should be rare; happens when the plan was created out-of-band).
-      - Set `last_updated` to the current ISO 8601 timestamp.
-      - Trim to max 5 entries (drop the oldest by `last_updated` ascending).
-
-      Do NOT modify `active_change.has_plan` or `active_change.plan_path` here -- those are owned by `/mvt-plan-dev`.
+    params:
+      current_skill: mvt-update-plan
+      update_change: true
 
   - type: shared
     source: sections/footer-next-steps.md

package/dist/build/plan-validator.d.ts

@@ -1,26 +0,0 @@
-export interface PlanValidationError {
-    path: string;
-    message: string;
-}
-export interface PlanTask {
-    id: string;
-    title: string;
-    status: string;
-    depends_on: string[];
-    skill_hint?: string;
-    acceptance?: string[];
-    artifacts?: string[];
-    notes?: string;
-}
-export interface Plan {
-    version: number;
-    change_id: string;
-    title: string;
-    created_at: string;
-    updated_at: string;
-    status: string;
-    current_task: string | null;
-    tasks: PlanTask[];
-}
-export declare function validatePlan(rawYaml: string): PlanValidationError[];
-//# sourceMappingURL=plan-validator.d.ts.map

package/dist/build/plan-validator.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"plan-validator.d.ts","sourceRoot":"","sources":["../../src/build/plan-validator.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,IAAI;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAsID,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,EAAE,CA+GnE"}