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

package/install-manifest.yaml

@@ -9,10 +9,10 @@ generated:
     source: "build:templates"
   - pattern: ".ai-agents/knowledge/core/_framework/**"
     source: "copy:sources/knowledge/core/_framework/"
-  - pattern: ".ai-agents/registry.yaml"
-    source: "copy:registry.yaml"
   - pattern: ".ai-agents/scripts/session-update.cjs"
     source: "bundle:sources/scripts/session-update.js"
+  - pattern: ".ai-agents/scripts/plan-update.cjs"
+    source: "bundle:sources/scripts/plan-update.js"
 
 create_once:
   - path: ".ai-agents/config.yaml"
@@ -23,6 +23,10 @@ create_once:
     source: "sources/defaults/project-context.yaml"
   - path: ".ai-agents/knowledge/core/manifest.yaml"
     source: "sources/knowledge/core/manifest.yaml"
+  # Reconcile-merged on update (see src/fs/registry-merge.ts): framework skills
+  # are refreshed, user `custom: true` skills and added knowledge bindings kept.
+  - path: ".ai-agents/registry.yaml"
+    source: "registry.yaml"
 
 user_data_dirs:
   - ".ai-agents/workspace/artifacts/"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uoyo/mvtt",
-  "version": "2.0.0-beta.3",
+  "version": "2.0.0-beta.4",
   "description": "My Virtual Tech Team - AI-guided prompt orchestration framework",
   "type": "module",
   "bin": {

package/sources/scripts/plan-update.js

@@ -0,0 +1,353 @@
+#!/usr/bin/env node
+
+/**
+ * plan-update.js — Mechanical plan.yaml mutation script
+ *
+ * Replaces AI-driven plan.yaml mutation with a deterministic Node.js script.
+ * /mvt-update-plan calls this instead of hand-editing the plan: it applies a
+ * single task status change, recomputes current_task via the DAG rules, runs
+ * the full plan validator, and writes back atomically.
+ *
+ * The LLM stays responsible for the semantic parts (resolving a default task,
+ * mapping natural-language "done"/"blocked: <reason>" to arguments, rendering
+ * the JSON result into the user-facing summary). This script does only the
+ * mechanical, rule-driven work.
+ *
+ * NOTE: This source file uses `import from "yaml"`. During the build pipeline,
+ * esbuild bundles it into a zero-dependency single file deployed to
+ * .ai-agents/scripts/plan-update.cjs.
+ *
+ * Usage:
+ *   node .ai-agents/scripts/plan-update.cjs \
+ *     --plan <path-to-plan.yaml> \
+ *     --task <task_id> \
+ *     --status <pending|in_progress|done|blocked|skipped> \
+ *     [--artifacts "<comma,separated,paths>"] \
+ *     [--notes "<free-form text>"]
+ *
+ * Output:
+ *   Success (exit 0): one-line JSON on stdout, e.g.
+ *     {"ok":true,"task":{...},"current_task":"t2","plan_status":"in_progress",...}
+ *   Failure (exit 1): plain-text error message(s) on stderr
+ */
+
+import { readFileSync, writeFileSync, renameSync, unlinkSync, existsSync } from "node:fs";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+
+// ── Constants ─────────────────────────────────────────────────────────────
+const VALID_STATUSES = ["pending", "in_progress", "done", "blocked", "skipped"];
+const TERMINAL_STATUSES = ["done", "blocked", "skipped"];
+
+const ERRORS = {
+  MISSING_PLAN: () => "Missing required argument: --plan",
+  MISSING_TASK: () => "Missing required argument: --task",
+  MISSING_STATUS: () => "Missing required argument: --status",
+  INVALID_STATUS: (val) =>
+    `Invalid --status "${val}". Must be one of: ${VALID_STATUSES.join(", ")}.`,
+  PLAN_NOT_FOUND: (p) => `Plan not found at ${p}. Run /mvt-plan-dev to create one.`,
+  PLAN_PARSE_FAILED: (detail) =>
+    `Failed to parse plan.yaml: ${detail}. Fix the file manually; not repairing silently.`,
+  TASK_NOT_FOUND: (id, valid) =>
+    `Task "${id}" not found. Valid task ids: ${valid.length ? valid.join(", ") : "(none)"}.`,
+  VALIDATION_FAILED: (errs) =>
+    `Plan validation failed; file not written:\n  - ${errs.join("\n  - ")}`,
+  PLAN_WRITE_FAILED: (detail) => `Failed to write plan.yaml: ${detail}`,
+};
+
+// ── CLI Parsing ─────────────────────────────────────────────────────────────
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i].startsWith("--")) {
+      const key = argv[i].slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith("--")) {
+        args[key] = next;
+        i++;
+      } else {
+        args[key] = true;
+      }
+    }
+  }
+  return args;
+}
+
+function validateArgs(args) {
+  if (!args.plan || args.plan === true) return ERRORS.MISSING_PLAN();
+  if (!args.task || args.task === true) return ERRORS.MISSING_TASK();
+  if (!args.status || args.status === true) return ERRORS.MISSING_STATUS();
+  if (!VALID_STATUSES.includes(args.status)) return ERRORS.INVALID_STATUS(args.status);
+  return null;
+}
+
+// ── Mutation ─────────────────────────────────────────────────────────────────
+function applyUpdate(plan, args, now) {
+  const task = plan.tasks.find((t) => t.id === args.task);
+
+  const oldStatus = task.status;
+  task.status = args.status;
+
+  if (args.artifacts && args.artifacts !== true) {
+    const incoming = args.artifacts
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    if (incoming.length) {
+      // artifacts may be null or missing a `files` key on initial plans.
+      if (!task.artifacts || typeof task.artifacts !== "object") {
+        task.artifacts = { files: [] };
+      }
+      if (!Array.isArray(task.artifacts.files)) {
+        task.artifacts.files = [];
+      }
+      const seen = new Set(task.artifacts.files);
+      for (const f of incoming) {
+        if (!seen.has(f)) {
+          task.artifacts.files.push(f);
+          seen.add(f);
+        }
+      }
+    }
+  }
+
+  if (args.notes && args.notes !== true) {
+    task.notes = args.notes;
+  }
+
+  // completed_at consistency: set only when transitioning to done, else null.
+  task.completed_at = args.status === "done" ? now : null;
+
+  plan.updated_at = now;
+
+  return { id: task.id, title: task.title || "", old_status: oldStatus, new_status: args.status };
+}
+
+// ── current_task recomputation (mirrors mvt-update-plan Step 4) ────────────────
+function recomputeCurrentTask(plan, changedTaskId) {
+  let warning = null;
+
+  const changedTask = plan.tasks.find((t) => t.id === changedTaskId);
+  const changedToTerminal =
+    changedTask && TERMINAL_STATUSES.includes(changedTask.status);
+
+  // 1. An in_progress task that is NOT the one we just moved to terminal wins.
+  const activeInProgress = plan.tasks.find(
+    (t) => t.status === "in_progress" && !(t.id === changedTaskId && changedToTerminal)
+  );
+  if (activeInProgress) {
+    plan.current_task = activeInProgress.id;
+    plan.status = "in_progress";
+    return { warning };
+  }
+
+  // 2. First pending task whose deps are all done.
+  const doneIds = new Set(
+    plan.tasks.filter((t) => t.status === "done").map((t) => t.id)
+  );
+  const nextPending = plan.tasks.find(
+    (t) =>
+      t.status === "pending" &&
+      (t.depends_on || []).every((d) => doneIds.has(d))
+  );
+  if (nextPending) {
+    nextPending.status = "in_progress";
+    plan.current_task = nextPending.id;
+    plan.status = "in_progress";
+    return { warning };
+  }
+
+  // 3. Everything done -> plan complete.
+  if (plan.tasks.every((t) => t.status === "done")) {
+    plan.status = "done";
+    plan.current_task = null;
+    return { warning };
+  }
+
+  // 4. Pending tasks remain but none are executable (blocked by deps).
+  plan.current_task = null;
+  plan.status = "in_progress";
+  warning =
+    "All remaining tasks are blocked by dependencies; resolve a blocker before continuing.";
+  return { warning };
+}
+
+// ── Validation (mirrors mvt-plan-dev Step 5 + mvt-update-plan Step 5) ──────────
+function validatePlan(plan) {
+  const errors = [];
+  const tasks = Array.isArray(plan.tasks) ? plan.tasks : [];
+
+  // Unique ids
+  const ids = tasks.map((t) => t.id);
+  const dupes = ids.filter((id, i) => ids.indexOf(id) !== i);
+  if (dupes.length) {
+    errors.push(`Duplicate task ids: ${[...new Set(dupes)].join(", ")}`);
+  }
+
+  const idSet = new Set(ids);
+
+  // Valid depends_on references
+  for (const t of tasks) {
+    for (const d of t.depends_on || []) {
+      if (!idSet.has(d)) {
+        errors.push(`Task "${t.id}" depends_on unknown task "${d}"`);
+      }
+    }
+  }
+
+  // DAG (no cycles) — only meaningful if all references resolve.
+  const cycle = findCycle(tasks);
+  if (cycle) {
+    errors.push(`Dependency cycle detected: ${cycle.join(" -> ")}`);
+  }
+
+  // At most one in_progress
+  const inProgress = tasks.filter((t) => t.status === "in_progress");
+  if (inProgress.length > 1) {
+    errors.push(
+      `More than one task is in_progress: ${inProgress.map((t) => t.id).join(", ")}`
+    );
+  }
+
+  // Acceptance required
+  for (const t of tasks) {
+    if (!Array.isArray(t.acceptance) || t.acceptance.length === 0) {
+      errors.push(`Task "${t.id}" has no acceptance criteria`);
+    }
+  }
+
+  // completed_at consistency
+  for (const t of tasks) {
+    if (t.status !== "done" && t.completed_at != null) {
+      errors.push(`Task "${t.id}" is not done but has completed_at set`);
+    }
+  }
+
+  // current_task validity
+  if (plan.status === "done") {
+    if (plan.current_task != null) {
+      errors.push("plan.status is done but current_task is not null");
+    }
+  } else if (plan.current_task != null) {
+    const ct = tasks.find((t) => t.id === plan.current_task);
+    if (!ct) {
+      errors.push(`current_task "${plan.current_task}" does not reference a task`);
+    } else if (ct.status !== "pending" && ct.status !== "in_progress") {
+      errors.push(
+        `current_task "${plan.current_task}" has status "${ct.status}" (must be pending or in_progress)`
+      );
+    }
+  }
+
+  return errors;
+}
+
+// Returns an array describing a cycle path, or null if the graph is a DAG.
+function findCycle(tasks) {
+  const adj = new Map();
+  for (const t of tasks) adj.set(t.id, t.depends_on || []);
+
+  const WHITE = 0, GRAY = 1, BLACK = 2;
+  const color = new Map(tasks.map((t) => [t.id, WHITE]));
+  const stack = [];
+
+  function dfs(node) {
+    color.set(node, GRAY);
+    stack.push(node);
+    for (const dep of adj.get(node) || []) {
+      if (!color.has(dep)) continue; // unresolved ref handled elsewhere
+      if (color.get(dep) === GRAY) {
+        const start = stack.indexOf(dep);
+        return [...stack.slice(start), dep];
+      }
+      if (color.get(dep) === WHITE) {
+        const found = dfs(dep);
+        if (found) return found;
+      }
+    }
+    stack.pop();
+    color.set(node, BLACK);
+    return null;
+  }
+
+  for (const t of tasks) {
+    if (color.get(t.id) === WHITE) {
+      const found = dfs(t.id);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+function main() {
+  const args = parseArgs(process.argv);
+
+  const argErr = validateArgs(args);
+  if (argErr) {
+    process.stderr.write(argErr + "\n");
+    process.exit(1);
+  }
+
+  if (!existsSync(args.plan)) {
+    process.stderr.write(ERRORS.PLAN_NOT_FOUND(args.plan) + "\n");
+    process.exit(1);
+  }
+
+  let plan;
+  try {
+    plan = parseYaml(readFileSync(args.plan, "utf-8"));
+  } catch (e) {
+    process.stderr.write(ERRORS.PLAN_PARSE_FAILED(e.message) + "\n");
+    process.exit(1);
+  }
+
+  if (!plan || !Array.isArray(plan.tasks)) {
+    process.stderr.write(ERRORS.PLAN_PARSE_FAILED("missing tasks[]") + "\n");
+    process.exit(1);
+  }
+
+  if (!plan.tasks.some((t) => t.id === args.task)) {
+    process.stderr.write(
+      ERRORS.TASK_NOT_FOUND(args.task, plan.tasks.map((t) => t.id)) + "\n"
+    );
+    process.exit(1);
+  }
+
+  const now = new Date().toISOString();
+
+  const taskChange = applyUpdate(plan, args, now);
+  const { warning } = recomputeCurrentTask(plan, args.task);
+
+  const validationErrors = validatePlan(plan);
+  if (validationErrors.length) {
+    process.stderr.write(ERRORS.VALIDATION_FAILED(validationErrors) + "\n");
+    process.exit(1);
+  }
+
+  const tmpPath = args.plan + ".tmp";
+  try {
+    writeFileSync(tmpPath, stringifyYaml(plan), "utf-8");
+    renameSync(tmpPath, args.plan);
+  } catch (e) {
+    try {
+      if (existsSync(tmpPath)) unlinkSync(tmpPath);
+    } catch {
+      // best effort
+    }
+    process.stderr.write(ERRORS.PLAN_WRITE_FAILED(e.message) + "\n");
+    process.exit(1);
+  }
+
+  const doneCount = plan.tasks.filter((t) => t.status === "done").length;
+  const result = {
+    ok: true,
+    task: taskChange,
+    current_task: plan.current_task ?? null,
+    plan_status: plan.status,
+    progress: { done: doneCount, total: plan.tasks.length },
+    warning,
+  };
+  process.stdout.write(JSON.stringify(result) + "\n");
+}
+
+main();

package/sources/sections/output-format-constraint.md

@@ -0,0 +1,14 @@
+## Output Format Constraint (Mandatory)
+
+All persisted document output (markdown written to disk) MUST follow the formatting rules below. These rules govern *how* content is rendered, independent of the language it is written in.
+**Scope**: artifact files, generated reports, plans, design documents, and any markdown written to disk. These rules do NOT apply to conversational output in the chat.
+
+**Rules**:
+- **Diagrams**: Express flowcharts, architecture, sequence, and structure diagrams as fenced `mermaid` code blocks. Do NOT draw diagrams with ASCII art (boxes made of `+`, `-`, `|`, arrows like `-->` outside mermaid, etc.).
+- **Tables**: Render tabular data as Markdown tables (`| col | col |`). Do NOT simulate tables with space- or tab-aligned text.
+- **Code**: Place code, commands, and config snippets in fenced code blocks with a language tag (e.g. ```` ```ts ````, ```` ```bash ````, ```` ```yaml ````). Do NOT leave code in bare or untagged fences.
+- **Headings**: Use the Markdown heading hierarchy (`#` -> `##` -> `###`) without skipping levels. Do NOT use bold text as a substitute for a heading.
+
+**Notes**:
+- If a diagram genuinely cannot be expressed in mermaid (e.g. a precise spatial/pixel layout), state that explicitly and prefer a Markdown table or prose description over ASCII art.
+- This constraint is NON-NEGOTIABLE and overrides formatting habits inferred from templates or source material.

package/sources/sections/project-context-profile.md

@@ -0,0 +1,29 @@
+## Document Profile: project-context.md
+
+Before writing to `project-context.md`, understand what this document IS and IS NOT.
+
+### Identity
+`project-context.md` is the project's **long-term semantic ground truth** -- a self-contained knowledge base consumed by AI skills to make decisions. It is NOT a copy of design documents, NOT a changelog, NOT an ADR index.
+
+### Audience
+The readers are AI skill instances (implementer, designer, tester, reviewer), NOT humans reading for reference. They use this document to make **binary decisions** (is this import legal? does this test cover this rule?) -- not to trace design rationale.
+
+### Content Quality Standards
+Every piece of content written into `project-context.md` must satisfy ALL of the following:
+
+1. **Self-contained**: understandable without consulting any external document, artifact, or ADR.
+2. **Actionable**: usable by an AI skill to make a yes/no decision or produce a concrete output (e.g., a test case).
+3. **Atomic**: each item is independently meaningful -- not a fragment of a larger argument that only makes sense in its source document.
+4. **Lean**: the token budget for this document is <= 4000 (healthy threshold). Content that does not directly serve a decision should be excluded.
+5. **Stable**: only persist knowledge with long-term reference value. Transient state (change metadata, in-progress decisions, temporary workarounds) belongs in session.yaml or artifacts.
+
+### Governing Principle (What Does NOT Belong)
+**If a reader must consult an external document to understand an entry, that entry -- or its reference marker -- does not belong here.**
+
+Strip any cross-reference marker (pointers to ADRs, design-document section numbers, internal rule labels, etc.). Remove only the *reference marker*, NEVER the *substantive content* it annotates.
+
+- ✅ `idempotency key or exists-or-skip semantics (ADR-06, §12.4)` → `idempotency key or exists-or-skip semantics`
+- ✅ `B-1: resume() degrades to rebuild on protocol error` → `resume() degrades to rebuild on protocol error`
+- ❌ `Subscriber Idempotency Contract` -- this is the term itself, keep it.
+
+> This profile applies ONLY when the target document is `project-context.md`. Other knowledge files (principle/, project/, core/user/, etc.) are not governed by it.

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

@@ -44,6 +44,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-analyze-code/manifest.yaml

@@ -14,6 +14,9 @@ sections:
 
       Analyze existing code to generate the project-context.md file, which describes the project's terms, modules, layer structure, business rules, and API overview. This is an independent operation that does not create a change-id.
 
+  - type: shared
+    source: sections/project-context-profile.md
+
   - type: shared
     source: sections/role-header.md
     params:
@@ -56,6 +59,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-cleanup/manifest.yaml

@@ -54,6 +54,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-create-skill/manifest.yaml

@@ -50,6 +50,9 @@ sections:
   - type: shared
     source: sections/output-language-constraint.md
 
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: inline
     content: |
       ### Step 4: Pre-flight Checks

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

@@ -55,6 +55,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-fix/manifest.yaml

@@ -47,6 +47,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-implement/business.md

@@ -14,7 +14,7 @@
   2. Topologically order files by dependency: domain entities -> repositories/adapters -> use-case/services -> controllers/UI.
   3. Group consecutive files that share a single conceptual change into one commit boundary.
   4. For each file, decide: `create | modify | delete`, and write a one-line intent.
-- **Plan-aware behavior**: if `plan.yaml` is present, restrict scope to the files implied by `current_task` (cross-reference `plan.tasks[*].artifacts.files`); do NOT silently expand into other tasks.
+- **Plan-aware behavior**: if `plan.yaml` is present, treat `current_task`'s `artifacts.files` (cross-reference `plan.tasks[*].artifacts.files`) as a **starting-scope hint, not a hard ceiling**. The source of truth for scope remains `design.md`'s `Change Tracking` (per Step 2.1). When `artifacts.files` is `null` or empty, derive scope entirely from `Change Tracking`. If implementation reveals files beyond this hint are genuinely required, do NOT silently expand — surface them via Step 3 confirmation and never absorb files that clearly belong to a different task.
 - **Output of this step**: an in-conversation list shown to user as a preview, with no write yet.
 
 ### Step 3: Confirm Scope (when needed)
@@ -23,6 +23,7 @@
   - The plan introduces a new public API (exported symbol, HTTP endpoint, CLI flag).
   - The plan deletes existing code (delete count > 0).
   - The plan deviates from `design.md` (e.g., adds files not in `Change Tracking` or skips files listed there).
+  - The plan touches files beyond `current_task`'s `artifacts.files` hint (state which files are added and why, in one line each).
 - **Otherwise**: proceed silently.
 - **On deviation from design**: explain the deviation reason in one line; if the deviation is structural (new module, layer change, interface break), STOP and recommend re-running `/mvt-design`.
 
@@ -59,7 +60,12 @@
   3. UI/frontend changes: per project rules, ask user to verify in browser; do NOT claim "tested" if you only ran type-check.
 
 ### Step 7: Write Artifact
-- **Path and template**: as defined in the **Artifact Structure** section below.
+- **Path and template**: as defined in the **Artifact Structure** section below. The artifact filename is ALWAYS `implementation.md` — one file per change, never per task. Do NOT invent task-suffixed names like `implementation-t1.md`.
+- **Multi-task plans (single-file accumulation)**: when `plan.yaml` drives the change and you implement tasks across separate invocations, all task implementations accumulate into the **same** `implementation.md`:
+  1. If `implementation.md` does not yet exist -> create it from the template.
+  2. If it already exists -> read it, then **append** a new `## Task: {current_task_id} — {task_title}` section for this task. Do NOT overwrite prior tasks' sections.
+  3. Under that task section, place this invocation's required content (the headings below). Keep earlier tasks' sections intact.
+  4. For single-task or plan-less changes, write the content at the top level without a per-task wrapper (existing behavior).
 - **Required content** (mapped to template headings):
   - `Implementation Summary` -- one paragraph: what was built, scope.
   - `Files Touched` -- table: path | create/modify/delete | one-line intent.
@@ -71,12 +77,10 @@
 
 ### Step 8: Plan-Aware Progress Hint (if applicable)
 - If `plan.yaml` exists and a single `current_task` covers this implementation, suggest the user run `/mvt-update-plan <task-id> done` (or `blocked` with reason).
+- If the files actually touched differ from `current_task`'s `artifacts.files` (extra files added during Step 3, or planned files left untouched), explicitly remind the user to run `/mvt-update-plan` so the plan's `artifacts.files` reflects reality for `/mvt-resume` and future sessions.
 - Do NOT modify `plan.yaml` directly from this skill; it is owned by `/mvt-update-plan`.
 - Do NOT modify `changes` directly; it is owned by `/mvt-plan-dev` / `/mvt-update-plan`.
 
-### Step 9: State Update
-Apply the State Update rules defined in the **State Update** section below.
-
 ## Edge Cases & Errors
 
 | Case | Handling |

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

@@ -43,6 +43,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-init/manifest.yaml

@@ -59,6 +59,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-manage-context/manifest.yaml

@@ -14,6 +14,9 @@ sections:
 
       Unified CRUD entry point for project context and knowledge entries. Handles add (with AI-driven skill routing), remove, move, rename, and list operations across `project-context.yaml`, `project-context.md`, `knowledge/principle/`, `knowledge/project/`, `knowledge/core/user/`, and the corresponding `registry.yaml` / `core/manifest.yaml` references.
 
+  - type: shared
+    source: sections/project-context-profile.md
+
   - type: shared
     source: sections/role-header.md
     params:
@@ -46,6 +49,9 @@ sections:
   - type: shared
     source: sections/output-language-constraint.md
 
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: inline
     content: |
       ### Step 4: Pre-flight Checks

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

@@ -48,6 +48,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-quick-dev/manifest.yaml

@@ -48,6 +48,9 @@ sections:
   - type: shared
     source: sections/output-language-constraint.md
 
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: inline
     content: |
       ## Operation Mode: Shortcut

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

@@ -65,6 +65,9 @@ sections:
   - type: shared
     source: sections/output-language-constraint.md
 
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: inline
     content: |
       ### Step 4: Pre-flight Checks

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

@@ -62,6 +62,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: