mandrel 1.69.0 → 1.71.0

package/.agents/README.md

@@ -333,7 +333,7 @@ See [`docs/SDLC.md` § Ticket hierarchy](docs/SDLC.md) for the diagram and execu
 | Check registry authoring rules | [§ Self-healing checks](#self-healing-checks) |
 | JSON Schema conventions | [§ Schemas](#schemas) |
 | Bootstrap script (project + GitHub setup) | [`scripts/bootstrap.js`](scripts/bootstrap.js) |
-| Adopt the QA workflows (`/qa-explore`, `/qa-assist`, `/qa-run-harness`) in your project | [§ Adopting the QA harness](#adopting-the-qa-harness) |
+| Adopt the QA workflows (`/qa-explore`, `/qa-assist`, `/qa-run`) in your project | [§ Adopting the QA harness](#adopting-the-qa-harness) |
 | Coordinate two operators on the same repo (lease model) | [§ Multi-developer coordination](#multi-developer-coordination) |
 
 ---
@@ -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.
 
@@ -890,12 +890,12 @@ known scenario set:
   `/qa-assist` when you hit something mid-flight and want it captured well
   without breaking stride; reach for `/qa-explore` when you want the agent to
   go hunt a named surface.
-- **`/qa-run-harness <selector>`** — the **automated complement**: it drives a
+- **`/qa-run <selector>`** — the **automated complement**: it drives a
   consumer's Gherkin `.feature` scenarios through a real browser (the
   `chrome-devtools` MCP surface), captures per-surface console/network into
   structured `F#` findings, and drafts follow-up tickets for operator
   sign-off. The end-to-end procedure is the SSOT in
-  [`workflows/qa-run-harness.md`](workflows/qa-run-harness.md); the
+  [`workflows/qa-run.md`](workflows/qa-run.md); the
   instrumentation conventions live in the
   [`skills/stack/qa/qa-harness`](skills/stack/qa/qa-harness/SKILL.md) skill; the
   architectural overview (run pipeline, contract fields, finding shape) is in
@@ -904,7 +904,7 @@ known scenario set:
 Reach for `/qa-explore` when you want the **agent** to hunt a freshly delivered
 Story/Feature or run a structured bug-hunt captured into a triageable ledger;
 reach for `/qa-assist` when **you** hit something mid-flight and want it
-enriched into a single triage-ready ledger item; reach for `/qa-run-harness` to
+enriched into a single triage-ready ledger item; reach for `/qa-run` to
 step a **known** scenario set through the browser for a regression pass.
 
 Binding the QA contract is **opt-in**. All three workflows resolve the
@@ -989,8 +989,8 @@ environment, never inlined) and `{ signInSkill }` points at a per-persona
 sign-in skill.
 
 Once these three `qa.*` keys are in place, `/qa-explore <surface>`,
-`/qa-assist`, and `/qa-run-harness <selector>` all resolve the contract and
-operate against the bound surface. For `/qa-run-harness`, the `chrome-devtools`
+`/qa-assist`, and `/qa-run <selector>` all resolve the contract and
+operate against the bound surface. For `/qa-run`, the `chrome-devtools`
 MCP surface is a host-provided runtime dependency; when it is unavailable the
 harness degrades with a clear error rather than falling back to a headless
 runner. `/qa-explore` and `/qa-assist` read the same `qa.*` keys to scope their

package/.agents/docs/SDLC.md

@@ -1103,7 +1103,7 @@ for the acceptance tier is governed by
 [`rules/gherkin-standards.md`](../rules/gherkin-standards.md).
 
 The acceptance tier is executed and reported via
-[`workflows/qa-run-harness.md`](../workflows/qa-run-harness.md) and consumed as
+[`workflows/qa-run.md`](../workflows/qa-run.md) and consumed as
 epic evidence by
 [`workflows/helpers/epic-testing.md`](../workflows/helpers/epic-testing.md).
 
@@ -1146,8 +1146,8 @@ set:
   (`qa-ledger.schema.json`) and reuses the same `scripts/lib/qa/` and
   `scripts/lib/findings/` decision seams, so a `/qa-assist` item flows through
   the identical dedup, classification, and promotion machinery later.
-- **[`workflows/qa-run-harness.md`](../workflows/qa-run-harness.md)**
-  (`/qa-run-harness`) — the **automated complement**: it steps a *known* set of
+- **[`workflows/qa-run.md`](../workflows/qa-run.md)**
+  (`/qa-run`) — the **automated complement**: it steps a *known* set of
   Gherkin `.feature` scenarios through a real browser, asserting `Then`
   outcomes semantically against the accessibility snapshot and bundling
   console/network problems into structured `F#` findings for operator sign-off.
@@ -1420,6 +1420,5 @@ For Stories already in flight, use one of the three options above.
 | *helper* `workflows/helpers/epic-deliver-story`               | Per-Story worker called by `/deliver`'s wave loop; not an operator slash command. See [`helpers/epic-deliver-story.md`](../workflows/helpers/epic-deliver-story.md).         |
 | *helper* `workflows/helpers/single-story-deliver`             | Per-Story worker called by `/deliver`; not an operator slash command. See [`helpers/single-story-deliver.md`](../workflows/helpers/single-story-deliver.md).                |
 | *helper* `workflows/helpers/code-review.md`                   | Auto-invoked by `/deliver`'s `delivery.code-review` state (scope: epic); not a slash command.                                                                            |
-| `/git-commit-all`                                | Stage and commit all changes                                                                                                                                                 |
-| `/git-push`                                      | Stage, commit, and push to remote                                                                                                                                            |
+| `/git-deliver`                                   | Ad-hoc delivery of working-tree changes — detects the git setup and escalates to commit, commit + push, or commit + push + PR (auto-merge armed).                            |
 | `epic-reconcile.js --explicit-delete`            | Hard reset — close orphaned Epic-scoped issues per `.agents/epics/<id>.yaml`                                                                                                 |

package/.agents/docs/configuration.md

@@ -748,8 +748,8 @@ number of keys.
 | `github.operatorHandle` | Committed as the `@[USERNAME]` placeholder; each contributor overrides it in gitignored `.agentrc.local.json` | `@[USERNAME]` | Schema-required, but per-contributor: the committed placeholder resolves to null and the lease guards fail closed until you set your own handle locally (see [Per-machine local overrides](#per-machine-local-overrides)). |
 | `delivery.worktreeIsolation.nodeModulesStrategy`     | `per-worktree`                        | `per-worktree`                             | npm-only repo (`package-lock.json`); worktree init runs `npm ci` per tree.                                                       |
 
-When a consumer runs `/agents-update`, the
-[`agents-sync-config`](../workflows/helpers/agents-sync-config.md)
+When a consumer runs `/mandrel-update`, the
+[`mandrel-sync-config`](../workflows/helpers/mandrel-sync-config.md)
 helper validates the project config against the schema, then adds any
 template-introduced keys the project does not already define. Project-side
 values that validate are preserved unconditionally — including optional keys
@@ -821,10 +821,10 @@ project-specific knob:
 1. Confirm the key is **already declared in the schema** at
    [`.agents/schemas/agentrc.schema.json`](../schemas/agentrc.schema.json)
    — if it isn't, the AJV validators will reject it on the next
-   `/agents-update`.
+   `/mandrel-update`.
 2. Set the key in `.agentrc.json`. Don't add it to the template unless it
    should ship to all consumers.
-3. Run `/agents-update` to confirm the helper preserves the key on round-trip.
+3. Run `/mandrel-update` to confirm the helper preserves the key on round-trip.
 
 ### Extending list-valued keys without losing template defaults
 
@@ -898,7 +898,7 @@ This is a framework-level change, not a project-level one. The path is:
    [`config-resolver.js`](../scripts/lib/config-resolver.js).
 4. Add tests under `tests/lib/config-*.test.js` and confirm
    `tests/config-schema-mirror-drift.test.js` passes.
-5. Document the key in this file and update `agents-sync-config.md` only if
+5. Document the key in this file and update `mandrel-sync-config.md` only if
    the merge semantics differ from the default (project-wins) rule.
 
 ---
@@ -979,10 +979,10 @@ allowlists drift project-to-project.
 
 ### Cadence
 
-Run `/fewer-permission-prompts` **once per `/agents-update`
+Run `/fewer-permission-prompts` **once per `/mandrel-update`
 invocation**, immediately after the package upgrade re-materializes
 `.agents/` and before the bump commit lands. The cadence is codified in
-[`/agents-update` Step 3.6](../workflows/agents-update.md). The
+[`/mandrel-update` Step 3.6](../workflows/mandrel-update.md). The
 operator who just bumped `.agents/` has the freshest transcript context
 in the active session, which is exactly what the skill scans, so this
 is the cheapest time to surface new high-frequency calls.
@@ -1024,7 +1024,7 @@ on the next cadence run if they remain high-frequency, so the cost of
 deferral is bounded.
 
 Stage the accepted `.claude/settings.json` diff alongside the
-`/agents-update` bump commit so the reviewer sees the framework pointer
+`/mandrel-update` bump commit so the reviewer sees the framework pointer
 move and the allowlist response in the same diff.
 
 ---
@@ -1093,7 +1093,7 @@ mandrel uninstall --include-github # acknowledge GitHub-side follow-ups
 - Resolver entry point —
   [`config-resolver.js`](../scripts/lib/config-resolver.js)
 - Sync helper —
-  [`agents-sync-config.md`](../workflows/helpers/agents-sync-config.md)
+  [`mandrel-sync-config.md`](../workflows/helpers/mandrel-sync-config.md)
 - Bootstrap script —
   [`bootstrap.js`](../scripts/bootstrap.js)
 - Quality gates runbook (CRAP onboarding, MI ratchet, lint ratchet) —

package/.agents/docs/workflows.md

@@ -25,11 +25,10 @@ by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`
 fails when it drifts from the on-disk workflow set. To change a command’s
 description, edit the workflow file’s front-matter and regenerate.
 
-## Commands (27)
+## Commands (25)
 
 | 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. |
 | `/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. |
@@ -48,11 +47,10 @@ description, edit the workflow file’s front-matter and regenerate.
 | `/deliver` | Unified delivery entry point. Inspects the ticket type(s) and Epic-reference state of the supplied IDs, composes a sequential segment plan over any mix of Epics and standalone Stories, then delegates each segment to the Epic wave loop or the standalone multi-Story fan-out — preserving every flag and the parallel-delivery contract of the retired commands. |
 | `/explain` | Walk the operator through a code change until they genuinely understand it. Targets a PR, a branch, or the working-tree diff, then drives the `core/knowledge-transfer` skill (restate-first, why-ladder, mastery gates, persistent checklist) with an operator-controlled stop at every checkpoint. |
 | `/git-cleanup` | Tidy the local checkout in four phases: fast-forward `main`, prune stale remote-tracking refs, sweep merged branches (squash-aware), and triage `git stash` entries — each step gated by operator confirmation. |
-| `/git-commit-all` | Stage every untracked and modified file, then create a single conventional-commit on the current branch (no push). |
+| `/git-deliver` | Single ad-hoc delivery command for working-tree changes. Detects the git setup and escalates to the right terminal step — commit only, commit + push, or commit + push + open a PR with native auto-merge — picking the default from observable state and letting flags pin any level explicitly. Replaces the retired git-commit-all, git-push, and git-pr-all trio. |
 | `/git-merge-pr` | Analyze, validate, resolve conflicts, and merge a given pull request by number. |
-| `/git-pr-all` | Stage all outstanding changes, commit, push to a feature branch, and open a pull request with native auto-merge enabled. |
-| `/git-push` | Commit all outstanding changes then push to the remote repository. |
+| `/mandrel-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. |
 | `/plan` | Unified planning entry point. Routes a seed idea (via scope triage) or an existing Epic ID to the right planning path — the full Epic pipeline (PRD, Tech Spec, Acceptance Spec, decomposition) or the standalone-Story authoring path — and absorbs every planning flag. |
 | `/qa-assist` | Human-led QA assist loop — set up, then ride a rolling multi-observation intake session. The operator reports observations in any order; the agent enriches each (repro + root-cause file:line + coverage verdict for bugs; analysis + options + recommendation for enhancements), asks clarifying questions only when ambiguous, and appends a redacted ledger item — recording, never planning — to a persistent, resumable session under temp/qa/. Only when the operator says they are done does it review the full ledger and hand off to /plan. |
 | `/qa-explore` | Agent-led exploratory-QA loop — the agent Plans a surface with an explicit static-vs-drive method choice, drives it (browser MCP or static), and captures ledger items read-only, then Triages — a bounded per-surface session, HITL-gated at every phase transition, routed through the shared dedup/coverage/classification/missing-test/redaction/session core under temp/qa/ |
-| `/qa-run-harness` | Drive Gherkin scenarios through a real browser as an agent-driven QA sweep |
+| `/qa-run` | Drive Gherkin scenarios through a real browser as an agent-driven QA sweep |

package/.agents/schemas/qa-finding.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "QaFinding",
-  "description": "Structured `F#` finding emitted by the agent-driven QA harness (`.agents/workflows/qa-run-harness.md`, Epic #3214). One object per genuine problem surfaced while sweeping a consumer's Gherkin scenarios through chrome-devtools MCP: a non-allowlisted console error, a failed/error-status network request, or a gross design-token violation. Findings are validated against this schema before they are bundled by likely root cause into operator-approved follow-up ticket drafts (the harness never files tickets autonomously). The shape mirrors the F# convergence in Tech Spec #3285 and is produced in its console-derived subset by `.agents/scripts/lib/qa/console-allowlist.js`.",
+  "description": "Structured `F#` finding emitted by the agent-driven QA harness (`.agents/workflows/qa-run.md`, Epic #3214). One object per genuine problem surfaced while sweeping a consumer's Gherkin scenarios through chrome-devtools MCP: a non-allowlisted console error, a failed/error-status network request, or a gross design-token violation. Findings are validated against this schema before they are bundled by likely root cause into operator-approved follow-up ticket drafts (the harness never files tickets autonomously). The shape mirrors the F# convergence in Tech Spec #3285 and is produced in its console-derived subset by `.agents/scripts/lib/qa/console-allowlist.js`.",
   "type": "object",
   "additionalProperties": false,
   "required": [

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

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+/**
+ * apply-quality-bootstrap.js — Story #4171
+ * (refactor(mandrel-update): extract the quality-bootstrap heredoc into a
+ * tested script)
+ *
+ * Replaces the inline `node -e "Promise.all([...])"` heredoc that Step 3.5 of
+ * the `/mandrel-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() {

package/.agents/scripts/bootstrap.js

@@ -534,6 +534,13 @@ export function buildQuestions(defaults, flags, env = process.env, lists = {}) {
   const reposList = lists.reposList;
   const projectsList = lists.projectsList;
   const pickerOwner = (answers) => answers?.owner || owner;
+  // `owner` / `repo` are GitHub-side answers. When `--skip-github` suppresses
+  // the entire GitHub bootstrap, they are not required — this lets a
+  // non-interactive `--assume-yes --skip-github` run materialize and configure
+  // a fresh non-git directory (no inferable remote) without hard-failing on
+  // `missing required answers: owner, repo`. With GitHub bootstrap active they
+  // remain required (the target repo must be resolvable).
+  const skipGithub = Boolean(flags?.['skip-github']);
   return [
     {
       key: 'owner',
@@ -541,7 +548,7 @@ export function buildQuestions(defaults, flags, env = process.env, lists = {}) {
       env: 'GH_OWNER',
       message: '\n\nGitHub repo owner',
       default: defaults.owner,
-      required: true,
+      required: !skipGithub,
       validate: (v) =>
         /^[A-Za-z0-9][A-Za-z0-9-]*$/.test(v) ? null : 'Invalid GitHub owner',
     },
@@ -567,7 +574,7 @@ export function buildQuestions(defaults, flags, env = process.env, lists = {}) {
       pickerMessage:
         'GitHub repo name  - Select existing or press ENTER to create',
       default: defaults.repo,
-      required: true,
+      required: !skipGithub,
       picker: {
         list: (answers) => {
           if (Array.isArray(reposList) && reposList.length > 0)
@@ -957,7 +964,10 @@ export async function collectAndConfirm(state) {
     });
     if (missing.length > 0) {
       Logger.error(
-        `[Bootstrap] missing required answers: ${missing.join(', ')}`,
+        `[Bootstrap] missing required answers: ${missing.join(', ')}. ` +
+          'Pass them as flags (e.g. `--owner <name> --repo <name>`), or run ' +
+          'with `--skip-github` to configure the files/local setup only and ' +
+          'wire GitHub later.',
       );
       return { ok: false, exit: 1 };
     }