mandrel 1.57.0

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

@@ -0,0 +1,323 @@
+---
+name: documentation-and-adrs
+description:
+  Records decisions and documentation. Use when making architectural decisions,
+  changing public APIs, shipping features, or when you need to record context
+  that future engineers and agents will need to understand the codebase.
+---
+
+# Documentation and ADRs
+
+## Policy Capsule
+
+- Document the **why**, not the what. Capture context, constraints, alternatives considered, and trade-offs — code already shows what was built.
+- Write an ADR for any decision that would be expensive to reverse (framework choice, data model, auth strategy, API architecture, hosting platform).
+- Store ADRs at `docs/decisions/` with sequential numbering (`ADR-001`, `ADR-002`, …) and the canonical sections: **Status, Date, Context, Decision, Alternatives Considered, Consequences**.
+- Mark an ADR's status as `Accepted`, `Superseded by ADR-XXX`, or `Deprecated`. Never silently delete an ADR — supersede it.
+- Do **not** document obvious code; do **not** restate what the code already says. Stale or redundant docs are worse than no docs.
+- Comments explain **non-obvious intent** (the why). If a comment describes what the code does, refactor the code instead.
+- Keep user-facing docs (README, API docs, changelog) updated as part of the change — out-of-date docs are bugs.
+- Pair every public API change with a changelog entry that links the relevant Story/Epic and any superseding ADR.
+- When you find yourself explaining the same thing repeatedly in chat, write it down — the explanation belongs in the project docs or an ADR.
+
+## 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
+
+### ADR Template
+
+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
+
+## 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)
+```
+
+## 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/epic-plan-consolidate/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: epic-plan-consolidate
+description: >-
+  Run a holistic, pre-persist consolidation pass over the draft Feature/Story
+  ticket array an Epic's decompose phase produced. Use during Phase 8 of
+  `/epic-plan`, after `epic-plan-decompose-author` writes
+  `temp/epic-<Epic_ID>/tickets.json` and before `epic-plan-decompose.js`
+  validates and persists it. Reconciles the draft against the Tech Spec
+  "Delivery Slicing" target via scope-preserving operations only.
+allowed_tools:
+  - Read
+  - Write
+  - Bash
+---
+
+# epic-plan-consolidate
+
+## Policy Capsule
+
+- Run only after `epic-plan-decompose-author` has written `temp/epic-<Epic_ID>/tickets.json`; fail loudly if the draft array is missing. Read the PRD / Tech Spec from `temp/epic-<Epic_ID>/decomposer-context.json` (the same envelope the author skill consumed) — never re-fetch from GitHub, and never call the GitHub API from this Skill.
+- Emit exactly two artifacts inside `temp/epic-<Epic_ID>/`: the **consolidated** `tickets.json` (overwriting the draft array in place) and a human-readable `consolidation-report.md` (the rationale + before/after diff the operator reviews at the HITL gate). Both MUST exist before returning.
+- **Scope conservation is the load-bearing invariant.** You are a *critic*, not a second author: you MUST NOT add scope, invent tickets, or drop acceptance criteria. Every acceptance item and every `verify` entry present in the draft MUST survive into the consolidated array (possibly re-homed onto a merged Story). **This is your contract, not a machine guarantee:** there is **no runtime acceptance-union diff** on your output. The only deterministic runtime backstop the validator applies after you run is `assertNoSingleStoryFeature` (Story #3777) plus the standard ticket-structure validation — neither re-derives the pre-consolidation acceptance/verify union, so a critic that silently dropped an acceptance item would **not** be caught downstream. (The repo's unit test exercises a *pure model* of the merge over an over-fragmented fixture to document the intended invariant; it does not inspect this Skill's actual output.) Conserve scope yourself, deliberately, on every merge.
+- Your operations are constrained to exactly four shapes: **(1) merge two or more Stories** into one (union their `changes`/`acceptance`/`verify`/`references`, keep one coherent `goal`); **(2) collapse a single-Story Feature** into a sibling Feature (re-parent its lone Story, drop the empty Feature) — **never** by manufacturing a second Story; **(3) re-parent** a Story to a different sibling Feature; **(4) rewire `depends_on`** so the edges still reference surviving sibling-Story slugs. No other mutation is permitted.
+- Consume the Tech Spec **"Delivery Slicing"** section as the authoritative target grouping when one is present: cluster the draft's Stories toward the N shippable Stories the Architect proposed. When the section is **absent**, degrade gracefully — apply only the cohesion + single-Story-Feature rules below and leave the rest of the draft shape intact.
+- Implement rec #2: resolve every single-Story Feature by **collapsing** it into a sibling (operation 2), not by splitting its lone Story into two. The `assertNoSingleStoryFeature` validator from Story #3777 stays as the post-consolidation backstop — your output must already satisfy it.
+- Apply the same cohesion heuristic the author skill leads with: **one Story = one coherent change with one reason to exist**, and the **single-consumer merge rule** (a Story whose only consumer is one sibling Story is merged into that sibling). Lead every merge decision with the change's reason, not its file count.
+- After every merge / collapse / re-parent, **rewire `depends_on`**: drop self-edges, collapse edges that now point at the absorbing Story onto itself, and re-point any edge that named a now-deleted slug at its surviving successor. Never leave a `depends_on` referencing a slug absent from the consolidated array — the validator HARD-rejects unknown deps.
+- The consolidation report MUST name each operation applied (merged slugs → surviving slug, collapsed Feature → sibling, re-parented Story, rewired edges) with a one-line reason, plus a before/after Story-count line, so the operator can approve or reject at the HITL diff gate before the persist call.
+
+## Role
+
+Senior Project Manager + Orchestrator, acting as a **holistic critic** with
+fresh context. This Skill is deliberately *separate* from
+`epic-plan-decompose-author` (the generator): a same-pass self-critique is the
+weak mode this is built to escape. The generator maps PRD capabilities to
+Stories ~1:1; this critic steps back and looks at the *whole* decomposition
+against the Tech Spec's intentional grouping before any GitHub write.
+
+## When to use
+
+`/epic-plan` Phase 8, as the **8.3 — Holistic Consolidation** sub-step:
+immediately after `epic-plan-decompose-author` writes
+`temp/epic-<Epic_ID>/tickets.json` and **before**
+`epic-plan-decompose.js --tickets …` validates and persists. The pass operates
+on the temp artifact so the holistic adjustment happens before the GitHub
+write; the deterministic validator runs *after* it, so the critic can never
+emit a plan the validator would reject.
+
+## Inputs
+
+The dispatcher passes the Epic ID as the Skill argument. The Skill itself
+reads:
+
+- `temp/epic-<Epic_ID>/tickets.json` — the **draft** Feature/Story array the
+  `epic-plan-decompose-author` Skill wrote. This is the consolidation input.
+- `temp/epic-<Epic_ID>/decomposer-context.json` — the authoring envelope
+  emitted by `epic-plan-decompose.js --emit-context`. Read `prd.body` /
+  `prd` and `techSpec.body` / `techSpec` from it. The **"Delivery Slicing"**
+  section (authored by `epic-plan-spec-author` in the Tech Spec) is the
+  target grouping when present; degrade gracefully when it is absent.
+
+## Outputs
+
+- `temp/epic-<Epic_ID>/tickets.json` — the **consolidated** array, overwriting
+  the draft. Same schema as the author skill emits (Feature → Story; Stories
+  carry top-level `acceptance[]` / `verify[]`; `body` is a serialized string).
+  The downstream `epic-plan-decompose.js --tickets …` validator is the final
+  gate — author for its rules, not for "looks right."
+- `temp/epic-<Epic_ID>/consolidation-report.md` — a human-readable
+  rationale + before/after diff. This is the artifact the workflow shows the
+  operator at the HITL diff gate before the persist call.
+
+Both files MUST exist before the Skill returns.
+
+## Procedure
+
+### Step 1 — Load the draft and the target
+
+Read `temp/epic-<Epic_ID>/tickets.json` (the draft array) and
+`temp/epic-<Epic_ID>/decomposer-context.json` (for the PRD / Tech Spec). Locate
+the Tech Spec **"Delivery Slicing"** section. Pin two facts before mutating
+anything:
+
+1. The **target grouping** — the N shippable Stories the Architect proposed in
+   Delivery Slicing, or `null` when the section is absent (graceful-degrade
+   mode: cohesion + single-Story-Feature rules only).
+2. The **draft Story count per Feature** — so you can spot single-Story
+   Features and over-fragmented capability clusters.
+
+### Step 2 — Plan the consolidation
+
+For each Feature, decide which Stories merge, which collapse, which re-parent:
+
+- **Single-Story Feature** → collapse its lone Story into a sibling Feature
+  whose capability is closest (Delivery-Slicing target, else thematic
+  proximity). Drop the now-empty Feature. Never split the lone Story.
+- **Over-fragmented capability** → when several draft Stories map to one
+  Delivery-Slicing target (or one coherent reason to exist), merge them into a
+  single Story: union their `changes` / `acceptance` / `verify` / `references`,
+  write one `goal` naming the parent Feature, and keep the union of labels.
+- **Single-consumer Story** → merge into the one sibling that consumes it.
+
+Record each decision with its one-line reason for the report.
+
+### Step 3 — Rewire dependencies and conserve scope
+
+After applying the operations:
+
+- **Rewire `depends_on`**: drop self-edges, re-point any edge that named a
+  deleted slug at its surviving successor, and dedupe. No `depends_on` may
+  reference a slug absent from the consolidated array.
+- **Conserve scope**: assert the union of all `acceptance` items and all
+  `verify` entries across the consolidated array equals the union across the
+  draft. Nothing is dropped; nothing new is invented. If you cannot preserve an
+  item, you have over-reached — back the operation out.
+
+### Step 4 — Write both artifacts
+
+Write the consolidated array to `temp/epic-<Epic_ID>/tickets.json` (2-space
+indent, machine-consumed) and the rationale + before/after diff to
+`temp/epic-<Epic_ID>/consolidation-report.md`.
+
+### Step 5 — Hand back to `/epic-plan`
+
+Return control. The workflow shows the operator the consolidation report at the
+HITL diff gate; on approval it runs
+`node .agents/scripts/epic-plan-decompose.js --epic <Epic_ID> --tickets
+temp/epic-<Epic_ID>/tickets.json`, which validates the consolidated array,
+persists the hierarchy, and flips the Epic to `agent::ready`.
+
+## Constraints
+
+- Do **not** call the GitHub API from this Skill. It reads two temp artifacts
+  and writes two temp artifacts; persistence belongs to the script.
+- Do **not** write outside `temp/epic-<Epic_ID>/`.
+- Do **not** add scope or invent tickets. The four permitted operations (merge
+  Stories, collapse single-Story Features, re-parent, rewire `depends_on`) are
+  exhaustive — anything else is out of contract.
+- If `temp/epic-<Epic_ID>/tickets.json` is missing, fail loudly and instruct
+  the caller to run the `epic-plan-decompose-author` Skill first.
+- The validator
+  ([`lib/orchestration/ticket-validator.js`](../../../scripts/lib/orchestration/ticket-validator.js))
+  is the authoritative post-consolidation gate — including
+  `assertNoSingleStoryFeature`. Re-consolidate when it rejects rather than
+  patching tickets by hand.