mandrel 1.74.0 → 1.76.0

package/.agents/instructions.md

@@ -76,6 +76,15 @@ environment variables that override project defaults. The config resolver
 deep-merges `.agentrc.local.json` over `.agentrc.json` (local wins; absent
 local file is a no-op). Do not modify these local files unless requested.
 
+**Durable slash commands.** Any `.md` file placed at
+`.agents/local/workflows/<name>.md` is automatically projected into
+`.claude/commands/<name>.md` by `sync-claude-commands.js`, making it
+invocable as `/<name>`. Because the entire `.agents/local/` subtree is
+exempt from `mandrel sync`'s prune pass, these commands survive
+`npm install`, `mandrel sync`, and `mandrel update` with no manual
+re-sync. Core payload commands of the same basename always win (the
+local copy is ignored with a `shadowed` warning).
+
 ### F. Modular Global Rules
 
 Before writing code or documentation, verify if any domain-agnostic rules

package/.agents/scripts/lib/orchestration/epic-plan-lease-guard.js

@@ -341,11 +341,20 @@ export async function assertNoOpenPlanChildren({
   const openChildren = (children ?? []).filter((t) => {
     const labels = Array.isArray(t.labels) ? t.labels : [];
     const isOpen = t.state === undefined || t.state === 'open';
-    // Any open typed plan ticket counts — `type::story` plus pre-v4
-    // `type::feature` leftovers. The prefix check is legacy-data
-    // detection, not compat support: the guard only refuses, it never
-    // processes the legacy tier. Context tickets (`context::*`) are
-    // untouched.
+    // Context spec tickets (PRD / Tech Spec / Acceptance Spec) carry a
+    // `context::*` label and — since the `createTicket` factory injects
+    // `type::story` by default — also `type::story`. They are reference
+    // artifacts that stay open across delivery, NOT plan children, so they
+    // MUST be excluded here: counting them would make every first decompose
+    // (where the three context tickets are the only open children) refuse.
+    const isContext = labels.some(
+      (l) => typeof l === 'string' && l.startsWith('context::'),
+    );
+    if (isContext) return false;
+    // Any remaining open typed plan ticket counts — `type::story` plus pre-v4
+    // `type::feature` leftovers. The prefix check is legacy-data detection,
+    // not compat support: the guard only refuses, it never processes the
+    // legacy tier.
     return (
       isOpen &&
       labels.some((l) => typeof l === 'string' && l.startsWith('type::'))

package/.agents/scripts/lib/orchestration/epic-runner/phases/build-wave-dag.js

@@ -35,6 +35,17 @@ export async function discoverOpenStories({ epicId, provider }) {
   for (const t of descendants) {
     const labels = t.labels ?? [];
     if (!labels.includes(TYPE_LABELS.STORY)) continue;
+    // Defense-in-depth: never enumerate a context spec ticket (PRD / Tech
+    // Spec / Acceptance Spec) as a deliverable Story even if it carries
+    // `type::story`. The `createTicket` factory no longer stamps context
+    // tickets that way, but a context ticket mislabelled out-of-band must
+    // still never reach a delivery wave (it has no `story-<id>` branch or
+    // acceptance contract to deliver against).
+    if (
+      labels.some((l) => typeof l === 'string' && l.startsWith('context::'))
+    ) {
+      continue;
+    }
     const rawState = t.state ?? 'open';
     const norm = typeof rawState === 'string' ? rawState.toLowerCase() : 'open';
     if (norm !== 'open') continue;

package/.agents/scripts/providers/github/tickets.js

@@ -320,13 +320,26 @@ export class TicketGateway {
     });
 
     // Mirror the Epic create path (issues.js:160 → `labels: TYPE_LABELS.EPIC`):
-    // always inject TYPE_LABELS.STORY so a spec that omits the labels array
-    // cannot produce an unlabeled, undispatchable Story. Dedupe to avoid
-    // duplicates when the caller already carries the label.
+    // inject TYPE_LABELS.STORY so a spec that omits the labels array cannot
+    // produce an unlabeled, undispatchable Story. Dedupe to avoid duplicates
+    // when the caller already carries the label.
+    //
+    // Context spec tickets (PRD / Tech Spec / Acceptance Spec) are a distinct
+    // ticket class created through this same factory carrying a `context::*`
+    // label (and no `type::story`). They MUST NOT be stamped `type::story`:
+    // doing so makes every `type::story`-counting consumer — the decompose
+    // open-children guard (`assertNoOpenPlanChildren`), the delivery wave
+    // builder (`discoverOpenStories`), the plan healthcheck — mis-classify
+    // them as deliverable Stories. Skip the injection when the caller's labels
+    // already classify the ticket as context.
     const callerLabels = ticketData.labels ?? [];
-    const labels = callerLabels.includes(TYPE_LABELS.STORY)
-      ? callerLabels
-      : [TYPE_LABELS.STORY, ...callerLabels];
+    const isContextTicket = callerLabels.some(
+      (l) => typeof l === 'string' && l.startsWith('context::'),
+    );
+    const labels =
+      isContextTicket || callerLabels.includes(TYPE_LABELS.STORY)
+        ? callerLabels
+        : [TYPE_LABELS.STORY, ...callerLabels];
     const result = await this._gh.api({
       method: 'POST',
       endpoint: `/repos/${this.owner}/${this.repo}/issues`,

package/.agents/scripts/sync-claude-commands.js

@@ -1,10 +1,18 @@
 #!/usr/bin/env node
 
 /**
- * Projects .agents/workflows/ into a flat `.claude/commands/` tree so Claude
- * Code exposes each workflow as a bare `/<name>` slash command. The workflows
- * directory remains the single source of truth; this script is the only writer
- * of `.claude/commands/`.
+ * Projects .agents/workflows/ (and .agents/local/workflows/ when present) into
+ * a flat `.claude/commands/` tree so Claude Code exposes each workflow as a
+ * bare `/<name>` slash command. Two source directories are enumerated in order:
+ *
+ *   1. PAYLOAD_SRC  — `.agents/workflows/`  (the installed Mandrel payload)
+ *   2. LOCAL_SRC    — `.agents/local/workflows/`  (consumer-authored, prune-exempt)
+ *
+ * The payload directory wins on basename collision: if both sources supply
+ * `foo.md`, the payload copy is projected and the local copy is ignored with a
+ * `shadowed` warning. Because both sources are unioned into `sourceSet`, local
+ * commands are also protected from the orphan-reap — they survive
+ * `npm install`, `mandrel sync`, and `mandrel update` with no manual re-sync.
  *
  * Flat projection (reverts the #3576 plugin cutover): the plugin command tree
  * (`.claude/plugins/mandrel/`) and the repo-local marketplace
@@ -48,9 +56,14 @@ const PROJECT_ROOT = process.cwd();
 // fixture workflow tree in isolation (regression test for the Epic #1185
 // frontmatter pass-through contract). When unset, behaviour is unchanged
 // — the script defaults to the real workflows / commands directories.
-const SRC_DIR =
+// SYNC_CLAUDE_COMMANDS_SRC overrides the PAYLOAD source only; the LOCAL_SRC
+// is always derived from the project root so fixture tests can isolate the
+// payload source while still allowing LOCAL_SRC to be present if needed.
+const PAYLOAD_SRC =
   process.env.SYNC_CLAUDE_COMMANDS_SRC ??
   path.join(PROJECT_ROOT, '.agents', 'workflows');
+const LOCAL_SRC = path.join(PROJECT_ROOT, '.agents', 'local', 'workflows');
+
 const DEST_DIR =
   process.env.SYNC_CLAUDE_COMMANDS_DEST ??
   path.join(PROJECT_ROOT, '.claude', 'commands');
@@ -58,6 +71,23 @@ const DEST_DIR =
 export const HEADER =
   '<!-- AUTO-GENERATED — do not edit. Source of truth: .agents/workflows/ -->\n<!-- Re-run: npm run sync:commands -->\n\n';
 
+export const LOCAL_HEADER =
+  '<!-- AUTO-GENERATED from .agents/local/ — do not edit. Source of truth: .agents/local/workflows/ -->\n<!-- Re-run: npm run sync:commands -->\n\n';
+
+/**
+ * Return true when the given directory path exists and is accessible.
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function dirExists(dir) {
+  try {
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Reap the generated plugin projection (the #3576 surface) so the namespaced
  * `/mandrel:<name>` commands and the repo-local marketplace stop shadowing the
@@ -102,12 +132,33 @@ fs.mkdirSync(DEST_DIR, { recursive: true });
 const isTopLevelWorkflow = (entry) =>
   entry.isFile() && entry.name.endsWith('.md');
 
+// Enumerate sources: payload first, then local (if it exists). Payload wins
+// on basename collision — a consumer must not silently shadow a core command.
+const SRC_DIRS = [PAYLOAD_SRC, LOCAL_SRC].filter(dirExists);
+
+/** @type {Array<{dir: string, name: string}>} */
+const entries = SRC_DIRS.flatMap((dir) =>
+  fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter(isTopLevelWorkflow)
+    .map((e) => ({ dir, name: e.name })),
+);
+
+// Collision policy: payload wins, warn on a shadowed local file.
+const byName = new Map();
+for (const e of entries) {
+  if (byName.has(e.name)) {
+    Logger.warn(`  shadowed  ${e.name} (local copy ignored; payload wins)`);
+    continue;
+  }
+  byName.set(e.name, e);
+}
+
+// sourceSet drives the orphan-reap: any existing command not in this set is
+// removed. Local-projected commands are included, so they survive the reap.
+const sourceSet = new Set(byName.keys());
+
 const existing = fs.readdirSync(DEST_DIR).filter((f) => f.endsWith('.md'));
-const sources = fs
-  .readdirSync(SRC_DIR, { withFileTypes: true })
-  .filter(isTopLevelWorkflow)
-  .map((entry) => entry.name);
-const sourceSet = new Set(sources);
 
 for (const file of existing) {
   if (!sourceSet.has(file)) {
@@ -118,18 +169,18 @@ for (const file of existing) {
 
 // Copy each workflow, injecting the auto-generated header after any leading
 // frontmatter (so the `---` block stays on line 1 and Claude Code parses the
-// command description). Parallelised so the ~30-file sync doesn't serialise on
-// per-file fs latency (noticeable on Windows where each syscall pays a larger
-// fixed cost).
+// command description). Use a distinct header comment for local-origin files.
+// Parallelised so the ~30-file sync doesn't serialise on per-file fs latency
+// (noticeable on Windows where each syscall pays a larger fixed cost).
 let synced = 0;
+const resolvedEntries = Array.from(byName.values());
 await Promise.all(
-  sources.map(async (file) => {
-    const content = await fs.promises.readFile(
-      path.join(SRC_DIR, file),
-      'utf8',
-    );
-    const dest = path.join(DEST_DIR, file);
-    const target = applyHeader(content, HEADER);
+  resolvedEntries.map(async ({ dir, name }) => {
+    const isLocal = dir === LOCAL_SRC;
+    const header = isLocal ? LOCAL_HEADER : HEADER;
+    const content = await fs.promises.readFile(path.join(dir, name), 'utf8');
+    const dest = path.join(DEST_DIR, name);
+    const target = applyHeader(content, header);
 
     // Skip write if content is already identical (avoid noisy git diffs).
     // Use try/catch over existsSync+readFile so we only pay one syscall.
@@ -142,10 +193,10 @@ await Promise.all(
 
     await fs.promises.writeFile(dest, target, 'utf8');
     synced++;
-    Logger.info(`  synced   ${file}`);
+    Logger.info(`  synced   ${name}`);
   }),
 );
 
 Logger.info(
-  `\n✔ ${synced} file(s) synced, ${sources.length} total commands in .claude/commands/`,
+  `\n✔ ${synced} file(s) synced, ${sourceSet.size} total commands in .claude/commands/`,
 );

package/docs/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.76.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.75.0...mandrel-v1.76.0) (2026-06-20)
+
+
+### Fixed
+
+* **plan:** stop stamping context spec tickets as type::story so first decompose isn't blocked ([#4246](https://github.com/dsj1984/mandrel/issues/4246)) ([#4247](https://github.com/dsj1984/mandrel/issues/4247)) ([564cfb8](https://github.com/dsj1984/mandrel/commit/564cfb81876f87ad5f61f3c670efb7cfc2c95540))
+
+## [1.75.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.74.0...mandrel-v1.75.0) (2026-06-19)
+
+
+### Added
+
+* **sync:** project .agents/local/workflows/ as prune-exempt slash commands ([#4244](https://github.com/dsj1984/mandrel/issues/4244)) ([9470f6a](https://github.com/dsj1984/mandrel/commit/9470f6a567b656eee508c2ef10910454a084ee43))
+
 ## [1.74.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.73.0...mandrel-v1.74.0) (2026-06-19)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "1.74.0",
+  "version": "1.76.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",