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

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

@@ -4,8 +4,8 @@
 - **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`.
+  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`).
@@ -32,57 +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`, `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 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`.
 
@@ -101,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`.
@@ -114,15 +142,16 @@ 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
@@ -136,7 +165,7 @@ 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 11: State Update
 Apply the State Update rules defined in the **State Update** section below.
 - The `--set-synced` parameter updates `session.last_synced_at`.
 
@@ -149,7 +178,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-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

@@ -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 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:
 

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

@@ -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: