mandrel 1.93.0 → 2.0.0

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

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

@@ -1,211 +0,0 @@
-# CI/CD and Automation — Examples
-
-Long stack-specific snippets extracted from `SKILL.md` so the skill stays
-focused on policy and routing. The samples below assume GitHub Actions plus
-Node 22 / npm; adapt to your project's runner, package manager, and language.
-
----
-
-## GitHub Actions: Basic CI Pipeline
-
-```yaml
-# .github/workflows/ci.yml
-name: CI
-
-on:
-  pull_request:
-    branches: [main]
-  push:
-    branches: [main]
-
-jobs:
-  quality:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-          cache: 'npm'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Lint
-        run: npm run lint
-
-      - name: Type check
-        run: npx tsc --noEmit
-
-      - name: Test
-        run: npm test -- --coverage
-
-      - name: Build
-        run: npm run build
-
-      - name: Security audit
-        run: npm audit --audit-level=high
-```
-
-## GitHub Actions: With Database Integration Tests
-
-```yaml
-integration:
-  runs-on: ubuntu-latest
-  services:
-    postgres:
-      image: postgres:16
-      env:
-        POSTGRES_DB: testdb
-        POSTGRES_USER: ci_user
-        POSTGRES_PASSWORD: ${{ secrets.CI_DB_PASSWORD }}
-      ports:
-        - 5432:5432
-      options: >-
-        --health-cmd pg_isready --health-interval 10s --health-timeout 5s
-        --health-retries 5
-
-  steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-node@v4
-      with:
-        node-version: '22'
-        cache: 'npm'
-    - run: npm ci
-    - name: Run migrations
-      run: npx prisma migrate deploy
-      env:
-        DATABASE_URL:
-          postgresql://ci_user:${{ secrets.CI_DB_PASSWORD
-          }}@localhost:5432/testdb
-    - name: Integration tests
-      run: npm run test:integration
-      env:
-        DATABASE_URL:
-          postgresql://ci_user:${{ secrets.CI_DB_PASSWORD
-          }}@localhost:5432/testdb
-```
-
-> **Note:** Even for CI-only test databases, use GitHub Secrets for credentials
-> rather than hardcoding values. This builds good habits and prevents accidental
-> reuse of test credentials in other contexts.
-
-## GitHub Actions: E2E Tests
-
-```yaml
-e2e:
-  runs-on: ubuntu-latest
-  steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-node@v4
-      with:
-        node-version: '22'
-        cache: 'npm'
-    - run: npm ci
-    - name: Install Playwright
-      run: npx playwright install --with-deps chromium
-    - name: Build
-      run: npm run build
-    - name: Run E2E tests
-      run: npx playwright test
-    - uses: actions/upload-artifact@v4
-      if: failure()
-      with:
-        name: playwright-report
-        path: playwright-report/
-```
-
-## Deployment: Preview on PR
-
-```yaml
-# Deploy preview on PR (Vercel/Netlify/etc.)
-deploy-preview:
-  runs-on: ubuntu-latest
-  if: github.event_name == 'pull_request'
-  steps:
-    - uses: actions/checkout@v4
-    - name: Deploy preview
-      run: npx vercel --token=${{ secrets.VERCEL_TOKEN }}
-```
-
-## Deployment: Manual Rollback Workflow
-
-```yaml
-# Manual rollback workflow
-name: Rollback
-on:
-  workflow_dispatch:
-    inputs:
-      version:
-        description: 'Version to rollback to'
-        required: true
-
-jobs:
-  rollback:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Rollback deployment
-        run: |
-          # Deploy the specified previous version
-          npx vercel rollback ${{ inputs.version }}
-```
-
-## Caching and Parallelism
-
-```yaml
-jobs:
-  lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: '22', cache: 'npm' }
-      - run: npm ci
-      - run: npm run lint
-
-  typecheck:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: '22', cache: 'npm' }
-      - run: npm ci
-      - run: npx tsc --noEmit
-
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: '22', cache: 'npm' }
-      - run: npm ci
-      - run: npm test -- --coverage
-```
-
-## Dependency Updates: Dependabot
-
-```yaml
-# .github/dependabot.yml
-version: 2
-updates:
-  - package-ecosystem: npm
-    directory: /
-    schedule:
-      interval: weekly
-    open-pull-requests-limit: 5
-```
-
-## Feature Flag Pattern
-
-```typescript
-// Simple feature flag pattern
-if (featureFlags.isEnabled('new-checkout-flow', { userId })) {
-  return renderNewCheckout();
-}
-return renderLegacyCheckout();
-```
-
-**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.