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

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-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/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

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

@@ -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:
@@ -71,10 +77,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 +96,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"