mandrel 2.0.0 → 2.2.0

package/.agents/skills/core/documentation-and-adrs/reference.md

@@ -0,0 +1,403 @@
+# Documentation and ADRs — 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. Nothing here
+relaxes a capsule MUST, and nothing here is required reading merely because
+the skill is active.
+
+## Overview
+
+Document decisions, not just code. The most valuable documentation captures the
+_why_ — the context, constraints, and trade-offs that led to a decision. Code
+shows _what_ was built; documentation explains _why it was built this way_ and
+_what alternatives were considered_. This context is essential for future humans
+and agents working in the codebase.
+
+## When to Use
+
+- Making a significant architectural decision
+- Choosing between competing approaches
+- Adding or changing a public API
+- Shipping a feature that changes user-facing behavior
+- Onboarding new team members (or agents) to the project
+- When you find yourself explaining the same thing repeatedly
+
+**When NOT to use:** Don't document obvious code. Don't add comments that
+restate what the code already says. Don't write docs for throwaway prototypes.
+
+## Architecture Decision Records (ADRs)
+
+ADRs capture the reasoning behind significant technical decisions. They're the
+highest-value documentation you can write.
+
+### When to Write an ADR
+
+- Choosing a framework, library, or major dependency
+- Designing a data model or database schema
+- Selecting an authentication strategy
+- Deciding on an API architecture (REST vs. GraphQL vs. tRPC)
+- Choosing between build tools, hosting platforms, or infrastructure
+- Any decision that would be expensive to reverse
+
+### Decisions-log layouts
+
+Mandrel ships **two supported layouts** for the decisions log. Both keep the
+mandatory-read file named `docs/decisions.md` (the `project.docsContextFiles`
+default), so `config-resolver.js` and every `.agents/` reference resolve the
+same regardless of which you pick — only the **shape** differs. Choose one at
+onboarding:
+
+| Layout                              | Shape                                                                 | Template(s)                                                                                                | When to use                                                                       |
+| ----------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| **Single-file dated entries** (default) | One `decisions.md` of append-only `## YYYY-MM-DD — title` entries     | [`templates/docs/decisions.md`](../../../templates/docs/decisions.md)                                      | Small projects; a handful of decisions; you want everything in one scannable file. |
+| **Index + `decisions/` directory**  | `decisions.md` is a one-row-per-ADR **index**; each ADR is `decisions/NNNN-*.md` | [`templates/docs/decisions.index.md`](../../../templates/docs/decisions.index.md) + [`templates/docs/decisions/_template.md`](../../../templates/docs/decisions/_template.md) | The log has outgrown a single file (dozens of ADRs); you want per-decision history and `git blame` per ADR. |
+
+To adopt the directory layout, replace `decisions.md` with the index variant,
+create a `decisions/` directory beside it, and scaffold each ADR from
+`decisions/_template.md` using zero-padded sequential numbering
+(`0001-*.md`, `0002-*.md`, …).
+
+> **Loading model (resolved design question).** The decisions **index** is the
+> only artifact loaded into mandatory task context — individual ADR bodies
+> under `decisions/` are **lazy / link-followed**, not auto-loaded. This is
+> **index-only by default**: auto-loading every ADR body into each task's
+> context would reintroduce exactly the bloat the split exists to remove.
+> `project.docsContextFiles` entries are plain filenames resolved against the
+> docs root (no glob expansion in the loader), so the index ships as a normal
+> mandatory-read with no loader change. A project that genuinely wants the full
+> ADR set in mandatory context can add explicit per-file entries (or a
+> `decisions/*.md`-style entry if it maintains its own globbing) as a
+> deliberate opt-in, but that is the exception, not the default.
+
+### ADR Template
+
+In the **single-file** layout, append a short dated entry per the
+`templates/docs/decisions.md` format. In the **directory** layout, store ADRs
+in `docs/decisions/` with sequential numbering:
+
+```markdown
+# ADR-001: Use PostgreSQL for primary database
+
+## Status
+
+Accepted | Superseded by ADR-XXX | Deprecated
+
+## Date
+
+2025-01-15
+
+## Deciders
+
+The platform team (architect + two senior engineers).
+
+## Context
+
+We need a primary database for the task management application. Key
+requirements:
+
+- Relational data model (users, tasks, teams with relationships)
+- ACID transactions for task state changes
+- Support for full-text search on task content
+- Managed hosting available (for small team, limited ops capacity)
+
+## Decision
+
+Use PostgreSQL with Prisma ORM.
+
+## Alternatives Considered
+
+### MongoDB
+
+- Pros: Flexible schema, easy to start with
+- Cons: Our data is inherently relational; would need to manage relationships
+  manually
+- Rejected: Relational data in a document store leads to complex joins or data
+  duplication
+
+### SQLite
+
+- Pros: Zero configuration, embedded, fast for reads
+- Cons: Limited concurrent write support, no managed hosting for production
+- Rejected: Not suitable for multi-user web application in production
+
+### MySQL
+
+- Pros: Mature, widely supported
+- Cons: PostgreSQL has better JSON support, full-text search, and ecosystem
+  tooling
+- Rejected: PostgreSQL is the better fit for our feature requirements
+
+## Consequences
+
+- Prisma provides type-safe database access and migration management
+- We can use PostgreSQL's full-text search instead of adding Elasticsearch
+- Team needs PostgreSQL knowledge (standard skill, low risk)
+- Hosting on managed service (Supabase, Neon, or RDS)
+```
+
+### ADR Lifecycle
+
+```text
+PROPOSED → ACCEPTED → (SUPERSEDED or DEPRECATED)
+```
+
+- **Don't delete old ADRs.** They capture historical context.
+- When a decision changes, write a new ADR that references and supersedes the
+  old one.
+
+## Inline Documentation
+
+### When to Comment
+
+Comment the _why_, not the _what_:
+
+```typescript
+// BAD: Restates the code
+// Increment counter by 1
+counter += 1;
+
+// GOOD: Explains non-obvious intent
+// Rate limit uses a sliding window — reset counter at window boundary,
+// not on a fixed schedule, to prevent burst attacks at window edges
+if (now - windowStart > WINDOW_SIZE_MS) {
+  counter = 0;
+  windowStart = now;
+}
+```
+
+### When NOT to Comment
+
+```typescript
+// Don't comment self-explanatory code
+function calculateTotal(items: CartItem[]): number {
+  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
+}
+
+// Don't leave TODO comments for things you should just do now
+// TODO: add error handling  ← Just add it
+
+// Don't leave commented-out code
+// const oldImplementation = () => { ... }  ← Delete it, git has history
+```
+
+### Document Known Gotchas
+
+```typescript
+/**
+ * IMPORTANT: This function must be called before the first render.
+ * If called after hydration, it causes a flash of unstyled content
+ * because the theme context isn't available during SSR.
+ *
+ * See ADR-003 for the full design rationale.
+ */
+export function initializeTheme(theme: Theme): void {
+  // ...
+}
+```
+
+## API Documentation
+
+For public APIs (REST, GraphQL, library interfaces):
+
+### Inline with Types (Preferred for TypeScript)
+
+```typescript
+/**
+ * Creates a new task.
+ *
+ * @param input - Task creation data (title required, description optional)
+ * @returns The created task with server-generated ID and timestamps
+ * @throws {ValidationError} If title is empty or exceeds 200 characters
+ * @throws {AuthenticationError} If the user is not authenticated
+ *
+ * @example
+ * const task = await createTask({ title: 'Buy groceries' });
+ * console.log(task.id); // "task_abc123"
+ */
+export async function createTask(input: CreateTaskInput): Promise<Task> {
+  // ...
+}
+```
+
+### OpenAPI / Swagger for REST APIs
+
+```yaml
+paths:
+  /api/tasks:
+    post:
+      summary: Create a task
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTaskInput'
+      responses:
+        '201':
+          description: Task created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Task'
+        '422':
+          description: Validation error
+```
+
+## README Structure
+
+Every project should have a README that covers:
+
+```markdown
+# Project Name
+
+One-paragraph description of what this project does.
+
+## Quick Start
+
+1. Clone the repo
+2. Install dependencies: `npm install`
+3. Set up environment: `cp .env.example .env`
+4. Run the dev server: `npm run dev`
+
+## Commands
+
+| Command         | Description              |
+| --------------- | ------------------------ |
+| `npm run dev`   | Start development server |
+| `npm test`      | Run tests                |
+| `npm run build` | Production build         |
+| `npm run lint`  | Run linter               |
+
+## Architecture
+
+Brief overview of the project structure and key design decisions. Link to ADRs
+for details.
+
+## Contributing
+
+How to contribute, coding standards, PR process.
+```
+
+## Changelog Maintenance
+
+For shipped features:
+
+```markdown
+# Changelog
+
+## [1.2.0] - 2025-01-20
+
+### Added
+
+- Task sharing: users can share tasks with team members (#123)
+- Email notifications for task assignments (#124)
+
+### Fixed
+
+- Duplicate tasks appearing when rapidly clicking create button (#125)
+
+### Changed
+
+- Task list now loads 50 items per page (was 20) for better UX (#126)
+```
+
+## Pruning & Archiving
+
+Living docs accrete history — dated changelog entries, closed decision-log
+rows, completed rollout checklists, resolved runbook incidents. Left
+unpruned, that verbatim history crowds out the live guidance a reader (human
+or agent) actually needs, and every task that loads the doc re-pays the cost.
+The fix is to **archive, don't delete**: relocate the cold history so the live
+doc stays lean while the record stays recoverable.
+
+### The archive-don't-delete rule
+
+**History is preserved by _moving_ it, never by deleting it.** Pruning a doc
+never destroys its past — the verbatim content is relocated to a dated archive
+file under version control, so the full record remains diffable and
+recoverable. Deleting history outright (even with "git has it") is the
+anti-pattern this convention exists to prevent: the archive is discoverable
+from the live doc, a buried git revision is not.
+
+### How to prune a doc
+
+1. **Extract the still-live signal first — before you archive anything.**
+   Gotchas, traps, and hard-won caveats buried in the history are the most
+   valuable lines in the doc. Lift them into the live doc's standing guidance
+   (a "Known gotchas" list, an inline warning, or an ADR) **before** the
+   history moves. Archiving first risks stranding a live trap in a cold file
+   nobody rereads.
+2. **Move the verbatim history to a dated archive file.** Relocate the cold
+   content — untouched, word-for-word — to
+   `docs/archive/<name>-<YYYY-MM>.md`, where `<name>` is the source doc's base
+   name and `<YYYY-MM>` is the archive date (e.g. `docs/archive/changelog-2025-01.md`,
+   `docs/archive/decisions-2024-11.md`). The archive is an exact copy of what
+   was live; do not summarize or rewrite it in the move.
+3. **Collapse completed checklists to a one-line summary.** A finished
+   checklist (a rollout runbook, a migration plan, a release gate) does not
+   need to keep every ticked box in the live doc. Replace it with a single
+   line recording the outcome and date — e.g.
+   `Auth-migration rollout — completed 2025-01-18, all 12 steps green` — and
+   let the archived copy carry the full detail.
+4. **Leave a one-line pointer behind.** Every archived doc leaves exactly one
+   line in the live doc pointing at where its history went, so the record is
+   never orphaned — e.g.
+   `Older entries archived to docs/archive/changelog-2024.md`. The pointer is
+   what makes "moved, not deleted" true from the reader's vantage point.
+
+### When to prune
+
+- A changelog, decision log, or runbook has grown long enough that the live
+  entries are hard to find among the historical ones.
+- A checklist or rollout plan is fully complete and its step-by-step detail is
+  now reference-only.
+- A doc reloaded into agent context on many tasks carries more cold history
+  than live guidance.
+
+Do **not** prune ADRs by archiving — an ADR that no longer holds is
+**superseded** in place (see [ADR Lifecycle](#adr-lifecycle)), keeping the
+numbered chain intact. Archiving is for the accreted history of living docs,
+not for the immutable decision record.
+
+## Documentation for Agents
+
+Special consideration for AI agent context:
+
+- **CLAUDE.md / rules files** — Document project conventions so agents follow
+  them
+- **Spec files** — Keep specs updated so agents build the right thing
+- **ADRs** — Help agents understand why past decisions were made (prevents
+  re-deciding)
+- **Inline gotchas** — Prevent agents from falling into known traps
+
+## Common Rationalizations
+
+| Rationalization                            | Reality                                                                                               |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| "The code is self-documenting"             | Code shows what. It doesn't show why, what alternatives were rejected, or what constraints apply.     |
+| "We'll write docs when the API stabilizes" | APIs stabilize faster when you document them. The doc is the first test of the design.                |
+| "Nobody reads docs"                        | Agents do. Future engineers do. Your 3-months-later self does.                                        |
+| "ADRs are overhead"                        | A 10-minute ADR prevents a 2-hour debate about the same decision six months later.                    |
+| "Comments get outdated"                    | Comments on _why_ are stable. Comments on _what_ get outdated — that's why you only write the former. |
+
+## Red Flags
+
+- Architectural decisions with no written rationale
+- Public APIs with no documentation or types
+- README that doesn't explain how to run the project
+- Commented-out code instead of deletion
+- TODO comments that have been there for weeks
+- No ADRs in a project with significant architectural choices
+- Documentation that restates the code instead of explaining intent
+
+## Verification
+
+After documenting:
+
+- [ ] ADRs exist for all significant architectural decisions
+- [ ] README covers quick start, commands, and architecture overview
+- [ ] API functions have parameter and return type documentation
+- [ ] Known gotchas are documented inline where they matter
+- [ ] No commented-out code remains
+- [ ] Rules files (CLAUDE.md etc.) are current and accurate

package/.agents/skills/core/gates-and-baselines/SKILL.md

@@ -18,10 +18,10 @@ allowed_tools:
 - **No gate may be skipped.** Failing lint means fix lint, not disable the rule; a failing test means fix the code, not `.skip` or delete the test. Gates are ordered shift-left so cheap checks fail first, and CI failure output is fed back verbatim with the directive to reproduce and fix locally before re-pushing.
 - **Introducing a gate that asserts on pre-existing state** (doc-drift, lint-vocabulary, dependency-cycle, missing-coverage) MUST land green at merge: either advisory-first (report-only until the backlog is burned down) or with the populated baseline committed in the same change that turns the gate on. Never wire a gate into `requiredChecks` that lands red on latent findings nobody authored.
 - **Refresh a baseline only when the change is deliberate** — a rename/move, an operator-approved complexity bump, a signed-off perf delta, an 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`.
+- Run the kind-specific refresh (`npm run crap:update` / `npm run maintainability:update`; dead-exports and lighthouse have no npm script — regenerate the rows and edit `baselines/dead-exports*.json` / `baselines/lighthouse.json` directly) on the **Story branch**, not on `main`.
 - Verify the refresh 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 `chore(baselines): refresh <kind> snapshot for <reason>` — never an ad-hoc leading token like `baseline-refresh:` (commitlint and the planner validator reject it). The body is **mandatory** and non-empty: what changed, why the new floor is correct, and the Story/Epic that triggered it.
-- Add the machine-readable trailer `baseline-refresh: true` (git-trailer `Key: value` style) and `Epic: #<epic-id>` to the body whenever observability classification matters. Never pass `--no-verify`; the `commit-msg` hook (commitlint) MUST run and pass.
+- Commit-subject contract: a **Conventional-Commits** subject `chore(baselines): refresh <kind> snapshot for <reason>` — never an ad-hoc leading token like `baseline-refresh:` (commitlint and the planner validator reject it). The body is **mandatory** and non-empty: what changed, why the new floor is correct, and the Story that triggered it.
+- Add the machine-readable trailer `baseline-refresh: true` (git-trailer `Key: value` style) and `Story: #<storyId>` to the body whenever observability classification matters. 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.
 - Keep credentials in GitHub Secrets (or platform equivalent) even for CI-only test databases; treat the security audit (`npm audit` or equivalent) as gating for critical/high vulnerabilities reachable in production code.
 
@@ -77,7 +77,7 @@ chore(baselines): refresh <kind> snapshot for <reason>
 baseline is the correct floor, and any operator sign-off reference>
 
 baseline-refresh: true
-Epic: #<epic-id>
+Story: #<storyId>
 ```
 
 The `commit-msg` hook (`commitlint`) rejects any subject whose leading token is
@@ -88,10 +88,10 @@ subject MUST conform. `release-please` consumes the subject on `main`;
 `chore(baselines):` keeps the refresh out of the user-facing changelog (correct —
 it is internal hygiene) while staying machine-parseable. The
 `baseline-refresh: true` **body trailer** is the canonical machine-readable
-marker (what
-[`.agents/scripts/lib/observability/baseline-refresh-rate.js`](../../../scripts/lib/observability/baseline-refresh-rate.js)
-classifies against) — subject-level leading tokens are not, and must not be, used
-for this purpose.
+marker — subject-level leading tokens are not, and must not be, used for this
+purpose. (Its only reader, `baseline-refresh-rate.js`, went with the
+execution-analysis surface in Story #4545; the trailer convention stands on its
+own as the parseable marker for any future reader.)
 
 ### Procedure
 
@@ -99,8 +99,8 @@ for this purpose.
 | --------------- | -------------------------------- |
 | CRAP            | `npm run crap:update`            |
 | Maintainability | `npm run maintainability:update` |
-| Dead-exports    | `npm run dead-exports:update`    |
-| Lighthouse      | `npm run lighthouse:update`      |
+| Dead-exports    | edit `baselines/dead-exports.json` / `baselines/dead-exports-production.json` (rows are `(file, symbol)`; `check-dead-exports.js --json` prints the current rows) |
+| Lighthouse      | edit `baselines/lighthouse.json`  |
 
 1. **Run the matching update command** on the Story branch (HEAD must already be
    the Story branch, not `main`).
@@ -115,10 +115,10 @@ for this purpose.
    git commit -m "$(cat <<'EOF'
    chore(baselines): refresh <kind> snapshot for <reason>
 
-   <body: what changed, why the new floor is correct, linking the Story/Epic.>
+   <body: what changed, why the new floor is correct, linking the Story.>
 
    baseline-refresh: true
-   Epic: #<epic-id>
+   Story: #<storyId>
    EOF
    )"
    ```

package/.agents/skills/core/idea-refinement/SKILL.md

@@ -13,7 +13,7 @@ description:
 - Phase 1 MUST restate the idea as a "How Might We" statement, ask 3–5 sharpening questions via `AskUserQuestion`, and generate 5–8 variations (not 20+ shallow ones); do not proceed until target user and success criteria are explicit.
 - Phase 2 grill loop poses **one** question at a time, each with a recommended answer + one-line rationale grounded in user input / codebase / first principles; never batch questions and never omit the recommendation.
 - Re-enumerate open branches after every grill answer; stop only when no unresolved decisions remain. Take the off-ramp directly to Phase 3 when the idea is already crisply scoped.
-- Phase 3 emits a markdown one-pager with the canonical five Epic headings exactly: `## Context`, `## Goal`, `## Non-Goals`, `## Scope`, `## Acceptance Criteria` (plus optional `## Open Questions`). No alternate heading text — the `/plan` clarity gate depends on this verbatim.
+- Phase 3 emits a markdown one-pager with the canonical five planning headings exactly: `## Context`, `## Goal`, `## Non-Goals`, `## Scope`, `## Acceptance Criteria` (plus optional `## Open Questions`). No alternate heading text — the `/plan` clarity gate depends on this verbatim.
 - Surface every key assumption inside `## Context` (or `## Scope`); assumptions do not get their own heading. Unresolved decisions MUST NOT carry into the one-pager.
 - The `## Non-Goals` list is mandatory and each entry includes a reason — focus is created by explicit exclusion.
 - Be honest, not supportive: push back on weak ideas with kindness; never function as a yes-machine.
@@ -63,7 +63,7 @@ bash /mnt/skills/user/idea-refine/scripts/idea-refine.sh
 ## Output
 
 The final output is a markdown one-pager saved to `docs/ideas/[idea-name].md`
-(after user confirmation), containing the five canonical Epic sections:
+(after user confirmation), containing the five canonical planning sections:
 
 - Context (problem framing + current state)
 - Goal (desired outcome)
@@ -211,7 +211,7 @@ it inside the grill loop, not after the one-pager is already written.
 Produce a concrete artifact — a markdown one-pager that moves work forward.
 The five canonical headings below match `.agents/templates/epic-from-idea.md`
 and the `/plan` clarity gate; emit them verbatim so the renderer can
-substitute the body into a new Epic without translation.
+substitute the body into a `/plan` Story seed without translation.
 
 ```markdown
 # [Idea Name]

package/.agents/skills/core/scope-triage/SKILL.md

@@ -22,6 +22,9 @@ description:
 - Lead with **cohesion**: one Story is one coherent change with one reason
   to exist. Coupled work stays one Story and uses `## Slicing` for
   intra-session checkpoints.
+- Emit an **advisory only** — `keep-single` (the default) or `split` with its
+  seam/overlap rationale. **Never auto-route**: the operator decides, and
+  `--yes` defaults to `keep-single`.
 
 ## Split policy (when N>1 is allowed)