mandrel 2.6.0 → 2.8.0

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

@@ -10,343 +10,45 @@ description:
 
 ## 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.
+- The always-on git core — canonical branch shape (`story-<storyId>` seeded from `main`), the Conventional-Commit subject contract and its allowed type set, the `refs #<id>` reference, and the push / hygiene MUSTs — lives in [`.agents/rules/git-conventions.md`](../../../rules/git-conventions.md); that rule is the SSOT and wins on conflict. This skill adds **only** what the rule does not own.
+- Commit early and often: each successful increment is its own save point. Never accumulate large uncommitted changes.
+- Keep commits atomic — one logical thing per commit. Never mix formatting changes with behavior changes, or refactors with features.
+- Treat commits as revertable save points: when a change breaks something, `git reset --hard HEAD` returns you to the last known-good increment, so you never lose more than one step of work.
+- Provide a structured Change Summary on completion with `CHANGES MADE`, `THINGS I DIDN'T TOUCH (intentionally)`, and `POTENTIAL CONCERNS` — the "didn't touch" section is mandatory to demonstrate scope discipline.
+- Use git worktrees (not branch-switching) for parallel agent work so concurrent streams stay isolated until explicitly merged. The runtime already materializes one worktree per Story under `.worktrees/story-<id>/`.
+
+## What the rule owns (do not restate)
+
+Branch naming, the allowed commit types, `refs #`, squash-merge delivery, push
+validation, and local-checkout hygiene are the always-on rule's job. Read
+[`git-conventions.md`](../../../rules/git-conventions.md) for those; do not
+carry a divergent copy here. In particular, the framework's only sanctioned
+delivery shape is `story-<id>` → PR → squash-merge to `main`: there is no
+short-lived personal branch flow to prescribe, and delivery is squash-merge, so
+this skill offers no contrary branching or history-preservation guidance.
+
+## The Save-Point Pattern
+
+Work in the loop `implement slice → test → verify → commit → next slice`. Each
+green increment is a commit; if the next change fails, revert to the last
+commit and investigate rather than debugging forward from a broken state. This
+means you never lose more than one increment of work.
 
 ## Change Summaries
 
-After any modification, provide a structured summary. This makes review easier,
+After any modification, provide a structured summary — it 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)
+- src/routes/auth.ts: Has a similar validation gap but out of scope
 
 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"]
-  }
-}
+- The new schema rejects extra fields — confirm that is desired.
 ```
 
-## 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
+The "DIDN'T TOUCH" section is the important one: it shows you exercised scope
+discipline and did not go on an unsolicited renovation.