mandrel 1.57.0

package/.agents/workflows/explain.md

@@ -0,0 +1,118 @@
+---
+description:
+  Walk the operator through a code change until they genuinely understand it.
+  Targets a PR, a branch, or the working-tree diff, then drives the
+  `core/knowledge-transfer` skill (restate-first, why-ladder, mastery gates,
+  persistent checklist) with an operator-controlled stop at every checkpoint.
+---
+
+# /explain [PR# | branch | --staged | --diff <ref>]
+
+## Overview
+
+`/explain` is the **operator-facing comprehension command**. Use it when code
+landed (or is about to) and you want to be sure you actually understand it —
+the problem it solves, why it was solved this way, the design decisions, the
+edge cases, and the blast radius. It is the after-the-fact counterpart to
+[`/epic-plan`](epic-plan.md) Phase 11 (which walks the operator through a
+*plan* before delivery); both drive the same engine.
+
+```text
+/explain 1234            → walk through merged/open PR #1234
+/explain story-104       → walk through the diff of branch story-104 vs main
+/explain --staged        → walk through the currently staged changes
+/explain --diff HEAD~3   → walk through the diff from HEAD~3 to working tree
+/explain                 → no subject given: ask what to explain, then proceed
+```
+
+This command **delegates the method** to the
+[`core/knowledge-transfer`](../skills/core/knowledge-transfer/SKILL.md) skill.
+This file owns only **subject resolution** (which diff) and the handoff into
+that skill. Read the skill before running — it defines the loop, the
+why-ladder, the depth levels, the quizzing rules, and the operator-stop
+contract.
+
+## When to use `/explain`
+
+| Scenario | Command |
+| --- | --- |
+| Understand a change that already merged | `/explain <PR#>` |
+| Understand a branch before merging it | `/explain <branch>` |
+| Understand what you are about to commit | `/explain --staged` |
+| Understand a freshly planned Epic backlog | `/epic-plan` Phase 11 (automatic) |
+
+## Step 1 — Resolve the subject
+
+Determine the change to explain from the argument:
+
+- **PR number** (`/explain 1234`) — read the PR metadata and diff:
+
+  ```bash
+  gh pr view 1234 --json title,body,state,headRefName,baseRefName
+  gh pr diff 1234
+  ```
+
+- **Branch** (`/explain story-104`) — diff the branch against the base
+  branch (`project.baseBranch`, default `main`):
+
+  ```bash
+  git diff main...story-104
+  ```
+
+- **`--staged`** — the staged working-tree changes:
+
+  ```bash
+  git diff --staged
+  ```
+
+- **`--diff <ref>`** — an explicit diff range:
+
+  ```bash
+  git diff <ref>
+  ```
+
+- **No argument** — ask the operator which PR, branch, or range they want
+  walked through, then resolve as above. Do not guess.
+
+Read the resolved diff **and** the surrounding code it touches before
+explaining anything — ground every explanation in the real artifact, never
+the title alone.
+
+## Step 2 — Drive the comprehension loop
+
+Activate [`core/knowledge-transfer`](../skills/core/knowledge-transfer/SKILL.md)
+with the resolved change as the subject. Follow the skill exactly:
+
+1. **Frame & gather** — state the change in one sentence; write the checklist
+   to `temp/comprehension-<subject>.md`.
+2. **Restate-first** — ask the operator what they already understand before
+   explaining.
+3. **Fill gaps one layer at a time** along the why-ladder
+   (problem → why → branches → solution → why this solution → design
+   decisions → edge cases → broader impact), confirming mastery at each layer
+   and offering the stop exit before advancing.
+4. **Close** — summarize coverage, note any unchecked items, leave the
+   checklist artifact in place.
+
+Honor depth requests (ELI5 / intern / peer) and quiz via the host's
+structured-question mechanism when it sharpens understanding.
+
+## Constraints
+
+- **Operator-invoked only.** Never auto-fire `/explain`, and never run it
+  inside a non-interactive delivery sub-agent — there is no operator to
+  teach.
+- **Operator controls the exit.** Stop the moment the operator says they are
+  satisfied; this command never blocks or gates anything.
+- **Read-only.** `/explain` teaches; it does not modify code, tickets, or
+  branches. The only file it writes is the `temp/` checklist artifact.
+
+## See also
+
+- [`core/knowledge-transfer`](../skills/core/knowledge-transfer/SKILL.md) —
+  the comprehension engine this command drives.
+- [`/epic-plan`](epic-plan.md) — Phase 11 runs the same engine over a plan
+  before delivery.
+- `/code-review` (Claude Code built-in) — correctness review of a diff. A
+  different concern: `/explain` builds *operator* understanding, not a defect
+  list.

package/.agents/workflows/git-cleanup.md

@@ -0,0 +1,250 @@
+---
+description: >-
+  Tidy the local checkout in four phases: fast-forward `main`, prune stale
+  remote-tracking refs, sweep merged branches (squash-aware), and triage
+  `git stash` entries — each step gated by operator confirmation.
+---
+
+# Git Cleanup Workflow
+
+`/git-cleanup` folds the four cleanup steps that operators routinely
+run by hand after a busy session into a single pipeline with per-step
+confirmation:
+
+1. **fast-forward `main`** — `git fetch origin <base>` then
+   `git merge --ff-only origin/<base>` on a clean working tree.
+2. **prune stale remote-tracking refs** — `git fetch --prune origin`
+   to drop `refs/remotes/origin/*` entries that GitHub already deleted.
+3. **reap merged local branches** — the existing squash-aware
+   `gh pr list --state merged` + `git branch --merged <base>` sweep,
+   with attached worktrees removed first. Optionally also deletes the
+   `origin/<branch>` ref when `--remote` is passed. With `--remote`,
+   the planner additionally enumerates `refs/remotes/origin/*` and
+   reaps any **remote-only** merged branches — branches whose local
+   ref is already gone (or never existed) but whose `origin/<branch>`
+   still points at a merged PR.
+4. **triage `git stash` entries** — list every stash and prompt for
+   `drop / keep / quit` per entry (or pass `--drop-stashes <ref>` for
+   non-interactive use).
+
+The enumeration + reap logic lives in
+[`git-cleanup.js`](../scripts/git-cleanup.js). When no phase flag is
+passed, **all four phases run** sequentially. Pass any of
+`--fast-forward-main`, `--prune-remotes`, `--branches`, `--stashes` to
+narrow the run.
+
+> **When to run**: After a session that landed several PRs, or before
+> starting a new Epic / Story, to put the local checkout into a known
+> tidy state.
+>
+> **Persona**: `devops-engineer` · **Skills**:
+> `core/git-workflow-and-versioning`
+
+<!-- markdownlint-disable-next-line MD028 -->
+
+> [!WARNING] The `--execute` flag mutates state: it can fast-forward
+> `main`, delete local branches, delete remote refs (with `--remote`),
+> and drop stashes. Without `--execute` the script is a dry-run preview.
+
+## Step 1 — Dry-run preview
+
+```powershell
+node .agents/scripts/git-cleanup.js
+```
+
+Walks all four phases without mutating anything. The fast-forward phase
+reports whether the tree is clean and how far behind `origin/<base>` the
+local ref is. The branches phase prints the merged-branch candidate
+list. The stashes phase lists every stash with its created-at and
+message.
+
+Add `--json` for a structured `{ fastForward, prune, stashes,
+candidates, … }` envelope.
+
+## Step 2 — Run a single phase
+
+Each phase is independently selectable. Useful when you want to scope
+the cleanup tightly:
+
+```powershell
+# Only fast-forward main (skip everything else)
+node .agents/scripts/git-cleanup.js --fast-forward-main --execute
+
+# Only sweep merged branches + their origin refs
+node .agents/scripts/git-cleanup.js --branches --execute --remote
+
+# Only prune stale tracking refs
+node .agents/scripts/git-cleanup.js --prune-remotes --execute
+```
+
+## Step 3 — Run all four phases
+
+The default. Confirms each destructive step independently:
+
+```powershell
+node .agents/scripts/git-cleanup.js --execute
+```
+
+The script prompts before each mutation:
+
+- **fast-forward-main**: skipped silently when the tree is dirty or the
+  FF would not be a fast-forward; otherwise prompts
+  `Fast-forward main by N commit(s)? [y/N]`.
+- **prune-remotes**: prompts before running
+  `git fetch --prune origin`.
+- **branches**: prints the dry-run candidate list, then prompts
+  `Reap N merged branch(es)? [y/N]`.
+- **stashes**: prompts per-stash with `drop / keep / quit`. A `quit`
+  reply stops the per-stash loop without dropping anything further.
+
+Add `--remote` to also reap `origin/<branch>` during the branches phase.
+
+## Step 4 — Non-interactive / CI
+
+Pass `--yes` to bypass every per-step prompt:
+
+```powershell
+node .agents/scripts/git-cleanup.js --execute --remote --yes
+```
+
+For the stash phase under `--yes` or `--json`, drops require an explicit
+allowlist via `--drop-stashes <ref>` (repeatable). Without that flag,
+stashes are listed but never dropped:
+
+```powershell
+node .agents/scripts/git-cleanup.js --stashes --execute --yes \
+  --drop-stashes 'stash@{0}' --drop-stashes 'stash@{2}'
+```
+
+This keeps the JSON / CI invocation contract explicit — the operator
+names exactly which stashes to drop, by ref.
+
+## Step 5 — JSON envelope
+
+`--json` emits a single line of structured output suitable for
+programmatic consumption:
+
+```json
+{
+  "dryRun": false,
+  "baseBranch": "main",
+  "fastForward": {
+    "ok": true,
+    "applied": true,
+    "skipped": false,
+    "behind": 2
+  },
+  "prune": {
+    "ok": true,
+    "attempted": true,
+    "remote": "origin",
+    "pruned": ["fix/old"]
+  },
+  "candidates": [
+    {
+      "branch": "fix/foo",
+      "prNumber": 1471,
+      "mergedAt": "2026-05-09T12:00:00Z",
+      "hasWorktree": true,
+      "worktreePath": "C:/repo/.worktrees/fix-foo",
+      "detectedBy": "gh"
+    }
+  ],
+  "worktrees": [{ "path": "C:/repo/.worktrees/fix-foo", "ok": true, "dirty": false }],
+  "local":  [{ "branch": "fix/foo", "ok": true, "alreadyGone": false }],
+  "remote": [{ "branch": "fix/foo", "ok": true, "alreadyGone": true }],
+  "stashes": {
+    "ok": true,
+    "actions": [
+      { "ref": "stash@{0}", "action": "drop", "dropped": true }
+    ],
+    "failures": []
+  },
+  "failures": [],
+  "ok": true
+}
+```
+
+## Exit codes
+
+- `0` — clean: dry-run preview, or at least one phase produced work and
+  no phase failed.
+- `1` — at least one phase reported a failure (fast-forward, prune,
+  branch reap, or stash drop). A failure in one phase **does not**
+  short-circuit later phases — each runs and reports independently.
+- `2` — every active phase produced nothing to do (informational; the
+  repo is already tidy).
+
+## Phase-specific behaviour
+
+### fast-forward-main
+
+- Skip reasons surfaced in `fastForward.reason`:
+  - `dirty-tree` — `git status --porcelain` returned non-empty.
+  - `not-fast-forward` — local `<base>` has commits the remote does
+    not (`git rev-list --left-right --count` shows local-ahead > 0).
+  - `already-up-to-date` — local and remote `<base>` point at the same
+    commit.
+  - `fetch-failed` / `merge-failed` — surface git's stderr verbatim.
+- When the current HEAD is not `<base>`, the script runs
+  `git checkout <base>` before merging. The original branch is **not**
+  restored at the end — operators on a feature branch should run
+  `git checkout -` after.
+
+### prune-remotes
+
+Runs as its own phase regardless of whether `--remote` was passed
+during the branches phase. The branches phase still runs its own
+follow-up prune when `--remote` is set, so passing both is idempotent
+(the second prune just reports `pruned: []`).
+
+### branches
+
+The merged-branch sweep semantics:
+
+- A branch is a candidate iff it is not `<base>`, not the current
+  HEAD, not in `git config branch.protectedBranches`, and either has a
+  merged PR (`gh pr list --head <branch> --state merged`) or appears in
+  `git branch --merged <base>`.
+- When a candidate has an attached worktree, the worktree is removed
+  (force if dirty) **before** `git branch -D`, mirroring the pattern in
+  [`worktree-lifecycle.md`](helpers/worktree-lifecycle.md).
+- `--remote` is required on top of `--execute` to touch `origin/`.
+
+The skip taxonomy distinguishes two unreapable cases:
+
+- `reason: 'protected'` — the base branch or a name in
+  `git config branch.protectedBranches`. Not reapable; ignore.
+- `reason: 'current-head'` — the current branch. Reapable after
+  `git checkout <base>`. The dry-run output surfaces a remediation
+  hint so the operator sees the recovery path without having to look
+  in the JSON envelope.
+
+The `--remote` flag also opts the planner into a **remote-only
+enumeration pass**: in addition to walking `refs/heads/*`, the planner
+also walks `refs/remotes/origin/*` and emits candidates for any branch
+that exists on `origin` with a merged PR but has no local ref. These
+candidates carry `detectedBy: 'remote-only'` and `localExists: false`,
+and the executor runs only the `git push --delete origin/<branch>`
+path for them (no local `git branch -D` is attempted — there is no
+local branch to delete).
+
+### stashes
+
+- Stashes are dropped high-index-first so the indices of remaining
+  stashes stay stable across consecutive drops (git renumbers from the
+  top of the stack).
+- In interactive mode (no `--yes`, no `--json`), each stash gets a
+  prompt: `drop / keep / quit`. The default on bare ENTER is `keep`.
+- In `--yes` or `--json` mode, only refs explicitly named via
+  `--drop-stashes <ref>` are dropped. Everything else is kept. There is
+  intentionally no "drop all" shorthand.
+
+## Constraint
+
+Do **not** run with `--execute` if there is unmerged work that needs
+saving. The fast-forward phase skips on a dirty tree (safe), but the
+branches phase will reap any merged-PR branch in scope — passing
+`--exclude '<pattern>'` is the only way to carve out exceptions. The
+remote reap (`--remote`) crosses `origin/` and cannot be undone without
+re-pushing.

package/.agents/workflows/git-commit-all.md

@@ -0,0 +1,15 @@
+---
+description: Stage every untracked and modified file, then create a single conventional-commit on the current branch (no push).
+---
+
+# /git-commit-all [Message]
+
+This is a compatibility alias for [`/git-push --no-push`](git-push.md) — it
+stages and commits all outstanding changes without pushing. See
+[`git-push.md`](git-push.md) for the canonical procedure, hook-failure guidance,
+and the parallel-execution warning.
+
+## Constraint
+
+Follow every constraint in [`git-push.md`](git-push.md) — this alias does not
+relax any of them.