mandrel 1.64.0 → 1.65.0

package/.agents/scripts/lib/test-tiers.js

@@ -26,6 +26,28 @@ export const INTEGRATION_INCLUDE = [
 
 const matchesIntegration = picomatch(INTEGRATION_INCLUDE, { dot: true });
 
+/**
+ * Repo-relative roots the tier walker scans for test files (names ending in
+ * `.test.js`).
+ *
+ * `tests` holds the framework's suite tree; `lib` holds the published CLI
+ * (under `lib/cli` and `lib/migrations`) whose tests are colocated in
+ * `__tests__` directories per the unit-tier convention in
+ * `rules/testing-standards.md`. Without `lib` here, both the quick /
+ * integration walk and the full-tier glob set miss the colocated CLI tests,
+ * leaving that coverage dark in `npm test`. The matching full-tier globs
+ * live in `FULL_TIER_GLOBS`.
+ */
+const TEST_WALK_ROOTS = ['tests', 'lib'];
+
+/**
+ * Glob targets for the `full` tier — one per walk root in `TEST_WALK_ROOTS`.
+ * The `tests` glob is a flat recursive sweep; the `lib` glob is scoped to
+ * `__tests__` subtrees so it only matches colocated tests, never the shipped
+ * source modules themselves.
+ */
+const FULL_TIER_GLOBS = ['tests/**/*.test.js', 'lib/**/__tests__/**/*.test.js'];
+
 /**
  * @param {string} dir
  * @param {string} prefix
@@ -56,13 +78,11 @@ function walkTestFiles(dir, prefix, fsLike) {
  * @returns {string[]}
  */
 export function listTestFilesForTier(tier, repoRoot, fsLike = fs) {
-  const all = walkTestFiles(
-    path.join(repoRoot, 'tests'),
-    'tests',
-    fsLike,
+  const all = TEST_WALK_ROOTS.flatMap((root) =>
+    walkTestFiles(path.join(repoRoot, root), root, fsLike),
   ).sort();
   if (tier === 'full') {
-    return ['tests/**/*.test.js'];
+    return [...FULL_TIER_GLOBS];
   }
   const integration = all.filter((file) => matchesIntegration(file));
   if (tier === 'integration') {

package/.agents/workflows/qa-assist.md

@@ -239,24 +239,61 @@ and optionally route or promote it — with the operator deciding each write.
    `regression-of-closed`. Stamp the `fingerprintFooter(sha)` marker into any
    Issue body so future runs dedup against it.
 
-3. **Optionally promote** the finding to a follow-up ticket via
+3. **Promote `file`-dispositioned findings through `/plan`** (never a raw
+   GitHub Issue) via
    [`promote-finding.js`](../scripts/lib/findings/promote-finding.js), which
-   clusters, routes, and files through the same ports — never hand-roll the
-   promotion:
+   clusters, sizes, routes, and files through the same ports `/qa-explore` and
+   `/audit-to-stories` consume — never hand-roll the promotion, the clustering,
+   or the sizing:
 
    ```js
    import { promoteFindings } from '../scripts/lib/findings/promote-finding.js';
-   const promotions = await promoteFindings(ledgerItems, { searchIssues, createStory });
+   const { promotions } = await promoteFindings(ledgerItems, {
+     searchIssues, // GitHub provider, open + closed
+     createStory, // tight cluster (≤2 surfaces): render seed → /plan --from-notes
+     createEpic, // broad cluster (>2 surfaces): render seed → /plan --idea
+   });
    ```
 
-4. **Gate:** any ledger append, ticket-filing, or label mutation is a write —
-   confirm **each one** with the operator before it happens. Redaction has
-   already run, so nothing unredacted reaches disk or GitHub.
+   - **Sizing is delegated, not decided in prose.** `promoteFindings` runs
+     `clusterLedgerItems` + `targetForCluster`: a cluster spanning **≤2**
+     distinct coverage surfaces routes to `createStory`; **>2** routes to
+     `createEpic`. Do not re-cluster, re-size, or re-dedup in the workflow —
+     [`route-finding.js`](../scripts/lib/findings/route-finding.js) /
+     [`promote-finding.js`](../scripts/lib/findings/promote-finding.js) are the
+     single implementation.
+   - **`createStory` (`/plan --from-notes`)** — render a **redacted**
+     `--from-notes` seed from the cluster (reuse the `/audit-to-stories`
+     Phase 5b notes shape; redaction already ran in Phase 2), **stamp the
+     cluster's `fingerprintFooter(sha)` verbatim into the seed body**, then
+     chain `/plan --from-notes <seed>`. The footer must survive into the issue
+     body the Story create path writes — it round-trips through
+     `story-plan.js --body <file> --dry-run` unchanged (asserted by the
+     deterministic round-trip test under `tests/`) so a later `routeFinding`
+     dedups the same finding instead of re-filing it.
+   - **`createEpic` (`/plan --idea`)** — carry the cluster's
+     `fingerprintFooter(sha)` into the `/plan --idea` seed, then chain
+     `/plan --idea <seed>`. **Known limitation (not solved here):**
+     per-child-Story fingerprint propagation through full Epic decomposition is
+     *not* guaranteed — the fingerprint is carried in the Epic seed only; the
+     child Stories `/plan` spawns from that seed are not individually
+     footer-stamped.
+   - **A `file` disposition never opens a raw GitHub Issue.** Every `file`
+     finding flows through `promoteFindings` → `/plan`; only `defer` (carry
+     forward as backlog) and `dismiss` (non-actionable) skip the `/plan`
+     handoff.
+
+4. **Gate:** any ledger append, seed write, `/plan` invocation, ticket-filing,
+   or label mutation is a write — confirm **each one** with the operator before
+   it happens. The plan→deliver hard stop is preserved: each `/plan` chain
+   pauses at its own HITL gates and never auto-delivers. Redaction has already
+   run, so nothing unredacted reaches disk or GitHub.
 
 After recording, summarize: the finding recorded, its coverage verdict and
 `missingTest`, any route/promotion decision
-(`new`/`update-existing`/`duplicate`/`regression-of-closed`), and the rolling
-backlog a resumed session will pick up.
+(`new`/`update-existing`/`duplicate`/`regression-of-closed`) and whether it was
+promoted to a Story (`/plan --from-notes`) or Epic (`/plan --idea`), and the
+rolling backlog a resumed session will pick up.
 
 ---
 
@@ -291,3 +328,24 @@ backlog a resumed session will pick up.
   promotion ([`promote-finding.js`](../scripts/lib/findings/promote-finding.js)),
   and session resolution ([`qa-session.js`](../scripts/lib/qa/qa-session.js))
   are deterministic — never re-derive them in prose.
+- **Promote through `/plan`, never a raw Issue.** A `file`-dispositioned
+  finding is promoted via `promoteFindings`, which chains into
+  [`/plan`](plan.md) (`--from-notes` for a tight cluster, `--idea` for a broad
+  one) — mirroring [`/audit-to-stories`](audit-to-stories.md). `/qa-assist`
+  never opens a bare GitHub Issue for a `file` finding. The cluster's
+  `fingerprintFooter(sha)` is stamped verbatim into the seed so a future
+  `routeFinding` dedups it.
+
+## See also
+
+- [`/plan`](plan.md) — the planning pipeline `/qa-assist` chains into when an
+  operator dispositions a finding `file` (`--from-notes` for a Story, `--idea`
+  for an Epic). The plan→deliver hard stop is preserved across the handoff.
+- [`/qa-explore`](qa-explore.md) — the agent-led sibling that drives a named
+  surface and triages through the same `/plan` handoff.
+- [`/audit-to-stories`](audit-to-stories.md) — the precedent for the
+  findings → `/plan` handoff and the shared fingerprint-footer dedup contract.
+- [`promote-finding.js`](../scripts/lib/findings/promote-finding.js) /
+  [`route-finding.js`](../scripts/lib/findings/route-finding.js) — the shared
+  cluster/size/promote and dedup/route/fingerprint-footer helpers. There is no
+  second clustering, sizing, or dedup implementation.

package/.agents/workflows/qa-explore.md

@@ -296,19 +296,62 @@ For each untriaged ledger item:
    `searchIssues` port to the GitHub provider (querying both open and closed
    Issues).
 
-3. **Decide the disposition** with the operator: `file` (promote to a
-   follow-up ticket with the classified labels + fingerprint footer), `defer`
-   (carry forward to a later session as backlog), or `dismiss` (non-actionable).
-   Record the chosen `disposition` back onto the ledger item.
+3. **Decide the disposition** with the operator: `file` (promote through
+   `/plan` — never a raw GitHub Issue), `defer` (carry forward to a later
+   session as backlog), or `dismiss` (non-actionable). Record the chosen
+   `disposition` back onto the ledger item.
 
-4. **Gate:** any ticket-filing or label mutation is a write — confirm each one
-   with the operator before it happens. Capture stayed read-only precisely so
-   that every state change lands here, deliberately and confirmed.
+4. **Promote the `file`-dispositioned findings through `/plan`** via
+   [`promote-finding.js`](../scripts/lib/findings/promote-finding.js) — the
+   same cluster/size/route/file path `/qa-assist` and `/audit-to-stories`
+   consume. Never hand-roll the clustering, sizing, or promotion in prose:
+
+   ```js
+   import { promoteFindings } from '../scripts/lib/findings/promote-finding.js';
+   const { promotions } = await promoteFindings(ledgerItems, {
+     searchIssues, // GitHub provider, open + closed
+     createStory, // tight cluster (≤2 surfaces): render seed → /plan --from-notes
+     createEpic, // broad cluster (>2 surfaces): render seed → /plan --idea
+   });
+   ```
+
+   - **Sizing is delegated, not decided in prose.** `promoteFindings` runs
+     `clusterLedgerItems` + `targetForCluster`: a cluster spanning **≤2**
+     distinct coverage surfaces routes to `createStory`; **>2** routes to
+     `createEpic`. The workflow introduces no new sizing, clustering, or dedup
+     logic — `route-finding.js` / `promote-finding.js` remain the single
+     implementation.
+   - **`createStory` (`/plan --from-notes`)** — render a **redacted**
+     `--from-notes` seed from the cluster (reuse the `/audit-to-stories`
+     Phase 5b notes shape; redaction already ran in Capture), **stamp the
+     cluster's `fingerprintFooter(sha)` verbatim into the seed body**, then
+     chain `/plan --from-notes <seed>`. The footer must survive into the issue
+     body the Story create path writes — it round-trips through
+     `story-plan.js --body <file> --dry-run` unchanged (asserted by the
+     deterministic round-trip test under `tests/`) so a later `routeFinding`
+     dedups the same finding instead of re-filing it.
+   - **`createEpic` (`/plan --idea`)** — carry the cluster's
+     `fingerprintFooter(sha)` into the `/plan --idea` seed, then chain
+     `/plan --idea <seed>`. **Known limitation (not solved here):**
+     per-child-Story fingerprint propagation through full Epic decomposition is
+     *not* guaranteed — the fingerprint is carried in the Epic seed only; the
+     child Stories `/plan` spawns from that seed are not individually
+     footer-stamped.
+   - **A `file` disposition never opens a raw GitHub Issue.** Every `file`
+     finding flows through `promoteFindings` → `/plan`; only `defer` and
+     `dismiss` skip the `/plan` handoff.
+
+5. **Gate:** any ticket-filing, seed write, `/plan` invocation, or label
+   mutation is a write — confirm each one with the operator before it happens.
+   Capture stayed read-only precisely so that every state change lands here,
+   deliberately and confirmed. The plan→deliver hard stop is preserved: each
+   `/plan` chain pauses at its own HITL gates and never auto-delivers.
 
 After triage, write the updated dispositions back to the ledger (still under
 `temp/qa/`), and summarize: items captured, the driving method used, classes,
-routes (`new`/`update-existing`/`duplicate`/`regression-of-closed`), filed
-tickets, and the deferred rolling backlog that a resumed session will pick up.
+routes (`new`/`update-existing`/`duplicate`/`regression-of-closed`), the
+Stories (`/plan --from-notes`) and Epics (`/plan --idea`) promoted, and the
+deferred rolling backlog that a resumed session will pick up.
 
 ---
 
@@ -343,8 +386,31 @@ tickets, and the deferred rolling backlog that a resumed session will pick up.
   ([`coverage-verdict.js`](../scripts/lib/qa/coverage-verdict.js)),
   missing-test ([`propose-missing-test.js`](../scripts/lib/qa/propose-missing-test.js)),
   classification ([`classify-finding.js`](../scripts/lib/findings/classify-finding.js)),
-  and dedup/route ([`route-finding.js`](../scripts/lib/findings/route-finding.js))
-  are deterministic — never re-derive them in prose.
+  dedup/route ([`route-finding.js`](../scripts/lib/findings/route-finding.js)),
+  and cluster/size/promote
+  ([`promote-finding.js`](../scripts/lib/findings/promote-finding.js)) are
+  deterministic — never re-derive them in prose.
+- **Promote through `/plan`, never a raw Issue.** A `file`-dispositioned
+  finding is promoted via `promoteFindings`, which chains into
+  [`/plan`](plan.md) (`--from-notes` for a tight cluster, `--idea` for a broad
+  one) — mirroring [`/audit-to-stories`](audit-to-stories.md). `/qa-explore`
+  never opens a bare GitHub Issue for a `file` finding. The cluster's
+  `fingerprintFooter(sha)` is stamped verbatim into the seed so a future
+  `routeFinding` dedups it.
 - **Resume safely.** A reused session appends and carries the un-triaged
   backlog forward via [`qa-session.js`](../scripts/lib/qa/qa-session.js); it
   never overwrites a prior ledger.
+
+## See also
+
+- [`/plan`](plan.md) — the planning pipeline `/qa-explore` Triage chains into
+  for a `file`-dispositioned finding (`--from-notes` for a Story, `--idea` for
+  an Epic). The plan→deliver hard stop is preserved across the handoff.
+- [`/qa-assist`](qa-assist.md) — the human-led sibling that enriches a single
+  operator observation and triages through the same `/plan` handoff.
+- [`/audit-to-stories`](audit-to-stories.md) — the precedent for the
+  findings → `/plan` handoff and the shared fingerprint-footer dedup contract.
+- [`promote-finding.js`](../scripts/lib/findings/promote-finding.js) /
+  [`route-finding.js`](../scripts/lib/findings/route-finding.js) — the shared
+  cluster/size/promote and dedup/route/fingerprint-footer helpers. There is no
+  second clustering, sizing, or dedup implementation.

package/docs/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.65.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.64.0...mandrel-v1.65.0) (2026-06-14)
+
+
+### Added
+
+* Epic [#4118](https://github.com/dsj1984/mandrel/issues/4118) ([#4127](https://github.com/dsj1984/mandrel/issues/4127)) ([d24a1f7](https://github.com/dsj1984/mandrel/commit/d24a1f7d3fc36d20015890fbadd7d08caa1d506b))
+* **qa:** route /qa-assist and /qa-explore triage into /plan (refs [#4115](https://github.com/dsj1984/mandrel/issues/4115)) ([#4116](https://github.com/dsj1984/mandrel/issues/4116)) ([de2a211](https://github.com/dsj1984/mandrel/commit/de2a211089104edd1cb76f77d668b0219a041c3e))
+
 ## [1.64.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.63.0...mandrel-v1.64.0) (2026-06-14)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "1.64.0",
+  "version": "1.65.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",
@@ -85,6 +85,7 @@
     "lint-staged": "^17.0.4",
     "markdownlint-cli2": "^0.18.1",
     "memfs": "^4.57.2",
+    "node-pty": "^1.0.0",
     "typescript": ">=5.0.0"
   },
   "dependencies": {