mandrel 1.57.0

package/.agents/workflows/story-plan.md

@@ -0,0 +1,233 @@
+---
+description:
+  Author a standalone Story (no parent Epic) from a short prompt. Builds a
+  context envelope, lets the host LLM draft the body, and creates the
+  GitHub Issue with type::story and a persona label — ready to feed into
+  /single-story-deliver.
+---
+
+# /story-plan
+
+## Overview
+
+`/story-plan` is the standalone counterpart to
+[`/epic-plan`](epic-plan.md) for Stories that are **not** attached to an
+Epic. It closes the gap between "one-line idea" and "well-formed
+standalone Story body ready for [`/single-story-deliver`](helpers/single-story-deliver.md)"
+using the same `host LLM authors + Node wrapper persists` split as
+`/epic-plan`.
+
+```text
+/story-plan --idea "<seed>"
+  → story-plan.js --emit-context               (envelope: seed, template, dup candidates)
+  → host LLM authors a draft Story body         (in chat, using the envelope)
+  → operator confirms (HITL)
+  → story-plan.js --body <file>                 (validate, gh issue create)
+  → "Next: /single-story-deliver <id>"
+```
+
+**When to use `/story-plan` vs. `/epic-plan` Phase 8:**
+
+| Trait                | `/story-plan`                              | `/epic-plan` Phase 8                         |
+| -------------------- | ------------------------------------------ | -------------------------------------------- |
+| Output               | One standalone Story Issue                 | Decomposed Feature/Story/Task hierarchy      |
+| Parent Epic          | None (no `Epic: #N` in body)               | Required                                     |
+| Downstream workflow  | `/single-story-deliver`                    | `/story-deliver` (per Story)                 |
+| Replan surface       | Out of scope (recreate manually if needed) | `/epic-plan --replan` regenerates everything |
+| Inbound route        | Direct, **or** an `/epic-plan` Phase 1.5 scope-triage handoff | Direct (`<epicId>` or `--idea`)         |
+| Outbound route       | Phase 2 may **escalate** an epic-sized draft to `/epic-plan --idea` (scope-triage handoff) | n/a — `/epic-plan` is already the Epic tier |
+
+If a Story-under-Epic needs replanning, use `/epic-plan --replan`. If you
+have a refactor, framework-maintenance idea, or any standalone unit of
+work, use this workflow.
+
+**Inbound from `/epic-plan` scope triage.** `/epic-plan` Phase 1.5 runs the
+[`core/scope-triage`](../skills/core/scope-triage/SKILL.md) rubric over the
+sharpened one-pager. On a `story` / `borderline` verdict the operator may route
+the work here via `/story-plan --from-notes <path>`. That invocation is a
+**scope-triage handoff** — the triage decision is already made, so `/story-plan`
+MUST NOT re-triage it (the no-re-triage rule in the skill); it proceeds straight
+to authoring the standalone Story body from the handed-off one-pager.
+
+## Prerequisites
+
+1. `GITHUB_TOKEN` or `gh auth status` clean — `gh issue create` runs at
+   persist time.
+2. The `type::story` label and the chosen `persona::*` label exist in the
+   repo. Run [`agents-bootstrap-github.js`](../scripts/agents-bootstrap-github.js)
+   once to provision them.
+
+## Invocation shapes
+
+```bash
+# Seed from an inline string:
+/story-plan --idea "rip out the unused TaskBodyMigrator export"
+
+# Seed from a notes file:
+/story-plan --from-notes temp/single-story-2293-notes.md
+
+# Inspect the draft body without creating an Issue:
+/story-plan --dry-run --body temp/single-story-draft.md
+```
+
+## Phase 1 — Emit Context
+
+Run the emit-context phase. The CLI prints a JSON envelope on stdout and
+routes all log lines to stderr so the captured file is unconditionally
+parseable by `JSON.parse`.
+
+```bash
+node .agents/scripts/story-plan.js --emit-context \
+  --idea "<seed>" \
+  [--persona engineer] \
+  [--refine | --no-refine] \
+  [--pretty] > temp/single-story-context.json
+```
+
+Envelope fields (`kind: "story-plan-context"`, `version: 1`):
+
+| Field                  | Purpose                                                   |
+| ---------------------- | --------------------------------------------------------- |
+| `seed`                 | The raw seed (verbatim from `--idea` / `--from-notes`).   |
+| `refine`               | `{ refine, reason }` heuristic verdict.                   |
+| `persona`              | Persona label to apply (default `engineer`).              |
+| `bodyTemplate`         | Contents of `.agents/templates/single-story-body.md`.     |
+| `requiredSections`     | `["Context", "Acceptance Criteria", "Out of Scope", "Notes"]`. |
+| `duplicateCandidates`  | Ranked open Stories whose titles fuzzy-match the seed.    |
+| `techStack`            | The `## Tech Stack` section of `docs/architecture.md`.    |
+| `deliverContract`      | Workflow path + required/forbidden labels and references. |
+
+### Refine heuristic
+
+`refine.refine` is `true` when the seed is shorter than 200 characters
+(or empty). Pass `--refine` / `--no-refine` to override. When the
+envelope advises refinement, activate the
+[`core/idea-refinement`](../skills/core/idea-refinement/SKILL.md) skill
+before drafting the body — same skill `/epic-plan` Phase 1 drives.
+
+## Phase 2 — Host LLM Authors a Draft Body
+
+Using the envelope above, draft a Story body that:
+
+- Starts with `# <title>` (the H1 becomes the GitHub Issue title at
+  persist time).
+- Includes every section in `requiredSections` (`## Context`,
+  `## Acceptance Criteria`, `## Out of Scope`, `## Notes`).
+- Has at least one unchecked checklist item under `## Acceptance Criteria`
+  (`- [ ] …`).
+- Does **NOT** contain any `Epic: #N` reference — that breaks the
+  standalone contract enforced by `single-story-init.js`.
+
+Write the draft to `temp/single-story-draft.md`.
+
+### Scope-triage escalation gate (symmetric counterpart to `/epic-plan` Phase 1.5)
+
+Once the draft body exists — and **only** then, because the seed alone is not
+an honest basis for a sizing judgment — run the
+[`core/scope-triage`](../skills/core/scope-triage/SKILL.md) rubric over the
+**drafted Story body** to catch an Epic-sized scope before it is persisted as a
+standalone Story. This is the outbound mirror of `/epic-plan` Phase 1.5's
+inbound downgrade gate: the two planning entry points route toward each other
+instead of each silently accepting wrong-sized work.
+
+**Skip the gate entirely when `/story-plan` was entered via a scope-triage
+handoff** — i.e. from `/epic-plan` Phase 1.5 (the inbound route above) or the
+`/epic-plan` Phase 5.5 existing-Epic conversion path. A handoff is a triage
+decision already made; re-running the rubric here would re-litigate a settled
+call and risk a ping-pong between the two workflows (the skill's no-re-triage
+rule).
+
+Otherwise, activate the skill **by reference** — read its `SKILL.md` via the
+`Read` tool and apply its rubric; do **not** restate its sizing thresholds or
+copy its verdict prose here. The skill anchors its sizing judgment to
+`DELIVERABLE_GRANULARITY_GUIDANCE` / `DEFAULT_TASK_SIZING` in
+[`ticket-validator-sizing.js`](../scripts/lib/orchestration/ticket-validator-sizing.js)
+and emits one verdict — `epic` | `story` | `borderline`. The verdict is
+host-LLM judgment: there is **no `--flag`**, no scorer, no schema, and no label
+transition behind it. (The `refine` heuristic in `story-plan.js` is unchanged —
+it is a deterministic seed-length proxy, not a scope-size judgment.) The verdict
+folds into the **existing** draft-confirmation HITL stop below — it does **not**
+add a second stop.
+
+### HITL — operator confirms the draft (verdict folded in)
+
+Display the draft to the operator and **STOP**. Do not call the persist phase
+until the operator explicitly confirms the draft. This mirrors the HITL gate
+`/epic-plan` Phase 3 enforces before opening the Epic Issue. The scope-triage
+verdict folds into this same stop:
+
+- **`story` verdict (or gate skipped via handoff)** → no extra prompt. The
+  operator confirms the draft as usual and the run proceeds to Phase 3
+  (persist).
+- **`epic` verdict** (multiple independent capabilities, a plausible
+  sizing-ceiling breach, or a real dependency structure) → the confirmation
+  prompt presents a **three-way operator choice**:
+  - **Recommended: escalate to `/epic-plan --idea`** (with the triage
+    rationale) — persist the notes/draft to a notes file and hand off to
+    `/epic-plan --idea` (or `--from-notes <path>`), identifying the invocation
+    as a **scope-triage handoff** so `/epic-plan` skips its own Phase 1.5 gate
+    (the skill's no-re-triage rule). Then **abandon the draft and exit
+    `/story-plan`** — no standalone Story is created.
+  - **Persist as a standalone Story anyway** — ignore the recommendation and
+    proceed to Phase 3 with the draft unchanged. Being wrong in the `epic`
+    direction is cheap to tolerate: if the operator persists an oversized Story,
+    the sizing validator and delivery reality push back later. The gate's value
+    is surfacing the recommendation while the scope is still free to change.
+  - **Abort** — stop planning entirely. No Issue is created.
+
+  **Never auto-route.** The verdict is advisory; the operator always decides,
+  and no `agent::*` / label transition happens on either side of the choice.
+
+## Phase 3 — Persist (`gh issue create`)
+
+```bash
+node .agents/scripts/story-plan.js \
+  --body temp/single-story-draft.md \
+  [--persona engineer]
+```
+
+The script:
+
+1. Reads the body file.
+2. Runs `validateStoryBody` — required sections present, no `Epic:`
+   reference, AC checklist non-empty. Fails fast on any error.
+3. Extracts the H1 title.
+4. Calls `gh issue create` with `--title`, `--body-file`, and the
+   `type::story` + `persona::<name>` labels.
+5. Prints a JSON line with `{ issueNumber, title, labels }` and a
+   trailing `Next: /single-story-deliver <id>` hint on stderr.
+
+### `--dry-run`
+
+```bash
+node .agents/scripts/story-plan.js \
+  --body temp/single-story-draft.md --dry-run
+```
+
+Prints the resolved title, labels, and `gh` argv plus the full body, then
+exits 0. No GitHub mutations. Use this to spot-check the draft and the
+exact `gh issue create` shape that would run.
+
+## Constraints
+
+- **No `Epic: #N` references.** This is the standalone contract; persist
+  fails fast if one is present. To attach a Story to an Epic, use
+  `/epic-plan` Phase 8 instead.
+- **No external LLM APIs.** Mirrors the v5.6 contract: the host LLM does
+  the authoring; the Node wrapper does the I/O.
+- **Idempotent.** Re-running `--emit-context` is safe. Re-running
+  `--body` opens a new Issue (it is not aware of prior runs); use
+  `--dry-run` first when iterating on the draft.
+- **Atomic by contract.** A Story is the leaf of the 3-tier hierarchy — it
+  has no child tickets. Its acceptance criteria and verification steps live
+  inline on the Story body
+  ([`single-story-deliver.md`](helpers/single-story-deliver.md)).
+
+## See also
+
+- [`/single-story-deliver`](helpers/single-story-deliver.md) — the consumer
+  workflow that picks the Story up after this one creates it.
+- [`/epic-plan`](epic-plan.md) — the Epic-tier equivalent. Phases 1–4
+  inspired the seed-capture + envelope-emit pattern used here.
+- [`core/idea-refinement`](../skills/core/idea-refinement/SKILL.md) —
+  optional pre-authoring skill activated when the seed is short.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Jennings (dsj1984)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,193 @@
+# Mandrel
+
+[![CI / CD](https://github.com/dsj1984/mandrel/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/dsj1984/mandrel/actions/workflows/ci.yml)
+
+An opinionated workflow framework for AI coding assistants built on
+Epic-centric GitHub orchestration. Planning, execution, and state all live
+natively in GitHub Issues, Labels, and Projects V2.
+
+## Prerequisites
+
+Mandrel is distributed as the
+[`mandrel`](https://www.npmjs.com/package/mandrel) npm
+package and wires its orchestration into your project's GitHub repository.
+You do **not** need a pre-created Git repo or GitHub remote — `bootstrap.js`
+provisions both as part of a cold start (`git init` → `gh repo create --push`
+→ `gh project create`). You need:
+
+- **Node.js** >= 22.22.1 (< 25).
+- **`git`** on your `PATH`.
+- **GitHub CLI `gh`** >= 2.40, authenticated — run `gh auth login` once so
+  orchestration scripts pick up your token from the OS keychain. A vanilla
+  `gh auth login` token does **not** carry the `project` scope needed to
+  provision the GitHub Projects V2 board; bootstrap degrades to
+  warn-and-skip-board in that case (no hard failure). To enable board
+  provisioning, grant the scope with `gh auth refresh -s project` (re-auth
+  in the browser when prompted) before running `bootstrap.js`.
+
+See the [Compatibility matrix](docs/upgrade-major.md#compatibility-matrix)
+section of `docs/upgrade-major.md` for the supported OS / Node /
+package-manager combinations.
+
+## Quickstart
+
+The canonical cold-start path is one launcher command, then two slash
+commands inside Claude Code:
+
+```bash
+npx create-mandrel        # install mandrel → sync → bootstrap
+```
+
+```text
+# then, inside Claude Code (commands load from .claude/commands/):
+/onboard            # guided first run: stack detect → docs → doctor → /epic-plan
+/epic-plan          # ideation -> PRD/Tech Spec -> Epic/Feature/Story hierarchy
+```
+
+`create-mandrel` installs `mandrel`, materializes `./.agents/` via
+`mandrel sync`, and runs `node .agents/scripts/bootstrap.js` for you,
+forwarding any flags you pass. `/onboard` then walks you from a clean
+checkout to a planned Epic (stack detection, docs scaffolding, a
+`mandrel doctor` readiness gate, and a started `/epic-plan`). Once you have a
+planned Epic, deliver it with `/epic-deliver <id>` (wave loop → validation →
+review → retro → open PR).
+
+### Manual equivalent
+
+If you prefer to drive the three steps `create-mandrel` wraps by hand, run
+them from your project root:
+
+```bash
+npm install mandrel   # pin an exact, provenance-signed version
+npx mandrel sync                # materialize ./.agents/ from the package
+node .agents/scripts/bootstrap.js
+```
+
+`npm install mandrel` pins an exact, provenance-signed version in
+your lockfile. The package's `postinstall` hook runs `mandrel sync`
+best-effort, so `./.agents/` is usually materialized automatically; the
+explicit `npx mandrel sync` above is the belt-and-suspenders step for
+`--ignore-scripts` or sandboxed-CI installs. Run `npx mandrel doctor` any
+time to confirm the install is healthy.
+
+`bootstrap.js` is interactive on a TTY and auto-accepts the
+owner/repo/base branch/operator handle it can infer from your local
+`git remote` and `git config user.name` — you only get prompted for
+fields it can't infer (typically the optional Projects V2 number). When the
+folder is not yet a git repo, or the GitHub repo doesn't exist, it
+provisions them: `git init` plus a first commit, then
+`gh repo create --source=. --push` (use `--visibility private|public|internal`,
+default `private`, to set the new repo's visibility), then `gh project create`
+for the Projects V2 board. Override anything inferred with `--owner`,
+`--repo`, `--base-branch`, or `--operator-handle`. For CI / scripted installs
+pass `--assume-yes` plus whichever overrides you need. The script is
+idempotent — safe to re-run anytime.
+
+For the consumer reference and the end-to-end workflow narrative, see
+[`.agents/README.md`](.agents/README.md) and
+[`.agents/docs/SDLC.md`](.agents/docs/SDLC.md). Every `.agentrc.json` key is
+documented in [`.agents/docs/configuration.md`](.agents/docs/configuration.md), and the
+slash-command index lives in
+[`.agents/docs/workflows.md`](.agents/docs/workflows.md).
+
+## Update
+
+Advance `mandrel` to the newest published version and
+re-materialize `./.agents/` in one command:
+
+```bash
+npx mandrel update
+```
+
+`mandrel update` runs an ordered cycle:
+
+1. **Resolve** the newest published version (a `npm view mandrel
+   version` registry probe) and the currently installed version.
+2. **Major gate** — if the newest version crosses a major boundary
+   (e.g. `1.x → 2.0`), the command declines, prints a pointer to
+   [`docs/upgrade-major.md`](docs/upgrade-major.md), and exits non-zero
+   without touching anything. Re-run with `--major` to apply it.
+3. **No-op short-circuit** — already on the newest version ⇒ nothing to do.
+4. **Install** the target version with the project's package manager —
+   auto-detected from the lockfile (`pnpm-lock.yaml` ⇒ pnpm, `yarn.lock` ⇒
+   yarn, otherwise npm) so the bump lands in your real lockfile. The
+   dependency bump is left **staged** on disk — `mandrel update` performs no
+   `git add` / `git commit`, so you review and commit the lockfile change
+   yourself.
+5. **Sync** — re-materialize `./.agents/` from the freshly installed payload.
+6. **Migrate** — apply version-keyed migration steps for the crossed range.
+7. **Doctor** — run the check registry to verify the resulting install.
+8. **Surface** the target changelog section.
+
+### Flags
+
+- `--dry-run` — print the resolved target version and the ordered step
+  plan, then exit. No dependency is bumped, no file is written, no seam
+  runs.
+- `--major` — apply a major-version crossing that the gate would otherwise
+  refuse. Review [`docs/upgrade-major.md`](docs/upgrade-major.md) first.
+- `--install-cmd "<cmd>"` — override the auto-detected install command. The
+  package manager is normally detected from your lockfile
+  (`pnpm-lock.yaml` ⇒ `pnpm add -D …`, `yarn.lock` ⇒ `yarn add -D …`,
+  otherwise `npm install …`), so an override is rarely needed. When you do
+  pass one, a `{target}` placeholder is substituted with the resolved newest
+  version — e.g. `--install-cmd "pnpm add -D mandrel@{target} -w"` —
+  so the override can still consume the auto-probed version. The registry
+  probe always stays on `npm view` (it is a PM-agnostic registry query).
+
+### Manual equivalent
+
+If you prefer to drive the steps by hand:
+
+```bash
+npm install mandrel@latest   # or pnpm add / yarn up
+npx mandrel sync                        # re-materialize ./.agents/
+npx mandrel doctor                      # verify the install
+```
+
+## Contributors
+
+Only `.agents/` is distributed to consumers — it ships inside the
+`mandrel` npm package and is materialized into a consumer's
+`./.agents/` directory by `mandrel sync`. Everything else in this
+repository is internal development tooling.
+
+Common commands while developing the framework itself:
+
+```bash
+npm run lint           # markdown + biome
+npm run format         # auto-format
+npm test               # framework tests
+npm run test:coverage  # tests with coverage gate
+```
+
+Deeper reference material lives in `docs/` rather than inline here:
+
+- [`docs/architecture.md`](docs/architecture.md) — module map, repo
+  layout, state machine, and tech stack.
+- [`.agents/docs/configuration.md`](.agents/docs/configuration.md) — every `.agentrc.json`
+  key explained.
+- [`.agents/docs/workflows.md`](.agents/docs/workflows.md) — slash-command
+  index (auto-generated from the workflow set).
+- [`docs/CHANGELOG.md`](docs/CHANGELOG.md) — release history.
+- [`AGENTS.md`](AGENTS.md) — repository onboarding, the two-package release
+  topology, PAT / npm-token setup, and major-version policy. Releases are
+  automated by `release-please`: land Conventional Commits on `main` and it
+  opens a combined `chore: release main` PR that squash-merges itself once
+  CI is green, tags `main`, and publishes `mandrel` to npm.
+
+Install scripts are disabled by default: the committed
+[`.npmrc`](.npmrc) sets `ignore-scripts=true`, so `npm install` / `npm ci`
+will not execute dependency lifecycle hooks — a defense-in-depth measure
+against malicious lifecycle scripts in compromised transitive packages
+(CWE-1357). CI passes `--ignore-scripts` explicitly. If you knowingly need
+install scripts for a specific install, run
+`npm install --ignore-scripts=false` for that invocation only.
+
+CRAP and Maintainability gates fire at every checkpoint (keystroke,
+pre-commit, pre-push, story-close, CI, Epic merge) against the same
+thresholds from `delivery.quality.*` in `.agentrc.json`.
+
+## License
+
+MIT

package/bin/mandrel.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// bin/mandrel.js — mandrel CLI entry point
+
+/**
+ * Convention-based subcommand dispatcher.
+ *
+ * Resolves `process.argv[2]` to `lib/cli/<name>.js` and dynamically
+ * imports it so the subcommand surface can grow without touching this
+ * file. Each subcommand module must export a default function `run(argv)`.
+ */
+
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function usage(badSub) {
+  if (badSub) {
+    process.stderr.write(
+      `mandrel: unknown subcommand '${badSub}'\n\nUsage: mandrel <subcommand> [args]\n`,
+    );
+  } else {
+    process.stderr.write('Usage: mandrel <subcommand> [args]\n');
+  }
+}
+
+const sub = process.argv[2];
+
+if (!sub) {
+  usage();
+  process.exit(1);
+}
+
+const subFile = path.resolve(__dirname, '..', 'lib', 'cli', `${sub}.js`);
+const subFileUrl = pathToFileURL(subFile).href;
+
+let mod;
+try {
+  mod = await import(subFileUrl);
+} catch (err) {
+  if (err.code === 'ERR_MODULE_NOT_FOUND' && err.message.includes(subFile)) {
+    usage(sub);
+    process.exit(1);
+  }
+  // Re-throw broken-module errors so they are visible rather than masked.
+  throw err;
+}
+
+if (typeof mod.default !== 'function') {
+  process.stderr.write(
+    `mandrel: subcommand '${sub}' does not export a default function\n`,
+  );
+  process.exit(1);
+}
+
+await mod.default(process.argv.slice(3));