mandrel 1.68.0 → 1.70.0

package/.agents/README.md

@@ -466,7 +466,7 @@ ticketing provider is GitHub, resolved by `provider-factory.js` from the
 `orchestration.provider` config key. CLI scripts receive provider
 instances from the SDK surface rather than importing provider
 implementations directly. Execution is Claude-Code-in-session — there is
-no separate adapter abstraction; `wave-dispatcher.js` synthesizes the
+no separate adapter abstraction; `manifest-builder.js` synthesizes the
 dispatch record inline and the dispatch manifest (md + structured
 comment) is the cross-runtime contract.
 

package/.agents/docs/agentrc-reference.json

@@ -59,7 +59,6 @@
     }
   },
   "planning": {
-    "maxTickets": 60,
     "context": {
       "maxBytes": 50000,
       "summaryMode": "auto"
@@ -91,7 +90,7 @@
       "Schema migrations that rewrite existing rows or drop columns without a backfill or rollback plan."
     ],
     "taskSizing": {
-      "softFiles": 8,
+      "softFiles": 15,
       "hardFiles": 30,
       "maxAcceptance": 14,
       "softAcceptanceCount": 10

package/.agents/docs/configuration.md

@@ -26,7 +26,7 @@ with the runtime validators.
   "$schema": "./.agents/schemas/agentrc.schema.json",
   "project":  { /* paths, commands, baseBranch, docsContextFiles */ },
   "github":   { /* owner, repo, branchProtection, mergeMethods, notifications */ },
-  "planning": { /* riskHeuristics, maxTickets, codebaseSnapshot, context */ },
+  "planning": { /* riskHeuristics, codebaseSnapshot, context */ },
   "delivery": { /* execution, quality, worktreeIsolation, deliverRunner, ... */ }
 }
 ```
@@ -97,7 +97,6 @@ top-level keys are validation errors.
 | Key | Required | Type | Default | Description |
 | --- | --- | --- | --- | --- |
 | `riskHeuristics` | No | `string[]` or `{ append?, prepend? }` | — | — |
-| `maxTickets` | No | `integer` | — | — |
 | `context` | No | `object` | — | Nested configuration block. |
 | `context.maxBytes` | No | `integer` | — | — |
 | `context.summaryMode` | No | `"auto"` \| `"always"` \| `"never"` | — | — |
@@ -107,7 +106,7 @@ top-level keys are validation errors.
 | `codebaseSnapshot.exclude` | No | `array<string>` | — | — |
 | `codebaseSnapshot.recentCommitWindow` | No | `integer` | — | — |
 | `taskSizing` | No | `object` | — | Story-sizing thresholds consumed by ticket-validator-sizing.js. Operator overrides shallow-merge with DEFAULT_TASK_SIZING defaults. Story #3760 collapsed the per-profile matrix and the parallel testSurface axis into a flat set of knobs; the sizingProfile enum was replaced by an optional body-level `wide` declaration that lifts the hardFiles rejection. Story #3874 cut over to one uniform relaxed profile sized for capability slices a frontier model delivers and self-verifies in one pass. |
-| `taskSizing.softFiles` | No | `integer` | — | File-count soft-warn threshold above which a typical-Story width finding fires (default 8). |
+| `taskSizing.softFiles` | No | `integer` | — | File-count soft-warn threshold above which a typical-Story width finding fires (default 15). |
 | `taskSizing.hardFiles` | No | `integer` | — | File-count hard ceiling: a Story exceeding it is rejected unless it declares `wide` with a reason (default 30). |
 | `taskSizing.maxAcceptance` | No | `integer` | — | Hard ceiling on acceptance[] item count (default 14). |
 | `taskSizing.softAcceptanceCount` | No | `integer` | — | Soft-warn threshold on acceptance[] item count (default 10). |
@@ -430,7 +429,6 @@ suppress a channel entirely, set its array to `[]`.
 | Field                          | Required | Default    | Purpose                                                                                          |
 | ------------------------------ | -------- | ---------- | ------------------------------------------------------------------------------------------------ |
 | `riskHeuristics`               | No       | `[]`       | Free-form rubric for `risk::high` decisions (informational only — `risk::high` does not gate runtime). Accepts a plain array or the `{ append/prepend }` extender form. |
-| `maxTickets`                   | No       | (none)     | Soft cap on tickets a single Epic may decompose.                                                 |
 | `failOnSharedEditors`          | No       | (none)     | Hard-fail Phase 7 when two Stories declare the same editor.                                       |
 | `requireExplicitCrossStoryDeps`| No       | (none)     | Require explicit cross-Story `blocked by` declarations rather than inferring from shared paths.   |
 

package/.agents/docs/workflows.md

@@ -29,7 +29,7 @@ description, edit the workflow file’s front-matter and regenerate.
 
 | Command | Description |
 | --- | --- |
-| `/agents-update` | npm-era upgrade wraparound for a Mandrel consumer. Runs `mandrel update` (resolve newest published version → install → re-materialize `.agents/` → migrate → doctor → surface changelog) as the single mechanical step, then walks the operator through the judgment wraparound the CLI deliberately leaves unowned: reconcile `.agentrc.json`, install the Epic #1386 quality-gate surface, refresh the harness permission allowlist, reconcile the consumer's `AGENTS.md` / runbooks against the surfaced changelog, and stage + commit the staged lockfile bump. |
+| `/agents-update` | npm-era upgrade wraparound for a Mandrel consumer. Runs `npx mandrel update` (resolve newest published version → install → re-materialize `.agents/` → migrate → doctor → surface changelog) as the single mechanical step, then walks the operator through the judgment wraparound the CLI deliberately leaves unowned: reconcile `.agentrc.json`, install the Epic #1386 quality-gate surface, refresh the harness permission allowlist, reconcile the consumer's `AGENTS.md` / runbooks against the surfaced changelog, and stage + commit the staged lockfile bump. |
 | `/audit-architecture` | Audit architectural boundaries, module coupling, and layering violations; emit a structured findings report keyed to High/Medium/Low severity. |
 | `/audit-clean-code` | Audit code smells, dead code, complexity hotspots, and maintainability-index outliers; emit a structured findings report. |
 | `/audit-dependencies` | Audit `package.json` for unused, outdated, and major-version-stale dependencies; surface Node-engine drift and propose upgrade batches. |

package/.agents/schemas/agentrc.schema.json

@@ -332,7 +332,7 @@
         "softFiles": {
           "type": "integer",
           "minimum": 1,
-          "description": "File-count soft-warn threshold above which a typical-Story width finding fires (default 8)."
+          "description": "File-count soft-warn threshold above which a typical-Story width finding fires (default 15)."
         },
         "hardFiles": {
           "type": "integer",
@@ -358,10 +358,6 @@
         "riskHeuristics": {
           "$ref": "#/$defs/listOrExtenderOfStrings"
         },
-        "maxTickets": {
-          "type": "integer",
-          "minimum": 1
-        },
         "context": {
           "$ref": "#/$defs/planningContext"
         },

package/.agents/schemas/lifecycle/epic.automerge.end.schema.json

@@ -8,7 +8,8 @@
   "properties": {
     "prUrl": { "type": "string", "format": "uri", "minLength": 1 },
     "merged": { "type": "boolean" },
-    "reason": { "type": "string" }
+    "reason": { "type": "string" },
+    "epicId": { "type": "integer", "minimum": 1 }
   },
   "additionalProperties": false
 }

package/.agents/scripts/agents-update-preflight.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+
+/**
+ * agents-update-preflight.js — Story #4170
+ * (feat(agents-update): add a first-run preflight before the updater)
+ *
+ * A first-run preflight for the `/agents-update` workflow. The workflow
+ * otherwise jumps straight to `npx mandrel update` with no guard rails;
+ * this preflight catches three day-0 failure modes *before* the version
+ * bump:
+ *
+ *   1. **Wrong project (hard stop).** Running the updater in the framework
+ *      repo itself or in a non-consumer (no `mandrel` dependency in
+ *      `package.json`, or no materialized `.agents/` directory) silently
+ *      does the wrong thing. The consumer-shape check is a BLOCKER: it
+ *      exits non-zero so the workflow halts before bumping anything.
+ *   2. **Dirty git index (warn).** `mandrel update` deliberately leaves the
+ *      lockfile *staged* (see `lib/cli/update.js`); the workflow's commit
+ *      step then `git add`s and commits. If the index already holds
+ *      unrelated staged changes, that step would sweep them into the
+ *      `chore: update mandrel` commit. Warn so the operator can unstage
+ *      first.
+ *   3. **Offline (warn).** The CLI throws a usable error on a failed
+ *      `npm view`, but a one-line up-front reachability check gives a
+ *      friendlier "you're offline" signal before any version probe.
+ *
+ * Severity is consistent with framework preflight conventions
+ * (cf. `story-close.js` runStoryClosePreflight, `epic-deliver-preflight.js`):
+ * the consumer-shape check is a hard stop (blocker), dirty-index and offline
+ * are warn-only and never block the run.
+ *
+ * Out of scope (per the Story): folding these checks into
+ * `lib/cli/update.js` itself — the CLI stays git-free and
+ * side-effect-scoped; this is a workflow-layer concern.
+ *
+ * The detection logic is a pure function (`runAgentsUpdatePreflight`) that
+ * takes injectable probes so it is unit-testable without touching the real
+ * filesystem, git index, or network. The CLI wrapper wires the real probes
+ * and maps a blocker finding to a non-zero exit code.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { runAsCli } from './lib/cli-utils.js';
+import { Logger } from './lib/Logger.js';
+
+/**
+ * @typedef {object} PreflightFinding
+ * @property {string} id        Stable check id.
+ * @property {'blocker'|'warning'} severity
+ * @property {string} summary   One-line human-readable description.
+ * @property {string} [fix]     Copy-pasteable remediation hint.
+ */
+
+/**
+ * Real-world probes. Each is overridable in tests via the `probes` option.
+ *
+ * @param {string} projectRoot Absolute consumer repo root.
+ */
+export function makeProbes(projectRoot) {
+  return {
+    /**
+     * Read + parse `package.json`. Returns the parsed object, or `null`
+     * when the file is missing or unparseable.
+     */
+    readPackageJson() {
+      const pkgPath = path.join(projectRoot, 'package.json');
+      if (!existsSync(pkgPath)) return null;
+      try {
+        return JSON.parse(readFileSync(pkgPath, 'utf8'));
+      } catch {
+        return null;
+      }
+    },
+    /** Does the materialized `.agents/` directory exist? */
+    agentsDirExists() {
+      return existsSync(path.join(projectRoot, '.agents'));
+    },
+    /**
+     * Are there staged (index) changes? Returns true when
+     * `git diff --cached --name-only` is non-empty. Returns false on any
+     * git error (not a repo, git missing) — a missing index is not a
+     * dirty index.
+     */
+    hasStagedChanges() {
+      try {
+        const out = execFileSync('git', ['diff', '--cached', '--name-only'], {
+          cwd: projectRoot,
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return out.trim().length > 0;
+      } catch {
+        return false;
+      }
+    },
+    /**
+     * Is the npm registry reachable? Probes `npm ping` (a PM-agnostic
+     * reachability query that does not mutate anything). Returns true when
+     * the ping succeeds, false on any failure (offline / registry down).
+     */
+    registryReachable() {
+      try {
+        execFileSync('npm', ['ping'], {
+          cwd: projectRoot,
+          encoding: 'utf8',
+          stdio: ['ignore', 'ignore', 'ignore'],
+          timeout: 10_000,
+        });
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  };
+}
+
+/**
+ * Pure preflight evaluator. Runs the three checks against the supplied
+ * probes and returns a structured result. Never throws; never performs
+ * I/O directly (all I/O is behind `probes`).
+ *
+ * @param {object} options
+ * @param {ReturnType<typeof makeProbes>} options.probes
+ * @returns {{ ok: boolean, blocked: boolean, findings: PreflightFinding[] }}
+ *   `blocked` is true when any blocker-severity finding fired (the
+ *   consumer-shape hard stop). `ok` is true when there are no findings of
+ *   any severity.
+ */
+export function runAgentsUpdatePreflight({ probes }) {
+  /** @type {PreflightFinding[]} */
+  const findings = [];
+
+  // 1. Consumer-shape check — BLOCKER (hard stop).
+  const pkg = probes.readPackageJson();
+  const deps = pkg
+    ? {
+        ...(pkg.dependencies ?? {}),
+        ...(pkg.devDependencies ?? {}),
+        ...(pkg.optionalDependencies ?? {}),
+      }
+    : {};
+  const hasMandrelDep = Object.hasOwn(deps, 'mandrel');
+  const hasAgentsDir = probes.agentsDirExists();
+
+  if (!pkg || !hasMandrelDep || !hasAgentsDir) {
+    const missing = [];
+    if (!pkg) missing.push('no readable package.json');
+    else if (!hasMandrelDep)
+      missing.push('package.json does not list "mandrel" as a dependency');
+    if (!hasAgentsDir) missing.push('no .agents/ directory');
+    findings.push({
+      id: 'consumer-shape',
+      severity: 'blocker',
+      summary: `Not a Mandrel consumer project (${missing.join('; ')}). Run /agents-update from a consumer repo that depends on "mandrel" and has a materialized .agents/ tree — not the framework repo itself or an unrelated project.`,
+      fix: 'cd into the consumer project root, or run `npm install -D mandrel && npx mandrel sync` to bootstrap one.',
+    });
+  }
+
+  // 2. Dirty-index check — WARN only.
+  if (probes.hasStagedChanges()) {
+    findings.push({
+      id: 'dirty-index',
+      severity: 'warning',
+      summary:
+        "The git index already has staged changes. `mandrel update` leaves the lockfile staged, and the workflow's commit step (Step 5) would sweep these unrelated staged files into the `chore: update mandrel` commit.",
+      fix: 'Unstage unrelated changes first: `git restore --staged <path>` (or `git reset` to clear the whole index), then re-run the preflight.',
+    });
+  }
+
+  // 3. Offline check — WARN only.
+  if (!probes.registryReachable()) {
+    findings.push({
+      id: 'offline',
+      severity: 'warning',
+      summary:
+        'The npm registry is not reachable. `npx mandrel update` resolves the newest published version via the registry and will fail its version probe while offline.',
+      fix: 'Check your network connection (or registry auth/proxy config) before running `npx mandrel update`.',
+    });
+  }
+
+  const blocked = findings.some((f) => f.severity === 'blocker');
+  return { ok: findings.length === 0, blocked, findings };
+}
+
+/**
+ * Render the findings to a logger. Blockers go to `error`, warnings to
+ * `warn`. A clean result logs a single `info` line.
+ *
+ * @param {{ ok: boolean, blocked: boolean, findings: PreflightFinding[] }} result
+ * @param {{ info: Function, warn: Function, error: Function }} logger
+ */
+export function reportPreflight(result, logger) {
+  if (result.ok) {
+    logger.info(
+      '✅ [agents-update-preflight] All checks passed — safe to run `npx mandrel update`.',
+    );
+    return;
+  }
+  for (const f of result.findings) {
+    const line = `[${f.id}] ${f.summary}${f.fix ? `\n  ↳ Fix: ${f.fix}` : ''}`;
+    if (f.severity === 'blocker') {
+      logger.error(`❌ ${line}`);
+    } else {
+      logger.warn(`⚠️  ${line}`);
+    }
+  }
+  if (result.blocked) {
+    logger.error(
+      '[agents-update-preflight] Hard stop: do not run `npx mandrel update` until the blocker above is resolved (exit 2).',
+    );
+  } else {
+    logger.warn(
+      '[agents-update-preflight] Warnings only — review them, then proceed if intentional.',
+    );
+  }
+}
+
+async function main() {
+  const projectRoot = process.cwd();
+  const probes = makeProbes(projectRoot);
+  const result = runAgentsUpdatePreflight({ probes });
+  reportPreflight(result, Logger);
+  // Machine-parsable JSON envelope on stdout for tooling / the workflow to
+  // read. Use process.stdout.write (not console.log) per the no-console
+  // enforcement boundary: human-facing output goes through Logger above.
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  return result.blocked ? 2 : 0;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'agents-update-preflight',
+  propagateExitCode: true,
+});

package/.agents/scripts/apply-quality-bootstrap.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+/**
+ * apply-quality-bootstrap.js — Story #4171
+ * (refactor(agents-update): extract the quality-bootstrap heredoc into a
+ * tested script)
+ *
+ * Replaces the inline `node -e "Promise.all([...])"` heredoc that Step 3.5 of
+ * the `/agents-update` workflow used to carry. That shape was fragile in three
+ * ways: it broke across shells (PowerShell vs bash quoting / backticks), it
+ * had no test so it silently drifted when the two helper signatures moved, and
+ * it could not be invoked or dry-run independently.
+ *
+ * This script runs the two Epic #1386 quality-gate installs in order against
+ * the consumer repo root:
+ *
+ *   1. `applyQualityBootstrap` — copies the code-quality-guardrails helper,
+ *      installs the `.husky/pre-commit` quality:preview line, backfills the
+ *      `quality:preview` / `quality:watch` npm scripts, and seeds the
+ *      `delivery.quality.{codingGuardrails,autoRefresh}` defaults.
+ *   2. `migrateBaselinesLayout` — relocates per-Epic baseline snapshots into
+ *      the `temp/epic/<id>/baselines/` namespace.
+ *
+ * Both helpers are idempotent by contract — a second run reports `no-change`
+ * on every install path — so this wrapper is safe to re-run. It prints the
+ * **same JSON result shape** the heredoc did: `{ quality, baselines }` to
+ * stdout, so any tooling that parsed the old output keeps working.
+ *
+ * The effectful work is a thin pure function (`applyBootstrapAndMigration`)
+ * that takes the two helpers and the project root, so the test suite can
+ * drive it against a tmp directory without spawning a child process. The CLI
+ * wrapper wires the real helpers and `process.cwd()`.
+ */
+
+import path from 'node:path';
+import { migrateBaselinesLayout } from './lib/bootstrap/baselines-layout-migration.js';
+import { applyQualityBootstrap } from './lib/bootstrap/quality-bootstrap.js';
+import { runAsCli } from './lib/cli-utils.js';
+
+/**
+ * Run the quality-bootstrap install and the baselines-layout migration
+ * against `projectRoot`, returning the combined `{ quality, baselines }`
+ * envelope. Pure relative to its injected helpers: the default helpers touch
+ * the filesystem under `projectRoot`, but tests can pass stubs to exercise
+ * the composition in isolation.
+ *
+ * @param {object} options
+ * @param {string} options.projectRoot Absolute consumer repo root.
+ * @param {typeof applyQualityBootstrap} [options.applyQualityBootstrap]
+ * @param {typeof migrateBaselinesLayout} [options.migrateBaselinesLayout]
+ * @returns {{ quality: object, baselines: object }}
+ */
+export function applyBootstrapAndMigration({
+  projectRoot,
+  applyQualityBootstrap: applyQuality = applyQualityBootstrap,
+  migrateBaselinesLayout: migrateBaselines = migrateBaselinesLayout,
+}) {
+  const quality = applyQuality({ projectRoot });
+  const baselines = migrateBaselines({
+    baselinesDir: path.join(projectRoot, 'baselines'),
+    repoRoot: projectRoot,
+  });
+  return { quality, baselines };
+}
+
+async function main() {
+  const projectRoot = process.cwd();
+  const result = applyBootstrapAndMigration({ projectRoot });
+  // Mirror the retired heredoc's output: pretty-printed `{ quality, baselines }`
+  // to stdout. Use process.stdout.write (not console.log) per the no-console
+  // enforcement boundary.
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  return 0;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'apply-quality-bootstrap',
+  propagateExitCode: true,
+});

package/.agents/scripts/audit-labels-bootstrap.js

@@ -1,14 +1,21 @@
 /**
- * audit-labels-bootstrap.js — Idempotently create the `audit::<dimension>`
+ * audit-labels-bootstrap.js — Idempotently create the `audit::<lens>`
  * label taxonomy in the configured GitHub repo.
  *
  * Run this once per repo before `/audit-to-stories` opens its first
  * Story. Re-runs are safe — existing labels are skipped, only missing
  * ones are created. Story #2583 acceptance criterion #6.
  *
- * The dimension list mirrors the 12 audit-* workflows in
- * `.agents/workflows/`. Adding a new audit-* workflow should also add a
- * corresponding entry below.
+ * The lens list is the shared SSOT `AUDIT_LENSES`
+ * (`lib/audit-to-stories/audit-lenses.js`), one per `/audit-<lens>` workflow
+ * under `.agents/workflows/`. Sourcing the list from the same module that
+ * `build-story-body.js` derives `audit::<lens>` labels from guarantees the
+ * label producer (this bootstrap) and the label deriver (story-body) cannot
+ * drift — a finding from `audit-documentation-results.md` derives
+ * `audit::documentation`, and this bootstrap creates exactly that label
+ * (Story #4195). The per-lens colour/description metadata lives in
+ * `LENS_META` below; adding a new `audit-*` workflow means adding its lens to
+ * `AUDIT_LENSES` and (optionally) a `LENS_META` entry.
  *
  * Delegates to `gh label create` so the script works without any
  * provider plumbing — `gh auth status` is the only prerequisite. Per
@@ -19,72 +26,87 @@
 import process from 'node:process';
 import { parseArgs } from 'node:util';
 
+import { AUDIT_LENSES } from './lib/audit-to-stories/audit-lenses.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
 import { gh as defaultGh, GhExecError } from './lib/gh-exec.js';
 
-const DIMENSIONS = Object.freeze([
-  {
-    name: 'architecture',
+/**
+ * Per-lens label presentation. Keyed by canonical lens name. A lens absent
+ * from this map falls back to {@link DEFAULT_LENS_META} so a newly-added
+ * `AUDIT_LENSES` entry still gets a label without a hard requirement to
+ * register colour/description here first.
+ */
+const LENS_META = Object.freeze({
+  architecture: {
     color: '6f42c1',
     description: 'Audit-sourced finding: architectural concerns',
   },
-  {
-    name: 'clean-code',
+  'clean-code': {
     color: '0e8a16',
     description: 'Audit-sourced finding: clean-code / maintainability',
   },
-  {
-    name: 'dependencies',
+  dependencies: {
     color: 'd4c5f9',
     description: 'Audit-sourced finding: dependencies / supply chain',
   },
-  {
-    name: 'devops',
+  devops: {
     color: 'fbca04',
     description: 'Audit-sourced finding: DevOps / CI / CD',
   },
-  {
-    name: 'lighthouse',
+  documentation: {
+    color: '1d76db',
+    description: 'Audit-sourced finding: documentation staleness / gaps',
+  },
+  lighthouse: {
     color: 'c5def5',
     description: 'Audit-sourced finding: Lighthouse score regressions',
   },
-  {
-    name: 'performance',
+  navigability: {
+    color: 'bfdadc',
+    description: 'Audit-sourced finding: route / nav reachability',
+  },
+  performance: {
     color: 'b60205',
     description: 'Audit-sourced finding: performance / latency',
   },
-  {
-    name: 'privacy',
+  privacy: {
     color: 'fef2c0',
     description: 'Audit-sourced finding: privacy / data handling',
   },
-  {
-    name: 'quality',
+  quality: {
     color: '0052cc',
     description: 'Audit-sourced finding: test quality / coverage gaps',
   },
-  {
-    name: 'security',
+  security: {
     color: 'b60205',
     description: 'Audit-sourced finding: security / OWASP',
   },
-  {
-    name: 'seo',
+  seo: {
     color: 'fbca04',
     description: 'Audit-sourced finding: SEO / discoverability',
   },
-  {
-    name: 'sre',
+  sre: {
     color: '0052cc',
     description: 'Audit-sourced finding: SRE / observability / reliability',
   },
-  {
-    name: 'ux-ui',
+  'ux-ui': {
     color: 'd4c5f9',
     description: 'Audit-sourced finding: UX / UI concerns',
   },
-]);
+});
+
+const DEFAULT_LENS_META = Object.freeze({
+  color: 'ededed',
+  description: 'Audit-sourced finding',
+});
+
+const DIMENSIONS = Object.freeze(
+  AUDIT_LENSES.map((name) => ({
+    name,
+    ...(LENS_META[name] ?? DEFAULT_LENS_META),
+  })),
+);
 
 async function labelExists(gh, owner, repo, name) {
   try {

package/.agents/scripts/audit-to-stories.js

@@ -39,6 +39,7 @@ import { groupFindings } from './lib/audit-to-stories/group-findings.js';
 import { parseAuditReports } from './lib/audit-to-stories/parse-audit-md.js';
 import { buildEpicSeedMarkdown } from './lib/audit-to-stories/seed-epic-from-findings.js';
 import { runAsCli } from './lib/cli-utils.js';
+import { Logger } from './lib/Logger.js';
 
 const SEVERITY_RANK = { critical: 4, high: 3, medium: 2, low: 1 };
 const DEFAULT_GLOB = 'temp/audits/audit-*-results.md';
@@ -109,6 +110,44 @@ async function loadProvider() {
   }
 }
 
+/**
+ * Render the loud, operator-visible warning emitted when the Phase 6 dedup
+ * does NOT run against real GitHub issues. Two distinct reasons:
+ *
+ *   - `'no-provider-port'` — the configured provider resolved but exposes no
+ *     `searchIssues` port (or `loadProvider()` threw). This is the
+ *     silent-no-op the workflow's "Never open a duplicate Issue" contract
+ *     was failing on: every group classifies `create` and the operator gets
+ *     zero automated dedup signal. Surfacing it loudly is the whole point.
+ *   - `'disabled'` — the operator passed `--no-provider`, intentionally
+ *     skipping dedup. Still warned (so a re-run that opens duplicates is
+ *     never a surprise), but framed as a deliberate choice.
+ *
+ * Pure: returns the message string so `buildPlan` owns the single
+ * `Logger.warn` write site and the text stays unit-testable.
+ *
+ * @param {'no-provider-port'|'disabled'} reason
+ * @returns {string}
+ */
+function dedupSkippedWarning(reason) {
+  if (reason === 'disabled') {
+    return (
+      'dedup skipped (--no-provider): every group is classified "create" ' +
+      'without checking GitHub for existing issues. A re-run may open ' +
+      'duplicates of already-tracked or already-closed findings. Drop ' +
+      '--no-provider to enable fingerprint dedup against real issues.'
+    );
+  }
+  return (
+    'dedup skipped (no provider port): the configured provider exposes no ' +
+    'searchIssues() port, so Phase 6 dedup did NOT run. Every group is ' +
+    'classified "create" and existing/closed issues are NOT checked — a run ' +
+    'that creates Stories from this plan WILL open duplicates of ' +
+    'already-tracked work. Verify `gh auth status` and the github.{owner,repo} ' +
+    'config so a real provider resolves.'
+  );
+}
+
 async function buildPlan({ glob: pattern, severity, useProvider }) {
   const reportPaths = await collectReportPaths(pattern ?? DEFAULT_GLOB);
   if (reportPaths.length === 0) {
@@ -143,6 +182,7 @@ async function buildPlan({ glob: pattern, severity, useProvider }) {
     matchedFingerprints: [],
   }));
   let summary = { create: groups.length, skipOpen: 0, skipReoccurring: 0 };
+  let dedupApplied = false;
 
   if (useProvider) {
     const provider = await loadProvider();
@@ -150,7 +190,18 @@ async function buildPlan({ glob: pattern, severity, useProvider }) {
       const result = await classifyGroupsAgainstGitHub({ groups, provider });
       classifications = result.classifications;
       summary = result.summary;
+      dedupApplied = true;
+    } else {
+      // The provider could not resolve a searchIssues port — the dedup gate
+      // is silently a no-op without this. Surface it loudly (stderr, so the
+      // --scan JSON on stdout stays clean) so the operator does not read a
+      // create-only plan as "no duplicates found".
+      Logger.warn(dedupSkippedWarning('no-provider-port'));
     }
+  } else {
+    // Operator explicitly opted out via --no-provider. Still warn so a
+    // duplicate-opening re-run is never a surprise.
+    Logger.warn(dedupSkippedWarning('disabled'));
   }
 
   return {
@@ -165,6 +216,7 @@ async function buildPlan({ glob: pattern, severity, useProvider }) {
       totalFindings: allFindings.length,
       filtered: filtered.length,
       tally: tallyBySeverity(filtered),
+      dedupApplied,
       ...summary,
     },
   };
@@ -188,6 +240,8 @@ export const __testing = {
   meetsSeverity,
   collectReportPaths,
   buildPlan,
+  loadProvider,
+  dedupSkippedWarning,
 };
 
 async function main() {