mandrel 2.40.0 → 2.42.0

package/.agents/rules/changelog-style.md

@@ -1,180 +0,0 @@
-# CHANGELOG Style Contract
-
-This rule governs the shape of per-release entries in the project CHANGELOG
-(typically `docs/CHANGELOG.md` or `CHANGELOG.md`). It applies whenever a
-release entry is authored or edited — most commonly inside Story #N's
-docs sweep before `/mandrel-deliver` opens the release PR.
-
-The contract is **guidance-tier**: no automated gate fails a close when an
-entry drifts off-template. It still binds every author.
-
-## Goal
-
-A reader scanning release notes should identify what ships in a release in
-under 30 seconds. Breaking changes, config-shape changes, and CLI renames
-must be impossible to miss. Internal refactor detail belongs in commit
-messages and PR descriptions — not here.
-
-## Per-Release Entry Shape
-
-Every entry starts with a version header line already produced by the
-release tooling:
-
-```markdown
-## [X.Y.Z] - YYYY-MM-DD
-```
-
-Immediately below, the entry MUST have:
-
-1. **A short section header** naming the theme of the release — one line,
-   Sentence case, no trailing punctuation.
-
-   ```markdown
-   ### Epic-runner throughput & caching pass
-   ```
-
-2. **A 1–3 sentence theme paragraph** that tells the reader, in plain
-   English, what the release is about and why it matters. No bullets, no
-   sub-headers, no code fences.
-
-3. **Bullets of user-visible changes**, grouped by natural topic if the
-   release spans more than one theme. Each bullet leads with a bold phrase
-   naming the change, followed by a one- or two-sentence explanation.
-
-```markdown
-## [5.21.0] - 2026-04-24
-
-### Epic-runner throughput & caching pass
-
-Performance and observability pass across the epic-runner hot paths — wave
-gating, commit assertion, progress reporting, and label polling. Caching
-and bounded concurrency throughout; new per-phase timing surface.
-
-- **Bounded-concurrency parallelism.** Wave gating, commit assertion, and
-  progress reporting now fan out in parallel with a configurable cap.
-- **Per-phase timing surface.** Story close posts a structured comment
-  with per-phase timings; the Epic progress comment aggregates median
-  and p95 across closed stories.
-```
-
-## Bullets: What Counts as "User-Visible"
-
-Include:
-
-- New CLI commands, flags, or scripts the operator invokes.
-- New or renamed labels, ticket shapes, or workflow phases the operator
-  touches.
-- New or renamed configuration keys, with the old → new mapping if any.
-- New behavioural guarantees (e.g., "retries on transient errors").
-- Bug fixes the operator would otherwise trip over.
-- Performance changes with a user-observable magnitude.
-
-Exclude:
-
-- Internal refactors with no behavioural delta.
-- Test additions, coverage bumps, lint cleanups.
-- Module renames or file moves invisible to operators.
-- Per-phase implementation details ("now uses a BFS walker").
-
-## Banned Content
-
-The following MUST NOT appear in a release entry:
-
-- **Per-ticket citations.** No `(Epic #553)`, `(resolves #612)`,
-  `(Story #645)` in bullet text. The theme paragraph may reference the
-  Epic once when the release is scoped to one Epic — that is the only
-  allowed citation, and only there.
-- **Internal file paths** (`lib/orchestration/epic-runner/commit-assertion.js`,
-  `.agents/scripts/story-init.js`). Callers care what changed, not
-  where it lives.
-- **Internal function, class, or method names** (`finalizeMerge`,
-  `WorkspaceProvisioner.verify`, `cascadeCompletion`). Name the behaviour,
-  not the symbol — unless the symbol is part of the public API.
-- **Test counts** (`47 new tests`, `95% coverage`). Tests are a means, not
-  a ship artefact.
-- **Module-sizing stats** (`shrinks epic-runner from 840 to 420 LOC`).
-- **Implementation mechanics** (`BFS walker`, `Promise.all over parents`,
-  `exponential backoff with 3 attempts, 500ms base`) unless the mechanism
-  is part of a new public contract.
-
-## Mandatory Prominence
-
-The following categories MUST be called out visibly — typically in **bold**
-at the start of a bullet, or in a short dedicated section above the
-bullet list:
-
-- **Breaking changes.** A bullet leading with `**Breaking:**` or a
-  `### Breaking Changes` sub-section. Include the migration path.
-- **Config-shape changes.** Moved, removed, renamed, or newly-required
-  config keys. Old key → new key, or removal notice with remediation.
-- **CLI renames.** Old command → new command, including whether the old
-  name remains as a deprecation alias and for how long.
-- **Schema shape changes** on structured comments, manifest files, or
-  public API payloads. Readers parsing these surfaces must be told.
-
-If a release ships any of the above, they belong at the top of the bullet
-list (or in a dedicated sub-section), not buried mid-list.
-
-## Line-Count Guidance
-
-Soft ceilings, not hard fails:
-
-- **Non-major release** (patch or minor): **≤60 lines**, including
-  header, theme paragraph, blank lines, and bullets.
-- **Major release**: **≤150 lines**. Major releases span larger surface
-  and warrant more prominence.
-
-If an entry exceeds the ceiling, prefer splitting a genuinely multi-theme
-release into grouped sub-sections over padding the bullet list. Before
-accepting a long entry, ask: which bullets are user-visible, and which
-are internal detail that migrated in from the Epic body?
-
-## Worked Example — On-Contract
-
-Off-contract entries — the style that drove the Epic #553 retro action item —
-pack several `###` sub-sections into one release and leak internal function
-names (`finalizeMerge`, `mergeFeatureBranch`, `ensure()`, `reap()`),
-implementation mechanics, internal step numbering, and lock-file name lists
-operators cannot act on. The on-contract version collapses all of that:
-
-```markdown
-## [5.8.7] - 2026-04-15
-
-### Parallel-wave merge robustness
-
-Parallel story waves kept tripping over each other at integration time.
-This release reduces the conflict surface at story close and stabilises
-worktree cleanup.
-
-- **Pre-merge rebase at story close** shrinks the conflict window to
-  each story's real delta; conflicts above the triage threshold abort
-  and surface to the operator.
-- **Shared-store worktrees.** Per-story worktrees link a shared
-  `node_modules` store, so parallel waves no longer duplicate installs
-  or leave residue that blocks reap.
-- **`/mandrel-deliver` auto-invokes pre-merge gates** (code review, retro)
-  inline. `--skip-code-review` is available as an override.
-- **Closure sweep covers Epic Health tickets** in addition to PRD and
-  Tech Spec tickets.
-- **Stale-lock sweep** on the shared `.git/` directory runs at
-  `/mandrel-deliver` start, clearing lock files left behind by interrupted
-  operations.
-```
-
-What changed: one theme section instead of five; the paragraph gives the
-"why" in two sentences; each bullet leads with the user-visible behaviour
-and drops internal symbols, file paths, and step numbers; the override
-flag (`--skip-code-review`) is kept because it is part of the public CLI
-surface; the lock-file list is dropped because operators do not act on
-individual lock names.
-
-## When to Deviate
-
-- **Major releases** may warrant multiple `###` sub-sections under a
-  single version header when the release genuinely spans multiple themes.
-  Keep each sub-section on-contract individually.
-- **Security fixes** may include CVE-style detail and remediation steps
-  beyond normal bullet shape — those callouts are always on-contract.
-- **When in doubt**, cut more aggressively. A reader can always follow
-  the Epic link for detail; they cannot un-read bullets that told them
-  nothing.

package/.agents/rules/shell-conventions.md

@@ -1,61 +0,0 @@
-# Shell & Terminal Conventions
-
-This rule applies when running shell commands during agent execution. The host
-shell varies — agents must adapt to the environment.
-
-## Detecting the Shell
-
-Before chaining commands, check the host shell. Common signals:
-
-- `$env:COMSPEC` set / `pwsh.exe` or `powershell.exe` → PowerShell
-- `$SHELL` set to `/bin/bash`, `/bin/zsh`, etc. → POSIX shell
-- Claude Code system prompt or harness directive announces the shell
-
-## PowerShell (Windows)
-
-PowerShell 5.1 (default on Windows) does **not** support `&&` as a statement
-separator and will throw a parser error. PowerShell 7+ does, but agents
-running on Windows should not assume version 7+.
-
-- **Standard separator**: `;` runs the next command regardless of the first's
-  exit status.
-- **Success chaining (logical AND)**: `; if ($?) { ... }` runs the second
-  command only when the first succeeded.
-- **Example**: `git add . ; if ($?) { git commit -m "..." }`
-
-Other PowerShell-isms agents must respect:
-
-- Use `$null` (not `/dev/null`).
-- Use `$env:VAR` (not `$VAR`).
-- Use backtick (`` ` ``) for line continuation, not backslash.
-
-## POSIX Shells (bash / zsh)
-
-`&&` and `||` work natively. No translation needed.
-
-- **Success chaining**: `cmd1 && cmd2`
-- **Fallback**: `cmd1 || cmd2`
-
-## Cross-Platform Tips
-
-- Prefer the host's tool wrappers (Bash tool, etc.) over raw shell strings
-  when the harness exposes them — they normalize quoting and escaping.
-- For multi-step pipelines that must run identically across platforms, write
-  a Node/Python script and invoke that, rather than chaining shell builtins.
-
-## Searching the Workspace
-
-Prefer, in order: the host's dedicated grep tool (ripgrep-backed — normalizes
-quoting, respects `.gitignore`, streams results), then `git grep` in a git
-repo (`-l` for filenames only), then `rg` outside a git repo or when you need
-multiline / type filters. Do not read whole files to scan for a pattern.
-
-### PowerShell-specific anti-patterns
-
-- If you must use `Select-String`, pass `-List` when you only need to
-  detect existence or collect file paths — without it, every match streams
-  through the pipeline.
-- NEVER chain `Select-Object -Unique` or `Sort-Object` directly after a
-  highly recursive `Get-ChildItem` on large trees. Both block the pipeline,
-  hold every result in memory, and frequently hang the terminal. Stream
-  through `Where-Object` filters first, or pre-narrow with a glob.

package/.agents/scripts/lib/qa/coverage-verdict.js

@@ -1,214 +0,0 @@
-// .agents/scripts/lib/qa/coverage-verdict.js
-//
-// Deterministic per-tier coverage verdict for a single finding surface.
-//
-// A "finding surface" is the unit of code a quality finding points at — a
-// symbol (function / class / module export) together with the set of tests
-// that exercise it. This helper answers one question, purely and without I/O:
-// for that surface, which of the three test tiers from
-// `.agents/rules/testing-standards.md` (unit / contract / acceptance) are
-// PRESENT, and which are ABSENT — and why.
-//
-// A scenario that is skipped does not exercise anything — a `@skip`
-// Gherkin tag (or a runner equivalent such as `it.skip` / `xit` /
-// `describe.skip`, or a `skipped: true` descriptor field) means the test is
-// inert at run time. This module therefore treats a skipped test as ABSENT
-// for its tier: it never bumps a tier into `present`, because a tier whose
-// only "coverage" is a skipped scenario is, operationally, uncovered.
-//
-// The companion process skill is `core/qa-coverage-mapping`, which shows how
-// to gather the surface input and act on the verdict. This module is the
-// deterministic seam that skill delegates to; it makes no network calls, runs
-// no child processes, and reads no environment or files.
-//
-// Public API:
-//
-//   coverageVerdict(surface) -> {
-//     unit:       { status, note },
-//     contract:   { status, note },
-//     acceptance: { status, note },
-//   }
-//
-//   status is 'present' when the tier has at least one classified,
-//   non-skipped test, or 'absent' otherwise. `note` is a short
-//   operator-facing string explaining the verdict (always populated,
-//   including for present tiers).
-//
-// Story #5008 removed the `acceptanceMatrix` feeder and the markdown report it
-// fed: the QA workflows read the per-tier verdict and author the missing-test
-// prose directly, so the AC x tier matrix was a round-trip with no reader.
-
-/** The three test tiers, in pyramid order (base -> top). */
-const TIERS = Object.freeze(['unit', 'contract', 'acceptance']);
-
-const PRESENT = 'present';
-const ABSENT = 'absent';
-
-/** True when `value` contains a `@skip` Gherkin-style tag. */
-function hasSkipTag(value) {
-  if (typeof value !== 'string') return false;
-  return /(^|[\s,])@skip\b/i.test(value);
-}
-
-/** True when `value` contains a runner-level skip/pending marker. */
-function hasRunnerSkipMarker(value) {
-  if (typeof value !== 'string') return false;
-  if (/\b(?:it|test|describe|context)\.(?:skip|todo)\b/i.test(value)) {
-    return true;
-  }
-  return /\bx(?:it|test|describe|context)\b/i.test(value);
-}
-
-/**
- * True when a test descriptor is marked skipped/pending and therefore must
- * NOT count toward its tier. Recognizes:
- *   - a `@skip` tag in a `tags` array or whitespace/comma string,
- *   - the same tags embedded in a path or descriptor `name`,
- *   - explicit boolean flags (`skipped`, `pending`),
- *   - runner skip markers in a path/name (`it.skip`, `xit`, `xdescribe`,
- *     `describe.skip`, `test.skip`, `.todo`).
- *
- * @param {string|object} test
- * @returns {boolean}
- */
-export function isSkipped(test) {
-  if (test == null) return false;
-
-  if (typeof test === 'object') {
-    // 1. Explicit boolean flags win.
-    if (test.skipped === true || test.pending === true) return true;
-
-    // 2. A `tags` field — array of tag strings or a single string.
-    const tags = test.tags;
-    if (Array.isArray(tags)) {
-      if (tags.some((t) => hasSkipTag(t))) return true;
-    } else if (typeof tags === 'string' && hasSkipTag(tags)) {
-      return true;
-    }
-  }
-
-  // 3. Scan a path/name string for an inline skip/pending tag or a runner
-  //    skip marker (covers both string inputs and descriptor `path`/`name`).
-  const scannable =
-    typeof test === 'string'
-      ? test
-      : typeof test === 'object'
-        ? [test.path, test.name].filter((s) => typeof s === 'string').join(' ')
-        : '';
-  return hasSkipTag(scannable) || hasRunnerSkipMarker(scannable);
-}
-
-/**
- * Classify a single test descriptor into one of the three tiers, or `null`
- * when it cannot be placed OR when it is skipped/pending. Tier placement
- * mirrors `.agents/rules/testing-standards.md`:
- *   - unit       — colocated `*.test.*` next to source, or under `__tests__/`.
- *   - contract   — lives under a `tests/contract/**` (or `**\/contract\/**`)
- *                  path.
- *   - acceptance — a Gherkin `.feature` file (e2e / acceptance tier).
- *
- * An explicit `tier` field on the descriptor always wins over path inference,
- * so callers that already know the tier can state it directly.
- *
- * A skipped/pending test (see {@link isSkipped}) is treated as inert and
- * returns `null` so it never counts toward its tier — a tier covered only by
- * a skipped scenario is, operationally, uncovered.
- */
-export function classifyTest(test) {
-  if (test == null) return null;
-
-  // A skipped/pending test exercises nothing — it cannot place into any tier.
-  if (isSkipped(test)) return null;
-
-  // 1. Explicit tier wins.
-  const explicit =
-    typeof test === 'object' && typeof test.tier === 'string'
-      ? test.tier.trim().toLowerCase()
-      : null;
-  if (explicit && TIERS.includes(explicit)) {
-    return explicit;
-  }
-
-  // 2. Infer from a path string.
-  const rawPath =
-    typeof test === 'string'
-      ? test
-      : typeof test === 'object' && typeof test.path === 'string'
-        ? test.path
-        : null;
-  if (!rawPath) return null;
-
-  const p = rawPath.replace(/\\/g, '/').toLowerCase();
-
-  if (p.endsWith('.feature')) return 'acceptance';
-  if (/(^|\/)contract\//.test(p) || /\.contract\.test\.[cm]?[jt]sx?$/.test(p)) {
-    return 'contract';
-  }
-  if (/\.test\.[cm]?[jt]sx?$/.test(p) || /(^|\/)__tests__\//.test(p)) {
-    return 'unit';
-  }
-  return null;
-}
-
-const ABSENT_NOTES = Object.freeze({
-  unit: 'no colocated unit test exercises this surface',
-  contract: 'no contract test asserts this surface’s wire shape or boundary',
-  acceptance: 'no acceptance scenario covers a user-visible journey here',
-});
-
-const PRESENT_NOTES = Object.freeze({
-  unit: (n) => `${n} unit test${n === 1 ? '' : 's'} present`,
-  contract: (n) => `${n} contract test${n === 1 ? '' : 's'} present`,
-  acceptance: (n) => `${n} acceptance scenario${n === 1 ? '' : 's'} present`,
-});
-
-/**
- * Compute the per-tier coverage verdict for one finding surface.
- *
- * @param {object} surface
- * @param {string} [surface.symbol] - The symbol the finding points at; echoed
- *   into notes for operator context. Optional.
- * @param {Array<string|{path?:string,tier?:string,tags?:string|string[],skipped?:boolean,pending?:boolean}>} [surface.tests] -
- *   The tests that exercise the surface. Each entry is either a path string or
- *   a descriptor with `path`, `tier`, and/or skip markers (`tags`, `skipped`,
- *   `pending`). Unclassifiable and skipped/pending entries are ignored.
- * @returns {{unit:{status:string,note:string},
- *            contract:{status:string,note:string},
- *            acceptance:{status:string,note:string}}}
- */
-export function coverageVerdict(surface = {}) {
-  if (surface === null || typeof surface !== 'object') {
-    throw new TypeError('coverageVerdict: surface must be an object');
-  }
-
-  const tests = Array.isArray(surface.tests) ? surface.tests : [];
-  const symbol =
-    typeof surface.symbol === 'string' && surface.symbol.trim() !== ''
-      ? surface.symbol.trim()
-      : null;
-
-  const counts = { unit: 0, contract: 0, acceptance: 0 };
-  for (const test of tests) {
-    const tier = classifyTest(test);
-    if (tier) counts[tier] += 1;
-  }
-
-  const verdict = {};
-  for (const tier of TIERS) {
-    const n = counts[tier];
-    if (n > 0) {
-      verdict[tier] = {
-        status: PRESENT,
-        note: PRESENT_NOTES[tier](n),
-      };
-    } else {
-      const base = ABSENT_NOTES[tier];
-      verdict[tier] = {
-        status: ABSENT,
-        note: symbol ? `${base} (${symbol})` : base,
-      };
-    }
-  }
-
-  return verdict;
-}

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

@@ -1,55 +0,0 @@
----
-name: api-and-interface-design
-description:
-  Designs stable, well-documented APIs and module interfaces. Use when
-  creating REST/GraphQL endpoints, defining contracts between modules, or
-  changing public interfaces. The wire-format SSOT — response envelope, HTTP
-  status codes, validation taxonomy, payload naming — lives in
-  `.agents/rules/api-conventions.md`; this skill shows authors how to apply
-  it.
----
-
-# Skill: api-and-interface-design
-
-## Policy Capsule
-
-- The wire-format SSOT lives in [`.agents/rules/api-conventions.md`](../../../rules/api-conventions.md) (envelope shape, HTTP status mapping, validation taxonomy, payload casing). Copy the canonical envelope and status codes from the rule rather than redrafting or hand-rolling a divergent shape. Validation failures return **400** `VALIDATION_ERROR` per [§ Validation Status](../../../rules/api-conventions.md#validation-status).
-- Be intentional about exposure (Hyrum's Law): every observable behaviour — undocumented quirks, error message text, ordering, timing — becomes a de facto contract once consumers depend on it. Don't leak implementation details.
-- Adopt the **One-Version Rule**: never force consumers to choose between simultaneous versions of the same API. Extend rather than fork.
-- 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. 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 [`security-baseline.md`](../../../rules/security-baseline.md) and [`testing-standards.md`](../../../rules/testing-standards.md) respectively — apply both, and never put DB/wire-shape assertions outside the contract tier.
-
-## When to Use
-
-- Designing new API endpoints, module boundaries, or component prop interfaces.
-- Establishing a database schema that informs API shape.
-- Changing existing public interfaces.
-
-## Wire format — defer to the rule
-
-The response envelope, HTTP status-code mapping, validation-status taxonomy,
-and payload-naming conventions are non-negotiable and live in the rule. When
-designing a new endpoint, **copy the canonical envelope from the rule** — do
-not redraft it, and do not invent a project-specific validation status:
-
-- Envelope shape: [`api-conventions.md` § Response Envelope](../../../rules/api-conventions.md#response-envelope).
-- Status table (200/201/400/401/403/404/409/500): [`§ HTTP Status Codes`](../../../rules/api-conventions.md#http-status-codes).
-- Validation status (**400** `VALIDATION_ERROR`): [`§ Validation Status`](../../../rules/api-conventions.md#validation-status).
-- Casing conventions: [`§ Payload Formatting`](../../../rules/api-conventions.md#payload-formatting).
-
-## Long-form reference — read on demand
-
-The elaboration behind the capsule — Hyrum's-Law implications, the
-contract-first stance, and where boundary validation does and does not belong,
-plus the pre-PR authoring checklist — lives in the on-demand sibling
-[`reference.md`](reference.md). Generic REST-catalog and TypeScript-idiom
-snippets are intentionally omitted (frontier-known; the rule owns the wire
-format). Open a section only when the task engages it.
-
-- [Hyrum's Law and the One-Version Rule](reference.md#hyrums-law-and-the-one-version-rule)
-- [Contract First and Boundary Validation](reference.md#contract-first-and-boundary-validation)
-- [Authoring Checklist](reference.md#authoring-checklist)

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

@@ -1,76 +0,0 @@
-# API & Interface Design — Reference (on-demand)
-
-**Read this when** a task engages one of the sections below and the Policy
-Capsule in [`SKILL.md`](SKILL.md) does not settle it on its own. The capsule
-is the contract; this file is the reference material behind it. Generic
-REST-verb tables and TypeScript pattern catalogs are deliberately not
-reproduced here — they are frontier-known, and the wire format is owned by the
-SSOT rule, [`api-conventions.md`](../../../rules/api-conventions.md).
-
-## Hyrum's Law and the One-Version Rule
-
-> With a sufficient number of users of an API, all observable behaviors of your
-> system will be depended on by somebody, regardless of what you promise in the
-> contract.
-
-Every observable behavior — undocumented quirks, error message text, timing,
-ordering — becomes a de facto contract once users depend on it. Practical
-implications:
-
-- **Be intentional about what you expose.** Every observable behavior is a
-  potential commitment; if users can observe it, they will depend on it.
-- **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.
-
-**One-Version Rule.** Avoid forcing consumers to choose between multiple
-versions of the same API. Diamond-dependency problems arise when different
-consumers need different versions of the same thing. Design for a world where
-only one version exists at a time — extend rather than fork.
-
-## Contract First and Boundary Validation
-
-Define the interface before implementing it — the contract is the spec, and
-implementation follows. Prefer **addition over modification**: add optional
-fields rather than changing existing field types or removing fields.
-
-Validation runs at system **boundaries**, where external input enters. After
-validation, internal code trusts the types. On failure, return the canonical
-**400** `VALIDATION_ERROR` envelope from
-[`api-conventions.md` § Response Envelope](../../../rules/api-conventions.md#response-envelope) —
-do not redraft the shape or the status.
-
-**Where validation belongs:**
-
-- API route handlers (user input).
-- Form submission handlers (user input).
-- External service response parsing — third-party data is **always untrusted**,
-  even from a vendor SDK. A compromised or misbehaving service can return
-  unexpected types, malicious content, or instruction-like text; validate shape
-  and content before using it in any logic, render, or decision.
-- Environment variable loading (configuration).
-
-**Where validation does NOT belong:**
-
-- Between internal functions that share type contracts.
-- In utility functions called by already-validated code.
-- On data that just came from your own database.
-
-## Authoring Checklist
-
-Before opening a PR that adds or edits an API surface:
-
-- [ ] Every endpoint has typed input and output schemas.
-- [ ] Error responses follow the envelope in
-      [`api-conventions.md` § Response Envelope](../../../rules/api-conventions.md#response-envelope).
-- [ ] Status codes match
-      [`api-conventions.md` § HTTP Status Codes](../../../rules/api-conventions.md#http-status-codes),
-      and validation failures return the canonical **400** `VALIDATION_ERROR`.
-- [ ] List endpoints support pagination.
-- [ ] New fields are additive and optional (backward compatible).
-- [ ] Naming follows
-      [`api-conventions.md` § Payload Formatting](../../../rules/api-conventions.md#payload-formatting).
-- [ ] API documentation or types are committed alongside the implementation.

package/.agents/skills/core/debugging-and-error-recovery/SKILL.md

@@ -1,45 +0,0 @@
----
-name: debugging-and-error-recovery
-description:
-  Guides systematic root-cause debugging. Use when tests fail, builds break,
-  behavior doesn't match expectations, or you encounter any unexpected error.
-  Use when you need a systematic approach to finding and fixing the root cause
-  rather than guessing.
----
-
-# Debugging and Error Recovery
-
-## Policy Capsule
-
-- **Stop the line** the instant something breaks: stop adding features, preserve evidence (errors, logs, repro), diagnose, fix root cause, guard against recurrence, **then** resume. Never push past a failing test or broken build.
-- Follow the triage checklist in order — **Reproduce → Localize → Diagnose → Fix → Verify → Guard** — and never skip steps.
-- A bug you cannot reproduce reliably is a bug you cannot fix with confidence. Invest in reproduction before patching.
-- Fix the **root cause**, not the symptom. Suppressing an error, swallowing an exception, or stubbing an assertion is not a fix.
-- Every bug fix ships with a **failing-then-passing regression test** (the Prove-It Pattern in `.agents/rules/testing-standards.md`). A fix without a guard test is incomplete.
-- Apply the **Anti-Thrashing** rule: if you have applied the same kind of fix more than once and the failure mode hasn't changed, the diagnosis is wrong — re-plan.
-- For non-reproducible bugs, classify them (timing / environment / state / random), add targeted instrumentation, and document conditions instead of chasing in the dark.
-- Bisect history with `git bisect` (or equivalent) when "something used to work" and you cannot localize from the diff.
-- After verification passes, document the root cause and the guard so the same class of failure cannot recur silently.
-
-## Long-form reference — read on demand
-
-The capsule above is the contract and the whole always-read surface of this
-skill. The long-form material behind it — patterns, worked examples,
-checklists, and rationalizations — lives in the on-demand sibling
-[`reference.md`](reference.md), matching the split the always-on rules already
-use ([`rules/git-conventions.md`](../../../rules/git-conventions.md) ⇄
-[`git-conventions-reference.md`](../../../rules/git-conventions-reference.md)).
-Activating this skill costs the capsule; open a section below only when the
-task actually engages it.
-
-- [Overview](reference.md#overview)
-- [When to Use](reference.md#when-to-use)
-- [The Stop-the-Line Rule](reference.md#the-stop-the-line-rule)
-- [The Triage Checklist](reference.md#the-triage-checklist)
-- [Error-Specific Patterns](reference.md#error-specific-patterns)
-- [Safe Fallback Patterns](reference.md#safe-fallback-patterns)
-- [Instrumentation Guidelines](reference.md#instrumentation-guidelines)
-- [Common Rationalizations](reference.md#common-rationalizations)
-- [Treating Error Output as Untrusted Data](reference.md#treating-error-output-as-untrusted-data)
-- [Red Flags](reference.md#red-flags)
-- [Verification](reference.md#verification)