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

package/install-manifest.yaml

@@ -11,6 +11,8 @@ generated:
     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"
 
 create_once:
   - path: ".ai-agents/config.yaml"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uoyo/mvtt",
-  "version": "2.0.0-beta.1",
+  "version": "2.0.0-beta.3",
   "description": "My Virtual Tech Team - AI-guided prompt orchestration framework",
   "type": "module",
   "bin": {
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && node build-scripts.js",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -45,6 +45,7 @@
     "@types/node": "^25.6.0",
     "@types/prompts": "^2.4.9",
     "@vitest/coverage-v8": "^2.1.9",
+    "esbuild": "^0.28.0",
     "typescript": "^5.4.0",
     "vitest": "^2.0.0"
   },

package/registry.yaml

@@ -100,6 +100,12 @@ skills:
     category: project
 
   # --- Developer Skills ---
+  mvt-bug-detect:
+    agent: analyst
+    description: "Analyze and detect bugs by investigating root cause, assessing severity and impact scope. Produces a structured diagnosis in conversation without applying fixes. This skill should be used when user suspects a bug, wants to understand a problem before fixing, or needs impact analysis."
+    path: .claude/skills/mvt-bug-detect/SKILL.md
+    template: null
+    category: shortcut
   mvt-implement:
     agent: developer
     description: "Implement features based on architecture design. This skill should be used when user wants to implement a feature, write production code, or translate design blueprints into working code."

package/sources/defaults/config.yaml

@@ -1,18 +1,13 @@
 # MVTT Framework - User Configuration
-# Unified config center: all skills read and enforce these settings via Activation Protocol
-# Modify via: /mvt-config or edit directly
 
 version: "2.0"
 
-# ============================================================
-# User Preferences (enforced by Activation Protocol Step 2)
-# ============================================================
 preferences:
-  # Language used for interactive responses (chat replies, prompts, tables shown to the user)
+  # Language used for interactive responses
   # Options: en-US, zh-CN
   interaction_language: en-US
 
-  # Language used for persistent document output (artifacts, project-context.md, generated reports)
+  # Language used for persistent document output
   # If absent, falls back to interaction_language.
   # Options: en-US, zh-CN
   document_output_language: en-US
@@ -25,3 +20,8 @@ preferences:
   # AI routing for /mvt-manage-context add
   context_routing:
     relevance_threshold: 70  # Skills scored >= this are pre-checked; below are folded
+
+  # Session history limits
+  history_limits:
+    history: 20             # Max history entries (1-100)
+    changes: 20             # Max changes entries (1-100)

package/sources/defaults/session.yaml

@@ -1,31 +1,24 @@
 # Workspace Session State
-# Supports flexible workflows -- no longer bound to a fixed pipeline
 
 session:
   initialized_at: ""
-  last_command: ""
+  last_synced_at: ""
 
-# Current active change (id/title/created_at set by /mvt-analyze;
-# plan_path/has_plan set by /mvt-plan-dev once a plan is generated)
 active_change:
   id: ""
   title: ""
   created_at: ""
   plan_path: ""
-  has_plan: false
 
-# Recent changes with active plans (max 5, owned by /mvt-plan-dev and /mvt-update-plan)
-# Each entry: { id, title, plan_path, last_updated }
-# Status is the responsibility of plan.yaml (read on demand by /mvt-resume).
-recent_changes: []
+changes: []
+  # - id: "chg-001"
+  #   title: "User authentication"
+  #   plan_path: ".ai-agents/workspace/artifacts/chg-001/plan.yaml"
+  #   status: "active"           # active | done | abandoned
+  #   updated_at: "2026-05-23T14:30:00"
 
-# Skill execution history (append-only, max 10)
-# Records which skills have been executed, replacing the old progress field
-skill_history: []
-  # - command: "/mvt-analyze"
+history: []
+  # - skill: "/mvt-analyze"
   #   completed_at: "2026-05-23T14:30:00"
   #   summary: "Analyzed user authentication requirements"
   #   change_id: ""   # set when work belongs to an active change
-
-# Recent actions (append-only, max 5)
-recent_actions: []

package/sources/scripts/session-update.js

@@ -0,0 +1,351 @@
+#!/usr/bin/env node
+
+/**
+ * session-update.js — Mechanical session state mutation script
+ *
+ * Replaces AI-driven YAML mutation with a deterministic Node.js script.
+ * All skills call this script instead of manually editing session.yaml.
+ *
+ * NOTE: This source file uses `import from "yaml"`. During the build
+ * pipeline, esbuild bundles it into a zero-dependency single file that
+ * gets deployed to .ai-agents/scripts/session-update.cjs.
+ *
+ * Usage:
+ *   node .ai-agents/scripts/session-update.cjs \
+ *     --skill <name> \
+ *     --summary <text> \
+ *     [--change-id <id>] \
+ *     [--new-change <title>] \
+ *     [--set-initialized] \
+ *     [--update-change] \
+ *     [--set-plan-path <path>] \
+ *     [--close-change] \
+ *     [--set-change-status <status>] \
+ *     [--no-change] \
+ *     [--set-synced] \
+ *     [--truncate-history <n>]
+ *
+ * Output:
+ *   Success (exit 0): {"ok":true}
+ *   Failure (exit 1): plain text error message on stderr
+ */
+
+import { readFileSync, writeFileSync, renameSync, unlinkSync, existsSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+
+// ── Error Messages ──────────────────────────────────────────────────────────
+// All error messages centralized here for visibility and easy maintenance.
+// Each key maps to a function that returns the stderr message string.
+
+const ERRORS = {
+  MISSING_SKILL:    () => "Missing required argument: --skill",
+  MISSING_SUMMARY: () => "Missing required argument: --summary",
+  CHANGE_ID_REQUIRED: () => "--new-change requires --change-id",
+  NO_PROJECT_ROOT: () => "Could not find project root (.ai-agents/ directory not found). Make sure you are inside an MVTT project.",
+  NO_SESSION_YAML: () => "session.yaml not found. Run /mvt-init first to initialize the project.",
+  SESSION_PARSE_FAILED: (detail) => `Failed to parse session.yaml: ${detail}. Check the file for syntax errors.`,
+  SESSION_WRITE_FAILED: (detail) => `Failed to write session.yaml: ${detail}`,
+  CONFIG_LIMIT_INVALID: (key, val, min, max, fallback) =>
+    `Warning: config history_limits.${key} value "${val}" is invalid (must be integer ${min}-${max}). Using default ${fallback}.`,
+};
+
+// ── Defaults ────────────────────────────────────────────────────────────────
+const DEFAULT_LIMITS = {
+  history: 20,
+  changes: 20,
+};
+
+const LIMIT_RANGES = {
+  history: { min: 1, max: 100 },
+  changes: { min: 1, max: 100 },
+};
+
+// ── Project Root Resolution ─────────────────────────────────────────────────
+function findProjectRoot(cwd) {
+  let dir = cwd;
+  while (true) {
+    if (existsSync(path.join(dir, ".ai-agents"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// ── 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;
+}
+
+// ── Config Loading ──────────────────────────────────────────────────────────
+function loadHistoryLimits(configPath) {
+  const limits = { ...DEFAULT_LIMITS };
+  if (!existsSync(configPath)) return limits;
+
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    const config = parseYaml(raw);
+    const configured = config?.preferences?.history_limits;
+    if (!configured || typeof configured !== "object") return limits;
+
+    for (const key of Object.keys(DEFAULT_LIMITS)) {
+      const val = configured[key];
+      if (val == null) continue;
+
+      const num = Number(val);
+      const range = LIMIT_RANGES[key];
+      if (!Number.isInteger(num) || num < range.min || num > range.max) {
+        console.warn(ERRORS.CONFIG_LIMIT_INVALID(key, val, range.min, range.max, DEFAULT_LIMITS[key]));
+        continue;
+      }
+      limits[key] = num;
+    }
+  } catch {
+    // If config can't be parsed, use defaults silently
+  }
+  return limits;
+}
+
+// ── Validation ──────────────────────────────────────────────────────────────
+function validate(args) {
+  if (!args.skill) return ERRORS.MISSING_SKILL();
+  if (!args.summary) return ERRORS.MISSING_SUMMARY();
+  if (args["new-change"] && !args["change-id"]) return ERRORS.CHANGE_ID_REQUIRED();
+  return null;
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+function main() {
+  const args = parseArgs(process.argv);
+
+  const validationError = validate(args);
+  if (validationError) {
+    process.stderr.write(validationError + "\n");
+    process.exit(1);
+  }
+
+  const projectRoot = findProjectRoot(process.cwd());
+  if (!projectRoot) {
+    process.stderr.write(ERRORS.NO_PROJECT_ROOT() + "\n");
+    process.exit(1);
+  }
+
+  const sessionPath = path.join(projectRoot, ".ai-agents/workspace/session.yaml");
+  if (!existsSync(sessionPath)) {
+    process.stderr.write(ERRORS.NO_SESSION_YAML() + "\n");
+    process.exit(1);
+  }
+
+  const configPath = path.join(projectRoot, ".ai-agents/config.yaml");
+  const limits = loadHistoryLimits(configPath);
+
+  // Read session
+  let session;
+  try {
+    session = parseYaml(readFileSync(sessionPath, "utf-8"));
+  } catch (e) {
+    process.stderr.write(ERRORS.SESSION_PARSE_FAILED(e.message) + "\n");
+    process.exit(1);
+  }
+
+  const now = new Date().toISOString();
+
+  // ── Mandatory updates ──────────────────────────────────────────────────
+
+  // history append + truncate
+  session.history = session.history || [];
+  // Use --no-change to force empty change_id, otherwise fall back to active_change.id
+  const activeChangeId = args["no-change"] ? "" : (args["change-id"] || session.active_change?.id || "");
+  session.history.push({
+    skill: `/${args.skill}`,
+    completed_at: now,
+    summary: args.summary,
+    change_id: activeChangeId,
+  });
+  if (session.history.length > limits.history) {
+    session.history = session.history.slice(-limits.history);
+  }
+
+  // ── Conditional updates ────────────────────────────────────────────────
+
+  // --new-change: auto-snapshot old active_change, then set new one
+  if (args["new-change"]) {
+    session.active_change = session.active_change || {};
+
+    // Auto-snapshot: if there's an existing active_change with an id, upsert into changes[]
+    if (session.active_change.id) {
+      session.changes = session.changes || [];
+      const existingIdx = session.changes.findIndex(
+        (e) => e.id === session.active_change.id
+      );
+      const snapshotEntry = {
+        id: session.active_change.id,
+        title: session.active_change.title || "",
+        plan_path: session.active_change.plan_path || "",
+        status: "active",
+        updated_at: now,
+      };
+      if (existingIdx >= 0) {
+        session.changes[existingIdx] = snapshotEntry;
+      } else {
+        session.changes.push(snapshotEntry);
+      }
+      // Sort + truncate changes
+      session.changes.sort((a, b) => a.updated_at.localeCompare(b.updated_at));
+      if (session.changes.length > limits.changes) {
+        session.changes = session.changes.slice(-limits.changes);
+      }
+    }
+
+    // Now set new active_change
+    session.active_change.id = args["change-id"];
+    session.active_change.title = args["new-change"];
+    session.active_change.created_at = now;
+    session.active_change.plan_path = "";
+  }
+
+  // --set-initialized
+  if (args["set-initialized"]) {
+    session.session = session.session || {};
+    if (!session.session.initialized_at) {
+      session.session.initialized_at = now;
+    }
+  }
+
+  // --set-synced: set session.last_synced_at to current time
+  if (args["set-synced"]) {
+    session.session = session.session || {};
+    session.session.last_synced_at = now;
+  }
+
+  // --set-plan-path: set active_change.plan_path
+  // NOTE: Must execute BEFORE --update-change so that
+  // the upserted changes entry contains the correct plan_path.
+  if (args["set-plan-path"]) {
+    session.active_change = session.active_change || {};
+    session.active_change.plan_path = args["set-plan-path"];
+  }
+
+  // --update-change: upsert active_change into changes[] + truncate
+  if (args["update-change"]) {
+    session.changes = session.changes || [];
+    const ac = session.active_change || {};
+    const existingIdx = session.changes.findIndex(
+      (e) => e.id === ac.id
+    );
+    const entry = {
+      id: ac.id || "",
+      title: ac.title || "",
+      plan_path: ac.plan_path || "",
+      status: "active",
+      updated_at: now,
+    };
+    if (existingIdx >= 0) {
+      session.changes[existingIdx] = entry;
+    } else {
+      session.changes.push(entry);
+    }
+    // Sort by updated_at ascending, then truncate to limit
+    session.changes.sort(
+      (a, b) => a.updated_at.localeCompare(b.updated_at)
+    );
+    if (session.changes.length > limits.changes) {
+      session.changes = session.changes.slice(-limits.changes);
+    }
+  }
+
+  // --close-change: snapshot active_change to changes[] with status:done, clear active_change
+  if (args["close-change"]) {
+    session.changes = session.changes || [];
+    const ac = session.active_change || {};
+    if (ac.id) {
+      const existingIdx = session.changes.findIndex(
+        (e) => e.id === ac.id
+      );
+      const entry = {
+        id: ac.id,
+        title: ac.title || "",
+        plan_path: ac.plan_path || "",
+        status: "done",
+        updated_at: now,
+      };
+      if (existingIdx >= 0) {
+        session.changes[existingIdx] = entry;
+      } else {
+        session.changes.push(entry);
+      }
+      session.changes.sort(
+        (a, b) => a.updated_at.localeCompare(b.updated_at)
+      );
+      if (session.changes.length > limits.changes) {
+        session.changes = session.changes.slice(-limits.changes);
+      }
+    }
+    // Clear active_change
+    session.active_change = {
+      id: "",
+      title: "",
+      created_at: "",
+      plan_path: "",
+    };
+  }
+
+  // --set-change-status: set status on changes[] entry matching active_change.id
+  if (args["set-change-status"]) {
+    session.changes = session.changes || [];
+    const ac = session.active_change || {};
+    if (ac.id) {
+      const existingIdx = session.changes.findIndex(
+        (e) => e.id === ac.id
+      );
+      if (existingIdx >= 0) {
+        session.changes[existingIdx].status = args["set-change-status"];
+        session.changes[existingIdx].updated_at = now;
+      }
+    }
+  }
+
+  // --truncate-history: keep last N history entries, discard older
+  if (args["truncate-history"]) {
+    const n = Number(args["truncate-history"]);
+    if (Number.isInteger(n) && n > 0) {
+      session.history = session.history || [];
+      if (session.history.length > n) {
+        session.history = session.history.slice(-n);
+      }
+    }
+  }
+
+  // ── Write back atomically ─────────────────────────────────────────────
+  const tmpPath = sessionPath + ".tmp";
+
+  try {
+    writeFileSync(tmpPath, stringifyYaml(session), "utf-8");
+    renameSync(tmpPath, sessionPath);
+  } catch (e) {
+    try {
+      if (existsSync(tmpPath)) unlinkSync(tmpPath);
+    } catch {
+      // Best effort cleanup
+    }
+    process.stderr.write(ERRORS.SESSION_WRITE_FAILED(e.message) + "\n");
+    process.exit(1);
+  }
+
+  process.stdout.write('{"ok":true}\n');
+}
+
+main();

package/sources/sections/activation-load-context.md

@@ -24,3 +24,7 @@ For each entry, resolve files relative to `.ai-agents/{source}`:
 - If the entry lists `files_from_manifest: true`, read `{source}/manifest.yaml` and load every `files[]` entry where `auto_load: true`.
 
 Skip any path that does not exist.
+
+### Archived Artifacts Convention
+
+The directory `.ai-agents/workspace/artifacts/_archived/` contains change-id directories that have been archived by `/mvt-cleanup`. All skills that scan `artifacts/` MUST exclude `_archived/` from their scan scope unless explicitly inspecting archived content.

package/sources/sections/footer-next-steps.md

@@ -22,7 +22,7 @@ Match the current state to one of the conditions below. If none match, use `defa
 ### Resolution order
 
 Infer 2-3 suggestions from:
-- `skill_history` in `session.yaml`
+- `history` in `session.yaml`
 - `category` and `description` of each skill in `registry.yaml`
 - The current `active_change` state (if in progress)
 - The `depends_on` relationships between skills

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

@@ -1,11 +1,11 @@
-## Output Language Constraint (Mandatory)
-
-All persisted document output (files written to disk) MUST be written in the language specified by `preferences.document_output_language` from config.yaml.
-
-**Scope**: artifact files, generated reports, plans, and any markdown written to disk.
-
-**Rules**:
-- Section headings defined in templates may remain in their original language, but all generated **content** MUST use the configured language
-- If `document_output_language` is not set, fall back to `interaction_language`
-- Do NOT infer output language from template headings, user prompt language, or source code comments
-- This constraint is NON-NEGOTIABLE and overrides any other language signals
+## Output Language Constraint (Mandatory)
+
+All persisted document output (files written to disk) MUST be written in the language specified by `preferences.document_output_language` from config.yaml.
+
+**Scope**: artifact files, generated reports, plans, and any markdown written to disk.
+
+**Rules**:
+- Section headings defined in templates may remain in their original language, but all generated **content** MUST use the configured language
+- If `document_output_language` is not set, fall back to `interaction_language`
+- Do NOT infer output language from template headings, user prompt language, or source code comments
+- This constraint is NON-NEGOTIABLE and overrides any other language signals