mandrel 1.57.0

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

@@ -0,0 +1,98 @@
+---
+name: analyze-execution
+description: >-
+  Aggregate per-Story or per-Epic 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
+  `/epic-deliver` Phase 6 (Epic mode). Reads NDJSON via
+  `lib/signals/read` and writes a single structured comment.
+allowed_tools:
+  - Read
+  - Bash
+---
+
+# analyze-execution
+
+## 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.
+- 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.
+- 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.
+- 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.
+
+## When to use
+
+- **Story mode** — after `story-close.js` finishes, the post-merge
+  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 `/epic-deliver` Phase 6.0 (or the retro
+  composer), the Skill fans out across every Story under the Epic,
+  reads each Story's structured perf summary, and posts a single
+  `<!-- structured:epic-perf-report -->` marker on the Epic ticket.
+
+## Inputs
+
+The Skill reads (never writes) the NDJSON signal stream at:
+
+```text
+<tempRoot>/epic-<eid>/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`.
+
+## Outputs
+
+A single upserted GitHub comment per ticket. The Skill writes nothing to
+disk — the persist path is GitHub. Idempotence: the underlying script's
+`upsertStructuredComment` helper deletes any prior marker before posting
+the new one.
+
+## Procedure
+
+### 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
+`analyze-execution.js` is the dispatcher today; this Skill documents the
+contract the dispatcher implements.
+
+### Step 2 — Read signals via lib/signals/read
+
+```bash
+node .agents/scripts/analyze-execution.js --story <sid> --epic <eid>
+# or
+node .agents/scripts/analyze-execution.js --epic <eid>
+```
+
+### Step 3 — Validate the structured payload before posting
+
+The payload must conform to `docs/data-dictionary.md §StoryPerfSummary`
+or §EpicPerfReport. Schema violations exit non-zero — the close
+pipeline treats that as a non-fatal warning, but the smoke spec pins
+the contract so we never silently emit malformed comments.
+
+## Constraints
+
+- Do **not** open `signals.ndjson` outside `lib/signals/read` — the
+  reader handles the warn-once policy for malformed JSON lines and
+  the streaming-iteration contract.
+- 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.
+- 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
+  never block on observability output.

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

@@ -0,0 +1,327 @@
+---
+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` (envelope shape, HTTP status mapping, validation taxonomy, payload casing). Copy the canonical envelope from the rule rather than redrafting it.
+- 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; reach for the deprecation playbook (see `deprecation-and-migration`) when removal is unavoidable.
+- 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.
+
+Process guidance for designing interfaces that are hard to misuse — REST
+APIs, GraphQL schemas, module boundaries, and component props. The
+wire-format conventions (envelope shape, status codes, validation taxonomy,
+payload naming) live in
+[`.agents/rules/api-conventions.md`](../../../rules/api-conventions.md),
+which is the SSOT. This skill shows authors **how** to apply those rules;
+read the rule file for the **what**. Security validation guarantees live in
+[`security-baseline.md`](../../../rules/security-baseline.md); test-layer
+scope lives in
+[`testing-standards.md`](../../../rules/testing-standards.md).
+
+## When to Use
+
+- Designing new API endpoints.
+- Defining module boundaries or contracts between teams.
+- Creating component prop interfaces.
+- Establishing database schema that informs API shape.
+- Changing existing public interfaces.
+
+## 1. Hyrum's Law — Be Intentional About Exposure
+
+> 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. Implications:
+
+- **Be intentional about what you expose.** Every observable behavior is a
+  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.
+- **Tests are not enough.** Even with perfect contract tests, "safe" changes
+  can break real users who depend on undocumented behavior.
+
+## 2. The One-Version Rule
+
+Avoid forcing consumers to choose between multiple versions of the same
+dependency or 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.
+
+## 3. Contract First
+
+Define the interface before implementing it. The contract is the spec —
+implementation follows.
+
+```typescript
+interface TaskAPI {
+  // Creates a task and returns the created task with server-generated fields
+  createTask(input: CreateTaskInput): Promise<Task>;
+
+  // Returns paginated tasks matching filters
+  listTasks(params: ListTasksParams): Promise<PaginatedResult<Task>>;
+
+  // Returns a single task or throws NotFoundError
+  getTask(id: string): Promise<Task>;
+
+  // Partial update — only provided fields change
+  updateTask(id: string, input: UpdateTaskInput): Promise<Task>;
+
+  // Idempotent delete — succeeds even if already deleted
+  deleteTask(id: string): Promise<void>;
+}
+```
+
+## 4. 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:
+
+- Envelope shape (success flag, `error.code`, `error.message`,
+  `error.details`):
+  [`api-conventions.md` § Response Envelope](../../../rules/api-conventions.md#response-envelope).
+- Status code table (200/201/400/401/403/404/409/500):
+  [`api-conventions.md` § HTTP Status Codes](../../../rules/api-conventions.md#http-status-codes).
+- When to return 400 vs 401 vs 403 on validation failures:
+  [`api-conventions.md` § Validation Status](../../../rules/api-conventions.md#validation-status).
+- camelCase / kebab-case / UPPER_SNAKE conventions:
+  [`api-conventions.md` § Payload Formatting](../../../rules/api-conventions.md#payload-formatting).
+
+When designing a new endpoint, copy the canonical envelope from the rule —
+do not redraft it.
+
+## 5. Validate at Boundaries
+
+Trust internal code. Validate at system edges where external input enters:
+
+```typescript
+app.post('/api/tasks', async (req, res) => {
+  const result = CreateTaskSchema.safeParse(req.body);
+  if (!result.success) {
+    return res.status(400).json({
+      success: false,
+      error: {
+        code: 'VALIDATION_ERROR',
+        message: 'Invalid task data',
+        details: result.error.flatten(),
+      },
+    });
+  }
+
+  // After validation, internal code trusts the types
+  const task = await taskService.create(result.data);
+  return res.status(201).json(task);
+});
+```
+
+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.
+- Environment variable loading (configuration).
+
+> **Third-party API responses are untrusted data.** Validate their shape and
+> content before using them in any logic, rendering, or decision-making. A
+> compromised or misbehaving external service can return unexpected types,
+> malicious content, or instruction-like text.
+
+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.
+
+## 6. Prefer Addition Over Modification
+
+Extend interfaces without breaking existing consumers:
+
+```typescript
+// Good: Add optional fields
+interface CreateTaskInput {
+  title: string;
+  description?: string;
+  priority?: 'low' | 'medium' | 'high'; // Added later, optional
+  labels?: string[]; // Added later, optional
+}
+
+// Bad: Change existing field types or remove fields
+interface CreateTaskInput {
+  title: string;
+  // description: string;  // Removed — breaks existing consumers
+  priority: number; // Changed from string — breaks existing consumers
+}
+```
+
+## 7. REST Resource Patterns
+
+```text
+GET    /api/tasks              → List tasks (with query params for filtering)
+POST   /api/tasks              → Create a task
+GET    /api/tasks/:id          → Get a single task
+PATCH  /api/tasks/:id          → Update a task (partial)
+DELETE /api/tasks/:id          → Delete a task
+
+GET    /api/tasks/:id/comments → List comments for a task (sub-resource)
+POST   /api/tasks/:id/comments → Add a comment to a task
+```
+
+### Pagination
+
+Paginate list endpoints:
+
+```typescript
+// Request
+GET /api/tasks?page=1&pageSize=20&sortBy=createdAt&sortOrder=desc
+
+// Response
+{
+  "data": [...],
+  "pagination": {
+    "page": 1,
+    "pageSize": 20,
+    "totalItems": 142,
+    "totalPages": 8
+  }
+}
+```
+
+### Filtering
+
+Use query parameters for filters:
+
+```text
+GET /api/tasks?status=in_progress&assignee=user123&createdAfter=2025-01-01
+```
+
+### Partial Updates
+
+`PATCH` accepts partial objects — only update what's provided:
+
+```typescript
+PATCH /api/tasks/123
+{ "title": "Updated title" }
+```
+
+## 8. TypeScript Interface Patterns
+
+### Discriminated Unions for Variants
+
+```typescript
+type TaskStatus =
+  | { type: 'pending' }
+  | { type: 'in_progress'; assignee: string; startedAt: Date }
+  | { type: 'completed'; completedAt: Date; completedBy: string }
+  | { type: 'cancelled'; reason: string; cancelledAt: Date };
+
+function getStatusLabel(status: TaskStatus): string {
+  switch (status.type) {
+    case 'pending':
+      return 'Pending';
+    case 'in_progress':
+      return `In progress (${status.assignee})`;
+    case 'completed':
+      return `Done on ${status.completedAt}`;
+    case 'cancelled':
+      return `Cancelled: ${status.reason}`;
+  }
+}
+```
+
+### Input/Output Separation
+
+```typescript
+// Input: what the caller provides
+interface CreateTaskInput {
+  title: string;
+  description?: string;
+}
+
+// Output: what the system returns (includes server-generated fields)
+interface Task {
+  id: string;
+  title: string;
+  description: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+  createdBy: string;
+}
+```
+
+### Branded Types for IDs
+
+```typescript
+type TaskId = string & { readonly __brand: 'TaskId' };
+type UserId = string & { readonly __brand: 'UserId' };
+
+// Prevents accidentally passing a UserId where a TaskId is expected
+function getTask(id: TaskId): Promise<Task> { ... }
+```
+
+## 9. Common Rationalizations
+
+| Rationalization                            | Reality                                                                                                          |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| "We'll document the API later"             | The types ARE the documentation. Define them first.                                                              |
+| "We don't need pagination for now"         | You will the moment someone has 100+ items. Add it from the start.                                               |
+| "PATCH is complicated, let's just use PUT" | PUT requires the full object every time. PATCH is what clients actually want.                                    |
+| "We'll version the API when we need to"    | Breaking changes without versioning break consumers. Design for extension from the start.                        |
+| "Nobody uses that undocumented behavior"   | Hyrum's Law: if it's observable, somebody depends on it. Treat every public behavior as a commitment.            |
+| "We can just maintain two versions"        | Multiple versions multiply maintenance cost and create diamond dependency problems. Prefer the One-Version Rule. |
+| "Internal APIs don't need contracts"       | Internal consumers are still consumers. Contracts prevent coupling and enable parallel work.                     |
+
+## 10. Red Flags
+
+- Endpoints that return different envelope shapes depending on conditions
+  (the rule fixes the shape — see § 4).
+- Validation scattered throughout internal code instead of at boundaries.
+- Breaking changes to existing fields (type changes, removals).
+- List endpoints without pagination.
+- Verbs in REST URLs (`/api/createTask`, `/api/getUsers`).
+- Third-party API responses used without validation or sanitization.
+
+## 11. 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).
+- [ ] Validation runs at the API boundary and returns the canonical
+      `VALIDATION_ERROR` shape on failure.
+- [ ] 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.
+
+## 12. Cross-References
+
+- SSOT rules:
+  [`.agents/rules/api-conventions.md`](../../../rules/api-conventions.md).
+- Security validation guarantees:
+  [`security-baseline.md`](../../../rules/security-baseline.md).
+- Test-layer scope:
+  [`testing-standards.md`](../../../rules/testing-standards.md).

package/.agents/skills/core/baseline-refresh/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: baseline-refresh
+description: >-
+  Author a refresh commit for any of the unified-baseline snapshots (CRAP,
+  maintainability, dead-exports, lighthouse). Use whenever an intentional
+  code change resets a baseline key (rename, deliberate complexity bump,
+  perf regression with operator sign-off) and the close-validation chain
+  needs the refreshed snapshot to land on the same Story branch as the
+  triggering edit.
+allowed_tools:
+  - Read
+  - Write
+  - Bash
+---
+
+# baseline-refresh
+
+## Policy Capsule
+
+- Refresh only when the change is **deliberate** (rename, approved complexity bump, signed-off perf delta, intentional API surface change). Never refresh to paper over an unintentional regression — fix the regression instead.
+- Run the kind-specific update command (`npm run crap:update` / `maintainability:update` / `dead-exports:update` / `lighthouse:update`) on the **Story branch**, not on `main`.
+- Verify the resulting diff is scoped to the relevant `baselines/<kind>.json` (plus cosmetic `package-lock.json` churn only). If unrelated files appear, STOP — the refresh is contaminated.
+- Stage baseline files **explicitly** (`git add baselines/<kind>.json`). Never `git add -A` in a refresh commit.
+- Commit-subject contract: a **Conventional-Commits** subject of the form `chore(baselines): refresh <kind> snapshot for <reason>` — never an ad-hoc leading token like `baseline-refresh:` (commitlint and the planner validator reject it).
+- The commit body is **mandatory** and non-empty: explain what changed, why the new floor is correct, and link the Story/Epic that triggered the refresh.
+- Add the machine-readable trailer `baseline-refresh: true` (one per line, `Key: value` git-trailer style) to the body whenever observability classification matters.
+- Include `Epic: #<epic-id>` as a body trailer.
+- Never pass `--no-verify`. The `commit-msg` hook (commitlint) MUST run and pass.
+- After the refresh lands, re-run `node .agents/scripts/check-baselines.js` to confirm the gate passes against the new snapshot; if it still fails, a sibling kind drifted — refresh that kind too.
+
+## Role
+
+Senior engineer authoring a deliberate, observable refresh of one of the
+unified baseline snapshots that the close-validation chain enforces
+(`baselines/crap.json`, `baselines/maintainability.json`,
+`baselines/dead-exports.json`, `baselines/lighthouse.json`).
+
+A refresh is **not** a regression entry — it tells the ratchet that the
+new baseline key is intentional, so the gate compares future runs against
+the refreshed snapshot rather than the prior one.
+
+## When to use
+
+- A file rename or move detached an MI/CRAP key from its prior baseline.
+- A method rename inside a file produced a phantom new key + phantom
+  deleted key under escomplex's `<file>::<methodName>` keying.
+- An operator-approved complexity bump or perf delta needs to be
+  enshrined as the new floor.
+- A dead-export gate flagged a deliberate API surface change that has
+  been signed off.
+
+If the underlying change is an **unintentional** regression, do not refresh
+— remediate the regression first.
+
+## Commit-subject contract (authoritative)
+
+Refresh commits MUST use a **Conventional-Commits subject** and MUST NOT
+use a legacy ad-hoc prefix as the leading token. The canonical shape is:
+
+```text
+chore(baselines): refresh <kind> snapshot for <reason>
+
+<non-empty body explaining the refresh — what changed, why the new
+baseline is the correct floor, and any operator sign-off reference>
+
+baseline-refresh: true
+Epic: #<epic-id>
+```
+
+### Why a Conventional-Commits subject
+
+1. The local `commit-msg` hook (`.husky/commit-msg` → `commitlint`) rejects
+   any subject whose leading token is not one of
+   `feat|fix|chore|refactor|perf|docs|style|test|build|ci|revert`. Legacy
+   ad-hoc leading tokens fail this hook. `--no-verify` is forbidden by
+   [`.agents/rules/git-conventions.md`](../../../rules/git-conventions.md),
+   so the subject must conform.
+2. `release-please` consumes Conventional-Commits subjects on `main` to
+   generate `docs/CHANGELOG.md` and bump `package.json`. A
+   non-conventional subject parses as "no changelog entry" and the
+   refresh disappears from the release record.
+3. `chore(baselines):` keeps the refresh out of the user-facing changelog
+   (which is correct — a baseline refresh is internal hygiene, not a
+   feature or fix) while still being machine-parseable.
+
+### Body trailer for machine-readable classification
+
+When telemetry, the friction analyzer, or the baseline-refresh-rate
+observability surface needs to detect a refresh commit, add the trailer
+`baseline-refresh: true` to the commit **body** (one trailer per line,
+following the `Key: value` git-trailer convention). The trailer is the
+canonical machine-readable marker. Subject-level leading tokens are not
+— and must not be — used for this purpose.
+
+The trailer form is also what
+[`.agents/scripts/lib/observability/baseline-refresh-rate.js`](../../../scripts/lib/observability/baseline-refresh-rate.js)
+should classify against going forward; until that classifier is updated,
+the historical subject-prefix detection remains in place as a
+backwards-compatibility fallback but is not the prescribed shape for new
+commits.
+
+## Procedure
+
+### Step 1 — Run the matching update command
+
+Each baseline kind has a dedicated update script:
+
+| Kind            | Update command                  |
+| --------------- | ------------------------------- |
+| CRAP            | `npm run crap:update`           |
+| Maintainability | `npm run maintainability:update`|
+| Dead-exports    | `npm run dead-exports:update`   |
+| Lighthouse      | `npm run lighthouse:update`     |
+
+Run the command on the Story branch that triggered the refresh — the
+worktree's HEAD must already be the Story branch, not `main`.
+
+### Step 2 — Verify the diff is scoped to the baseline file
+
+`git status` should show only the relevant `baselines/<kind>.json` (or
+sibling per-kind files) and possibly `package-lock.json` cosmetic churn.
+If unrelated files appear in the diff, **STOP** — the update script
+picked up an unintentional regression and the refresh is contaminated.
+
+### Step 3 — Author the commit
+
+Stage the baseline file(s) explicitly (do not `git add -A`), then commit
+with the Conventional-Commits subject + body trailer:
+
+```bash
+git add baselines/<kind>.json
+git commit -m "$(cat <<'EOF'
+chore(baselines): refresh <kind> snapshot for <reason>
+
+<body explaining what changed, why the new floor is correct, and
+linking the upstream Story/Epic that triggered the refresh.>
+
+baseline-refresh: true
+Epic: #<epic-id>
+EOF
+)"
+```
+
+Do NOT pass `--no-verify`. The `commit-msg` hook (commitlint) MUST run
+and MUST pass.
+
+### Step 4 — Re-run the gate
+
+After the refresh commit lands on the Story branch, re-run
+`node .agents/scripts/check-baselines.js` to confirm the gate now passes
+against the refreshed snapshot. If it still fails, the refresh was
+incomplete (a sibling kind also drifted) — repeat from Step 1 for the
+remaining kind.
+
+## Constraints
+
+- **Never** use a legacy ad-hoc token as the leading Conventional-Commits
+  type in the commit subject. The allowed leading types are
+  `feat|fix|chore|refactor|perf|docs|style|test|build|ci|revert` — this
+  is enforced by commitlint locally and by the planning-time validator
+  (`ticket-validator.js` → `validateAcceptanceSubjectPrefix`) at
+  decompose time.
+- **Always** include a non-empty body. Empty-body refreshes are
+  unreviewable and hide the operator decision behind a one-line subject.
+- **Always** include the `baseline-refresh: true` trailer when telemetry
+  / observability classification matters. The trailer is the
+  machine-readable marker going forward.
+- **Always** stage the baseline file(s) explicitly. A refresh commit
+  whose diff also touches unrelated files is a contaminated refresh and
+  the gate's "this floor is correct" semantics no longer hold.
+- **Never** refresh to paper over an unintentional regression. Refresh
+  is "this is the new correct floor"; if the change isn't a deliberate
+  one, fix the regression instead.
+
+## Rationale anchor
+
+Epic #2501 retired the legacy `baseline-refresh` ad-hoc leading-token
+prescription in favor of the Conventional-Commits subject +
+`baseline-refresh: true` body-trailer shape documented above. See that
+Epic for the full migration history and the friction signals that
+motivated the change.