mandrel 1.92.0 → 1.94.0

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

@@ -1,227 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * plan-critics.js — deterministic dispatch gate for the conditional
- * author-step critics of the collapsed /plan flow (Epic #4474 PR6,
- * design §4).
- *
- * Runs between authoring and gate #2, entirely git-local (zero GitHub
- * calls): reads the authored artifacts, evaluates the risk/size dispatch
- * conditions for the consolidation (8.3) and pre-mortem (8.5) critics via
- * `lib/orchestration/plan-critic-conditions.js`, and emits one JSON
- * verdict on stdout. The workflow dispatches a fresh-context sub-agent
- * ONLY for critics with `dispatch: true`; every skip decision is appended
- * to the plan-metrics ledger (`kind: "critic-skip"`, with reasons) so
- * under-firing is auditable — the persist validators remain unchanged
- * hard gates regardless of what this gate decides.
- *
- * Conditions (design §4 / §6 PR6):
- *   - Consolidation: the existing deterministic precondition
- *     (`evaluateConsolidationPrecondition`) says dispatch AND (the draft
- *     has > 5 stories OR a confirmed divergence from the Tech Spec's
- *     Delivery Slicing table). Skipped outright in the single-delivery
- *     shape (no tickets exist to consolidate).
- *   - Pre-mortem: risk verdict overall level is high, OR ticket count is
- *     at least half `maxTickets`, OR any `planning.riskHeuristics` phrase
- *     matches the plan text (case-insensitive substring over tech spec +
- *     tickets + risk summary).
- *
- * Modes:
- *   --epic <id>          Artifact paths default to the per-Epic temp tree
- *                        (`temp/epic-<id>/techspec.md`, `risk-verdict.json`,
- *                        `tickets.json`); skip records land on the
- *                        per-Epic plan-metrics ledger.
- *   explicit paths       Ideation mode: pass --tech-spec/--risk-verdict
- *                        (and --tickets when fan-out) explicitly; skip
- *                        records land on the standalone ledger stream.
- *
- * Output (stdout-pure JSON):
- *   { epicId, consolidation: { critic, dispatch, reasons },
- *     premortem: { critic, dispatch, reasons } }
- *
- * Exit codes: 0 — verdict emitted (dispatch decisions are data, not
- * failures); 1 — fatal error (unreadable/invalid artifacts, bad args).
- */
-
-// Fail-fast if the framework's runtime deps are not installed — must be the
-// first import so the check runs before any third-party-importing sibling
-// module is evaluated (Story #3432).
-import './lib/runtime-deps/ensure-installed.js';
-import { readFile } from 'node:fs/promises';
-import { parseArgs } from 'node:util';
-
-import { runAsCli } from './lib/cli-utils.js';
-import { epicArtifactPath } from './lib/config/temp-paths.js';
-import {
-  getLimits,
-  resolveConfig,
-  validateOrchestrationConfig,
-} from './lib/config-resolver.js';
-import { routeAllOutputToStderr } from './lib/Logger.js';
-import { loadRiskVerdict } from './lib/orchestration/epic-plan-spec/phases/risk-verdict.js';
-import {
-  evaluateConsolidationDispatch,
-  evaluatePremortemDispatch,
-} from './lib/orchestration/plan-critic-conditions.js';
-import {
-  appendCriticSkip,
-  recordPlanInvocation,
-} from './lib/orchestration/plan-metrics.js';
-
-const USAGE =
-  'Usage: plan-critics.js (--epic <EpicId> | --tech-spec <file> ' +
-  '--risk-verdict <file> [--tickets <file>]) [--pretty]';
-
-/**
- * Resolve the planning risk heuristics list from the canonical config
- * block (same resolution `plan-context.js` and the decompose context use).
- *
- * @param {object} config
- * @returns {string[]}
- */
-function resolveRiskHeuristics(config = {}) {
-  if (Array.isArray(config.planning?.riskHeuristics)) {
-    return config.planning.riskHeuristics;
-  }
-  return config.agentSettings?.planning?.riskHeuristics || [];
-}
-
-async function readOptional(filePath, { required }) {
-  try {
-    return await readFile(filePath, 'utf8');
-  } catch (err) {
-    if (!required && err?.code === 'ENOENT') return null;
-    throw new Error(`Cannot read ${filePath}: ${err.message}`);
-  }
-}
-
-async function main() {
-  const { values } = parseArgs({
-    options: {
-      epic: { type: 'string' },
-      'tech-spec': { type: 'string' },
-      'risk-verdict': { type: 'string' },
-      tickets: { type: 'string' },
-      pretty: { type: 'boolean', default: false },
-    },
-    strict: true,
-  });
-
-  let epicId = null;
-  if (values.epic !== undefined) {
-    epicId = Number.parseInt(values.epic, 10);
-    if (!Number.isInteger(epicId)) {
-      throw new Error(
-        `--epic must be a numeric issue id (got "${values.epic}").\n${USAGE}`,
-      );
-    }
-  }
-
-  // stdout is reserved for the JSON verdict — flip every Logger sink to
-  // stderr before any pipeline code runs (same guarantee plan-context.js
-  // gives its envelope).
-  routeAllOutputToStderr();
-
-  let config;
-  try {
-    config = resolveConfig();
-    validateOrchestrationConfig(config);
-  } catch (err) {
-    throw new Error(`Config schema validation failed:\n${err.message}`);
-  }
-
-  const fallback = (basename) =>
-    epicId === null ? undefined : epicArtifactPath(epicId, basename, config);
-  const techSpecPath = values['tech-spec'] ?? fallback('techspec.md');
-  const riskVerdictPath =
-    values['risk-verdict'] ?? fallback('risk-verdict.json');
-  const ticketsPath = values.tickets ?? fallback('tickets.json');
-  if (!techSpecPath || !riskVerdictPath) {
-    throw new Error(
-      `Missing artifact path(s): without --epic, explicit --tech-spec and --risk-verdict are required.\n${USAGE}`,
-    );
-  }
-
-  const verdict = await recordPlanInvocation(
-    { cli: 'plan-critics', mode: 'evaluate', epicId, config },
-    async () => {
-      const techSpecContent = await readOptional(techSpecPath, {
-        required: true,
-      });
-      const riskVerdict = loadRiskVerdict(riskVerdictPath);
-      // Tickets are shape-dependent: a single-delivery plan authors none.
-      // Required only when passed explicitly.
-      const ticketsRaw = ticketsPath
-        ? await readOptional(ticketsPath, {
-            required: values.tickets !== undefined,
-          })
-        : null;
-      let tickets = null;
-      if (ticketsRaw !== null) {
-        try {
-          tickets = JSON.parse(ticketsRaw);
-        } catch (err) {
-          throw new Error(
-            `Failed to parse tickets file "${ticketsPath}" as JSON: ${err.message}`,
-          );
-        }
-        if (!Array.isArray(tickets)) {
-          throw new Error(
-            `Tickets file "${ticketsPath}" must contain a JSON array.`,
-          );
-        }
-      }
-
-      const consolidation =
-        tickets === null
-          ? {
-              critic: 'consolidation',
-              dispatch: false,
-              reasons: [
-                'single-delivery shape — no draft tickets exist to consolidate.',
-              ],
-            }
-          : evaluateConsolidationDispatch({
-              draftStories: tickets,
-              specText: techSpecContent,
-            });
-
-      const premortem = evaluatePremortemDispatch({
-        riskVerdict,
-        ticketCount: tickets?.length ?? 0,
-        maxTickets: getLimits(config).maxTickets,
-        riskHeuristics: resolveRiskHeuristics(config),
-        planText: [
-          techSpecContent,
-          ticketsRaw ?? '',
-          riskVerdict.summary ?? '',
-        ].join('\n'),
-      });
-
-      // Skip-audit trail (#4474 PR6): every non-dispatch is a ledger
-      // record. Best-effort — a failed append never fails the gate.
-      for (const decision of [consolidation, premortem]) {
-        if (!decision.dispatch) {
-          await appendCriticSkip(
-            {
-              critic: decision.critic,
-              reasons: decision.reasons,
-              cli: 'plan-critics',
-              epicId,
-            },
-            config,
-          );
-        }
-      }
-
-      return { epicId, consolidation, premortem };
-    },
-  );
-
-  const json = values.pretty
-    ? JSON.stringify(verdict, null, 2)
-    : JSON.stringify(verdict);
-  process.stdout.write(`${json}\n`);
-}
-
-runAsCli(import.meta.url, main, { source: 'plan-critics' });

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

@@ -1,181 +0,0 @@
----
-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.

package/.agents/skills/core/ci-cd-and-automation/SKILL.md

@@ -1,274 +0,0 @@
----
-name: ci-cd-and-automation
-description:
-  Automates CI/CD pipeline setup. Use when setting up or modifying build and
-  deployment pipelines. Use when you need to automate quality gates, configure
-  test runners in CI, or establish deployment strategies.
----
-
-# CI/CD and Automation
-
-## Policy Capsule
-
-- Every PR passes the same quality-gate pipeline before merge: **lint → typecheck → unit tests → build → integration tests → optional E2E → security audit → bundle-size**. Gates are ordered shift-left so cheap checks fail first.
-- **No gate may be skipped.** Failing lint means fix lint, not disable the rule. Failing a test means fix the code, not delete or `.skip` the test.
-- **Faster is safer.** Prefer many small, frequent releases over big-bang merges; one deploy of three changes is debuggable, one deploy of thirty is not.
-- Cache aggressively (npm cache, build cache) and split lint / typecheck / test into parallel jobs to keep PR feedback under ~10 minutes.
-- Use GitHub Secrets (or platform equivalent) for every credential — even in CI-only test databases. Never hardcode credentials in workflow YAML.
-- Wire preview deployments for every PR so reviewers can exercise the change in a production-like environment before merge.
-- Feed CI failure output verbatim back to the agent loop with the specific error and the directive to verify locally before re-pushing.
-- Treat the security audit (`npm audit` or equivalent) as gating: critical and high vulnerabilities reachable in production code MUST be remediated before merge.
-- Enforce a bundle-size budget in CI; a budget breach blocks the change just like a failing test.
-
-## Overview
-
-Automate quality gates so that no change reaches production without passing
-tests, lint, type checking, and build. CI/CD is the enforcement mechanism for
-every other skill — it catches what humans and agents miss, and it does so
-consistently on every single change.
-
-**Shift Left:** Catch problems as early in the pipeline as possible. A bug
-caught in linting costs minutes; the same bug caught in production costs hours.
-Move checks upstream — static analysis before tests, tests before staging,
-staging before production.
-
-**Faster is Safer:** Smaller batches and more frequent releases reduce risk, not
-increase it. A deployment with 3 changes is easier to debug than one with 30.
-Frequent releases build confidence in the release process itself.
-
-## When to Use
-
-- Setting up a new project's CI pipeline
-- Adding or modifying automated checks
-- Configuring deployment pipelines
-- When a change should trigger automated verification
-- Debugging CI failures
-
-## The Quality Gate Pipeline
-
-Every change goes through these gates before merge:
-
-```text
-Pull Request Opened
-    │
-    ▼
-┌─────────────────┐
-│   LINT CHECK     │  eslint, prettier
-│   ↓ pass         │
-│   TYPE CHECK     │  tsc --noEmit
-│   ↓ pass         │
-│   UNIT TESTS     │  jest/vitest
-│   ↓ pass         │
-│   BUILD          │  npm run build
-│   ↓ pass         │
-│   INTEGRATION    │  API/DB tests
-│   ↓ pass         │
-│   E2E (optional) │  Playwright/Cypress
-│   ↓ pass         │
-│   SECURITY AUDIT │  npm audit
-│   ↓ pass         │
-│   BUNDLE SIZE    │  bundlesize check
-└─────────────────┘
-    │
-    ▼
-  Ready for review
-```
-
-**No gate can be skipped.** If lint fails, fix lint — don't disable the rule. If
-a test fails, fix the code — don't skip the test.
-
-**Introducing a new gate that asserts on pre-existing state** (doc-drift,
-lint-vocabulary, dependency-cycle, missing-test-coverage) has its own
-hazard: the gate lands red because of latent findings nobody authored,
-and every downstream PR is blocked until someone hotfixes the integration
-branch. Before wiring such a gate into `requiredChecks`, read
-[`core/introducing-a-baseline-gate`](../introducing-a-baseline-gate/SKILL.md) —
-it covers the two landing shapes (advisory-first or
-populate-the-baseline) that keep the gate green at merge.
-
-## CI Configuration (GitHub Actions)
-
-A representative pipeline for a Node project runs lint → type check → unit
-tests → build → security audit on every PR and push to `main`. Add
-integration jobs that spin up service containers (e.g. Postgres) and an E2E
-job that installs Playwright and uploads the report on failure.
-
-> See [`examples.md`](./examples.md) for full GitHub Actions YAML covering:
->
-> - Basic CI pipeline (lint, types, tests, build, audit)
-> - Integration tests with a Postgres service container + Prisma migrations
-> - Playwright E2E with report artifacts
-> - Caching and parallelism (split lint/typecheck/test into separate jobs)
->
-> Use GitHub Secrets for credentials — even in CI-only test databases — to
-> avoid normalizing hardcoded values that could leak into other contexts.
-
-## Feeding CI Failures Back to Agents
-
-The power of CI with AI agents is the feedback loop. When CI fails:
-
-```text
-CI fails
-    │
-    ▼
-Copy the failure output
-    │
-    ▼
-Feed it to the agent:
-"The CI pipeline failed with this error:
-[paste specific error]
-Fix the issue and verify locally before pushing again."
-    │
-    ▼
-Agent fixes → pushes → CI runs again
-```
-
-**Key patterns:**
-
-```text
-Lint failure → Agent runs `npm run lint --fix` and commits
-Type error  → Agent reads the error location and fixes the type
-Test failure → Agent follows debugging-and-error-recovery skill
-Build error → Agent checks config and dependencies
-```
-
-## Deployment Strategies
-
-### Preview Deployments
-
-Every PR gets a preview deployment for manual testing — most platforms (Vercel,
-Netlify, Cloudflare Pages) ship a one-step action you wire into the PR
-workflow. See [`examples.md`](./examples.md) for a representative Vercel
-preview-deploy job.
-
-### Feature Flags
-
-Feature flags decouple deployment from release. Deploy incomplete or risky
-features behind flags so you can:
-
-- **Ship code without enabling it.** Merge to main early, enable when ready.
-- **Roll back without redeploying.** Disable the flag instead of reverting code.
-- **Canary new features.** Enable for 1% of users, then 10%, then 100%.
-- **Run A/B tests.** Compare behavior with and without the feature.
-
-**Flag lifecycle:** Create → Enable for testing → Canary → Full rollout →
-Remove the flag and dead code. Flags that live forever become technical debt —
-set a cleanup date when you create them. See [`examples.md`](./examples.md)
-for a minimal flag-check pattern.
-
-### Staged Rollouts
-
-```text
-PR merged to main
-    │
-    ▼
-  Staging deployment (auto)
-    │ Manual verification
-    ▼
-  Production deployment (manual trigger or auto after staging)
-    │
-    ▼
-  Monitor for errors (15-minute window)
-    │
-    ├── Errors detected → Rollback
-    └── Clean → Done
-```
-
-### Rollback Plan
-
-Every deployment should be reversible. Wire a `workflow_dispatch` job that
-takes a target version as input and re-deploys it; see
-[`examples.md`](./examples.md) for a representative manual-rollback workflow.
-
-## Environment Management
-
-```text
-.env.example       → Committed (template for developers)
-.env                → NOT committed (local development)
-.env.test           → Committed (test environment, no real secrets)
-CI secrets          → Stored in GitHub Secrets / vault
-Production secrets  → Stored in deployment platform / vault
-```
-
-CI should never have production secrets. Use separate secrets for CI testing.
-
-## Automation Beyond CI
-
-### Dependabot / Renovate
-
-Schedule dependency updates so they show up as PRs you can triage in batches
-rather than chasing security advisories ad hoc. A minimal `dependabot.yml` is
-in [`examples.md`](./examples.md); Renovate's config covers the same shape
-with more knobs.
-
-### Build Cop Role
-
-Designate someone responsible for keeping CI green. When the build breaks, the
-Build Cop's job is to fix or revert — not the person whose change caused the
-break. This prevents broken builds from accumulating while everyone assumes
-someone else will fix it.
-
-### PR Checks
-
-- **Required reviews:** At least 1 approval before merge
-- **Required status checks:** CI must pass before merge
-- **Branch protection:** No force-pushes to main
-- **Auto-merge:** If all checks pass and approved, merge automatically
-
-## CI Optimization
-
-When the pipeline exceeds 10 minutes, apply these strategies in order of impact:
-
-```text
-Slow CI pipeline?
-├── Cache dependencies
-│   └── Use actions/cache or setup-node cache option for node_modules
-├── Run jobs in parallel
-│   └── Split lint, typecheck, test, build into separate parallel jobs
-├── Only run what changed
-│   └── Use path filters to skip unrelated jobs (e.g., skip e2e for docs-only PRs)
-├── Use matrix builds
-│   └── Shard test suites across multiple runners
-├── Optimize the test suite
-│   └── Remove slow tests from the critical path, run them on a schedule instead
-└── Use larger runners
-    └── GitHub-hosted larger runners or self-hosted for CPU-heavy builds
-```
-
-### Example: Caching and Parallelism
-
-Split lint, typecheck, and test into separate jobs that each restore the npm
-cache via `actions/setup-node`'s `cache: 'npm'` option. See
-[`examples.md`](./examples.md) for a parallel three-job layout.
-
-## Common Rationalizations
-
-| Rationalization                   | Reality                                                                                                            |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| "CI is too slow"                  | Optimize the pipeline (see CI Optimization below), don't skip it. A 5-minute pipeline prevents hours of debugging. |
-| "This change is trivial, skip CI" | Trivial changes break builds. CI is fast for trivial changes anyway.                                               |
-| "The test is flaky, just re-run"  | Flaky tests mask real bugs and waste everyone's time. Fix the flakiness.                                           |
-| "We'll add CI later"              | Projects without CI accumulate broken states. Set it up on day one.                                                |
-| "Manual testing is enough"        | Manual testing doesn't scale and isn't repeatable. Automate what you can.                                          |
-
-## Red Flags
-
-- No CI pipeline in the project
-- CI failures ignored or silenced
-- Tests disabled in CI to make the pipeline pass
-- Production deploys without staging verification
-- No rollback mechanism
-- Secrets stored in code or CI config files (not secrets manager)
-- Long CI times with no optimization effort
-
-## Verification
-
-After setting up or modifying CI:
-
-- [ ] All quality gates are present (lint, types, tests, build, audit)
-- [ ] Pipeline runs on every PR and push to main
-- [ ] Failures block merge (branch protection configured)
-- [ ] CI results feed back into the development loop
-- [ ] Secrets are stored in the secrets manager, not in code
-- [ ] Deployment has a rollback mechanism
-- [ ] Pipeline runs in under 10 minutes for the test suite