mandrel 1.57.0

package/.agents/skills/core/git-workflow-and-versioning/SKILL.md

@@ -0,0 +1,352 @@
+---
+name: git-workflow-and-versioning
+description:
+  Structures git workflow practices. Use when making any code change. Use when
+  committing, branching, resolving conflicts, or when you need to organize work
+  across multiple parallel streams.
+---
+
+# Git Workflow and Versioning
+
+## Policy Capsule
+
+- Default to trunk-based development: branch from `main`, keep feature branches short-lived (1–3 days), and delete them after merge. Prefer feature flags over long-lived branches.
+- Commit early and often — each successful increment is its own save point. Never accumulate large uncommitted changes.
+- Keep commits atomic: each commit does exactly one logical thing. Never mix formatting changes with behavior changes, or refactors with features.
+- Write commit messages that explain the **why**, not the what. Follow the `<type>: <description>` convention with types drawn from `feat | fix | refactor | test | docs | chore` (imperative mood).
+- Target ~100 lines per commit/PR; split anything over ~1000 lines into smaller logical changes before submitting.
+- Before every commit: review the staged diff, scan for secrets/PII, run tests + lint + typecheck; automate via husky/lint-staged when available.
+- Provide a structured Change Summary on completion that includes `CHANGES MADE`, `THINGS I DIDN'T TOUCH (intentionally)`, and `POTENTIAL CONCERNS` — the "didn't touch" section is mandatory to demonstrate scope discipline.
+- Never commit `.env`, build output (`dist/`, `.next/`), `node_modules/`, IDE-private config, or any hardcoded secret. Keep a `.gitignore` that covers these from day one.
+- Never force-push to shared branches; on rejected pushes, fix the underlying issue and create a follow-up commit rather than amending.
+- Use worktrees (not branch-switching) for parallel agent work so concurrent streams are isolated until explicitly merged.
+
+## Overview
+
+Git is your safety net. Treat commits as save points, branches as sandboxes, and
+history as documentation. With AI agents generating code at high speed,
+disciplined version control is the mechanism that keeps changes manageable,
+reviewable, and reversible.
+
+## When to Use
+
+Always. Every code change flows through git.
+
+## Core Principles
+
+### Trunk-Based Development (Recommended)
+
+Keep `main` always deployable. Work in short-lived feature branches that merge
+back within 1-3 days. Long-lived development branches are hidden costs — they
+diverge, create merge conflicts, and delay integration. DORA research
+consistently shows trunk-based development correlates with high-performing
+engineering teams.
+
+```text
+main ──●──●──●──●──●──●──●──●──●──  (always deployable)
+        ╲      ╱  ╲    ╱
+         ●──●─╱    ●──╱    ← short-lived feature branches (1-3 days)
+```
+
+This is the recommended default. Teams using gitflow or long-lived branches can
+adapt the principles (atomic commits, small changes, descriptive messages) to
+their branching model — the commit discipline matters more than the specific
+branching strategy.
+
+- **Dev branches are costs.** Every day a branch lives, it accumulates merge
+  risk.
+- **Release branches are acceptable.** When you need to stabilize a release
+  while main moves forward.
+- **Feature flags > long branches.** Prefer deploying incomplete work behind
+  flags rather than keeping it on a branch for weeks.
+
+### 1. Commit Early, Commit Often
+
+Each successful increment gets its own commit. Don't accumulate large
+uncommitted changes.
+
+```text
+Work pattern:
+  Implement slice → Test → Verify → Commit → Next slice
+
+Not this:
+  Implement everything → Hope it works → Giant commit
+```
+
+Commits are save points. If the next change breaks something, you can revert to
+the last known-good state instantly.
+
+### 2. Atomic Commits
+
+Each commit does one logical thing:
+
+```text
+# Good: Each commit is self-contained
+git log --oneline
+a1b2c3d Add task creation endpoint with validation
+d4e5f6g Add task creation form component
+h7i8j9k Connect form to API and add loading state
+m1n2o3p Add task creation tests (unit + integration)
+
+# Bad: Everything mixed together
+git log --oneline
+x1y2z3a Add task feature, fix sidebar, update deps, refactor utils
+```
+
+### 3. Descriptive Messages
+
+Commit messages explain the _why_, not just the _what_:
+
+```text
+# Good: Explains intent
+feat: add email validation to registration endpoint
+
+Prevents invalid email formats from reaching the database.
+Uses Zod schema validation at the route handler level,
+consistent with existing validation patterns in auth.ts.
+
+# Bad: Describes what's obvious from the diff
+update auth.ts
+```
+
+**Format:**
+
+```text
+<type>: <short description>
+
+<optional body explaining why, not what>
+```
+
+**Types:**
+
+- `feat` — New feature
+- `fix` — Bug fix
+- `refactor` — Code change that neither fixes a bug nor adds a feature
+- `test` — Adding or updating tests
+- `docs` — Documentation only
+- `chore` — Tooling, dependencies, config
+
+### 4. Keep Concerns Separate
+
+Don't combine formatting changes with behavior changes. Don't combine refactors
+with features. Each type of change should be a separate commit — and ideally a
+separate PR:
+
+```text
+# Good: Separate concerns
+git commit -m "refactor: extract validation logic to shared utility"
+git commit -m "feat: add phone number validation to registration"
+
+# Bad: Mixed concerns
+git commit -m "refactor validation and add phone number field"
+```
+
+**Separate refactoring from feature work.** A refactoring change and a feature
+change are two different changes — submit them separately. This makes each
+change easier to review, revert, and understand in history. Small cleanups
+(renaming a variable) can be included in a feature commit at reviewer
+discretion.
+
+### 5. Size Your Changes
+
+Target ~100 lines per commit/PR. Changes over ~1000 lines should be split. See
+the splitting strategies in `code-review-and-quality` for how to break down
+large changes.
+
+```text
+~100 lines  → Easy to review, easy to revert
+~300 lines  → Acceptable for a single logical change
+~1000 lines → Split into smaller changes
+```
+
+## Branching Strategy
+
+### Feature Branches
+
+```text
+main (always deployable)
+  │
+  ├── feature/task-creation    ← One feature per branch
+  ├── feature/user-settings    ← Parallel work
+  └── fix/duplicate-tasks      ← Bug fixes
+```
+
+- Branch from `main` (or the team's default branch)
+- Keep branches short-lived (merge within 1-3 days) — long-lived branches are
+  hidden costs
+- Delete branches after merge
+- Prefer feature flags over long-lived branches for incomplete features
+
+### Branch Naming
+
+```text
+feature/<short-description>   → feature/task-creation
+fix/<short-description>       → fix/duplicate-tasks
+chore/<short-description>     → chore/update-deps
+refactor/<short-description>  → refactor/auth-module
+```
+
+## Working with Worktrees
+
+For parallel AI agent work, use git worktrees to run multiple branches
+simultaneously:
+
+```bash
+# Create a worktree for a feature branch
+git worktree add ../project-feature-a feature/task-creation
+git worktree add ../project-feature-b feature/user-settings
+
+# Each worktree is a separate directory with its own branch
+# Agents can work in parallel without interfering
+ls ../
+  project/              ← main branch
+  project-feature-a/    ← task-creation branch
+  project-feature-b/    ← user-settings branch
+
+# When done, merge and clean up
+git worktree remove ../project-feature-a
+```
+
+Benefits:
+
+- Multiple agents can work on different features simultaneously
+- No branch switching needed (each directory has its own branch)
+- If one experiment fails, delete the worktree — nothing is lost
+- Changes are isolated until explicitly merged
+
+## The Save Point Pattern
+
+```text
+Agent starts work
+    │
+    ├── Makes a change
+    │   ├── Test passes? → Commit → Continue
+    │   └── Test fails? → Revert to last commit → Investigate
+    │
+    ├── Makes another change
+    │   ├── Test passes? → Commit → Continue
+    │   └── Test fails? → Revert to last commit → Investigate
+    │
+    └── Feature complete → All commits form a clean history
+```
+
+This pattern means you never lose more than one increment of work. If an agent
+goes off the rails, `git reset --hard HEAD` takes you back to the last
+successful state.
+
+## Change Summaries
+
+After any modification, provide a structured summary. This makes review easier,
+documents scope discipline, and surfaces unintended changes:
+
+```text
+CHANGES MADE:
+- src/routes/tasks.ts: Added validation middleware to POST endpoint
+- src/lib/validation.ts: Added TaskCreateSchema using Zod
+
+THINGS I DIDN'T TOUCH (intentionally):
+- src/routes/auth.ts: Has similar validation gap but out of scope
+- src/middleware/error.ts: Error format could be improved (separate task)
+
+POTENTIAL CONCERNS:
+- The Zod schema is strict — rejects extra fields. Confirm this is desired.
+- Added zod as a dependency (72KB gzipped) — already in package.json
+```
+
+This pattern catches wrong assumptions early and gives reviewers a clear map of
+the change. The "DIDN'T TOUCH" section is especially important — it shows you
+exercised scope discipline and didn't go on an unsolicited renovation.
+
+## Pre-Commit Hygiene
+
+Before every commit:
+
+```bash
+# 1. Check what you're about to commit
+git diff --staged
+
+# 2. Ensure no secrets
+git diff --staged | grep -i "password\|secret\|api_key\|token"
+
+# 3. Run tests
+npm test
+
+# 4. Run linting
+npm run lint
+
+# 5. Run type checking
+npx tsc --noEmit
+```
+
+Automate this with git hooks:
+
+```json
+// package.json (using lint-staged + husky)
+{
+  "lint-staged": {
+    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
+    "*.{json,md}": ["prettier --write"]
+  }
+}
+```
+
+## Handling Generated Files
+
+- **Commit generated files** only if the project expects them (e.g.,
+  `package-lock.json`, Prisma migrations)
+- **Don't commit** build output (`dist/`, `.next/`), environment files (`.env`),
+  or IDE config (`.vscode/settings.json` unless shared)
+- **Have a `.gitignore`** that covers: `node_modules/`, `dist/`, `.env`,
+  `.env.local`, `*.pem`
+
+## Using Git for Debugging
+
+```bash
+# Find which commit introduced a bug
+git bisect start
+git bisect bad HEAD
+git bisect good <known-good-commit>
+# Git checkouts midpoints; run your test at each to narrow down
+
+# View what changed recently
+git log --oneline -20
+git diff HEAD~5..HEAD -- src/
+
+# Find who last changed a specific line
+git blame src/services/task.ts
+
+# Search commit messages for a keyword
+git log --grep="validation" --oneline
+```
+
+## Common Rationalizations
+
+| Rationalization                        | Reality                                                                                                                                 |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| "I'll commit when the feature is done" | One giant commit is impossible to review, debug, or revert. Commit each slice.                                                          |
+| "The message doesn't matter"           | Messages are documentation. Future you (and future agents) will need to understand what changed and why.                                |
+| "I'll squash it all later"             | Squashing destroys the development narrative. Prefer clean incremental commits from the start.                                          |
+| "Branches add overhead"                | Short-lived branches are free and prevent conflicting work from colliding. Long-lived branches are the problem — merge within 1-3 days. |
+| "I'll split this change later"         | Large changes are harder to review, riskier to deploy, and harder to revert. Split before submitting, not after.                        |
+| "I don't need a .gitignore"            | Until `.env` with production secrets gets committed. Set it up immediately.                                                             |
+
+## Red Flags
+
+- Large uncommitted changes accumulating
+- Commit messages like "fix", "update", "misc"
+- Formatting changes mixed with behavior changes
+- No `.gitignore` in the project
+- Committing `node_modules/`, `.env`, or build artifacts
+- Long-lived branches that diverge significantly from main
+- Force-pushing to shared branches
+
+## Verification
+
+For every commit:
+
+- [ ] Commit does one logical thing
+- [ ] Message explains the why, follows type conventions
+- [ ] Tests pass before committing
+- [ ] No secrets in the diff
+- [ ] No formatting-only changes mixed with behavior changes
+- [ ] `.gitignore` covers standard exclusions

package/.agents/skills/core/hydrate-context/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: hydrate-context
+description: >-
+  Hydrate a Task or Story ticket into a structured ContextEnvelope (or the
+  legacy `{ prompt }` stdout wrapper). Reads the ticket body, parses
+  Feature / Epic hierarchy, fetches the Tech Spec + PRD, and assembles
+  named sections with provenance and section-aware elision. Successor to
+  the retired mandrel MCP `context.hydrate` tool.
+allowed_tools:
+  - Read
+  - Bash
+---
+
+# hydrate-context
+
+## Policy Capsule
+
+- Invoke via `node .agents/scripts/hydrate-context.js --ticket <id> [--epic <id>]`; the wrapping CLI is the only supported entry point and delegates to `lib/orchestration/context-hydration-engine.js`.
+- Treat the operation as strictly **read-only on GitHub** — never modify ticket bodies, never post comments, never apply labels.
+- When `--epic` is omitted, parse the Epic ID from the ticket body's `Epic: #N` line; do not infer it from elsewhere.
+- Surface `persona::*` and `skill::*` labels from the ticket into the composed prompt so the downstream executor can pin its sub-agent dispatch.
+- Emit exactly one JSON object on stdout (`{ "prompt": "..." }` by default, or `{ "envelope": {...} }` with `--emit envelope`) and nothing else — no temp files, no diagnostic prints that would corrupt the envelope.
+- Honour the engine's context-budget cap via section-aware elision (`elideEnvelope`): lower-priority sections drop or summarize before higher-priority ones. Never silently truncate mid-string.
+- Do not persist the composed prompt to disk; forwarding is the caller's responsibility.
+
+## Role
+
+Context aggregator. Resolves a ticket's hierarchy (Task → Story →
+Feature → Epic) and stitches the linked planning artifacts into a
+single prompt the executor consumes.
+
+## When to use
+
+Whenever an Epic-scoped sub-agent needs the same context bundle the
+human operator would assemble manually before opening the file editor.
+The wrapping script `hydrate-context.js` is the CLI today; this Skill
+documents the dispatch contract for callers that want to invoke via
+the Skill tool.
+
+## Inputs
+
+- `--ticket <id>` — GitHub issue number to hydrate (required).
+- `--epic <id>` (optional) — when omitted, parsed from the ticket
+  body's `Epic: #N` line.
+
+Persona and skill labels are read off the ticket
+(`persona::*`, `skill::*`) and surfaced in the composed prompt so the
+executor can pin its sub-agent dispatch.
+
+## Outputs
+
+The engine assembles a typed **ContextEnvelope** (`lib/orchestration/context-envelope.js`) and serializes it for consumers:
+
+| Field | Role |
+| --- | --- |
+| `schemaVersion` | Always `"1"` for the current contract. |
+| `task` | `{ id, title, persona?, skills?, protocolVersion? }` from the ticket and labels. |
+| `sections[]` | Named blocks (`protocolPolicy`, `persona`, `skillCapsules`, `hierarchy`, `acceptanceCriteria`, `verificationCommands`, `taskInstructions`) each with `priority`, `elideWhenOverBudget` (`drop` \| `summarize`), `content`, `estimatedTokens`, optional `source`. |
+| `provenance[]` | Ticket snapshots: `{ id, version, hash, retrievedAt }` so auditors can cite what was fetched. |
+| `budget` | `{ maxTokens, used, elided[] }` after `elideEnvelope` runs. |
+| `warnings[]` | Non-fatal hydration notices (missing files, skipped skills, etc.). |
+
+Default CLI stdout (backward-compatible wrapper):
+
+```json
+{ "prompt": "..." }
+```
+
+`prompt` is `envelopeToPrompt(envelope)` — sections joined in `SECTION_RENDER_ORDER`, not elision priority. For inspection or downstream tools that consume the typed shape:
+
+```bash
+node .agents/scripts/hydrate-context.js --ticket <id> --emit envelope
+```
+
+```json
+{ "envelope": { "schemaVersion": "1", "task": { ... }, "sections": [ ... ], "provenance": [ ... ], "budget": { ... }, "warnings": [ ... ] } }
+```
+
+The Skill writes nothing else — no GitHub comments, no temp files.
+Idempotence is trivial because the operation is read-only.
+
+## Procedure
+
+```bash
+node .agents/scripts/hydrate-context.js --ticket <id> [--epic <id>]
+```
+
+Delegates to `hydrateContext` from
+`lib/orchestration/context-hydration-engine.js`. The engine handles
+provider I/O, body parsing, provenance stamping, and
+`elideEnvelope` when `budget.used` exceeds `limits.maxTokenBudget`.
+
+**Section-aware elision.** Each section carries a numeric `priority`
+(lower drops first) and an `elideWhenOverBudget` policy (`drop` removes
+the section; `summarize` keeps a head excerpt). Defaults live in
+`DEFAULT_SECTION_PRIORITIES` and `DEFAULT_ELIDE_POLICIES` in
+`context-envelope.js`. Elided section names are recorded in
+`budget.elided`.
+
+**Capsule-only skill loading.** Activated skills resolve through
+`skills.index.json` and `loadSkillCapsule`, emitting only the Policy
+Capsule (the skill's non-negotiables) plus a pointer instruction into the
+`skillCapsules` section. Full `SKILL.md` bodies are never inlined into a
+task prompt — the sub-agent reads the full playbook on demand via the
+rendered `Read <path>` pointer. The full-body injection path, the
+`fullSkillBodies` config flag, and the `skill::full` label were removed in
+a hard cutover (Story #3863); the only residual full-body emission is the
+defensive fallback when a `SKILL.md` is missing its capsule marker (a
+malformed manifest), which also logs a warning.
+
+## Constraints
+
+- Do **not** modify ticket bodies or post comments. The Skill is
+  strictly read-only on GitHub.
+- Do **not** persist the composed prompt to disk. The caller is
+  responsible for forwarding the stdout envelope to its consumer.
+- Do **not** bypass the context-budget cap — honour `elideEnvelope`
+  and the per-section policies; never silently truncate.