mandrel 1.93.0 → 2.0.0

package/.agents/scripts/stories-wave-tick.js

@@ -11,7 +11,7 @@
  * emits the set of Stories safe to dispatch **on this beat** — a Story
  * becomes dispatchable the instant its own dependencies are done, under the
  * same global concurrency cap and the same file-overlap co-dispatch guard
- * the Epic path uses. There is no wave barrier: this no longer batches
+ * `lib/wave-runner/ready-set.js` applies everywhere. There is no wave barrier: this no longer batches
  * Stories into fully-draining waves; it selects continuously.
  *
  * The previous static wave-batch plan (group N must fully drain before
@@ -50,9 +50,9 @@
  * `/deliver` uses — `resolveConfig` + `getRunners` reading
  * `delivery.deliverRunner.concurrencyCap` (default 3) — so a
  * `.agentrc.local.json` override is honored. A `--concurrency <n>` CLI flag
- * overrides the config-resolved value for that run only. This puts both the
- * standalone (`/deliver`) and Epic (`/deliver`) delivery paths on one
- * deterministic config source **and** one scheduling kernel.
+ * overrides the config-resolved value for that run only. This shares one
+ * deterministic config source (`delivery.deliverRunner.concurrencyCap`) and
+ * one scheduling kernel with every `/deliver` multi-Story invocation.
  *
  * On cycle detection, exits with code 2 and sets cycleError in the envelope.
  */
@@ -74,7 +74,7 @@ Continuous ready-set planner for standalone Story delivery. Consumes a
 dependency graph of Story IDs plus the live run progress and emits the set
 of Stories safe to dispatch on this beat — a Story is dispatchable the
 instant its own dependencies are done — plus the resolved per-beat
-concurrency cap and the same file-overlap guard the Epic path uses.
+concurrency cap and the same file-overlap guard as selectReadySet.
 
 Input DAG format (JSON array):
   [{ "id": 101, "dependsOn": [] }, { "id": 102, "dependsOn": [101] }]
@@ -257,7 +257,7 @@ export function parseConcurrencyOverride(raw) {
 /**
  * Resolve the per-beat concurrency cap.
  *
- * Mirrors the `/deliver` seam (`epic-deliver-prepare.js`): resolve the
+ * Mirrors the `/deliver` multi-Story seam (`helpers/deliver-story.md`): resolve the
  * project config (which deep-merges `.agentrc.local.json` over `.agentrc.json`)
  * then read `delivery.deliverRunner.concurrencyCap` via `getRunners` (default
  * 3). An explicit `override` (the `--concurrency <n>` CLI flag) wins over

package/.agents/scripts/story-plan.js

@@ -2,33 +2,17 @@
 /* node:coverage ignore file */
 
 /**
- * story-plan.js — Local `/plan` wrapper.
+ * story-plan.js — QA helper for promote round-trips and `--emit-context`
+ * envelope emission.
  *
- * Standalone counterpart to `/plan` for Stories that do **not**
- * attach to an Epic. The script is deliberately a thin CLI around the
- * pure helpers in `lib/story-plan.js`:
+ * Canonical operator planning is `plan-context.js` + `plan-persist.js` (see
+ * `.agents/workflows/plan.md`). Use this CLI only for QA promote
+ * round-trips (`--body` / `--dry-run`) or test harnesses that need the
+ * standalone envelope shape.
  *
- *   1. `--emit-context` mode — given a `--idea`/`--from-notes` seed,
- *      build the context envelope (seed, refine heuristic, persona,
- *      body template, duplicate candidates, tech-stack summary, and a
- *      corpus-aware `corpusContext` — the docs digest plus relevant
- *      existing-Epic Tech Spec excerpts, Story #4432) and print it as
- *      JSON on stdout. Logs route to stderr so the envelope is
- *      byte-clean for `JSON.parse`.
- *   2. Persist mode — given a `--body <file>` authored by the host
- *      LLM after operator confirmation, validate the shape and persist
- *      via `provider.createIssue` (which also adds the new Story to
- *      the configured Projects V2 board — Story #3822) with
- *      `type::story` + the chosen persona label, falling back to
- *      `gh issue create` when the provider lacks a createIssue
- *      analogue. Prints `Next: /single-story-deliver <id>`.
- *   3. `--dry-run` — same as persist but exits without touching
- *      GitHub. Echoes the rendered body and the `gh` argv it would
- *      have run.
- *
- * Mirrors the `/plan` pattern: deterministic Node I/O wrappers
- * with HITL gating handled by the host LLM in chat. No external LLM
- * APIs are called from this script.
+ * Operator planning:
+ *   node .agents/scripts/plan-context.js --seed "…" | --seed-file <path> | --tickets <ids>
+ *   node .agents/scripts/plan-persist.js --stories … --risk-verdict …
  */
 
 import { readFile } from 'node:fs/promises';
@@ -53,10 +37,10 @@ import {
 
 const HELP = `\
 Usage:
-  story-plan.js --emit-context (--idea "<seed>" | --from-notes <file>) \\
-    [--persona <name>] [--refine | --no-refine] [--pretty]
+  story-plan.js --emit-context (--seed "<seed>" | --seed-file <file>) \\
+    [--refine | --no-refine] [--pretty]
 
-  story-plan.js --body <file> [--persona <name>] [--dry-run]
+  story-plan.js --body <file> [--dry-run]
 
   story-plan.js --help
 
@@ -66,12 +50,11 @@ Modes:
                    draft body using the envelope and the body template.
   --body <file>    Persist a pre-authored body. Validates shape (required
                    sections, no Epic: ref, AC checklist non-empty) and
-                   calls \`gh issue create\` with type::story + persona.
+                   calls \`gh issue create\` with type::story.
   --dry-run        With --body: print the body and the gh argv that would
                    be invoked, then exit 0. No GitHub mutations.
 
 Options:
-  --persona <name>   Persona label (default: engineer).
   --refine           Force the idea-refinement hint on regardless of seed
                      length. Default heuristic: refine when seed < 200
                      chars.
@@ -80,17 +63,17 @@ Options:
 `;
 
 /**
- * Resolve the seed string from --idea or --from-notes. One of the two
+ * Resolve the seed string from --seed or --seed-file. One of the two
  * must be present in --emit-context mode.
  */
-async function resolveSeed({ idea, fromNotes }) {
-  if (idea && fromNotes) {
-    throw new Error('Pass either --idea or --from-notes, not both.');
+async function resolveSeed({ seed, seedFile }) {
+  if (seed && seedFile) {
+    throw new Error('Pass either --seed or --seed-file, not both.');
   }
-  if (idea) return idea;
-  if (fromNotes) return (await readFile(fromNotes, 'utf8')).trim();
+  if (seed) return seed;
+  if (seedFile) return (await readFile(seedFile, 'utf8')).trim();
   throw new Error(
-    '--emit-context requires --idea "<seed>" or --from-notes <file>.',
+    '--emit-context requires --seed "<seed>" or --seed-file <file>.',
   );
 }
 
@@ -147,12 +130,11 @@ async function runEmitContext({
   write = (s) => process.stdout.write(s),
 }) {
   const seed = await resolveSeed({
-    idea: values.idea,
-    fromNotes: values['from-notes'],
+    seed: values.seed,
+    seedFile: values['seed-file'],
   });
   const override = values.refine ? 'on' : values['no-refine'] ? 'off' : null;
   const refine = shouldRefine({ seed, override });
-  const persona = values.persona ?? 'engineer';
 
   // Corpus lookup uses the raw (un-defaulted) docsContextFiles list, same
   // as the `/deliver` per-Epic digest builder: `config.project` fills in
@@ -186,7 +168,6 @@ async function runEmitContext({
   const envelope = buildContextEnvelope({
     seed,
     refine,
-    persona,
     bodyTemplate,
     duplicateCandidates,
     techStack,
@@ -221,8 +202,7 @@ async function runPersist({
   }
 
   const title = extractTitle(body);
-  const persona = values.persona ?? 'engineer';
-  const labels = [TYPE_LABELS.STORY, `persona::${persona}`];
+  const labels = [TYPE_LABELS.STORY];
   const argv = renderGhArgv({ title, bodyPath, labels });
 
   if (dryRun) {
@@ -264,7 +244,7 @@ async function runPersist({
   }
 
   write(`${JSON.stringify({ issueNumber, title, labels }, null, 2)}\n`);
-  Logger.info(`Next: /single-story-deliver ${issueNumber}`);
+  Logger.info(`Next: /deliver ${issueNumber}`);
 }
 
 /* node:coverage ignore next */
@@ -272,10 +252,9 @@ async function main() {
   const { values } = parseArgs({
     options: {
       'emit-context': { type: 'boolean', default: false },
-      idea: { type: 'string' },
-      'from-notes': { type: 'string' },
+      seed: { type: 'string' },
+      'seed-file': { type: 'string' },
       body: { type: 'string' },
-      persona: { type: 'string' },
       refine: { type: 'boolean', default: false },
       'no-refine': { type: 'boolean', default: false },
       pretty: { type: 'boolean', default: false },

package/.agents/scripts/sync-claude-agents.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+
+/**
+ * Projects .agents/agents/ (and .agents/local/agents/ when present) into a flat
+ * `.claude/agents/` tree so Claude Code exposes each role definition as a
+ * role-scoped sub-agent (`subagent_type: <name>`). Exact sibling of
+ * `sync-claude-commands.js` — same header, same local-shadow policy, same
+ * orphan-reap, same prune-exempt handling for the consumer-authored
+ * `.agents/local/agents/` source. Two source directories are enumerated in
+ * order:
+ *
+ *   1. PAYLOAD_SRC  — `.agents/agents/`  (the installed Mandrel payload)
+ *   2. LOCAL_SRC    — `.agents/local/agents/`  (consumer-authored, prune-exempt)
+ *
+ * The payload directory wins on basename collision: if both sources supply
+ * `foo.md`, the payload copy is projected and the local copy is ignored with a
+ * `shadowed` warning. Because both sources are unioned into `sourceSet`, local
+ * agent defs are also protected from the orphan-reap — they survive
+ * `npm install`, `mandrel sync`, and `mandrel update` with no manual re-sync.
+ *
+ * Only top-level `.md` files project (`.claude/agents/<name>.md`). Unlike the
+ * commands sync there is no `loops/` namespace and no plugin tree to reap — the
+ * agent surface is flat.
+ *
+ * A `.claude/agents/<name>.md` runs on its **own** system prompt — it does NOT
+ * inherit the `CLAUDE.md` @-import closure — so a spawn routed to a role agent
+ * stops re-paying the always-loaded context (issue #4478). The role defs
+ * @-import `security-baseline.md` so the inviolable security MUSTs stay
+ * single-sourced.
+ *
+ * Usage:  node .agents/scripts/sync-claude-agents.js
+ */
+
+// cli-opt-out: top-level-await script with no main() function — runAsCli wraps an async main, which doesn't apply here.
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { applyHeader } from './lib/command-header.js';
+import { Logger } from './lib/Logger.js';
+
+// Resolve the project root from the invocation cwd — the consumer project where
+// `.agents/` is materialized and where Claude Code loads `.claude/agents/`.
+// It MUST NOT use `__dirname/../..`: in an npm-installed consumer this script
+// runs from `node_modules/mandrel/.agents/scripts/`, so that climb lands on the
+// package dir and the defs would be written *inside node_modules* rather than
+// the consumer. Every real invocation runs with cwd at the project root
+// (`npm run sync:agents`, the prepare hook). Tests drive fixture trees via the
+// SYNC_CLAUDE_AGENTS_SRC/DEST overrides below.
+const PROJECT_ROOT = process.cwd();
+
+// Env-var overrides exist so the sync logic can be exercised against a fixture
+// agents tree in isolation. When unset, behaviour is unchanged — the script
+// defaults to the real agents / .claude/agents directories. SYNC_CLAUDE_AGENTS_SRC
+// overrides the PAYLOAD source only; LOCAL_SRC is always derived from the project
+// root so fixture tests can isolate the payload source.
+const PAYLOAD_SRC =
+  process.env.SYNC_CLAUDE_AGENTS_SRC ??
+  path.join(PROJECT_ROOT, '.agents', 'agents');
+const LOCAL_SRC = path.join(PROJECT_ROOT, '.agents', 'local', 'agents');
+
+const DEST_DIR =
+  process.env.SYNC_CLAUDE_AGENTS_DEST ??
+  path.join(PROJECT_ROOT, '.claude', 'agents');
+
+export const HEADER =
+  '<!-- AUTO-GENERATED — do not edit. Source of truth: .agents/agents/ -->\n<!-- Re-run: npm run sync:agents -->\n\n';
+
+export const LOCAL_HEADER =
+  '<!-- AUTO-GENERATED from .agents/local/ — do not edit. Source of truth: .agents/local/agents/ -->\n<!-- Re-run: npm run sync:agents -->\n\n';
+
+/**
+ * Return true when the given directory path exists and is accessible.
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function dirExists(dir) {
+  try {
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+fs.mkdirSync(DEST_DIR, { recursive: true });
+
+// Top-level .md files project flat. Subdirectories are skipped.
+const isTopLevelAgent = (entry) => entry.isFile() && entry.name.endsWith('.md');
+
+// Enumerate sources: payload first, then local (if it exists). Payload wins on
+// basename collision — a consumer must not silently shadow a core role def.
+const SRC_DIRS = [PAYLOAD_SRC, LOCAL_SRC].filter(dirExists);
+
+/** @type {Array<{dir: string, name: string}>} */
+const entries = SRC_DIRS.flatMap((dir) =>
+  fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter(isTopLevelAgent)
+    .map((e) => ({ dir, name: e.name })),
+);
+
+// Collision policy: payload wins, warn on a shadowed local file.
+const byName = new Map();
+for (const e of entries) {
+  if (byName.has(e.name)) {
+    Logger.warn(`  shadowed  ${e.name} (local copy ignored; payload wins)`);
+    continue;
+  }
+  byName.set(e.name, e);
+}
+
+// sourceSet drives the orphan-reap: any existing agent def not in this set is
+// removed.
+const sourceSet = new Set(byName.keys());
+
+/**
+ * List the `.md` agent defs currently on disk in the destination.
+ *
+ * @returns {string[]}
+ */
+function listExistingAgents() {
+  try {
+    return fs.readdirSync(DEST_DIR).filter((f) => f.endsWith('.md'));
+  } catch {
+    return [];
+  }
+}
+
+for (const name of listExistingAgents()) {
+  if (!sourceSet.has(name)) {
+    fs.unlinkSync(path.join(DEST_DIR, name));
+    Logger.info(`  removed  ${name} (no longer in .agents/agents)`);
+  }
+}
+
+// Copy each role def, injecting the auto-generated header after any leading
+// frontmatter (so the `---` block stays on line 1 and Claude Code parses the
+// agent's name/description). Use a distinct header comment for local-origin files.
+let synced = 0;
+const resolvedEntries = Array.from(byName.values());
+await Promise.all(
+  resolvedEntries.map(async ({ dir, name }) => {
+    const isLocal = dir === LOCAL_SRC;
+    const header = isLocal ? LOCAL_HEADER : HEADER;
+    const content = await fs.promises.readFile(path.join(dir, name), 'utf8');
+    const dest = path.join(DEST_DIR, name);
+    const target = applyHeader(content, header);
+
+    // Skip write if content is already identical (avoid noisy git diffs).
+    try {
+      const existingContent = await fs.promises.readFile(dest, 'utf8');
+      if (existingContent === target) return;
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+    }
+
+    await fs.promises.writeFile(dest, target, 'utf8');
+    synced++;
+    Logger.info(`  synced   ${name}`);
+  }),
+);
+
+Logger.info(
+  `\n✔ ${synced} file(s) synced, ${sourceSet.size} total agents in .claude/agents/`,
+);

package/.agents/scripts/update-ticket-state.js

@@ -1,18 +1,17 @@
 /**
- * .agents/scripts/update-ticket-state.js — CLI Re-export Shim
- *
- * Thin backward-compatibility shim. The core logic has been moved to
- * `lib/orchestration/ticketing.js` as part of the SDK refactor.
- *
- * This file preserves backward compatibility for CLI usage and existing
- * testing patterns.
- *
- * Successor to the retired mandrel MCP tools. See ADR 20260424-702a in docs/decisions.md for the migration table.
+ * .agents/scripts/update-ticket-state.js — CLI entrypoint for ticket
+ * label transitions. Core logic lives in `lib/orchestration/ticketing.js`;
+ * this file is the operator-facing command surface (not a compatibility
+ * layer).
  */
 
 import { parseArgs } from 'node:util';
 import { resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
+import {
+  enqueueLabel,
+  outboxPathFor,
+} from './lib/orchestration/bookkeeping-outbox.js';
 import {
   cascadeCompletion,
   STATE_LABELS,
@@ -29,25 +28,23 @@ if (
   const { values } = parseArgs({
     args: process.argv.slice(2),
     options: {
-      task: { type: 'string' },
       ticket: { type: 'string' },
       state: { type: 'string' },
       'remove-label': { type: 'string' },
+      buffer: { type: 'boolean' },
+      epic: { type: 'string' },
     },
     strict: false,
   });
 
-  // `--ticket` is the v5.9.0 alias for `--task` (labels can apply to any
-  // ticket type, not just Tasks). Both continue to work.
-  const idSource = values.ticket ?? values.task;
-  const ticketId = Number.parseInt(idSource, 10);
+  const ticketId = Number.parseInt(values.ticket, 10);
   const state = values.state;
   const removeLabel = values['remove-label'];
 
   if (Number.isNaN(ticketId) || (!state && !removeLabel)) {
     throw new Error(
       'Usage: node update-ticket-state.js ' +
-        '(--ticket|--task) <id> ' +
+        '--ticket <id> ' +
         '[--state <state> | --remove-label <label>]',
     );
   }
@@ -69,6 +66,31 @@ if (
       return;
     }
 
+    // Headless buffering (Epic #4476 M5): buffer an intermediate state flip to
+    // the per-Epic outbox instead of a live GitHub round-trip; finalize's
+    // bookkeeping-reconcile.js drains it once. `agent::blocked` (the HITL gate,
+    // §1.J) and `agent::done` (its cascade must run live) ALWAYS surface
+    // immediately and are never buffered. Requires --epic to locate the outbox.
+    if (
+      values.buffer &&
+      state !== STATE_LABELS.BLOCKED &&
+      state !== STATE_LABELS.DONE
+    ) {
+      const epicId = Number.parseInt(values.epic ?? '', 10);
+      if (!Number.isInteger(epicId) || epicId <= 0) {
+        throw new Error('--buffer requires --epic <id>');
+      }
+      enqueueLabel({
+        outboxPath: outboxPathFor(epicId, config),
+        ticketId,
+        state,
+      });
+      Logger.info(
+        `[State-Sync] Buffered #${ticketId} → ${state} (headless; drained at finalize)`,
+      );
+      return;
+    }
+
     Logger.info(
       `[State-Sync] Transitioning ticket #${ticketId} to ${state}...`,
     );

package/.agents/skills/core/analyze-execution/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: analyze-execution
 description: >-
-  Aggregate per-Story or per-Epic execution signals into a structured
+  Aggregate per-Story or per-plan-run execution signals into a structured
   perf-summary or perf-report and upsert it onto the corresponding GitHub
-  ticket. Use after a Story closes (Story mode) or as part of
-  `/deliver` Phase 6 (Epic mode). Reads NDJSON via
+  ticket. Use after a Story closes (Story mode) or during run closeout
+  (plan-run mode). Reads NDJSON via
   `lib/signals/read` and writes a single structured comment.
 allowed_tools:
   - Read
@@ -16,42 +16,42 @@ allowed_tools:
 ## Policy Capsule
 
 - Invoke via the wrapping CLI `node .agents/scripts/analyze-execution.js`; do not duplicate the read/write logic from this Skill body.
-- Resolve mode strictly by flags: `--story <sid> --epic <eid>` → Story mode; `--epic <eid>` alone → Epic mode.
-- Read NDJSON signals only through `lib/signals/read` (the async-iterator entry point). Never open `<tempRoot>/epic-<eid>/story-<sid>/signals.ndjson` directly — the reader owns the warn-once malformed-JSON policy.
+- Resolve mode strictly by flags: Story + run id → Story mode; run id alone → plan-run mode. The current CLI still spells the run-id flag as `--epic <id>`; treat that value as the run id and do not add a second executor path here.
+- Read NDJSON signals only through `lib/signals/read` (the async-iterator entry point). Never open `<tempRoot>/run-<id>/stories/story-<sid>/signals.ndjson` directly — the reader owns the warn-once malformed-JSON policy.
 - Emit a single structured GitHub comment per ticket (`<!-- structured:story-perf-summary -->` or `<!-- structured:epic-perf-report -->`); rely on `upsertStructuredComment` for idempotence — never post duplicates.
-- Never rename or alter the structured-marker IDs; the retro composer and Epic dashboard grep them verbatim.
+- Never rename or alter the structured-marker IDs; the retro composer and run dashboard grep them verbatim.
 - Validate the structured payload against `docs/data-dictionary.md §StoryPerfSummary` or `§EpicPerfReport` before posting. Schema violations exit non-zero.
-- Soft-fail (exit 0 with a warning) when NDJSON is missing for a Story or an Epic has no children — observability output MUST NOT block the close pipeline.
+- Soft-fail (exit 0 with a warning) when NDJSON is missing for a Story or a plan-run has no children — observability output MUST NOT block the close pipeline.
 - Do not write to disk. Persistence is GitHub; the Skill is read-NDJSON + post-comment only.
 
 ## Role
 
 Observability writer. Composes the structured `story-perf-summary` /
 `epic-perf-report` comment bodies the retro composer downstream renders
-into the Epic dashboard.
+into the run dashboard.
 
 ## When to use
 
-- **Story mode** — after `story-close.js` finishes, the post-merge
+- **Story mode** — after `single-story-close.js` finishes, the close
   pipeline dispatches this Skill (or the wrapping script) to roll up the
   Story's NDJSON signals into a single `<!-- structured:story-perf-summary -->`
   marker comment on the Story ticket.
-- **Epic mode** — during `/deliver` Phase 6.0 (or the retro
-  composer), the Skill fans out across every Story under the Epic,
+- **Plan-run mode** — during run closeout (or the retro
+  composer), the Skill fans out across every Story under the plan-run,
   reads each Story's structured perf summary, and posts a single
-  `<!-- structured:epic-perf-report -->` marker on the Epic ticket.
+  `<!-- structured:epic-perf-report -->` marker on the run ticket.
 
 ## Inputs
 
 The Skill reads (never writes) the NDJSON signal stream at:
 
 ```text
-<tempRoot>/epic-<eid>/story-<sid>/signals.ndjson
+<tempRoot>/run-<id>/stories/story-<sid>/signals.ndjson
 ```
 
 Use the `lib/signals/read` async-iterator entry point — never open the
 file directly. Story mode also reads `phase-timings.json` written by
-`post-merge-close.js`.
+the close pipeline.
 
 ## Outputs
 
@@ -64,8 +64,8 @@ the new one.
 
 ### Step 1 — Resolve mode
 
-If both `--story <sid>` and `--epic <eid>` are supplied → Story mode.
-If only `--epic <eid>` is supplied → Epic mode. The script
+If both Story id and run id are supplied → Story mode.
+If only run id is supplied → plan-run mode. The script
 `analyze-execution.js` is the dispatcher today; this Skill documents the
 contract the dispatcher implements.
 
@@ -77,6 +77,9 @@ node .agents/scripts/analyze-execution.js --story <sid> --epic <eid>
 node .agents/scripts/analyze-execution.js --epic <eid>
 ```
 
+`--epic <eid>` is the legacy spelling of the run-id flag in the current
+CLI; treat `<eid>` as the run id for path/layout purposes.
+
 ### Step 3 — Validate the structured payload before posting
 
 The payload must conform to `docs/data-dictionary.md §StoryPerfSummary`
@@ -92,7 +95,7 @@ the contract so we never silently emit malformed comments.
 - Do **not** rename the structured-marker IDs
   (`<!-- structured:story-perf-summary -->`,
   `<!-- structured:epic-perf-report -->`); the retro composer and the
-  Epic dashboard both grep for them verbatim.
+  run dashboard both grep for them verbatim.
 - Soft-failure mode is intentional: missing NDJSON for a Story or no
-  children for an Epic returns exit 0 with a warning so close pipelines
+  children for a plan-run returns exit 0 with a warning so close pipelines
   never block on observability output.

package/.agents/skills/core/api-and-interface-design/SKILL.md

@@ -19,7 +19,7 @@ description:
 - Define the contract before implementing — interfaces are the spec; implementation follows.
 - Validate at system **boundaries** (API routes, form handlers, env-var loaders, third-party responses) using a strict schema. After validation, internal code trusts the types; do not re-validate between internal functions.
 - Treat third-party API responses as untrusted data — validate shape and content before using them in any decision, render, or logic path.
-- Prefer **addition over modification**: extend interfaces with optional fields rather than changing existing types or removing fields; reach for the deprecation playbook (see `deprecation-and-migration`) when removal is unavoidable.
+- Prefer **addition over modification**: extend interfaces with optional fields rather than changing existing types or removing fields. When removal is unavoidable, use an expand–contract migration — ship the replacement, migrate consumers, then remove the old surface in a later release.
 - Follow REST resource conventions (`GET/POST/PATCH/DELETE /resource`, sub-resources at `/resource/:id/child`) and paginate every list endpoint with `page` + `pageSize` query params and a `pagination` envelope.
 - Security input-validation and test-tier MUSTs come from `.agents/rules/security-baseline.md` and `.agents/rules/testing-standards.md` respectively — apply both, and never put DB/wire-shape assertions outside the contract tier.
 
@@ -55,8 +55,10 @@ ordering — becomes a de facto contract once users depend on it. Implications:
   potential commitment.
 - **Don't leak implementation details.** If users can observe it, they will
   depend on it.
-- **Plan for deprecation at design time.** See `deprecation-and-migration`
-  for how to safely remove things users depend on.
+- **Plan for deprecation at design time.** Remove things users depend on via
+  expand–contract: add the replacement, migrate consumers behind a deprecation
+  window, then delete the old surface — never break a published contract in one
+  step.
 - **Tests are not enough.** Even with perfect contract tests, "safe" changes
   can break real users who depend on undocumented behavior.