mandrel 1.94.0 → 2.1.0

package/.agents/workflows/audit-documentation.md

@@ -16,7 +16,7 @@ renamed, scripts move, described workflows change shape, and
 version/topology claims go stale. The deterministic gates
 (`check-doc-links.js`, `check-lifecycle-doc-drift.js`,
 `validate-docs-freshness.js`) catch broken links, drift against generators,
-and Epic-scoped freshness — they cannot tell whether the prose still
+and per-delivery freshness — they cannot tell whether the prose still
 describes how the code actually behaves. That semantic verification is this
 lens's job.
 
@@ -47,10 +47,10 @@ generator", not "edit the doc". Auto-generated changelog files
 (`docs/CHANGELOG.md`, release-please-owned) are likewise excluded from
 semantic review beyond Step 1's deterministic checks.
 
-## Scope (Epic mode)
+## Scope (Story / plan-run mode)
 
-When this lens is invoked from `/deliver` Phase 4 (epic-audit), the
-following block is populated with the Epic's change-set file list.
+When this lens is invoked from `/deliver` close lenses (or a plan-run audit), the
+following block is populated with the Story (or plan-run) change-set file list.
 Otherwise — for any manual `/audit-<dimension>` invocation — the block
 renders the literal substitution token and you MUST treat it as **no
 scope filter — run the lens codebase-wide** exactly as you would have
@@ -71,8 +71,7 @@ before this section existed.
 ## Execution strategy (dual-path)
 
 This lens runs along one of two execution paths. Both emit the **identical**
-report contract (Step 3); downstream consumers (`/deliver` Phase 4
-epic-audit, `audit-to-stories`) are agnostic to which path produced it.
+report contract (Step 3); downstream consumers (`audit-to-stories`) are agnostic to which path produced it.
 
 - **Orchestrated (dynamic-workflow) path.** When Claude Code's
   [dynamic workflows](https://code.claude.com/docs/en/workflows) are
@@ -174,7 +173,7 @@ and check each one:
    renames).
 3. **Workflow & Contract Descriptions:** Described workflows, label
    taxonomies (`agent::*`, `type::*`, `meta::*`), branch shapes
-   (`story-<id>`, `epic/<id>`), and artifact contracts match how the
+   (`story-<id>`), and artifact contracts match how the
    current scripts actually behave — read the implementation when the
    prose makes a behavioural claim.
 4. **Version & Topology Claims:** Version numbers, package names, release
@@ -279,8 +278,8 @@ match the code), the deterministic-gate verdicts, and primary drift themes.]
 ## Periodic full-scope sweep
 
 Context Economy findings accrete slowly — a doc that is lean today grows a
-bloated tail over many Epics, and no single change-set-scoped `/deliver`
-Phase 4 run sees the whole picture. Run this lens **full-scope** on a
+bloated tail over many deliveries, and no single change-set-scoped `/deliver`
+run sees the whole picture. Run this lens **full-scope** on a
 recurring cadence so the drift is caught before it compounds:
 
 - **Scheduled invocation** — `/schedule` running `/audit-documentation`
@@ -293,7 +292,7 @@ recurring cadence so the drift is caught before it compounds:
 Route the resulting `audit-documentation-results.md` through
 [`/audit-to-stories`](audit-to-stories.md), which groups the findings,
 deduplicates them against existing Issues by fingerprint, and opens
-remediation Stories (or chains into `/plan --idea`) so the Context-Economy
+remediation Stories (or chains into `/plan --seed`) so the Context-Economy
 findings land as actionable, tracked work rather than a report nobody reads.
 
 ## Constraint

package/.agents/workflows/audit-lighthouse.md

@@ -5,6 +5,14 @@ command: false
 
 # Lighthouse Audit & Analysis
 
+## Applicability
+
+**Web targets only.** Registered with `target: "web"` in
+[`audit-rules.json`](../schemas/audit-rules.json): the selector skips this lens
+on a project with no web surface, since there is no page to launch Lighthouse
+against. See the `target` key's schema description for how applicability is
+probed from the consumer's checkout.
+
 ## Role
 
 Senior Web Performance & Quality Engineer. You operate Lighthouse end-to-end:
@@ -30,10 +38,10 @@ inflate Performance scores misleadingly.
 (check `viewport` meta, responsive CSS, or operator instruction), run
 **Mobile** instead and note the choice in the report.
 
-## Scope (Epic mode)
+## Scope (Story / plan-run mode)
 
-When this lens is invoked from `/deliver` Phase 4 (epic-audit), the
-following block is populated with the Epic's change-set file list.
+When this lens is invoked from `/deliver` close lenses (or a plan-run audit), the
+following block is populated with the Story (or plan-run) change-set file list.
 Otherwise — for any manual `/audit-<dimension>` invocation — the block
 renders the literal substitution token and you MUST treat it as **no
 scope filter — run the lens codebase-wide** exactly as you would have

package/.agents/workflows/audit-navigability.md

@@ -8,6 +8,16 @@ description: >-
 
 # Navigability Audit
 
+## Applicability
+
+**Web targets only.** Registered with `target: "web"` in
+[`audit-rules.json`](../schemas/audit-rules.json). This is consistent with the
+lens's own no-op contract below rather than an additional constraint: the
+web-surface probe's first signal _is_ configured `routeGlobs`, so a consumer
+that has configured this lens's route-tree SSOT always clears the gate. The
+gate only bites where the lens had no route data to read anyway — it converts a
+silent no-op run into no run at all.
+
 ## Role
 
 Information-Architecture Reviewer & Frontend Navigation Auditor
@@ -61,8 +71,9 @@ Read the consumer's navigability config (resolved from `.agentrc.json`):
 
 - `delivery.quality.navigability.routeGlobs` — globs identifying the
   route-adding files / route tree (e.g. `pages/**`, `app/**/route.ts`). Drives
-  both the route-tree enumeration here and the route-added routing in
-  [`epic-audit-prepare.js`](../scripts/epic-audit-prepare.js).
+  both the route-tree enumeration here and the plan-persist draft
+  reachability gate
+  ([`plan-reachability.js`](../scripts/lib/orchestration/plan-reachability.js)).
 - `delivery.quality.navigability.navRegistry` — path(s) to the consumer's
   nav-registry SSOT this lens reads.
 

package/.agents/workflows/audit-performance.md

@@ -1,5 +1,5 @@
 ---
-description: Audit hot paths, algorithmic complexity, and I/O bottlenecks in the tooling surface (`epic-close`, dispatcher, gates); propose remediations.
+description: Audit hot paths, algorithmic complexity, and I/O bottlenecks in the tooling surface (`single-story-close`, dispatcher, gates); propose remediations.
 ---
 
 # Performance & Bottleneck Audit
@@ -14,10 +14,10 @@ Analyze the application for performance regressions, bottlenecks, and efficiency
 gaps. Your goal is to identify why a system is slow or where it might fail under
 load.
 
-## Scope (Epic mode)
+## Scope (Story / plan-run mode)
 
-When this lens is invoked from `/deliver` Phase 4 (epic-audit), the
-following block is populated with the Epic's change-set file list.
+When this lens is invoked from `/deliver` close lenses (or a plan-run audit), the
+following block is populated with the Story (or plan-run) change-set file list.
 Otherwise — for any manual `/audit-<dimension>` invocation — the block
 renders the literal substitution token and you MUST treat it as **no
 scope filter — run the lens codebase-wide** exactly as you would have
@@ -38,8 +38,7 @@ before this section existed.
 ## Execution strategy (dual-path)
 
 This lens runs along one of two execution paths. Both emit the **identical**
-report contract (Step 3); downstream consumers (`/deliver` Phase 4
-epic-audit, `audit-to-stories`) are agnostic to which path produced it.
+report contract (Step 3); downstream consumers (`audit-to-stories`) are agnostic to which path produced it.
 
 - **Orchestrated (dynamic-workflow) path.** When Claude Code's
   [dynamic workflows](https://code.claude.com/docs/en/workflows) are

package/.agents/workflows/audit-privacy.md

@@ -15,10 +15,10 @@ Personally Identifiable Information (PII) and ensure compliance with data
 protection standards (GDPR, CCPA). Your goal is to find accidental logging,
 insecure storage, or unnecessary collection of sensitive data.
 
-## Scope (Epic mode)
+## Scope (Story / plan-run mode)
 
-When this lens is invoked from `/deliver` Phase 4 (epic-audit), the
-following block is populated with the Epic's change-set file list.
+When this lens is invoked from `/deliver` close lenses (or a plan-run audit), the
+following block is populated with the Story (or plan-run) change-set file list.
 Otherwise — for any manual `/audit-<dimension>` invocation — the block
 renders the literal substitution token and you MUST treat it as **no
 scope filter — run the lens codebase-wide** exactly as you would have

package/.agents/workflows/audit-quality.md

@@ -15,7 +15,7 @@ infrastructure, test coverage, and overall quality assurance practices. Your
 goal is to identify testing gaps, flaky tests, inefficient mocking strategies,
 and opportunities to improve test execution speed and reliability without making
 any immediate changes. Additionally, you must evaluate the implemented tests
-against the active Epic and the current codebase to ensure all quality
+against the Story under audit and the current codebase to ensure all quality
 requirements are met and correctly documented.
 
 **Note on Testing Responsibilities**: When evaluating test maturity, note the
@@ -24,10 +24,10 @@ and integration test coverage alongside their feature implementations. The QA
 Engineering function focuses on End-to-End (E2E) testing, complex system
 integrations, and test environment stability.
 
-## Scope (Epic mode)
+## Scope (Story / plan-run mode)
 
-When this lens is invoked from `/deliver` Phase 4 (epic-audit), the
-following block is populated with the Epic's change-set file list.
+When this lens is invoked from `/deliver` close lenses (or a plan-run audit), the
+following block is populated with the Story (or plan-run) change-set file list.
 Otherwise — for any manual `/audit-<dimension>` invocation — the block
 renders the literal substitution token and you MUST treat it as **no
 scope filter — run the lens codebase-wide** exactly as you would have
@@ -48,8 +48,7 @@ before this section existed.
 ## Execution strategy (dual-path)
 
 This lens runs along one of two execution paths. Both emit the **identical**
-report contract (Step 3); downstream consumers (`/deliver` Phase 4
-epic-audit, `audit-to-stories`) are agnostic to which path produced it.
+report contract (Step 3); downstream consumers (`audit-to-stories`) are agnostic to which path produced it.
 
 - **Orchestrated (dynamic-workflow) path.** When Claude Code's
   [dynamic workflows](https://code.claude.com/docs/en/workflows) are
@@ -101,8 +100,8 @@ degrade to the sequential path.
 
 ## Step 0 - Project Context
 
-1.  Read the active Epic and its child tickets to identify the current milestone
-    and target features.
+1.  Read the Story under audit — its `## Goal`, inline `acceptance[]` /
+    `verify[]`, and folded `## Spec` — to identify the target features.
 2.  Identify the target codebase paths for the audit.
 
 ## Step 1: Context Gathering (Read-Only Scan)
@@ -116,8 +115,8 @@ files. Pay special attention to:
   `playwright.config.ts`, `cypress.json`).
 - Test directories and files (e.g., `__tests__/`, `spec/`, `e2e/`, `*.test.ts`,
   `*.spec.js`).
-- The active Epic and its child tickets to map out expected features versus
-  implemented tests.
+- The Story's `acceptance[]` / `verify[]` arrays, to map expected behaviour
+  versus implemented tests.
 - Mocking and stubbing setups (e.g., `__mocks__/`, `setupTests.js`, MSW
   handlers).
 - CI/CD workflow files to understand how and when tests are executed.
@@ -140,8 +139,8 @@ Evaluate the gathered context against the following test quality dimensions:
 5. **Performance & Execution:** Find bottlenecks in the test suite, such as
    unnecessary serial execution, heavy setup running too frequently, or
    opportunities for parallelization.
-6. **Requirement Alignment:** Cross-reference the features outlined in the
-   active Epic to ensure they have corresponding and complete test coverage.
+6. **Requirement Alignment:** Cross-reference the Story's `acceptance[]`
+   criteria to ensure they have corresponding and complete test coverage.
    Verify that the implementation found in the codebase correctly matches the
    architectural requirements and highlight any inconsistencies or gaps.
 

package/.agents/workflows/audit-security.md

@@ -15,10 +15,10 @@ Conduct a comprehensive security review of the codebase. Your goal is to
 identify common vulnerabilities (OWASP Top 10), insecure configurations, and
 potential attack vectors.
 
-## Scope (Epic mode)
+## Scope (Story / plan-run mode)
 
-When this lens is invoked from `/deliver` Phase 4 (epic-audit), the
-following block is populated with the Epic's change-set file list.
+When this lens is invoked from `/deliver` close lenses (or a plan-run audit), the
+following block is populated with the Story (or plan-run) change-set file list.
 Otherwise — for any manual `/audit-<dimension>` invocation — the block
 renders the literal substitution token and you MUST treat it as **no
 scope filter — run the lens codebase-wide** exactly as you would have
@@ -39,8 +39,7 @@ before this section existed.
 ## Execution strategy (dual-path)
 
 This lens runs along one of two execution paths. Both emit the **identical**
-report contract (Step 3); downstream consumers (`/deliver` Phase 4
-epic-audit, `audit-to-stories`) are agnostic to which path produced it.
+report contract (Step 3); downstream consumers (`audit-to-stories`) are agnostic to which path produced it.
 
 - **Orchestrated (dynamic-workflow) path.** When Claude Code's
   [dynamic workflows](https://code.claude.com/docs/en/workflows) are

package/.agents/workflows/audit-seo.md

@@ -4,6 +4,16 @@ description: Audit SEO fundamentals and Generative Engine Optimization signals (
 
 # SEO & Generative Engine Optimization Audit
 
+## Applicability
+
+**Web targets only.** This lens is registered with `target: "web"` in
+[`audit-rules.json`](../schemas/audit-rules.json), so the selector skips it
+entirely on a project with no web surface — however well its keyword triggers
+match the ticket prose. Applicability is derived from the consumer's own
+checkout (configured navigability `routeGlobs`, a declared web-framework
+dependency, or a tracked `.html` / `.css` / `.jsx` / `.tsx` source file), not
+from an `.agentrc` key, and the probe fails open when indeterminate.
+
 ## Role
 
 Senior Technical SEO and Generative Engine Optimization (GEO) Specialist. You
@@ -18,10 +28,10 @@ codebase. Your goal is to surface structural, semantic, and content-level
 improvements that will increase discoverability in both traditional search
 indexes and AI-powered answer engines — without making any immediate changes.
 
-## Scope (Epic mode)
+## Scope (Story / plan-run mode)
 
-When this lens is invoked from `/deliver` Phase 4 (epic-audit), the
-following block is populated with the Epic's change-set file list.
+When this lens is invoked from `/deliver` close lenses (or a plan-run audit), the
+following block is populated with the Story (or plan-run) change-set file list.
 Otherwise — for any manual `/audit-<dimension>` invocation — the block
 renders the literal substitution token and you MUST treat it as **no
 scope filter — run the lens codebase-wide** exactly as you would have

package/.agents/workflows/audit-sre.md

@@ -15,10 +15,10 @@ release candidate. Your goal is to surface critical risks across configuration
 integrity, security, observability, and code quality — providing a prioritized,
 actionable report that can be handed off for remediation before deployment.
 
-## Scope (Epic mode)
+## Scope (Story / plan-run mode)
 
-When this lens is invoked from `/deliver` Phase 4 (epic-audit), the
-following block is populated with the Epic's change-set file list.
+When this lens is invoked from `/deliver` close lenses (or a plan-run audit), the
+following block is populated with the Story (or plan-run) change-set file list.
 Otherwise — for any manual `/audit-<dimension>` invocation — the block
 renders the literal substitution token and you MUST treat it as **no
 scope filter — run the lens codebase-wide** exactly as you would have

package/.agents/workflows/audit-to-stories.md

@@ -3,7 +3,7 @@ description:
   Convert findings produced by the audit-* workflows into actionable
   GitHub Stories. Reads temp/audits/audit-*-results.md, groups findings
   cross-audit, deduplicates against existing Issues by fingerprint, and
-  either chains into /plan --idea or opens standalone Stories.
+  either chains into /plan --seed-file or opens standalone Stories.
 ---
 
 # /audit-to-stories [audit-file-or-glob]
@@ -22,8 +22,8 @@ Dimension / Category, Current State, Recommendation, Agent Prompt).
 `/audit-to-stories` closes the loop: it parses those reports, groups
 related findings (including across audit dimensions), classifies each
 group as eligible-to-create or already-tracked, and — at the operator's
-choice — either chains into `/plan --idea` for a single planned
-Epic or opens standalone Stories directly.
+choice — either chains into `/plan --seed-file` for a planned Story
+(or N>1 under the split policy) or opens standalone Stories directly.
 
 The audit producers themselves are **not modified** by this workflow.
 They remain read-only emitters of audit reports.
@@ -117,23 +117,23 @@ Ask:
 
 > How would you like these `<M>` Stories created?
 >
-> - **Single Epic via `/plan`** **[Recommended]** — opens one Epic,
->   then chains into `/plan --idea` so the standard spec-and-WBS
->   authoring handles decomposition. Grouped Stories become the
->   seed for the authoring step's decomposition.
+> - **Single plan via `/plan`** **[Recommended]** — chains into
+>   `/plan --seed-file <emitted.md>` so the standard Story authoring
+>   handles the seed. Prefer one Story; split only under the
+>   default-single policy.
 > - **Individual standalone Stories** — opens one GitHub Issue per
->   group directly, no Epic wrapper.
+>   group directly (no plan ceremony).
 
 **STOP** until the operator picks.
 
-## Phase 5a — Single-Epic path
+## Phase 5a — Single-plan path
 
-Build the `/plan` idea seed from the filtered plan envelope:
+Build the `/plan` seed from the filtered plan envelope:
 
 ```bash
-node .agents/scripts/audit-to-stories.js --emit-epic-seed \
+node .agents/scripts/audit-to-stories.js --emit-plan-seed \
   --plan temp/audits/audit-to-stories-plan.json \
-  --out "temp/audits/audit-epic-seed-$(date +%Y%m%dT%H%M%S).md"
+  --out "temp/audits/audit-plan-seed-$(date +%Y%m%dT%H%M%S).md"
 ```
 
 The seed renders the canonical one-pager sections — Problem Statement,
@@ -144,11 +144,11 @@ authoring step has concrete anchors), Not Doing.
 Chain into the existing planning entrypoint:
 
 ```text
-/plan --idea "<path-to-seed>"
+/plan --seed-file <path-to-seed>
 ```
 
-`/plan` then runs its 3-step Epic path (interrogate → author →
-persist), as documented in its workflow.
+(`/plan --seed "$(cat <path>)"` also works for small seeds). `/plan`
+then runs its author → persist path, as documented in its workflow.
 Each Story it spawns from the seed carries `context::audit:
 <reportLink>` and `audit-fingerprint: <sha>` in its body so future
 Phase 6 idempotency works on the next run.
@@ -220,13 +220,13 @@ Persist `temp/audits/audit-to-stories-$(date +%Y%m%dT%H%M%S).md`
 summarising the run:
 
 - Per-group breakdown: which findings merged, fingerprints, dependency
-  edges, created/skipped Issue link (or new Epic link).
+  edges, created/skipped Issue link (or plan-run / Story links).
 - The severity threshold and grouping mode the operator chose.
 - Final tally: `"<M> groups planned · <K> created · <J> skipped (open)
   · <L> skipped (re-occurring)"`.
 
-When the Single-Epic path ran, link the Epic the chained `/plan`
-opened. When the Standalone-Stories path ran, list every Issue URL.
+When the single-plan path ran, link the Story (or plan-run) the chained
+`/plan` opened. When the Standalone-Stories path ran, list every Issue URL.
 
 ## Constraints
 
@@ -261,8 +261,8 @@ issue 4482.)
 
 ## See also
 
-- [`/plan`](helpers/plan-epic.md) — the planning pipeline `/audit-to-stories`
-  chains into for the Single-Epic grouping mode.
+- [`/plan`](plan.md) — the planning pipeline `/audit-to-stories`
+  chains into for Story creation.
 - [`lib/findings/route-finding.js`](../scripts/lib/findings/route-finding.js) —
   the shared fingerprint/dedup/route helper this workflow and `qa-explore`
   both consume. There is no second dedup implementation.

package/.agents/workflows/audit-ux-ui.md

@@ -4,6 +4,13 @@ description: Audit UX/UI consistency and design system adherence
 
 # UX/UI & Design System Audit
 
+## Applicability
+
+**Web targets only.** Registered with `target: "web"` in
+[`audit-rules.json`](../schemas/audit-rules.json): the selector skips this lens
+on a project with no rendered frontend. See the `target` key's schema
+description for how applicability is probed from the consumer's checkout.
+
 ## Role
 
 Lead Product Designer & Frontend Architect
@@ -14,10 +21,10 @@ Evaluate the frontend implementation for UI consistency, UX best practices, and
 adherence to the project's design system. Ensure the application feels premium
 and cohesive.
 
-## Scope (Epic mode)
+## Scope (Story / plan-run mode)
 
-When this lens is invoked from `/deliver` Phase 4 (epic-audit), the
-following block is populated with the Epic's change-set file list.
+When this lens is invoked from `/deliver` close lenses (or a plan-run audit), the
+following block is populated with the Story (or plan-run) change-set file list.
 Otherwise — for any manual `/audit-<dimension>` invocation — the block
 renders the literal substitution token and you MUST treat it as **no
 scope filter — run the lens codebase-wide** exactly as you would have