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

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

@@ -1,74 +1,66 @@
-name: mvt-status
-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."
-
-sections:
-  - type: inline
-    content: |
-      # MVT Status
-
-      ## Purpose
-
-      Display comprehensive project and workflow status, showing progress through development phases, active changes, and current session state.
-
-  - type: shared
-    source: sections/role-header.md
-    params:
-      role: Conductor
-      role_desc: "a Workflow Coordinator"
-      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"
-      boundaries:
-        - scope: "analyze requirements"
-          skill: "/mvt-analyze"
-        - scope: "design architecture"
-          skill: "/mvt-design"
-        - scope: "write implementation code"
-          skill: "/mvt-implement"
-
-  - type: shared
-    source: sections/activation-load-context.md
-
-  - type: shared
-    source: sections/activation-load-config.md
-
-  - type: shared
-    source: sections/activation-preflight.md
-    params:
-      checks:
-        - 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.
-
-  - 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.
-
-      ## Suggested Next Steps
-      After completion, suggest the logical next workflow step based on current progress.
+name: mvt-status
+output: .claude/skills/mvt-status/SKILL.md
+
+frontmatter:
+  name: mvt-status
+  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
+    content: |
+      # MVT Status
+
+      ## Purpose
+
+      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
+    params:
+      role: Conductor
+      role_desc: "a Workflow Coordinator"
+      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 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"
+        - scope: "design architecture"
+          skill: "/mvt-design"
+        - scope: "write implementation code"
+          skill: "/mvt-implement"
+
+  - type: shared
+    source: sections/activation-load-context.md
+
+  - 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: "session.initialized_at"
+          level: "WARN"
+          message: "Session not initialized. Run `/mvt-init` first."
+
+  - type: file
+    source: ./business.md
+
+  - type: shared
+    source: sections/session-update.md
+    params:
+      read_only: true
+
+  - 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)
+## Execution Flow
+
+### 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

@@ -1,84 +1,96 @@
-name: mvt-sync-context
-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."
-
-sections:
-  - type: inline
-    content: |
-      # MVT Sync Context
-
-      ## 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.
-
-  - type: shared
-    source: sections/role-header.md
-    params:
-      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"
-      boundaries:
-        - scope: "analyze requirements"
-          skill: "/mvt-analyze"
-        - scope: "design architecture"
-          skill: "/mvt-design"
-        - scope: "write implementation code"
-          skill: "/mvt-implement"
-
-  - 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.)
-
-  - type: shared
-    source: sections/activation-load-context.md
-
-  - type: shared
-    source: sections/activation-load-config.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.
-
-  - 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/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"
+name: mvt-sync-context
+output: .claude/skills/mvt-sync-context/SKILL.md
+
+frontmatter:
+  name: mvt-sync-context
+  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
+    content: |
+      # MVT Sync Context
+
+      ## Purpose
+
+      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
+    params:
+      role: Conductor
+      role_desc: "a Workflow Coordinator"
+      decision_rules:
+        - 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: "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 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: "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: shared
+    source: sections/session-update.md
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      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"