mandrel 1.59.0 → 1.61.0

package/lib/cli/version-helpers.js

@@ -0,0 +1,59 @@
+// lib/cli/version-helpers.js
+/**
+ * Shared semver-ish parse and compare helpers used by both
+ * `lib/cli/update.js` and `lib/cli/registry.js`.
+ *
+ * Both files previously defined local copies of `parseVersion` and
+ * `compareVersions`; this module is the single authoritative
+ * implementation (Story #4048 B3 — multiplied helpers).
+ *
+ * Builtins only — this module is imported from both the CLI surface
+ * (`lib/cli/`) and the doctor registry which runs before third-party
+ * packages are guaranteed to be present.
+ */
+
+/**
+ * Parse a dotted semver-ish string into a numeric tuple. Non-numeric or
+ * missing segments coerce to 0 so a partial version still compares sanely.
+ *
+ * @param {string} version
+ * @returns {[number, number, number]}
+ */
+export function parseVersion(version) {
+  const [major, minor, patch] = String(version).split('.');
+  return [
+    Number.parseInt(major, 10) || 0,
+    Number.parseInt(minor, 10) || 0,
+    Number.parseInt(patch, 10) || 0,
+  ];
+}
+
+/**
+ * Compare two version strings. Negative when `a < b`, zero when equal,
+ * positive when `a > b` (the standard `Array.sort` comparator contract).
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+export function compareVersions(a, b) {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+  for (let i = 0; i < 3; i += 1) {
+    if (pa[i] !== pb[i]) return pa[i] - pb[i];
+  }
+  return 0;
+}
+
+/**
+ * True when `target`'s major axis is strictly greater than `current`'s —
+ * the gated "crosses a major boundary" condition used by the update
+ * orchestrator.
+ *
+ * @param {string} current
+ * @param {string} target
+ * @returns {boolean}
+ */
+export function crossesMajor(current, target) {
+  return parseVersion(target)[0] > parseVersion(current)[0];
+}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "mandrel",
-  "version": "1.59.0",
+  "version": "1.61.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
-  "main": "index.js",
   "files": [
     ".agents/",
     "bin/",
-    "lib/"
+    "docs/CHANGELOG.md",
+    "lib/",
+    "!lib/**/__tests__"
   ],
   "publishConfig": {
     "access": "public",
@@ -83,7 +84,8 @@
     "knip": "^6.14.0",
     "lint-staged": "^17.0.4",
     "markdownlint-cli2": "^0.18.1",
-    "memfs": "^4.57.2"
+    "memfs": "^4.57.2",
+    "typescript": ">=5.0.0"
   },
   "dependencies": {
     "ajv": "^8.20.0",
@@ -92,7 +94,6 @@
     "minimatch": "^10.0.0",
     "picomatch": "^4.0.4",
     "string-argv": "^0.3.2",
-    "typescript": ">=5.0.0",
     "typhonjs-escomplex": "^0.1.0"
   },
   "peerDependencies": {
@@ -100,7 +101,7 @@
   },
   "peerDependenciesMeta": {
     "typescript": {
-      "optional": false
+      "optional": true
     }
   }
 }

package/.agents/scripts/lib/orchestration/reconciler.js

@@ -1,137 +0,0 @@
-/**
- * lib/orchestration/reconciler.js — Ticket Hierarchy Reconciliation
- */
-
-import { Logger } from '../Logger.js';
-import { AGENT_LABELS, TYPE_LABELS } from '../label-constants.js';
-import { concurrentMap } from '../util/concurrent-map.js';
-import { STATE_LABELS } from './ticketing.js';
-
-const AGENT_DONE_LABEL = STATE_LABELS.DONE;
-
-// Inlined parent-id parser. The reconciler only needs the direct parent
-// reference scraped from a ticket body's `parent: #N` trailer; pulling the
-// helper inline keeps reconciler.js self-contained for the 3-tier
-// hierarchy walk (Stories → Features).
-const PARENT_ID_PATTERN = /^parent:\s*#(\d+)/m;
-
-function parseParentIdFromBody(body) {
-  const match = (body ?? '').match(PARENT_ID_PATTERN);
-  return match ? Number.parseInt(match[1], 10) : null;
-}
-
-// Cap=4 — bounded parallelism for ticket-update fan-outs. Reconciliation
-// iterates an Epic-sized set of independent GitHub mutations; cap matches
-// the established pattern across the orchestration layer (wave-gate,
-// progress-reporter, sub-issue link reconcile) and stays well under the
-// secondary rate-limit ceiling observed for issue PATCHes.
-const RECONCILE_CONCURRENCY = 4;
-
-/**
- * Reconcile the ticket hierarchy bottom-up (Stories → Features).
- *
- * Walks every Story and Feature under the Epic; if all children of a
- * container are done, closes the container and applies `agent::done`.
- *
- * Epic auto-closure is intentionally excluded — Epics close only through
- * the formal `/epic-deliver` workflow.
- *
- * Per-ticket provider failures are logged and swallowed so a single bad
- * ticket cannot halt reconciliation across the rest of the graph.
- *
- * @param {import('../ITicketingProvider.js').ITicketingProvider} provider  Ticketing provider.
- * @param {number} _epicId                                               Epic id (reserved — currently unused; kept for call-site stability).
- * @param {object} _epic                                                 Epic ticket record (reserved — currently unused).
- * @param {object[]} allTickets                                          Every ticket under the Epic.
- * @param {boolean} dryRun                                               When true, mutate nothing.
- * @returns {Promise<void>}
- */
-export async function reconcileHierarchy(
-  provider,
-  _epicId,
-  _epic,
-  allTickets,
-  dryRun,
-) {
-  const ticketMap = new Map(allTickets.map((t) => [t.id, t]));
-
-  const childrenOf = new Map();
-  for (const ticket of allTickets) {
-    const parentId = parseParentIdFromBody(ticket.body);
-    if (parentId != null) {
-      if (!childrenOf.has(parentId)) childrenOf.set(parentId, []);
-      childrenOf.get(parentId).push(ticket.id);
-    }
-  }
-
-  function isDone(ticketId) {
-    const t = ticketMap.get(ticketId);
-    if (!t) return false;
-    return (
-      t.state === 'closed' ||
-      (t.labelSet ?? new Set(t.labels)).has(AGENT_DONE_LABEL)
-    );
-  }
-
-  function shouldClose(id) {
-    const ticket = ticketMap.get(id);
-    if (!ticket || ticket.state === 'closed') return null;
-    const children = childrenOf.get(id) ?? [];
-    if (children.length === 0) return null;
-    if (!children.every((cid) => isDone(cid))) return null;
-    return ticket;
-  }
-
-  async function applyClose(id, typeName, ticket) {
-    try {
-      await provider.updateTicket(id, {
-        labels: {
-          add: [AGENT_DONE_LABEL],
-          remove: [AGENT_LABELS.READY, AGENT_LABELS.EXECUTING],
-        },
-        state: 'closed',
-        state_reason: 'completed',
-      });
-      ticket.state = 'closed';
-      Logger.info(`✅ ${typeName} #${id} closed and marked agent::done.`);
-    } catch (err) {
-      Logger.warn(`Failed to close ${typeName} #${id}: ${err.message}`);
-    }
-  }
-
-  async function maybeClose(id, typeName) {
-    const ticket = shouldClose(id);
-    if (!ticket) return;
-    Logger.info(
-      `All children of ${typeName} #${id} "${ticket.title}" are done. Closing...`,
-    );
-    if (dryRun) {
-      Logger.info(
-        `[DRY-RUN] Would close ${typeName} #${id} and set agent::done.`,
-      );
-      ticket.state = 'closed';
-      return;
-    }
-    await applyClose(id, typeName, ticket);
-  }
-
-  const storyIds = allTickets
-    .filter((t) => (t.labelSet ?? new Set(t.labels)).has(TYPE_LABELS.STORY))
-    .map((t) => t.id);
-  const featureIds = allTickets
-    .filter((t) => (t.labelSet ?? new Set(t.labels)).has(TYPE_LABELS.FEATURE))
-    .map((t) => t.id);
-
-  // cap=4 — Stories are container leaves of this reconcile (their children
-  // are Tasks already settled by reconcileClosedTasks); independent close
-  // mutations can fan out without ordering. Features stay sequential because
-  // a Feature may parent another Feature, and bottom-up close depends on
-  // child-Feature state already being mutated in the same pass.
-  await concurrentMap(storyIds, (id) => maybeClose(id, 'Story'), {
-    concurrency: RECONCILE_CONCURRENCY,
-  });
-  for (const id of featureIds) await maybeClose(id, 'Feature');
-
-  // EXCLUSION: Epic auto-closure removed.
-  // The Epic ticket now stays open until the formal /epic-deliver workflow is executed.
-}

package/.agents/workflows/onboard.md

@@ -1,208 +0,0 @@
----
-description: >-
-  Guided first-run onboarding for a freshly installed Mandrel. Detects the
-  consumer stack, offers to scaffold any missing docsContextFiles, runs
-  `mandrel doctor` as a readiness gate, and hands off to a started /epic-plan.
-  The whole path is designed to take about 15 minutes from a clean checkout to
-  a planned Epic.
----
-
-# /onboard
-
-## Role
-
-Onboarding guide. You walk a first-time operator from a freshly installed
-Mandrel to their first planned Epic, composing the building blocks shipped by
-the guided-onboard Feature (#3514): stack detection, docs scaffolding, the
-`mandrel doctor` readiness check, and a started `/epic-plan` handoff.
-
-## Overview
-
-`/onboard` is the **guided first-successful-run path**. It sequences four
-phases that each lean on an already-shipped, independently tested building
-block, then hands the operator off to planning:
-
-```text
-/onboard
-  → Phase 1 — Detect stack          (lib/onboard/detect-stack.js#detectStack)
-  → Phase 2 — Offer docs scaffolding (lib/onboard/scaffold-docs.js#scaffoldDocs)
-  → Phase 3 — Readiness gate         (mandrel doctor → lib/cli/doctor.js)
-  → Phase 4 — Handoff to /epic-plan  (started, not auto-run)
-```
-
-Each phase is **advisory and resumable**: re-running `/onboard` on an
-already-onboarded project re-detects, re-checks, and offers the same handoff
-without duplicating any scaffolding (the scaffolder only writes files that are
-genuinely missing, and `mandrel doctor` is read-only).
-
-### When to use `/onboard`
-
-| Scenario | Command |
-| --- | --- |
-| First run after installing Mandrel into a project | `/onboard` |
-| Plan a new Epic once onboarded | `/epic-plan <epicId>` or `/epic-plan --idea "<seed>"` |
-| Deliver Epic-attached Stories | `/epic-deliver <epicId>` |
-
-## Prerequisites
-
-1. Mandrel installed and bootstrapped into the project. The zero-to-installed
-   path is `npx mandrel init`, which installs the `mandrel`
-   package (when absent), runs `mandrel sync` to materialize the `.agents/`
-   bundle, and then — on the **configure now** prompt option — execs
-   `.agents/scripts/bootstrap.js` to provision the project (labels,
-   board, `.agentrc.json` seed). `/onboard` runs **after** that bootstrap
-   completes — it does not invoke `bootstrap.js` itself, so the coupling is
-   indirect: bootstrap owns first-time provisioning, `/onboard` owns the
-   guided first-successful-run. By the time you reach `/onboard`, the
-   `.agents/` bundle is present and `mandrel` resolves on the `PATH`.
-2. `GITHUB_TOKEN` available in the project's `.env` (Phase 3 checks this; the
-   token value is never echoed).
-
-## The ~15-minute first-successful-run path
-
-`/onboard` is tuned so a brand-new operator can go from a clean checkout to a
-planned Epic in roughly **15 minutes**. The budget breaks down as:
-
-| Step | Phase | Rough budget |
-| --- | --- | --- |
-| Detect the stack and confirm the report | Phase 1 | ~1 min |
-| Review the missing-docs offer and accept the scaffold | Phase 2 | ~3 min |
-| Run `mandrel doctor` and clear any ✘ checks | Phase 3 | ~5 min |
-| Start `/epic-plan` and describe the first Epic idea | Phase 4 | ~6 min |
-
-If any single phase blows its budget — most often a Phase 3 remedy such as
-authenticating `gh` or installing runtime deps — clear that one check and
-re-run `/onboard`; the earlier phases are cheap and idempotent, so re-running
-costs seconds.
-
-### Sample-repo pointer
-
-If you do not have a project to onboard yet and just want to see the path
-end-to-end, point `/onboard` at the **stack-detection sample-repo fixture**
-that ships with the framework. `detectStack` is fixture-driven by design (its
-filesystem facade reads a real directory), and the unit suite exercises it
-against an on-disk sample repo — see
-[`tests/onboard/detect-stack.test.js`](../../tests/onboard/detect-stack.test.js),
-which builds a sample repo with a lockfile, a `package.json`, and source files
-and asserts the detected package manager, test runner, and primary language.
-Use that fixture (or any small throwaway repo with a `package.json` and a few
-source files) as the target for a dry first run before onboarding a real
-project.
-
-## Phase 1 — Detect the stack
-
-Inspect the consumer repository root and report what Mandrel inferred before
-touching anything. Use the detection helper shipped by Story #3520:
-
-```bash
-node -e "import('./.agents/scripts/lib/onboard/detect-stack.js').then(m => console.log(JSON.stringify(m.detectStack(process.cwd()), null, 2)))"
-```
-
-`detectStack(root)` returns `{ packageManager, testRunner, primaryLanguage }`,
-each inferred from on-disk signals (lockfiles, `package.json`, source-file
-extensions) and `null` when no signal is found. Relay the report to the
-operator so they can confirm Mandrel understood the project. Detection is
-**read-only** — it never writes to disk — so a wrong guess is harmless and the
-operator can simply correct course in their `.agentrc.json` later.
-
-## Phase 2 — Offer to scaffold missing `docsContextFiles`
-
-Mandrel agents perform a **mandatory read** of every file listed in
-`project.docsContextFiles` before each task; a missing entry degrades every
-downstream run. Detect which are absent and offer to scaffold stubs, using the
-helper shipped by Story #3519:
-
-1. **Preview (no writes).** Detect the missing set first:
-
-   ```bash
-   node -e "import('./.agents/scripts/lib/onboard/scaffold-docs.js').then(m => console.log(JSON.stringify(m.scaffoldDocs({ write: false }), null, 2)))"
-   ```
-
-   `scaffoldDocs({ write: false })` returns `{ docsRoot, docsContextFiles,
-   missing, present, created }` without creating any files.
-
-2. **Offer.** Show the operator the `missing` list and ask whether to scaffold
-   stubs. If the list is empty, report "all docsContextFiles present" and skip
-   to Phase 3.
-
-3. **Scaffold (on acceptance).** When the operator accepts, write the stubs:
-
-   ```bash
-   node -e "import('./.agents/scripts/lib/onboard/scaffold-docs.js').then(m => console.log(JSON.stringify(m.scaffoldDocs({ write: true }), null, 2)))"
-   ```
-
-   Each missing file is seeded from a dedicated template under
-   `.agents/templates/docs/<name>` when one ships, otherwise from a generic
-   placeholder stub. The operator replaces the stub content with real docs
-   later; the point of the scaffold is that the mandatory-read never resolves
-   to a missing file.
-
-This phase is **idempotent**: the scaffolder only writes files that are
-actually absent, so re-running `/onboard` after a partial scaffold creates
-only the still-missing stubs.
-
-## Phase 3 — Readiness gate (`mandrel doctor`)
-
-Run the doctor as a **readiness gate** before handing off to planning:
-
-```bash
-mandrel doctor
-```
-
-`mandrel doctor` (see [`lib/cli/doctor.js`](../../lib/cli/doctor.js)) runs
-every check in the registry in order — `node-version`, `git-available`,
-`gh-available`, `github-token`, `gh-auth`, `commands-in-sync`, `runtime-deps`,
-`agents-materialized`, `agents-drift`, `version-current` — and prints a
-`✔`/`✘` line per check. Every failing check prints a `→ <remedy>` line, and
-the command exits:
-
-- **0** with `✅  Ready (N/N checks passed)` — proceed to Phase 4.
-- **non-zero** with `❌  Not ready (M/N checks failed)` — **stop**. Work
-  through the `→` remedies (e.g. authenticate `gh`, set `GITHUB_TOKEN`,
-  install runtime deps), then re-run `mandrel doctor` until it is green.
-
-Do **not** hand off to `/epic-plan` while the doctor is red — planning needs a
-working `gh` / `GITHUB_TOKEN` and a materialized `.agents/` bundle, exactly
-what the gate verifies. The `github-token` check never echoes the token value
-(security baseline § Secrets Management).
-
-## Phase 4 — Handoff to a started `/epic-plan`
-
-With a green readiness gate, hand the operator off to planning. `/onboard`
-**starts** the handoff — it surfaces the entry point and the idea-refinement
-path — but does **not** auto-run `/epic-plan`, because Epic planning authors
-GitHub artifacts and must stay under explicit operator control.
-
-Present the operator with the two `/epic-plan` entry shapes:
-
-- **From an idea** (no Epic exists yet):
-
-  ```text
-  /epic-plan --idea "<one-line description of the first thing to build>"
-  ```
-
-  This enters [`/epic-plan`](epic-plan.md) at Phase 1 (Idea Refinement),
-  which refines the seed into a PRD, Tech Spec, and a decomposed
-  Epic → Feature → Story backlog.
-
-- **From an existing Epic** (a `type::epic` issue already exists):
-
-  ```text
-  /epic-plan <epicId>
-  ```
-
-Stop here and let the operator invoke `/epic-plan` themselves. Once they have
-a planned Epic, the natural next step is `/epic-deliver <epicId>` to execute
-it — but that is beyond the onboarding path.
-
-## Constraints
-
-- **Read-before-write.** Phases 1 and 3 are read-only; Phase 2 writes only
-  files that are genuinely missing and only on explicit operator acceptance.
-- **Do not auto-run `/epic-plan`.** Phase 4 starts the handoff; the operator
-  invokes planning. Planning authors GitHub artifacts and stays under human
-  control.
-- **Never echo secrets.** The `github-token` check and any token-related
-  remedy must not print the token value.
-- **Stop on a red doctor.** A non-zero `mandrel doctor` exit blocks the
-  handoff until the operator clears the failing checks.