@uoyo/mvtt 2.0.0-beta.6 → 2.1.0

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

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.
@@ -126,8 +119,15 @@ function parseArgs(argv) {
 function validateArgs(args) {
   if (!args.plan || args.plan === true) return ERRORS.MISSING_PLAN();
   if (!args.task || args.task === true) return ERRORS.MISSING_TASK();
-  if (!args.status || args.status === true) return ERRORS.MISSING_STATUS();
-  if (!VALID_STATUSES.includes(args.status)) return ERRORS.INVALID_STATUS(args.status);
+  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 +136,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 +166,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 +205,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) --
@@ -576,7 +580,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,59 @@
+# 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,...]]
+```
+
+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"` |
+
+## 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. |
+
+## 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.

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}
@@ -226,12 +209,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

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

@@ -1,11 +1,8 @@
-### Step 4: Load Config & Apply Preferences (Config Foundation)
-Read `.ai-agents/config.yaml` and enforce the following throughout this entire session:
+### Stage 4: Load Config & Apply Preferences (Config Foundation)
+Read `.ai-agents/config.yaml` and enforce it for the whole session:
 
-**Language**:
-- `preferences.interaction_language` → Use for everything spoken to the user (chat, prompts, tables); NOT for files written to disk.
-- `preferences.document_output_language` → See **Output Language Constraint** section below for the full rules governing files written to disk.
-
-**Other preferences**:
-- `preferences.output.no_emojis` → If true, never use emojis
-- `preferences.output.data_format` → Use this format for data sections in artifacts
-- `preferences.context_routing.relevance_threshold` → Used by `/mvt-manage-context add` for AI routing (default 70 if missing)
+- `preferences.interaction_language`: language for chat, prompts, status lines, tables, and summaries.
+- `preferences.document_output_language`: language for files written to disk.
+- `preferences.output.no_emojis`: if true, never use emojis.
+- `preferences.output.data_format`: format for artifact data sections.
+- `preferences.context_routing.relevance_threshold`: AI routing threshold for `/mvt-manage-context add` (default 70).

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

@@ -1,7 +1,7 @@
 ## Activation Protocol
 
-### Step 1: Load Context
-Load these files as foundational context:
+### Stage 1: Load Context
+Load foundational context:
 - `.ai-agents/workspace/project-context.yaml` -- Project index (structural info)
 - `.ai-agents/registry.yaml` -- Available skills registry and knowledge declarations
 {{?extended_context}}
@@ -12,43 +12,33 @@ Extended context for this skill:
 - {{.}}
 {{/extended_context}}
 
-### Step 2: Resolve Project Scope (PS)
+### Stage 2: Resolve Project Scope (PS)
 
 Read `project-context.yaml > projects[]`.
 
-**Single project** (`projects.length == 1`): Set PS = [sole project name]. Skip remaining PS steps.
+**Single project** (`projects.length == 1`): PS = [sole project name]; skip the rest of this step.
 
 **Multi-project** (`projects.length > 1`):
 **Mode A -- Plan-driven** (active plan exists and skill operates on plan tasks):
-1. **Plan signal**: PS = current task's `project` array from plan's `current_tasks`. Drop stale project names (not in `projects[]`), fall through.
-2. **Path match**: Match current working paths against `projects[].path` and `source_paths`.
-3. **Prompt**: If still unresolved, list candidates and ask user. Never silently load all projects.
+1. **Plan signal**: PS = current task `project` values from plan `current_tasks`; drop names absent from `projects[]`.
+2. **Path match**: Match current paths against `projects[].path` and `source_paths`.
+3. **Prompt**: If unresolved, list candidates and ask user. Never silently load all projects.
 
 **Mode B -- Non-plan** (no active plan or ad-hoc changes):
-Defer PS to execution: identify change target, match against `projects[].path` and `source_paths`, load project-specific knowledge on demand (Step 3).
+Defer PS to execution: identify change target, match against `projects[].path` and `source_paths`, load project-specific knowledge on demand (Stage 3).
 
-### Step 3: Load Knowledge
+### Stage 3: Load Knowledge
 
-Registry uses project-keyed maps; `_all` is a reserved key (all projects). Applies to both top-level `knowledge` and `skills.<name>.knowledge`.
+Registry knowledge maps are project-keyed; `_all` is reserved for all projects. This applies to top-level `knowledge` and `skills.<name>.knowledge`.
 
 **Knowledge Loading Protocol**:
-For each knowledge entry in the registry, follow these steps:
-1. **Read the `source` field** from the registry entry (e.g., `knowledge/project/_generated/`).
-2. **Construct the base directory**: join `.ai-agents/` with the `source` value → `.ai-agents/{source_value}/`.
-3. **Load files**:
-   - `files: [a.md, b.md]` → load `.ai-agents/{source_value}/a.md`, `.ai-agents/{source_value}/b.md`.
-   - `files_from_manifest: true` → read `.ai-agents/{source_value}/manifest.yaml`, load entries with `auto_load: true`.
+For each registry knowledge entry:
+1. Read its `source` field, e.g. `knowledge/project/_generated/`.
+2. Base dir = `.ai-agents/` + `source`, e.g. `.ai-agents/knowledge/project/_generated/`.
+3. Load `files` entries from that base dir; if `files_from_manifest: true`, read `manifest.yaml` there and load entries with `auto_load: true`.
 4. **Skip non-existent paths** silently (do not error or warn).
 
-**Worked example**:
-Given this registry entry:
-```yaml
-- id: project-context
-  source: knowledge/project/_generated/
-  files:
-    - project-context.md
-```
-Resolution: `.ai-agents/` + `knowledge/project/_generated/` + `project-context.md` = `.ai-agents/knowledge/project/_generated/project-context.md`
+Example: `source: knowledge/project/_generated/` + `files: [project-context.md]` resolves to `.ai-agents/knowledge/project/_generated/project-context.md`.
 
 **Anti-pattern -- DO NOT**:
 - Guess or hardcode base directories (e.g., `.ai-agents/workspace/`).

package/sources/sections/activation-preflight.md

@@ -1,4 +1,4 @@
-### Step 5: Pre-flight Checks
+### Stage 5: Pre-flight Checks
 
 For each check below, if the condition holds, perform the action implied by its **Level**:
 

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

@@ -0,0 +1,11 @@
+## Language Constraint (Mandatory)
+
+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)
+
+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)
+
+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.

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

@@ -1,14 +1,11 @@
-## 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.
+## Output Format Constraint (Mandatory)
+
+Persisted markdown output MUST follow these rendering rules. Scope: artifact files, generated reports, plans, design documents, and any markdown written to disk. Chat output is out of scope.
+
+**Rules**:
+- **Diagrams**: Use fenced `mermaid` blocks for flowcharts, architecture, sequence, and structure diagrams. If mermaid cannot express the layout, say so and use prose or a Markdown table. Never use ASCII art.
+- **Tables**: Use Markdown tables (`| col | col |`), not aligned spaces or tabs.
+- **Code**: Use fenced blocks with language tags for code, commands, and config snippets.
+- **Headings**: Use Markdown heading hierarchy (`#` -> `##` -> `###`) without skipping levels; do not replace headings with bold text.
+
+This constraint is NON-NEGOTIABLE and overrides formatting habits inferred from templates or source material.

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

@@ -1,29 +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.
+## 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/script-usage-rule.md

@@ -0,0 +1,32 @@
+## Script Usage Rule
+
+{{#uses_plan_update}}To mutate `plan.yaml`, call `plan-update.cjs`. Do NOT hand-edit `plan.yaml` or choose `current_tasks`.
+
+**Minimal command** (always required flags):
+```bash
+node .ai-agents/scripts/plan-update.cjs --plan "<active_change.plan_path>" --task <task_id> --status <new_status> --projects "<project_list>"
+```
+For flags, argument sources, or output not rendered here, read `.ai-agents/scripts/plan-update.md`. Do NOT read `.cjs`/`.js` source.
+
+{{/uses_plan_update}}
+{{#plan_update_inline_command_only}}To mutate `plan.yaml`, use the exact `plan-update.cjs` command rendered in this skill's workflow. Do NOT hand-edit `plan.yaml`, choose `current_tasks`, or read `.cjs`/`.js` source.
+
+{{/plan_update_inline_command_only}}
+{{#plan_update_project_reminder}}When calling `plan-update.cjs` for a project-attributed plan, pass `--projects` with the relevant project list. Do NOT hand-edit `plan.yaml` or read `.cjs`/`.js` source. For flags or value sources not rendered here, read `.ai-agents/scripts/plan-update.md`.
+
+{{/plan_update_project_reminder}}
+{{#uses_epic_update}}To mutate `epic.yaml` (complete a child, set child status, switch active, add children, or validate), call `epic-update.cjs`. Do NOT hand-edit `epic.yaml` or advance `current_change`.
+
+**Minimal command** (most common mode — complete child):
+```bash
+node .ai-agents/scripts/epic-update.cjs --epic "<active_epic.epic_path>" --complete-child <active_change.id>
+```
+For modes not rendered here, read `.ai-agents/scripts/epic-update.md`. Do NOT read `.cjs`/`.js` source.
+
+{{/uses_epic_update}}
+{{#epic_update_inline_modes_only}}To mutate `epic.yaml`, use the exact `epic-update.cjs` mode commands rendered in this skill's workflow. Do NOT hand-edit `epic.yaml`, advance `current_change`, or read `.cjs`/`.js` source.
+
+{{/epic_update_inline_modes_only}}
+{{#epic_update_fallback_for_unrendered_modes}}To mutate `epic.yaml`, use the `epic-update.cjs` mode commands rendered in this skill's workflow. Do NOT hand-edit `epic.yaml`, advance `current_change`, or read `.cjs`/`.js` source. For modes or flags not rendered here, read `.ai-agents/scripts/epic-update.md`.
+
+{{/epic_update_fallback_for_unrendered_modes}}