@uoyo/mvtt 2.0.0-beta.2 → 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.2",
+  "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/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/session-update.md

@@ -1,47 +1,115 @@
 {{?read_only}}
 ## State Update
 
-This skill is read-only and does NOT modify `.ai-agents/workspace/session.yaml`. No state mutation, no `skill_history` append, no `recent_actions` append.
+This skill is read-only and does NOT modify `.ai-agents/workspace/session.yaml`.
 {{/read_only}}
 {{^read_only}}
-## State Update (Required)
-
-After execution, update `.ai-agents/workspace/session.yaml` with the following fields.
-
-### Mandatory (every skill must set)
-
-- `session.last_command`: Set to the current skill command (e.g., `"/mvt-analyze"`)
-- `skill_history`: Append entry:
-  ```yaml
-  - command: "/{skill-name}"
-    completed_at: "{current timestamp ISO 8601}"
-    summary: "{one-line summary of what was accomplished}"
-    change_id: "{active_change.id if set, otherwise empty string}"
-  ```
-  Keep max 10 entries. If exceeds, drop the oldest. The `change_id` field enables `/mvt-resume` to filter history per change when multiple changes are in flight.
-- `recent_actions`: Append one-line summary with format:
-  `[{YYYY-MM-DD HH:MM}] /{command}: {one-line summary}`
-  Keep max 5 entries. If exceeds, drop the oldest.
-{{#update_active_change}}
+## State Update
+
+After completing the skill's main task, run the session update script **exactly once** with the following arguments:
+
+```bash
+node .ai-agents/scripts/session-update.cjs --skill <skill_command_name> --summary "<concise one-line summary>"{{#update_active_change}} --new-change "<active_change.title>" --change-id <active_change.id>{{/update_active_change}}{{#set_plan_path}} --set-plan-path ".ai-agents/workspace/artifacts/{active_change.id}/plan.yaml"{{/set_plan_path}}{{#update_change}} --update-change{{/update_change}}{{#close_change}} --close-change{{/close_change}}{{#set_change_status}} --set-change-status <status>{{/set_change_status}}{{#no_change}} --no-change{{/no_change}}{{#set_synced}} --set-synced{{/set_synced}}{{#truncate_history}} --truncate-history <count>{{/truncate_history}}{{#update_initialized_at}} --set-initialized{{/update_initialized_at}}
 
-### Conditional (set only when applicable)
+```
 
-- `active_change.id`: Set when this skill creates a new change
-- `active_change.title`: Set when this skill creates a new change
-- `active_change.created_at`: Set when this skill creates a new change
+If the script exits with code 0, the state update was applied successfully; there is no need to read or verify the session file.
+
+### Argument values
+
+| Argument | Value source | Example |
+|----------|-------------|---------|
+| `--skill` | The exact skill command name without the leading `/` | `{{current_skill}}` |
+| `--summary` | A concise one-line description of what this invocation accomplished, in the configured `interaction_language` | `"Identified auth requirements and created change chg-001"` |
+{{#update_active_change}}
+| `--new-change` | The title of the new change being created (same value written to `active_change.title`) | `"User authentication system"` |
+| `--change-id` | The unique identifier of the new change (same value written to `active_change.id`) | `chg-001` |
 {{/update_active_change}}
+{{#set_plan_path}}
+| `--set-plan-path` | The path to the newly created plan.yaml | `".ai-agents/workspace/artifacts/chg-001/plan.yaml"` |
+{{/set_plan_path}}
+{{#update_change}}
+| `--update-change` | Flag only, no value. Upserts the current `active_change` into `changes[]`. | — |
+{{/update_change}}
+{{#close_change}}
+| `--close-change` | Flag only, no value. Snapshots `active_change` into `changes[]` with `status: done`, then clears `active_change`. | — |
+{{/close_change}}
+{{#set_change_status}}
+| `--set-change-status` | The status to set on the `changes[]` entry matching `active_change.id`. Values: `active`, `done`, `abandoned`. | `done` |
+{{/set_change_status}}
+{{#no_change}}
+| `--no-change` | Flag only, no value. Forces `history[].change_id` to empty string (skips `active_change.id` fallback). | — |
+{{/no_change}}
+{{#set_synced}}
+| `--set-synced` | Flag only, no value. Sets `session.last_synced_at` to current time. | — |
+{{/set_synced}}
+{{#truncate_history}}
+| `--truncate-history` | Number of most recent history entries to keep (read from `config.yaml > preferences.history_limits.history`, default 20); older entries are discarded. | `20` |
+{{/truncate_history}}
 {{#update_initialized_at}}
+| `--set-initialized` | Flag only, no value. Set when this skill initializes the project for the first time. | — |
+{{/update_initialized_at}}
 
-### Conditional (set only when applicable)
+{{#update_active_change}}
+### Parameter semantics
 
-- `session.initialized_at`: Set to current timestamp when this skill initializes the project
+| Argument | When to use | Effect on `session.yaml` |
+|----------|-------------|--------------------------|
+| `--new-change` + `--change-id` | Skill creates or identifies a new change | Sets `active_change.id`, `.title`, `.created_at`. Auto-snapshots old `active_change` into `changes[]` if non-empty. Requires both arguments together. |
+{{#set_plan_path}}
+| `--set-plan-path` | Skill creates a new `plan.yaml` for the active change | Sets `active_change.plan_path`. Must be used together with `--update-change`. |
+{{/set_plan_path}}
+{{#update_change}}
+| `--update-change` | Skill creates or modifies a plan (i.e., after `plan.yaml` is written/updated) | Upserts current `active_change` into `changes[]` (with `status: active`), sets `updated_at`, sorts ascending, truncates to configured limit. |
+{{/update_change}}
+{{#close_change}}
+| `--close-change` | All plan tasks are completed | Snapshots `active_change` into `changes[]` with `status: done`, then clears all `active_change` fields. |
+{{/close_change}}
+{{#set_change_status}}
+| `--set-change-status` | Explicitly mark a change as `done` or `abandoned` | Sets `status` on the `changes[]` entry whose `id` matches `active_change.id`. |
+{{/set_change_status}}
+{{#no_change}}
+| `--no-change` | Skill should not be associated with any change | Forces `history[].change_id` to empty string, skipping the `active_change.id` fallback. |
+{{/no_change}}
+{{#set_synced}}
+| `--set-synced` | Skill synchronizes context files | Sets `session.last_synced_at` to the current time. |
+{{/set_synced}}
+{{#truncate_history}}
+| `--truncate-history` | Maintenance: trim old history entries | Keeps the most recent N entries in `history[]`, discards older ones. |
+{{/truncate_history}}
+{{#update_initialized_at}}
+| `--set-initialized` | Skill initializes the project for the first time | Sets `session.initialized_at` (idempotent — only writes if empty). |
 {{/update_initialized_at}}
+{{/update_active_change}}
+{{^update_active_change}}
+### Parameter semantics
+
+| Argument | When to use | Effect on `session.yaml` |
+|----------|-------------|--------------------------|
+{{#update_change}}
+| `--update-change` | Skill modifies a plan (i.e., after `plan.yaml` is updated) | Upserts current `active_change` into `changes[]` (with `status: active`), sets `updated_at`, sorts ascending, truncates to configured limit. |
+{{/update_change}}
+{{#close_change}}
+| `--close-change` | All plan tasks are completed | Snapshots `active_change` into `changes[]` with `status: done`, then clears all `active_change` fields. |
+{{/close_change}}
+{{#set_change_status}}
+| `--set-change-status` | Explicitly mark a change as `done` or `abandoned` | Sets `status` on the `changes[]` entry whose `id` matches `active_change.id`. |
+{{/set_change_status}}
+{{#no_change}}
+| `--no-change` | Skill should not be associated with any change | Forces `history[].change_id` to empty string, skipping the `active_change.id` fallback. |
+{{/no_change}}
+{{#set_synced}}
+| `--set-synced` | Skill synchronizes context files | Sets `session.last_synced_at` to the current time. |
+{{/set_synced}}
+{{#truncate_history}}
+| `--truncate-history` | Maintenance: trim old history entries | Keeps the most recent N entries in `history[]`, discards older ones. |
+{{/truncate_history}}
+{{#update_initialized_at}}
+| `--set-initialized` | Skill initializes the project for the first time | Sets `session.initialized_at` (idempotent — only writes if empty). |
+{{/update_initialized_at}}
+{{/update_active_change}}
 
-### Forbidden
+### Failure handling
 
-- Do NOT update fields not listed above
-- Do NOT overwrite `active_change` unless this skill creates a new change
-- Do NOT modify `skill_history` entries other than appending a new one
-- Do NOT modify `recent_changes` -- it is owned by `/mvt-plan-dev` and `/mvt-update-plan`
-- Do NOT modify `active_change.plan_path` or `active_change.has_plan` -- these are owned by `/mvt-plan-dev`
+If the script fails (non-zero exit), do NOT abort the skill's main task. Continue execution and add a brief note at the end of your response that the session could not be updated.
 {{/read_only}}

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

@@ -71,6 +71,7 @@ sections:
   - type: shared
     source: sections/session-update.md
     params:
+      current_skill: mvt-analyze
       update_active_change: true
 
   - type: shared

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

@@ -71,10 +71,11 @@ sections:
 
   - type: inline
     content: |
-      ### Independent Operation Rules
-      - This is an independent operation -- no workflow prerequisites required
-      - Does NOT create a change-id
-      - Output is written to `.ai-agents/knowledge/project/_generated/project-context.md`
+      ## Operation Mode: Independent
+
+      This is an independent operation — no workflow prerequisites required.
+      - Does NOT create a change-id.
+      - Output is written to `.ai-agents/knowledge/project/_generated/project-context.md`.
 
   - type: file
     source: ./business.md
@@ -89,8 +90,21 @@ sections:
 
   - type: shared
     source: sections/session-update.md
+    params:
+      current_skill: mvt-analyze-code
 
   - type: shared
     source: sections/footer-next-steps.md
     params:
       current_skill: mvt-analyze-code
+      conditional_suggestions:
+        conditions:
+          - condition: "project-context.md generated, no active change"
+            primary: mvt-analyze
+            primary_desc: "Analyze requirements for a new feature"
+          - condition: "project-context.md generated, active change exists"
+            primary: mvt-design
+            primary_desc: "Design with the updated project context"
+          - condition: "analysis revealed outdated knowledge"
+            primary: mvt-manage-context
+            primary_desc: "Update knowledge entries"