@uoyo/mvtt 2.0.0 → 2.2.0

package/install-manifest.yaml

@@ -17,6 +17,10 @@ generated:
     source: "bundle:sources/scripts/plan-update.js"
   - pattern: ".ai-agents/scripts/epic-update.cjs"
     source: "bundle:sources/scripts/epic-update.js"
+  - pattern: ".ai-agents/scripts/plan-update.md"
+    source: "copy:sources/scripts/plan-update.md"
+  - pattern: ".ai-agents/scripts/epic-update.md"
+    source: "copy:sources/scripts/epic-update.md"
 
 create_once:
   - path: ".ai-agents/config.yaml"

package/package.json

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

package/sources/defaults/config.yaml

@@ -20,3 +20,8 @@ preferences:
   history_limits:
     history: 10
     changes: 10
+
+  # Planning granularity for /mvt-plan-dev
+  # Options: coarse (fewer, larger tasks) | medium (balanced) | fine (more, smaller tasks)
+  planning:
+    granularity: medium

package/sources/scripts/epic-update.js

@@ -11,27 +11,9 @@
  * esbuild bundles it into a zero-dependency single file deployed to
  * .ai-agents/scripts/epic-update.cjs.
  *
- * Usage:
- *   node .ai-agents/scripts/epic-update.cjs \
- *     --epic <path-to-epic.yaml> \
- *     --complete-child <change_id>
- *
- *   node .ai-agents/scripts/epic-update.cjs \
- *     --epic <path> \
- *     --set-child-status <change_id> --child-status <status>
- *
- *   node .ai-agents/scripts/epic-update.cjs \
- *     --epic <path> \
- *     --switch-active <change_id>
- *
- *   node .ai-agents/scripts/epic-update.cjs \
- *     --epic <path> \
- *     --add-child <id> --child-title "<t>" --child-scope "<s>" \
- *     [--child-depends-on "dep1,dep2"] \
- *     [--add-child <id2> --child-title "<t2>" ...]
- *
- *   node .ai-agents/scripts/epic-update.cjs \
- *     --validate <path-to-epic.yaml>
+ * Usage: see the "Script Usage Rule" section in any skill that references
+ *   sections/script-usage-rule.md, or read the full reference at
+ *   .ai-agents/scripts/epic-update.md.
  *
  * Output:
  *   Success (exit 0): one-line JSON on stdout
@@ -506,7 +488,76 @@ function main() {
     process.exit(1);
   }
 
-  process.stdout.write(JSON.stringify({ ok: true, ...result }) + "\n");
+  // Best-effort session sync when epic closes (does not affect epic.yaml write).
+  let sessionSync = null;
+  if (epic.status === "done") {
+    sessionSync = syncSessionOnEpicClose(epic, epicPath, now);
+  }
+
+  process.stdout.write(
+    JSON.stringify({ ok: true, ...result, session_sync: sessionSync }) + "\n"
+  );
+}
+
+// ── Session Sync ────────────────────────────────────────────────────────────
+// Best-effort: clears session.active_epic and updates epics[] snapshot when
+// the active epic transitions to "done". Failures are reported in the result
+// but never roll back the epic.yaml write.
+function syncSessionOnEpicClose(epic, epicPath, now) {
+  const projectRoot = findProjectRootFromPath(epicPath);
+  if (!projectRoot) {
+    return { ok: false, reason: "no-project-root" };
+  }
+
+  const sessionPath = join(projectRoot, ".ai-agents", "workspace", "session.yaml");
+  if (!existsSync(sessionPath)) {
+    return { ok: false, reason: "session-missing" };
+  }
+
+  let session;
+  try {
+    session = parseYaml(readFileSync(sessionPath, "utf-8"));
+  } catch (e) {
+    return { ok: false, reason: "parse-failed", detail: e.message };
+  }
+
+  if (!session || typeof session !== "object") {
+    return { ok: false, reason: "session-not-object" };
+  }
+
+  const epicId = epic.epic_id;
+  if (session.active_epic?.id !== epicId) {
+    return { ok: true, applied: false, reason: "active_epic-not-matching" };
+  }
+
+  session.epics = session.epics || [];
+  const epicIdx = session.epics.findIndex((e) => e.id === epicId);
+  if (epicIdx >= 0) {
+    session.epics[epicIdx].status = "done";
+    session.epics[epicIdx].updated_at = now;
+  }
+
+  session.active_epic = {
+    id: "",
+    title: "",
+    created_at: "",
+    epic_path: "",
+  };
+
+  const sessionTmp = sessionPath + ".tmp";
+  try {
+    writeFileSync(sessionTmp, stringifyYaml(session, { lineWidth: 200 }), "utf-8");
+    renameSync(sessionTmp, sessionPath);
+  } catch (e) {
+    try {
+      if (existsSync(sessionTmp)) unlinkSync(sessionTmp);
+    } catch {
+      // best-effort cleanup — temp file overwritten next run
+    }
+    return { ok: false, reason: "write-failed", detail: e.message };
+  }
+
+  return { ok: true, applied: true, epic_id: epicId };
 }
 
 main();

package/sources/scripts/epic-update.md

@@ -0,0 +1,57 @@
+# Epic Update Script — Full Reference
+
+> **This file is the authoritative usage reference for `epic-update.cjs`.**
+> Read this file before calling the script. Do NOT read the `.cjs` or `.js` source to learn flag names or semantics.
+
+The script has five modes — use exactly one mode per invocation:
+
+## Commands
+
+```bash
+# Mode 1 — Complete the current child and advance to the next sub-change
+node .ai-agents/scripts/epic-update.cjs --epic <epic_path> --complete-child <change_id>
+
+# Mode 2 — Set a child's status without advancing current_change
+node .ai-agents/scripts/epic-update.cjs --epic <epic_path> --set-child-status <change_id> --child-status <active|pending|done|abandoned>
+
+# Mode 3 — Switch the active child to a different one (reorder)
+node .ai-agents/scripts/epic-update.cjs --epic <epic_path> --switch-active <change_id>
+
+# Mode 4 — Add one or more children to an existing epic
+node .ai-agents/scripts/epic-update.cjs --epic <epic_path> \
+  --add-child <id> --child-title "<title>" --child-scope "<scope>" [--child-depends-on "dep1,dep2"] \
+  [--add-child <id2> --child-title "<title2>" --child-scope "<scope2>" ...]
+
+# Mode 5 — Validate an epic.yaml (read-only, no write)
+node .ai-agents/scripts/epic-update.cjs --validate <epic_path>
+```
+
+## Argument values
+
+| Argument | Value source | Example |
+|----------|-------------|---------|
+| `--epic` | `active_epic.epic_path` resolved from session.yaml | `".ai-agents/workspace/artifacts/epic-20260608-ecommerce-platform/epic.yaml"` |
+| `--complete-child` | `active_change.id` of the child whose plan is fully done | `20260608-sub` |
+| `--set-child-status` | target child `change_id` to re-status | `20260608-sub` |
+| `--child-status` | new status (with `--set-child-status`): `active` / `pending` / `done` / `abandoned` | `done` |
+| `--switch-active` | target child `change_id` to make the active one | `20260609-sub2` |
+| `--add-child` | new child id (repeatable for multiple children in one invocation) | `20260620-sub3` |
+| `--child-title` | title for the child added by the preceding `--add-child` | `"Cart"` |
+| `--child-scope` | scope description for the child added by the preceding `--add-child` | `"Shopping cart CRUD and checkout flow"` |
+| `--child-depends-on` | optional; comma-separated prerequisite child `change_id` values | `"20260608-sub"` |
+| `--validate` | path to an `epic.yaml` to validate (read-only) | same as `--epic` |
+
+## Parameter semantics
+
+| Argument | When to use | Effect on `epic.yaml` |
+|----------|-------------|------------------------|
+| `--complete-child` | A child change's plan is fully done and the epic should advance | Sets the child `status: done`, advances `current_change` to the next `pending` child whose `depends_on` are all `done` (DAG-based). |
+| `--set-child-status` + `--child-status` | Mark a child `done` or `abandoned` without advancing `current_change` (e.g. defer mode) | Sets the child's status only; `current_change` unchanged. |
+| `--switch-active` | Reorder to a different child (dependencies permitting) | Sets the target child `active`, others `pending`, updates `current_change`. Rejects if the target's `depends_on` have unfinished prerequisites. |
+| `--add-child` (+ `--child-title` / `--child-scope` / `--child-depends-on`) | Append one or more children to an existing epic | Adds entries to `children[]`; validates id uniqueness + DAG; defaults `project` to the sole project name when single-project. |
+| `--validate` | Verify `epic.yaml` integrity (e.g. after `/mvt-decompose` writes it) | Read-only check; no write. Reports DAG/structure errors on stderr. |
+
+## Output interpretation
+
+- **Exit 0**: success. stdout is a single-line JSON object (mirrors `plan-update.cjs` protocol). Use the fields directly to render output. The file is already written — do NOT read it back to verify.
+- **Exit 1**: failure. stderr carries a plain-text error (unknown mode, child not found, dependency unsatisfied, validation failure, parse/write error). The file was **not** modified. Report the error to the user and do not fabricate a success summary.

package/sources/scripts/plan-update.js

@@ -19,16 +19,9 @@
  * 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> \
- *     [--projects "web,api"] \
- *     [--artifacts "<comma,separated,paths>"] \
- *     [--notes "<free-form text>"] \
- *     [--deliverables-pointer current] \
- *     [--mark-deliverable-stale <task_id>[,task_id2,...]]
+ * Usage: see the "Script Usage Rule" section in any skill that references
+ *   sections/script-usage-rule.md, or read the full reference at
+ *   .ai-agents/scripts/plan-update.md.
  *
  * Output:
  *   Success (exit 0): one-line JSON on stdout, e.g.
@@ -124,10 +117,18 @@ function parseArgs(argv) {
 }
 
 function validateArgs(args) {
+  if (args.validate) return null;
   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);
+  const hasStatus = args.status && args.status !== true;
+  const hasMutation = hasStatus ||
+    (args.artifacts && args.artifacts !== true) ||
+    (args.notes && args.notes !== true) ||
+    (args["deliverables-pointer"] && args["deliverables-pointer"] !== true) ||
+    (args["mark-deliverable-stale"] && args["mark-deliverable-stale"] !== true);
+  if (!hasMutation) return ERRORS.MISSING_STATUS();
+  if (args.status === true) return ERRORS.MISSING_STATUS();
+  if (hasStatus && !VALID_STATUSES.includes(args.status)) return ERRORS.INVALID_STATUS(args.status);
   return null;
 }
 
@@ -136,7 +137,9 @@ 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.status && args.status !== true) {
+    task.status = args.status;
+  }
 
   if (args.artifacts && args.artifacts !== true) {
     const incoming = args.artifacts
@@ -164,11 +167,13 @@ function applyUpdate(plan, args, now) {
     task.notes = args.notes;
   }
 
-  // completed_at consistency: set only on first transition to done, else null.
-  if (args.status === "done" && !task.completed_at) {
-    task.completed_at = now;
-  } else if (args.status !== "done") {
-    task.completed_at = null;
+  // completed_at consistency: set only on status updates.
+  if (args.status && args.status !== true) {
+    if (args.status === "done" && !task.completed_at) {
+      task.completed_at = now;
+    } else if (args.status !== "done") {
+      task.completed_at = null;
+    }
   }
 
   // --deliverables-pointer current
@@ -201,7 +206,7 @@ function applyUpdate(plan, args, now) {
 
   plan.updated_at = now;
 
-  return { id: task.id, title: task.title || "", old_status: oldStatus, new_status: args.status };
+  return { id: task.id, title: task.title || "", old_status: oldStatus, new_status: task.status };
 }
 
 // -- current_tasks recomputation (per-project independent advancement) --
@@ -516,6 +521,10 @@ function findCycleInSubgraph(tasks, taskIds) {
 function main() {
   const args = parseArgs(process.argv);
 
+  if (args.validate && args.validate !== true && !args.plan) {
+    args.plan = args.validate;
+  }
+
   const argErr = validateArgs(args);
   if (argErr) {
     process.stderr.write(argErr + "\n");
@@ -540,13 +549,6 @@ function main() {
     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);
-  }
-
   // Parse --projects; if not provided, derive from tasks
   let projectList = null;
   if (args.projects && args.projects !== true) {
@@ -557,10 +559,30 @@ function main() {
     projectList = deriveProjectList(plan.tasks);
   }
 
+  if (args.validate) {
+    const validationErrors = validatePlan(plan, projectList);
+    if (validationErrors.length) {
+      process.stderr.write(ERRORS.VALIDATION_FAILED(validationErrors) + "\n");
+      process.exit(1);
+    }
+    process.stdout.write(JSON.stringify({ ok: true, plan_status: plan.status, tasks: plan.tasks.length }) + "\n");
+    return;
+  }
+
+  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);
+  }
+
   // Migrate old current_task (string) to current_tasks (Record) if needed.
   // Also remove legacy current_task field even when null (YAML `current_task: null`).
   if (plan.current_task != null && (!plan.current_tasks || typeof plan.current_tasks !== "object")) {
-    plan.current_tasks = { default: plan.current_task };
+    const legacyProject = projectList.length === 1
+      ? projectList[0]
+      : (loadSoleProject(findProjectRootFromPath(args.plan))?.[0] || "default");
+    plan.current_tasks = { [legacyProject]: plan.current_task };
   }
   if ("current_task" in plan) {
     delete plan.current_task;
@@ -576,7 +598,13 @@ function main() {
     process.stderr.write(taskChange.error + "\n");
     process.exit(1);
   }
-  const { warning, project_switch: switchNotif } = recomputeCurrentTasks(plan, args.task, projectList);
+  let warning = null;
+  let switchNotif = null;
+  if (args.status && args.status !== true) {
+    const recomputed = recomputeCurrentTasks(plan, args.task, projectList);
+    warning = recomputed.warning;
+    switchNotif = recomputed.project_switch;
+  }
 
   const validationErrors = validatePlan(plan, projectList);
   if (validationErrors.length) {

package/sources/scripts/plan-update.md

@@ -0,0 +1,68 @@
+# Plan Update Script — Full Reference
+
+> **This file is the authoritative usage reference for `plan-update.cjs`.**
+> Read this file before calling the script. Do NOT read the `.cjs` or `.js` source to learn flag names or semantics.
+
+## Command
+
+```bash
+node .ai-agents/scripts/plan-update.cjs \
+  --plan "<active_change.plan_path>" \
+  --task <task_id> \
+  --projects "<comma,separated,project,names>" \
+  [--status <pending|in_progress|done|blocked|skipped>] \
+  [--artifacts "<comma,separated,paths>"] \
+  [--notes "<free-form text>"] \
+  [--deliverables-pointer current] \
+  [--mark-deliverable-stale <task_id>[,task_id2,...]]
+```
+
+Read-only validation mode:
+
+```bash
+node .ai-agents/scripts/plan-update.cjs --validate "<draft-plan-path>" [--projects "<comma,separated,project,names>"]
+```
+
+Include `--artifacts`, `--notes`, `--deliverables-pointer`, and `--mark-deliverable-stale` only when the skill's logic determines they apply; omit each flag otherwise.
+
+## Argument values
+
+| Argument | Value source | Example |
+|----------|-------------|---------|
+| `--plan` | `active_change.plan_path` resolved from session.yaml | `".ai-agents/workspace/artifacts/chg-001/plan.yaml"` |
+| `--task` | the `task_id` being updated (resolved by the skill's Step 1) | `t1` |
+| `--status` | optional; the new status: `pending` / `in_progress` / `done` / `blocked` / `skipped` | `done` |
+| `--projects` | comma-separated project names from `project-context.yaml > projects[].name` (single-project: the sole project name) | `"web,api"` |
+| `--artifacts` | optional; comma-separated paths to append (the script de-duplicates) | `"src/auth.ts,src/auth.test.ts"` |
+| `--notes` | optional; overwrites the task's `notes` | `"blocked on API spec"` |
+| `--deliverables-pointer` | optional; set to `current` to record that this task's deliverables section is written | `current` |
+| `--mark-deliverable-stale` | optional; comma-separated downstream task ids whose deliverables are now stale | `"t3,t4"` |
+| `--validate` | optional read-only validation target; accepts the plan path as its value | `".ai-agents/workspace/artifacts/chg-001/plan.yaml"` |
+
+## Parameter semantics
+
+| Argument | When to use | Effect on `plan.yaml` |
+|----------|-------------|------------------------|
+| `--task` + optional `--status` | Use `--status` for status transitions; omit it for metadata-only updates such as deliverables freshness | When present, sets the task status; sets `completed_at` to now when `done`, else `null`; refreshes `plan.updated_at`. When omitted, status, `completed_at`, DAG advancement, and `current_tasks` are left unchanged. |
+| `--projects` | Always (per-project validation) | Drives per-project DAG advancement of `current_tasks` and per-project validation. Required for correct multi-project plans. |
+| `--artifacts` | Task produced or touched files | Appends + de-duplicates paths into the task's `artifacts.files`; handles `artifacts: null`. |
+| `--notes` | Task needs a free-form note | Overwrites the task's existing `notes`. |
+| `--deliverables-pointer` + `--mark-deliverable-stale` | Task wrote its deliverables section (e.g. `/mvt-implement` Step 8) | Records the deliverables pointer on the task; marks the listed downstream tasks' deliverables as stale so `/mvt-resume` and `/mvt-status` surface a warning. Use both flags together in a single invocation. |
+| `--validate` | `/mvt-plan-dev` has assembled a draft plan before final write | Parses and validates the plan, prints JSON on success, and never writes the file. |
+
+## What the script does (deterministically)
+
+1. **Apply**: when `--status` is present, sets the task status and `completed_at`; appends + de-duplicates `--artifacts`; overwrites `--notes`; refreshes `plan.updated_at`.
+2. **Recompute `current_tasks`** only when `--status` is present (per-project independent advancement): for each project, finds the `in_progress` task or advances the first `pending` task whose `depends_on` are all in `resolvedIds` (done + skipped; blocked does NOT satisfy). Detects `project_switch` when advancement crosses a project boundary. Plan done -> `current_tasks = {}`.
+3. **Validate** the mutated plan (unique ids, valid `depends_on` references, DAG/no-cycle per project, one `in_progress` per project, every task has acceptance, `completed_at` consistency, `current_tasks` validity, project naming constraint, task project membership).
+4. **Write atomically** (temp + rename) only if validation passes.
+
+## Output interpretation
+
+- **Exit 0**: success. stdout is a single-line JSON object, e.g.:
+  ```json
+  {"ok":true,"task":{"id":"t1","title":"...","old_status":"in_progress","new_status":"done"},"current_tasks":{"default":"t2"},"plan_status":"in_progress","progress":{"done":1,"total":4},"warning":null,"project_switch":null}
+  ```
+  Use these fields directly to render output. The file is already written — do NOT read it back to verify. If `warning` is non-null, surface it. If `project_switch` is non-null, note the project boundary crossing.
+- **Exit 1**: failure. stderr carries the error (invalid status, task not found, validation failure, parse/write error). The file was **not** modified. Report the error to the user and do not fabricate a success summary.
+- **Read-only validation**: exit 0 stdout is `{"ok":true,"plan_status":"...","tasks":N}`. Exit 1 stderr carries parse or validation errors; no file is modified.

package/sources/scripts/session-update.js

@@ -10,25 +10,8 @@
  * 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>] \
- *     [--new-epic <title> --epic-id <id>] \
- *     [--set-epic-path <path>] \
- *     [--set-epic-status <status>] \
- *     [--close-epic] \
- *     [--epic-id <id>]   (with --new-change, links sub-change to epic)
+ * Usage: see the "State Update" section in any skill that references
+ *   sections/session-update.md (rendered with per-skill flag parameters).
  *
  * Output:
  *   Success (exit 0): {"ok":true}
@@ -57,6 +40,7 @@ const ERRORS = {
   CLOSE_NEW_EPIC_CONFLICT: () => "--close-epic and --new-epic are mutually exclusive",
   NO_ACTIVE_EPIC: (flag) => `${flag} requires an active epic (active_epic.id is empty)`,
   EPIC_ID_ORPHAN: () => "--epic-id (for sub-change) requires --new-change",
+  MISSING_REMOVE_VALUE: () => "--remove-change / --remove-epic requires a non-empty value",
 };
 
 // ── Defaults ────────────────────────────────────────────────────────────────
@@ -99,6 +83,17 @@ function parseArgs(argv) {
   return args;
 }
 
+// ── Multi-id Helper ─────────────────────────────────────────────────────────
+// Comma-separated list of ids, used by --remove-change / --remove-epic.
+// Mirrors the convention in sources/scripts/epic-update.js.
+function parseIdList(value) {
+  if (value == null) return [];
+  return String(value)
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
 // ── Config Loading ──────────────────────────────────────────────────────────
 function loadHistoryLimits(configPath) {
   const limits = { ...DEFAULT_LIMITS };
@@ -134,11 +129,25 @@ function validate(args) {
   if (!args.summary) return ERRORS.MISSING_SUMMARY();
   if (args["new-change"] && !args["change-id"]) return ERRORS.CHANGE_ID_REQUIRED();
 
-  // Epic combo validation (§9.1.1, ADR-10)
+  // Epic combo validation
   if (args["new-epic"] && !args["epic-id"]) return ERRORS.EPIC_ID_REQUIRED();
   if (args["close-epic"] && args["new-epic"]) return ERRORS.CLOSE_NEW_EPIC_CONFLICT();
   if (args["epic-id"] && !args["new-change"] && !args["new-epic"]) return ERRORS.EPIC_ID_ORPHAN();
 
+  // Remove flags require non-empty values
+  if (
+    args["remove-change"] !== undefined
+    && (args["remove-change"] === true || !String(args["remove-change"]).trim())
+  ) {
+    return ERRORS.MISSING_REMOVE_VALUE();
+  }
+  if (
+    args["remove-epic"] !== undefined
+    && (args["remove-epic"] === true || !String(args["remove-epic"]).trim())
+  ) {
+    return ERRORS.MISSING_REMOVE_VALUE();
+  }
+
   return null;
 }
 
@@ -226,12 +235,13 @@ function main() {
       }
     }
 
-    // Now set new active_change
+    // Now set new active_change (preserve fields only when re-invoking on same change)
+    const isSameChange = session.active_change.id === args["change-id"];
     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 = "";
-    session.active_change.epic_id = args["epic-id"] || "";
+    session.active_change.created_at = isSameChange ? (session.active_change.created_at || now) : now;
+    session.active_change.plan_path = isSameChange ? (session.active_change.plan_path || "") : "";
+    session.active_change.epic_id = args["epic-id"] || session.active_change.epic_id || "";
   }
 
   // --set-initialized
@@ -429,6 +439,40 @@ function main() {
     };
   }
 
+  // --remove-change <ids>: filter session.changes[]
+  if (args["remove-change"] !== undefined) {
+    session.changes = session.changes || [];
+    const rawIds = args["remove-change"];
+    let removed = 0;
+    for (const id of parseIdList(rawIds)) {
+      const before = session.changes.length;
+      session.changes = session.changes.filter((e) => e.id !== id);
+      if (session.changes.length < before) removed++;
+    }
+    if (removed === 0) {
+      process.stderr.write(
+        `Warning: --remove-change requested ids [${rawIds}] not found; no entries removed.\n`,
+      );
+    }
+  }
+
+  // --remove-epic <ids>: filter session.epics[]
+  if (args["remove-epic"] !== undefined) {
+    session.epics = session.epics || [];
+    const rawIds = args["remove-epic"];
+    let removed = 0;
+    for (const id of parseIdList(rawIds)) {
+      const before = session.epics.length;
+      session.epics = session.epics.filter((e) => e.id !== id);
+      if (session.epics.length < before) removed++;
+    }
+    if (removed === 0) {
+      process.stderr.write(
+        `Warning: --remove-epic requested ids [${rawIds}] not found; no entries removed.\n`,
+      );
+    }
+  }
+
   // ── Write back atomically ─────────────────────────────────────────────
   const tmpPath = sessionPath + ".tmp";
 

package/sources/sections/activation-protocol.md

@@ -0,0 +1,46 @@
+## Activation Protocol
+
+Two blocks: **Load** (what to read, and when) then **Resolve** (what to decide). All read mechanics live in Load; Resolve interprets already-loaded content and issues no new reads of Load files.
+
+### Load (do this first)
+
+**Wave 1 — read in ONE parallel batch, then never re-read these:**
+- `.ai-agents/workspace/project-context.yaml`
+- `.ai-agents/registry.yaml`
+- `.ai-agents/config.yaml`
+{{#activation_reads}}
+- `.ai-agents/workspace/{{.}}`
+{{/activation_reads}}
+
+**Deferred (load after Wave 1; do not re-read Wave 1 files):**
+- *Knowledge* — depends on the loaded `registry.yaml`; resolve and load per the rule in Resolve. May be serial (manifest-driven).
+{{?extended_context}}
+- *Extended Context* (listed below) — once `session.yaml` values such as `{active_change.id}` / `{plan_path}` are known, read the concrete files (e.g. `analysis.md`, `design.md`, `plan.yaml`, template paths) in ONE parallel sub-batch. Discovery directives (e.g. "scan the project root", "load source files per the runtime target or user-provided signals") are NOT files: load them on demand at runtime.
+
+Extended Context entries:
+{{/extended_context}}
+{{#extended_context}}
+- {{.}}
+{{/extended_context}}
+
+### Resolve (interpret loaded content — no new reads of Load files)
+
+**Project Scope (PS)** — from `project-context.yaml > projects[]`:
+- **Single project** → PS = [the sole project]. Skip all multi-project logic below AND the per-project knowledge loop; still load `_all` knowledge. This is the common case.
+- **Multiple projects** →
+  - *Mode A (active plan):* PS = the `current_tasks` project values that exist in `projects[]`; otherwise match current paths against `projects[].path` / `source_paths`; if still unresolved, list candidates and ask. Never silently load all.
+  - *Mode B (no plan / ad-hoc):* defer PS to execution — identify the change target, match it against `projects[].path` / `source_paths`.
+
+**Knowledge** — always load `knowledge._all` + `skills.<current-skill>.knowledge._all`. In multi-project Mode A/B, additionally load `knowledge[P]` + `skills.<current-skill>.knowledge[P]` for each resolved P. For every entry: base dir = `.ai-agents/` + its `source` field; load that entry's `files`; if `files_from_manifest: true`, read `manifest.yaml` in that dir and load entries with `auto_load: true`. Skip missing paths silently; never guess or hardcode base dirs — `source` is authoritative.
+
+**Config** — apply `config.yaml` preferences for the whole session: `preferences.interaction_language` (chat/prompts/tables), `preferences.document_output_language` (files on disk), `preferences.output.no_emojis`, `preferences.output.data_format`, `preferences.context_routing.relevance_threshold`.
+{{?has_preflight}}
+
+**Pre-flight** — evaluate each check below against the loaded `session.yaml` / `project-context.yaml`. Levels: **WARN** = emit message, ask "Continue? (y/n)", default **y**; **BLOCK** / **REQUIRED** = emit and stop until satisfied; **INFO** = emit and proceed.
+
+| # | Condition | Level | Message |
+|---|-----------|-------|---------|
+{{#checks}}
+| {{order}} | `{{#condition}}{{condition}}{{/condition}}{{^condition}}{{field}} is empty{{/condition}}` | {{level}} | {{message}} |
+{{/checks}}
+{{/has_preflight}}

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

@@ -24,7 +24,7 @@ Match the current state to one of the conditions below. If none match, use `defa
 
 Infer 2-3 suggestions, choosing **only** from the skills declared under `skills` in `registry.yaml`:
 - `history` in `session.yaml`
-- `category` and `description` of each skill in `registry.yaml`
+- Skill names and `description` fields in `registry.yaml`
 - The current `active_change` state (if in progress)
 - The standard workflow order (analyze → design → implement → review → test)
 {{/conditional_suggestions}}

package/sources/sections/language-constraint.md

@@ -1,26 +1,11 @@
 ## Language Constraint (Mandatory)
 
-This constraint governs the language of **everything** this skill produces. It has two independent scopes — interactive output (what you say to the user) and persisted document output (what you write to disk). Both are NON-NEGOTIABLE and override any other language signals.
+This governs **all language output**. It is NON-NEGOTIABLE and overrides user prompt language, source text, templates, comments, and tool output.
 
 ### Interactive Output (spoken to the user)
 
-All interactive output — chat replies, questions, prompts, status lines, tables, and summaries shown in the conversation — MUST be written in the language specified by `preferences.interaction_language` from config.yaml.
-
-**Rules**:
-- This applies to EVERY message in the conversation, not just the first — re-assert it on every turn, including long sessions.
-- Do NOT mirror the language of: the user's prompt, the source code or its comments, this skill's own English body, file contents you just read, or tool output. None of these are language signals.
-- If the user writes to you in a different language, still reply in the configured `interaction_language` (unless they explicitly ask you to switch).
-- If `interaction_language` is not set, fall back to `en-US`.
-- This constraint is NON-NEGOTIABLE and overrides any other language signals.
+Use `preferences.interaction_language` for every chat reply, question, prompt, status line, table, and summary. Re-assert it every turn, including long sessions. If absent, use `en-US`. Only an explicit user request to switch language overrides it.
 
 ### Persisted Document Output (files written to disk)
 
-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
+Use `preferences.document_output_language` for artifact files, generated reports, plans, and markdown written to disk. If absent, fall back to `interaction_language`. Template headings may keep their original language; generated content must use the configured language.