@uoyo/mvtt 2.0.0-beta.0 → 2.0.0-beta.1

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

@@ -3,7 +3,7 @@ output: .claude/skills/mvt-review/SKILL.md
 
 frontmatter:
   name: mvt-review
-  description: "Perform code review for quality, standards compliance, and best practices. Identifies issues by severity and suggests improvements. Use when user wants code reviewed or quality checked."
+  description: "Perform code review for quality, standards compliance, and best practices. This skill should be used when user wants code reviewed, quality checked, or to identify issues before merging."
 
 sections:
   - type: inline
@@ -12,7 +12,7 @@ sections:
 
       ## Purpose
 
-      Review code for quality, standards compliance, and best practices. Identify issues by severity, suggest improvements, and ensure architecture compliance. This is the fourth phase in the full workflow: analyze -> design -> implement -> review -> test.
+      Review code for quality, standards compliance, and best practices. Identify issues by severity, suggest improvements, and ensure architecture compliance.
 
   - type: shared
     source: sections/role-header.md
@@ -21,7 +21,7 @@ sections:
       role_desc: "a Code Quality Guardian"
       decision_rules:
         - rule: "Critical issue found (security, data loss, crash) -> Mark as CRITICAL, require fix before merge"
-        - rule: "Architecture violation found -> Flag for Architect, suggest `/mvt-design`"
+        - rule: "Layer violation found -> Flag for Architect, suggest `/mvt-design`"
         - rule: "Minor style issue -> Note as suggestion, don't block"
         - rule: "Subjective preference -> Mark as \"non-blocking\" optional improvement"
         - rule: "Good code pattern found -> Highlight positively"
@@ -41,7 +41,7 @@ sections:
 
       | Aspect | Focus Areas |
       |--------|-------------|
-      | `architecture` | Pattern compliance, module boundaries, dependency direction |
+      | `architecture` | Layer compliance, module boundaries, dependency direction |
       | `security` | Input validation, injection prevention, authentication |
       | `performance` | N+1 queries, memory leaks, caching |
       | `style` | Naming conventions, formatting, documentation |
@@ -49,15 +49,10 @@ sections:
       Usage: `/mvt-review` or `/mvt-review --aspect {type}`
 
   - type: shared
-    source: sections/activation-load-context.md
-    params:
-      extended_context:
-        - ".ai-agents/knowledge/core/review-principles.md -- Universal review principles"
-        - ".ai-agents/knowledge/principle/coding-standards.md -- Project coding standards"
-        - ".ai-agents/knowledge/patterns/{pattern.active}/review-checklist.md -- Pattern-specific checklist"
+    source: sections/activation-load-config.md
 
   - type: shared
-    source: sections/activation-load-config.md
+    source: sections/output-language-constraint.md
 
   - type: shared
     source: sections/activation-preflight.md
@@ -66,41 +61,27 @@ sections:
         - order: "1"
           field: "session.initialized_at"
           level: "WARN"
-          message: 'Session not initialized. Run `/mvt-init` first.'
+          message: "Session not initialized. Run `/mvt-init` first."
         - order: "2"
           field: "no code to review"
           level: "WARN"
-          message: 'No code to review. Run `/mvt-implement` first or specify files.'
-        - order: "3"
-          field: "pattern.active"
-          level: "WARN"
-          message: 'Architecture pattern not set. Suggest `/mvt-init`." (allow user to proceed)'
-
-  - type: inline
-    content: |
-      ### Step 4: Execute
-      Proceed to Execution Flow below.
+          message: "No code to review. Run `/mvt-implement` first or specify files."
 
   - type: file
     source: ./business.md
 
   - type: inline
     content: |
-      ## Output Format
-
-      Read and use the output template from: `.ai-agents/skills/_templates/review-output.md`
-
+      ## Artifact Structure
+      Read the document structure template from: `.ai-agents/skills/_templates/review-output.md`
       If a custom version exists at `.ai-agents/skills/_templates/custom/review-output.md`, use the custom version instead.
+      The template defines section headings only. Generate content for each section based on review results.
+      Write the artifact to: `.ai-agents/workspace/artifacts/{change-id}/review.md`
 
-      Fill the template placeholders with the review results.
-
-      Every response MUST end with a Suggested Next Steps section.
+  - type: shared
+    source: sections/session-update.md
 
   - type: shared
     source: sections/footer-next-steps.md
     params:
-      next_primary: mvt-fix
-      next_primary_desc: "Address critical issues"
-      next_alternatives:
-        - skill: mvt-test
-          when: "Add missing tests"
+      current_skill: mvt-review

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

@@ -1,24 +1,71 @@
-## Execution Flow
-
-### Step 1: Load State
-- Read `session.yaml` for progress, active change, recent actions
-- Read `project-context.yaml` for project info, tech stack, architecture
-
-### Step 2: Determine Current Phase
-- Check `progress` fields (analyze, design, implement, review, test)
-- Identify which phases are `done`, `pending`, or `in-progress`
-- Determine the current active phase
-
-### Step 3: Build Workflow Visualization
-- Generate Mermaid flowchart showing phase progression
-- Color-code phases: green (done), yellow (current), gray (pending)
-
-### Step 4: Compile Status Report
-- Project info summary
-- Progress table with phase status
-- Active change details (if any)
-- Recent actions history
-
-### Step 5: Suggest Next Step
-- Based on current progress, recommend the logical next command
-- If all phases done -> Suggest `/mvt-cleanup` or starting a new feature
+## Execution Flow
+
+### Step 1: Load Inputs
+- **Recommended**:
+  - `.ai-agents/knowledge/project/_generated/project-context.md` -- semantic context (only checked for existence here, not parsed).
+- **Fallback / robustness**:
+  - If a YAML file is missing, mark its section as `(unavailable)` in the report and continue. Do not abort the whole skill.
+  - If a YAML file fails to parse, surface a one-line error with the file path and skip the affected section. Do not attempt automatic repair.
+  - 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.
+- **How**:
+  1. Read `skill_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`).
+  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 |
+  | 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 |
+
+### Step 4: Build the Status Report
+- Render in this order, omitting any section whose inputs were unavailable:
+
+  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`.
+  5. **Changes Overview** -- table from Step 3 (skip if no plans). Render with these columns:
+
+     | change-id | title | status | progress | current_task | last_updated |
+     |-----------|-------|--------|----------|--------------|--------------|
+  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.
+
+### 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.
+- 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 |
+| 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 |
+| 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

@@ -3,7 +3,7 @@ output: .claude/skills/mvt-status/SKILL.md
 
 frontmatter:
   name: mvt-status
-  description: "Show current project and workflow status including progress through phases, active changes, and session state. Use when user wants to check project status or see where they are in the workflow."
+  description: "Display current project and workflow status including skill history, active changes, and session state. This skill should be used when user wants to check project status, review workflow progress, or see where they are in the development cycle."
 
 sections:
   - type: inline
@@ -12,7 +12,7 @@ sections:
 
       ## Purpose
 
-      Display comprehensive project and workflow status, showing progress through development phases, active changes, and current session state.
+      Display comprehensive project and workflow status, showing project list, semantic context availability, skill history, active changes, and current session state.
 
   - type: shared
     source: sections/role-header.md
@@ -22,7 +22,10 @@ sections:
       decision_rules:
         - rule: "If project not initialized -> Warn and suggest `/mvt-init`"
         - rule: "If no active change -> Show project info only, suggest starting a workflow"
-        - rule: "If workflow in progress -> Highlight current phase and next recommended step"
+        - 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"
       boundaries:
         - scope: "analyze requirements"
           skill: "/mvt-analyze"
@@ -37,6 +40,9 @@ 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:
@@ -44,31 +50,17 @@ sections:
         - order: "1"
           field: "session.initialized_at"
           level: "WARN"
-          message: 'Session not initialized. Run `/mvt-init` first.'
-        - order: "2"
-          field: "project.name"
-          level: "WARN"
-          message: 'Project not initialized. Run `/mvt-init` first.'
-
-  - type: inline
-    content: |
-      ### Step 4: Execute
-      Proceed to Execution Flow below.
+          message: "Session not initialized. Run `/mvt-init` first."
 
   - type: file
     source: ./business.md
 
-  - type: inline
-    content: |
-      ## Output Format
-
-      Read and use the output template from: `.ai-agents/skills/_templates/status-output.md`
-
-      If a custom version exists at `.ai-agents/skills/_templates/custom/status-output.md`, use the custom version instead.
-
-      Fill the template placeholders with the current state data.
-
-      Every response MUST end with a Suggested Next Steps section.
+  - type: shared
+    source: sections/session-update.md
+    params:
+      read_only: true
 
-      ## Suggested Next Steps
-      After completion, suggest the logical next workflow step based on current progress.
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-status

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

@@ -1,25 +1,150 @@
 ## Execution Flow
 
-### Step 1: Detect Changes
-- If git available:
-  - Run `git diff --name-only` (unstaged changes)
-  - Run `git diff --name-only --cached` (staged changes)
-  - Run `git diff --name-only HEAD~1` (last commit changes)
-  - Merge results and deduplicate
-- If git not available:
-  - Scan for recently modified files in source directories
-
-### Step 2: Analyze Changed Files
-- Read each changed file
-- Extract entities (classes, models, types)
-- Extract services (service classes, API handlers)
-- Extract keywords and topics
-
-### Step 3: Update Workspace
-1. Update `.ai-agents/workspace/project-context.yaml`:
-   - Add new entities to architecture section
-   - Add new services
-   - Update module mappings
-2. Update `.ai-agents/workspace/session.yaml`:
-   - Set `session.last_command: "/mvt-sync-context"`
-   - Append one-line summary to `recent_actions` (keep max 3)
+### 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).
+  5. Exclude `active_change.id` (work in flight).
+
+- **Present** the list:
+
+  | # | change-id | title | status | analysis.md | design.md | implementation.md |
+  |---|-----------|-------|--------|-------------|-----------|-------------------|
+
+- **Always print before user confirmation**:
+  > Run `/mvt-sync-context` BEFORE `/mvt-cleanup`. Once cleanup archives a change-id, this skill will skip it.
+
+- **Prompt**: "Select changes to aggregate. Indices (e.g. 1,3,5), `a` for all, `n` to cancel."
+
+- Cancel / empty selection -> stop with "no changes applied".
+
+### Step 2: 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`.
+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.).
+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.
+
+### Step 3: Extract and Classify Artifact Content
+
+- **What**: from each selected change-id, extract atomic knowledge items and classify them against the section map from Step 2.
+- **How**:
+  1. For each selected change-id, read available artifacts (`analysis.md`, `design.md`, `implementation.md`).
+  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:
+     - 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:
+     - `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)
+
+#### 4a. Section-mapped items
+| # | change-id | item | type | target section | classification |
+|---|-----------|------|------|----------------|----------------|
+
+#### 4b. Conflicts requiring resolution (every `modify` item)
+| # | item | section | current value | proposed value (from {change-id}) |
+|---|------|---------|---------------|-----------------------------------|
+
+#### 4c. Ambiguous and orphan items
+| # | item | reason | candidate sections (or proposed new section) |
+|---|------|--------|----------------------------------------------|
+
+#### 4d. Implied yaml changes
+| # | yaml field | current | proposed |
+|---|------------|---------|----------|
+
+### Step 5: 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.
+
+Then ask: **"Run optional read-only code verification before applying? (y/n)"**
+
+### Step 6: (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`.
+
+If user opts in:
+1. For each accepted item naming a code entity (module path, file, class, function), search the codebase under registered `source_paths`:
+   - Module path -> directory exists?
+   - File -> file exists?
+   - Symbol -> grep within source_paths
+2. Classify findings:
+
+   | Finding | Action |
+   |---------|--------|
+   | Artifact item matches code | Mark `verified`; keep in apply list |
+   | Artifact item NOT found in code | Flag `unverified`; ask user: drop or proceed (likely reverted / un-merged) |
+   | Code contains module / file / symbol that NO artifact item references | **Do NOT add to apply list.** Print: `Code-only entity detected: {path}. Run /mvt-analyze-code for ground-truth rebuild.` |
+
+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.
+
+### Step 7: 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`.
+  2. Backup write failure -> STOP, do not modify originals.
+
+- **Update `project-context.md`** (merge, never rewrite):
+  1. Each `new` item: append to target section, matching the section's existing style (bullet vs paragraph).
+  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.
+
+- **Update `project-context.yaml`** (structured merge):
+  1. Apply accepted entries from Table 4d.
+  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
+
+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):
+   > 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**:
+   - 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.
+
+## Edge Cases & Errors
+
+| Case | Handling |
+|------|----------|
+| `project-context.md` does not exist | Caught at preflight; recommend `/mvt-analyze-code` |
+| `.md` has zero `##` sections | STOP at Step 2; recommend `/mvt-analyze-code` |
+| 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 |

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

@@ -3,7 +3,7 @@ output: .claude/skills/mvt-sync-context/SKILL.md
 
 frontmatter:
   name: mvt-sync-context
-  description: "Synchronize workspace context with code changes after manual modifications or git operations. Use when context seems out of sync with code, after manual edits, or after git merge/rebase."
+  description: "Aggregate completed change artifacts (analysis/design/implementation) and merge new domain knowledge into project-context.md and project-context.yaml. This skill should be used after one or more changes are completed to keep long-term project knowledge in sync with delivered work."
 
 sections:
   - type: inline
@@ -12,7 +12,7 @@ sections:
 
       ## Purpose
 
-      Synchronize the MVTT workspace context with code changes made outside the workflow. This is a code-driven, automatic synchronization that scans git diffs and file changes to update project context.
+      Keep `project-context.md` (semantic) and `project-context.yaml` (structural index) in sync with completed work. This is an artifact-driven, incremental synchronization: it reads workspace artifacts of completed changes, classifies new domain knowledge, and merges it into the long-term context. It does NOT scan code for new content; an optional read-only code verification step can validate that artifact-claimed entities exist.
 
   - type: shared
     source: sections/role-header.md
@@ -20,65 +20,77 @@ sections:
       role: Conductor
       role_desc: "a Workflow Coordinator"
       decision_rules:
-        - rule: "Git available -> Use git diff to detect changes"
-        - rule: "Git not available -> Scan for recently modified files"
-        - rule: "Changes detected -> Analyze and update context"
-        - rule: "No changes detected -> Report context is already in sync"
+        - rule: "Completed changes found -> List for user confirmation, then aggregate"
+        - rule: "No completed changes since last sync -> Report nothing to do"
+        - rule: "Conflicts with existing project-context.md -> Render conflict table, require user resolution"
+        - rule: "User opts in to code verification -> Run read-only scan; flag artifact entries that cannot be located"
+        - rule: "Code-only entities discovered (in code, not in artifacts) -> Do NOT write; recommend /mvt-analyze-code"
+        - rule: "Artifact references modules/source_paths absent from project-context.yaml -> Propose yaml additions for user confirmation"
       boundaries:
-        - scope: "analyze requirements"
-          skill: "/mvt-analyze"
-        - scope: "design architecture"
-          skill: "/mvt-design"
-        - scope: "write implementation code"
-          skill: "/mvt-implement"
+        - scope: "regenerate project-context.md from full code scan"
+          skill: "/mvt-analyze-code"
+        - scope: "archive completed change artifacts"
+          skill: "/mvt-cleanup"
+        - scope: "manage shared / per-skill knowledge files"
+          skill: "/mvt-manage-context"
 
   - type: inline
     content: |
       ### When to Use
-      - After manual code changes outside the workflow
-      - When context seems out of sync with code
-      - After git operations (merge, rebase, etc.)
+      - After one or more changes are marked `completed` and you want to fold their knowledge into long-term context
+      - BEFORE running `/mvt-cleanup` (sync first, archive after)
+      - When `project-context.md` looks behind delivered work but you do not want to pay a full `/mvt-analyze-code` regeneration
+
+      ### When NOT to Use
+      - For deletions, renames, or module deprecations -> use `/mvt-analyze-code` (full ground-truth rebuild)
+      - To pick up code changes never recorded as MVTT changes -> use `/mvt-analyze-code`
+      - To clean / archive workspace -> use `/mvt-cleanup`
 
   - type: shared
     source: sections/activation-load-context.md
+    params:
+      extended_context:
+        - ".ai-agents/workspace/artifacts/{change-id}/ -- Source artifacts for completed changes"
+        - ".ai-agents/knowledge/project/_generated/project-context.md -- Current semantic context (merge target)"
+        - ".ai-agents/workspace/project-context.yaml -- Current structural index (merge target)"
 
   - type: shared
     source: sections/activation-load-config.md
 
+  - type: shared
+    source: sections/output-language-constraint.md
+
   - type: shared
     source: sections/activation-preflight.md
     params:
       checks:
         - order: "1"
-          field: "project-context is empty"
-          level: "WARN"
-          message: 'Project not initialized. Run `/mvt-init` first.'
-
-  - type: inline
-    content: |
-      ### Step 4: Execute
-      Proceed to Execution Flow below.
+          field: "session.initialized_at"
+          level: "BLOCK"
+          message: "Session not initialized. Run `/mvt-init` first."
+        - order: "2"
+          field: ".ai-agents/knowledge/project/_generated/project-context.md exists"
+          level: "BLOCK"
+          message: "project-context.md not found. Run `/mvt-analyze-code` to create the initial document; this skill only handles incremental updates."
 
   - type: file
     source: ./business.md
 
-  - type: inline
-    content: |
-      ## Output Format
-
-      Read and use the output template from: `.ai-agents/skills/_templates/sync-context-output.md`
-
-      If a custom version exists at `.ai-agents/skills/_templates/custom/sync-context-output.md`, use the custom version instead.
-
-      Fill the template placeholders with the sync results.
-
-      Every response MUST end with a Suggested Next Steps section.
+  - type: shared
+    source: sections/session-update.md
 
   - type: shared
     source: sections/footer-next-steps.md
     params:
-      next_primary: mvt-status
-      next_primary_desc: "Verify context state after sync"
-      next_alternatives:
-        - skill: "(continue)"
-          when: "Continue with your current task"
+      current_skill: mvt-sync-context
+      conditional_suggestions:
+        conditions:
+          - condition: "merge applied successfully"
+            primary: "mvt-cleanup"
+            primary_desc: "Archive aggregated change artifacts now that knowledge is sync'd"
+          - condition: "code verification flagged code-only entities"
+            primary: "mvt-analyze-code"
+            primary_desc: "Regenerate project-context.md from full code scan"
+          - condition: "default"
+            primary: "mvt-check-context"
+            primary_desc: "Audit token cost and overall context health"