mandrel 1.90.0 → 1.92.0

package/.agents/scripts/plan-persist.js

@@ -0,0 +1,383 @@
+#!/usr/bin/env node
+
+/**
+ * plan-persist.js — single GitHub-write surface for the collapsed /plan
+ * flow (Epic #4474, PR3 — design §1 Step 3).
+ *
+ * Supersedes the retired 12-phase pipeline's separate persist halves
+ * (Epic #4474 PR7 — the delegate CLIs are import shims now, deleted next
+ * release). Given the author-written planning artifacts
+ * (Tech Spec, optional Acceptance Table, risk verdict, tickets JSON), this
+ * CLI performs every GitHub mutation of the plan flow in one ordered,
+ * fail-closed pass:
+ *
+ *   section gate → risk-verdict + mode-coherence → ticket validator /
+ *   file-assumption gate / DAG / budget → (ideation: open the Epic) →
+ *   Epic lease → managed sections + risk comment + freshness advisory →
+ *   story creation (structural reconciler) → inline healthcheck →
+ *   single terminal `agent::ready` flip (no intermediate
+ *   `agent::review-spec`) → checkpoint v2 + `plan-summary` comment with
+ *   the dry-run wave table → temp cleanup at terminal success only.
+ *
+ * Modes:
+ *   --epic <id>          Persist against an existing Epic. Artifact paths
+ *                        default to the per-Epic temp tree
+ *                        (`temp/epic-<id>/techspec.md`, `risk-verdict.json`,
+ *                        `tickets.json`, and `acceptance-spec.md` when
+ *                        present).
+ *   --one-pager <path>   Ideation mode: render + open the Epic from a
+ *                        sharpened one-pager first (folds the former
+ *                        Phase 3/4 steps in). Artifact paths must be
+ *                        explicit (there is no Epic id to derive them from).
+ *
+ * Modes (Epic #4474 PR4, design §2 mode matrix): the risk verdict's
+ * optional `deliveryShape` field selects between the full fan-out persist
+ * (default; requires tickets) and the spec-only single-delivery variant
+ * (`deliveryShape: "single"`; NO tickets — the ticket validator + DAG are
+ * skipped, fenced by construction, and the `delivery::single` routing
+ * marker is applied instead of a Story tree; inert until #4475 lands the
+ * deliver-side reader). `--amend` selects the change-request delta path:
+ * tickets carry `op: add|modify|keep|close` and the persist maps the ops
+ * onto the existing tree.
+ *
+ * Flags:
+ *   --force              Deliberate re-persist: overwrite managed sections,
+ *                        close + recreate the story tree (reconciler
+ *                        --explicit-delete). Reuses on-disk artifacts —
+ *                        cleanup is deferred to terminal success, so a
+ *                        failed run leaves them in place.
+ *   --resume             Continue a partial persist after a crash
+ *                        (rate-limit, network): sections short-circuit
+ *                        idempotently, the reconciler creates only the
+ *                        missing slugs from its per-slug state ledger.
+ *   --amend              Change-request delta persist: every ticket carries
+ *                        `op: add|modify|keep|close`; close-and-recreate is
+ *                        scoped to modify/close slugs only, keeps are
+ *                        untouched, and the DAG is validated over the
+ *                        merged set.
+ *   --explicit-delete    Confirm the close ops of an --amend plan (mirrors
+ *                        epic-reconcile.js). Without it, an amend carrying
+ *                        close ops prints the dry-run diff and exits 2.
+ *   --steal              Force-transfer a live foreign Epic-lease claim.
+ *   --force-review       Operator-forced review routing (recorded in the
+ *                        checkpoint's reviewRouting envelope).
+ *   --allow-over-budget / --allow-large-fan-out
+ *                        Same overrides as the retired split persist.
+ *
+ * Exit codes: 0 — persist complete, Epic is `agent::ready`; 1 — fatal
+ * error (see stderr); 2 — amend close ops require --explicit-delete (the
+ * dry-run diff is printed; nothing was mutated); 3 — reachability orphans
+ * (Epic #4474 PR6 named soft failure: the deterministic route-glob vs
+ * `planning.navigation.navRegistry` scan found route-adding draft stories
+ * with no navigation owner — the orphan-surface list is printed, nothing
+ * was mutated; apply one targeted amend and re-run the persist once). The
+ * Epic lease is released on every exit path.
+ */
+
+// Fail-fast if the framework's runtime deps are not installed — must be the
+// first import so the check runs before any third-party-importing sibling
+// module is evaluated (Story #3432).
+import './lib/runtime-deps/ensure-installed.js';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+
+import { runAsCli } from './lib/cli-utils.js';
+import { epicArtifactPath } from './lib/config/temp-paths.js';
+import {
+  PROJECT_ROOT,
+  resolveConfig,
+  validateOrchestrationConfig,
+} from './lib/config-resolver.js';
+import { Logger } from './lib/Logger.js';
+import { drainPendingCleanupAtBoot } from './lib/orchestration/epic-plan-spec/phases/drain.js';
+import { loadRiskVerdict } from './lib/orchestration/epic-plan-spec/phases/risk-verdict.js';
+import {
+  readPlanMetrics,
+  recordPlanInvocation,
+  renderPlanMetricsSummaryLine,
+  summarizePlanMetrics,
+} from './lib/orchestration/plan-metrics.js';
+import {
+  resolveDeliveryMode,
+  runPlanPersist,
+  writeCheckpointV2,
+} from './lib/orchestration/plan-persist/run-plan-persist.js';
+import {
+  buildPlanSummaryCommentBody,
+  buildWaveTable,
+  PLAN_SUMMARY_COMMENT_TYPE,
+} from './lib/orchestration/plan-persist/summary.js';
+import { createProvider } from './lib/provider-factory.js';
+
+// Re-exports for the stable public API (tests import through the CLI
+// module, mirroring the plan-context.js CLI-shell shape).
+export {
+  buildPlanSummaryCommentBody,
+  buildWaveTable,
+  PLAN_SUMMARY_COMMENT_TYPE,
+  resolveDeliveryMode,
+  runPlanPersist,
+  writeCheckpointV2,
+};
+
+export const EPIC_FROM_IDEA_TEMPLATE_PATH = path.resolve(
+  PROJECT_ROOT,
+  '.agents',
+  'templates',
+  'epic-from-idea.md',
+);
+
+const CLI_OPTIONS = {
+  epic: { type: 'string' },
+  'one-pager': { type: 'string' },
+  'tech-spec': { type: 'string' },
+  'acceptance-table': { type: 'string' },
+  'risk-verdict': { type: 'string' },
+  tickets: { type: 'string' },
+  force: { type: 'boolean', default: false },
+  resume: { type: 'boolean', default: false },
+  steal: { type: 'boolean', default: false },
+  'force-review': { type: 'boolean', default: false },
+  'allow-over-budget': { type: 'boolean', default: false },
+  'allow-large-fan-out': { type: 'boolean', default: false },
+  amend: { type: 'boolean', default: false },
+  'explicit-delete': { type: 'boolean', default: false },
+};
+
+const USAGE =
+  'Usage: plan-persist.js (--epic <EpicId> | --one-pager <file>) ' +
+  '[--tech-spec <file>] [--acceptance-table <file>] [--risk-verdict <file>] ' +
+  '[--tickets <file>] [--force | --resume | --amend [--explicit-delete]] ' +
+  '[--steal] [--force-review] [--allow-over-budget] [--allow-large-fan-out]';
+
+/**
+ * Parse `--epic`; returns null when absent (ideation mode).
+ */
+function parseEpicId(rawEpic) {
+  if (rawEpic === undefined) return null;
+  const epicId = Number.parseInt(rawEpic, 10);
+  if (Number.isNaN(epicId)) {
+    throw new Error(
+      `Invalid epic ID: "${rawEpic}" — must be a number.\n${USAGE}`,
+    );
+  }
+  return epicId;
+}
+
+/**
+ * Resolve the artifact file paths. Existing-Epic mode defaults each path to
+ * the per-Epic temp tree — the same locations the authoring skill writes to
+ * — so a `--force`/`--resume` re-persist reuses the on-disk artifacts with
+ * no re-typing (they survive until terminal success now that cleanup is
+ * deferred). Ideation mode has no Epic id to derive from, so the paths must
+ * be explicit.
+ */
+function resolveArtifactPaths({ epicId, values, config }) {
+  const fallback = (basename) =>
+    epicId === null ? undefined : epicArtifactPath(epicId, basename, config);
+  const techSpecPath = values['tech-spec'] ?? fallback('techspec.md');
+  const riskVerdictPath =
+    values['risk-verdict'] ?? fallback('risk-verdict.json');
+  const ticketsPath = values.tickets ?? fallback('tickets.json');
+  const acceptancePath =
+    values['acceptance-table'] ?? fallback('acceptance-spec.md');
+  if (!techSpecPath || !riskVerdictPath) {
+    throw new Error(
+      `Missing artifact path(s): ideation mode requires explicit --tech-spec and --risk-verdict.\n${USAGE}`,
+    );
+  }
+  return {
+    techSpecPath,
+    riskVerdictPath,
+    ticketsPath,
+    acceptancePath,
+    acceptanceExplicit: values['acceptance-table'] !== undefined,
+    ticketsExplicit: values.tickets !== undefined,
+  };
+}
+
+async function readOptional(filePath, { required }) {
+  try {
+    return await readFile(filePath, 'utf8');
+  } catch (err) {
+    if (!required && err?.code === 'ENOENT') return null;
+    throw new Error(`Cannot read ${filePath}: ${err.message}`);
+  }
+}
+
+async function main() {
+  const { values } = parseArgs({ options: CLI_OPTIONS });
+
+  if (values.force && values.resume) {
+    throw new Error('--force and --resume are mutually exclusive.');
+  }
+  if (values.amend && (values.force || values.resume)) {
+    throw new Error(
+      '--amend is mutually exclusive with --force/--resume — the amend ' +
+        'delta is already an incremental re-persist.',
+    );
+  }
+
+  const epicId = parseEpicId(values.epic);
+  const onePagerPath = values['one-pager'];
+  if (epicId === null && !onePagerPath) {
+    throw new Error(USAGE);
+  }
+  if (epicId !== null && onePagerPath) {
+    throw new Error(
+      '--epic and --one-pager are mutually exclusive (ideation mode opens ' +
+        `the Epic itself).\n${USAGE}`,
+    );
+  }
+
+  let config;
+  try {
+    config = resolveConfig();
+    validateOrchestrationConfig(config);
+  } catch (err) {
+    throw new Error(`Config schema validation failed:\n${err.message}`);
+  }
+  const settings = {
+    baseBranch: config.project?.baseBranch,
+    paths: config.project?.paths,
+    planning: config.planning,
+    docsContextFiles: config.project?.docsContextFiles,
+  };
+  const provider = createProvider(config);
+
+  try {
+    await drainPendingCleanupAtBoot({
+      repoRoot: PROJECT_ROOT,
+      config,
+      provider,
+    });
+  } catch (err) {
+    Logger.warn(`[plan-persist] pending-cleanup drain skipped: ${err.message}`);
+  }
+
+  const {
+    techSpecPath,
+    riskVerdictPath,
+    ticketsPath,
+    acceptancePath,
+    acceptanceExplicit,
+    ticketsExplicit,
+  } = resolveArtifactPaths({ epicId, values, config });
+
+  // Deterministic local reads + validation before any GitHub call. A
+  // malformed risk verdict fails closed here (Epic #3865); the section
+  // gate itself runs first inside runPlanPersist.
+  const techSpecContent = await readOptional(techSpecPath, { required: true });
+  const riskVerdict = loadRiskVerdict(riskVerdictPath);
+  // Tickets are mode-dependent (#4474 PR4): required when explicitly
+  // passed or in --amend mode; otherwise best-effort — a single-delivery
+  // plan authors no tickets file at all, and the mode-coherence gate
+  // (`resolveDeliveryMode`) hard-errors on every contradictory combination
+  // (including a stale tickets.json next to a `deliveryShape: "single"`
+  // verdict).
+  const ticketsRequired = ticketsExplicit || values.amend;
+  const ticketsRaw = ticketsPath
+    ? await readOptional(ticketsPath, { required: ticketsRequired })
+    : null;
+  let tickets = null;
+  if (ticketsRaw !== null) {
+    try {
+      tickets = JSON.parse(ticketsRaw);
+    } catch (err) {
+      throw new Error(
+        `Failed to parse tickets file "${ticketsPath}" as JSON: ${err.message}`,
+      );
+    }
+  }
+  // Acceptance table: explicit path is required to exist; the per-Epic
+  // default is best-effort (absent file → no acceptance section, matching
+  // the waived/none dispositions).
+  const acceptanceSpecContent = acceptancePath
+    ? await readOptional(acceptancePath, { required: acceptanceExplicit })
+    : null;
+  const onePagerContent = onePagerPath
+    ? await readOptional(onePagerPath, { required: true })
+    : null;
+  const templateContent = onePagerContent
+    ? await readOptional(EPIC_FROM_IDEA_TEMPLATE_PATH, { required: true })
+    : null;
+
+  // Plan-metrics ledger (#4474 PR1): stamp entry/exit + mode. Ideation runs
+  // have no Epic id at entry, so they stamp on the standalone stream.
+  const mode = values.amend
+    ? 'amend'
+    : values.resume
+      ? 'resume'
+      : values.force
+        ? 'force'
+        : 'persist';
+  let result;
+  try {
+    result = await recordPlanInvocation(
+      { cli: 'plan-persist', mode, epicId, config },
+      () =>
+        runPlanPersist({
+          epicId,
+          provider,
+          artifacts: {
+            techSpecContent,
+            acceptanceSpecContent,
+            riskVerdict,
+            tickets,
+            onePagerContent,
+            templateContent,
+          },
+          config,
+          settings,
+          opts: {
+            force: values.force,
+            resume: values.resume,
+            amend: values.amend,
+            explicitDelete: values['explicit-delete'],
+            steal: values.steal,
+            forceReview: values['force-review'],
+            allowOverBudget: values['allow-over-budget'],
+            allowLargeFanOut: values['allow-large-fan-out'],
+          },
+        }),
+    );
+  } catch (err) {
+    // Amend close-op confirmation gate (exit 2, mirroring the
+    // epic-reconcile.js contract): print the dry-run diff so the operator
+    // reviews exactly what would close, mutate nothing, and exit 2 so
+    // non-interactive callers can branch on the code.
+    if (err?.code === 'PLAN_AMEND_EXPLICIT_DELETE_REQUIRED') {
+      process.stdout.write(`${err.diff}\n\n${err.message}\n`);
+      process.exitCode = 2;
+      return;
+    }
+    // Reachability soft failure (#4474 PR6): the orphan-surface list is the
+    // message; nothing was mutated (the check runs before any provider
+    // call). Exit 3 so non-interactive callers can branch on the code.
+    if (err?.code === 'PLAN_REACHABILITY_ORPHANS') {
+      process.stdout.write(`${err.message}\n`);
+      process.exitCode = 3;
+      return;
+    }
+    throw err;
+  }
+
+  // Surface the whole plan run's invocation ledger in the persist summary
+  // (#4474 PR1). Additive and best-effort.
+  try {
+    const summary = summarizePlanMetrics(
+      await readPlanMetrics(result.epicId, config),
+    );
+    if (summary) {
+      result.planMetrics = summary;
+      Logger.info(`[plan-persist] ${renderPlanMetricsSummaryLine(summary)}`);
+    }
+  } catch (err) {
+    Logger.warn(`[plan-persist] plan-metrics summary skipped: ${err.message}`);
+  }
+
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+runAsCli(import.meta.url, main, { source: 'plan-persist' });

package/.agents/scripts/pr-watch-with-update.js

@@ -19,13 +19,13 @@
  *             IMMEDIATELY, consuming no resume budget. On red the CLI
  *             writes `temp/epic-<id>-ci-digest.{json,md}` (failing check
  *             name, run id, a `gh run view --log-failed` tail, and a
- *             coarse classification) and prints the `/loop
- *             /loops:fix-failing-tests` handoff.
+ *             coarse classification) and prints the red-green
+ *             remediation handoff.
  *   - STILL-RUNNING — the poll cap fired with checks still pending and
  *             none failed; the watcher re-armed up to
  *             `delivery.ci.watch.maxResumes` times, then returned a
  *             `still-running` verdict → exit 2 (NEVER 1, NEVER
- *             `timed_out`). The CLI prints the `/loop 5m /loops:watch-ci`
+ *             `timed_out`). The CLI prints the `gh pr checks --watch`
  *             handoff so the host can keep polling on its own cadence.
  *
  * Config (Story #4356 namespace, read via `getCiDelivery`):
@@ -350,9 +350,9 @@ export async function runPrWatch({
       .map(([k]) => k)
       .join(', ');
     logger.warn?.(
-      `[pr-watch] required check(s) still running after ${result.polls} polls + ${result.resumesApplied} resumes: ${stillPending}. Hand off to the interval watch loop:`,
+      `[pr-watch] required check(s) still running after ${result.polls} polls + ${result.resumesApplied} resumes: ${stillPending}. Keep polling natively:`,
     );
-    logger.warn?.('[pr-watch]   /loop 5m /loops:watch-ci');
+    logger.warn?.('[pr-watch]   gh pr checks <pr> --watch');
     return STILL_RUNNING_EXIT_CODE;
   }
 
@@ -392,8 +392,9 @@ export async function runPrWatch({
   if (digestPaths) {
     logger.error?.(`[pr-watch] CI failure digest → ${digestPaths.jsonPath}`);
   }
-  logger.error?.('[pr-watch] a required check failed. Drive it to green with:');
-  logger.error?.('[pr-watch]   /loop /loops:fix-failing-tests');
+  logger.error?.(
+    '[pr-watch] a required check failed. Read the digest, apply the smallest fix, and re-run the suite until green.',
+  );
   return 1;
 }
 

package/.agents/scripts/run-lint.js

@@ -56,6 +56,16 @@ const tasks = [
     cmd: 'node',
     args: ['.agents/scripts/check-lifecycle-lint.js'],
   },
+  {
+    // Custom Node-based lint for the workflow prose surface (Epic #4474
+    // PR5). Enforces: no workflow may instruct calling an exported
+    // library function that has no CLI entrypoint — the measured
+    // shim-writing failure mode the /plan collapse killed. See
+    // check-workflow-cli-lint.js for the paragraph-level heuristic.
+    name: 'workflow-cli-lint',
+    cmd: 'node',
+    args: ['.agents/scripts/check-workflow-cli-lint.js'],
+  },
   {
     // Custom Node-based lint for label-vocabulary citations in
     // `.agents/docs/SDLC.md` and `.agents/workflows/**/*.md` (Story #2892,
@@ -78,17 +88,6 @@ const tasks = [
     cmd: 'node',
     args: ['.agents/scripts/check-arch-cycles.js'],
   },
-  {
-    // Loop-unit frontmatter gate (Story #4288, Epic #4284). Validates
-    // every `.agents/workflows/loops/*.md` loop unit against
-    // `.agents/schemas/loop-unit.schema.json`. An absent/empty loops
-    // directory is a clean pass; a malformed unit (e.g. a self-paced
-    // cadence missing its required `verify`) fails the lint gate with a
-    // message naming the offending file + field.
-    name: 'loop-units',
-    cmd: 'node',
-    args: ['.agents/scripts/check-loop-units.js'],
-  },
 ];
 
 function runTask({ name, cmd, args }) {

package/.agents/scripts/single-story-init.js

@@ -59,6 +59,7 @@ import {
   executeFastForward,
   planFastForward,
 } from './lib/orchestration/git-cleanup/phases/fast-forward.js';
+import { verifyRemote } from './lib/orchestration/remote-verifier.js';
 import { acquireStoryLease } from './lib/orchestration/single-story-lease-guard.js';
 import {
   STATE_LABELS,
@@ -446,6 +447,7 @@ export async function runSingleStoryInit({
   injectedAcquireLease,
   steal = false,
   leaseNow,
+  injectedVerifyRemote,
 } = {}) {
   const parsed =
     storyIdParam !== undefined
@@ -487,6 +489,20 @@ export async function runSingleStoryInit({
   );
   progress('INIT', `Initializing standalone Story #${storyId}...`);
 
+  // Issue #4483 — deterministic remote evidence at the standalone entry
+  // seam (the counterpart to `epic-deliver-preflight.js`'s probe). The
+  // probe is read-only, so it runs under --dry-run too. The CLI records
+  // the fact; the workflow owns the `agent::blocked` transition on
+  // `remoteVerified: false` — inline delivery to local `main` is never a
+  // sanctioned fallback.
+  const remote = (injectedVerifyRemote ?? verifyRemote)({ cwd });
+  progress(
+    'REMOTE',
+    remote.remoteVerified
+      ? `✅ remoteVerified=true — ${remote.detail}`
+      : `⛔ remoteVerified=false — ${remote.detail}`,
+  );
+
   const story = await provider.getTicket(storyId);
   assertDeliverableStory(story, storyId);
 
@@ -563,6 +579,9 @@ export async function runSingleStoryInit({
     dependenciesInstalled,
     installFailed: installStatus.status === 'failed',
     dryRun,
+    // Issue #4483 — verified remote evidence for the orchestrating agent.
+    remoteVerified: remote.remoteVerified,
+    remoteProbe: { remoteUrl: remote.remoteUrl, detail: remote.detail },
   };
 
   // Upsert the `story-init` structured comment + flip Story to executing.
@@ -632,6 +651,8 @@ export function renderSingleStoryInitComment(result) {
     worktreeCreated: result.worktreeCreated,
     dependenciesInstalled: result.dependenciesInstalled,
     installStatus: result.installStatus,
+    remoteVerified: result.remoteVerified,
+    remoteProbe: result.remoteProbe,
   };
   return [
     '## Story init (standalone)',
@@ -641,6 +662,7 @@ export function renderSingleStoryInitComment(result) {
     `- **baseBranch:** \`${result.baseBranch}\``,
     `- **workCwd:** \`${result.workCwd}\``,
     `- **worktreeEnabled:** \`${result.worktreeEnabled}\``,
+    `- **remoteVerified:** \`${result.remoteVerified}\``,
     `- **dependenciesInstalled:** \`${result.dependenciesInstalled}\``,
     '',
     '```json',

package/.agents/scripts/story-plan.js

@@ -39,6 +39,7 @@ import { PROJECT_ROOT, resolveConfig } from './lib/config-resolver.js';
 import { exec as ghExec } from './lib/gh-exec.js';
 import { Logger, routeAllOutputToStderr } from './lib/Logger.js';
 import { TYPE_LABELS } from './lib/label-constants.js';
+import { recordPlanInvocation } from './lib/orchestration/plan-metrics.js';
 import { buildCorpusContext } from './lib/planning-corpus.js';
 import { createProvider } from './lib/provider-factory.js';
 import {
@@ -298,16 +299,27 @@ async function main() {
   if (values['emit-context']) {
     // Reserve stdout for the JSON envelope so a captured file is
     // unconditionally parseable by `JSON.parse`. Mirrors the contract
-    // `epic-plan-spec.js` enforces for its own --emit-context mode.
+    // `plan-context.js` enforces for its emit mode.
     routeAllOutputToStderr();
-    return runEmitContext({ values, provider, projectRoot, config });
+    // Plan-metrics ledger (#4474 PR1): standalone plans have no Epic, so
+    // `epicId: null` routes the stamp to the standalone stream
+    // (`temp/standalone/plan-metrics.json`) — same pattern as friction.
+    return recordPlanInvocation(
+      { cli: 'story-plan', mode: 'emit-context', epicId: null, config },
+      () => runEmitContext({ values, provider, projectRoot, config }),
+    );
   }
 
-  return runPersist({
-    values,
-    provider,
-    dryRun: values['dry-run'],
-  });
+  // Plan-metrics ledger (#4474 PR1): stamp entry/exit + mode.
+  return recordPlanInvocation(
+    { cli: 'story-plan', mode: 'persist', epicId: null, config },
+    () =>
+      runPersist({
+        values,
+        provider,
+        dryRun: values['dry-run'],
+      }),
+  );
 }
 
 runAsCli(import.meta.url, main, { source: 'story-plan' });

package/.agents/scripts/sync-claude-commands.js

@@ -47,7 +47,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { applyHeader } from './lib/command-header.js';
+import { applyHeader, isCommandExcluded } from './lib/command-header.js';
 import { Logger } from './lib/Logger.js';
 
 // Resolve the project root from the invocation cwd — the consumer project where
@@ -154,9 +154,7 @@ const isTopLevelWorkflow = (entry) =>
 /**
  * `README.md` (any case) under `loops/` is namespace documentation, not a
  * loop unit — it carries no `loop:` frontmatter and must not project as a
- * `/loops:README` command. Exclude it from the loop-unit enumeration (this
- * mirrors `check-loop-units.js#isLoopUnitFile`, which excludes it from the
- * lint gate).
+ * `/loops:README` command. Exclude it from the loop-unit enumeration.
  *
  * @param {import('node:fs').Dirent} entry
  * @returns {boolean}
@@ -204,13 +202,20 @@ const entries = SRC_DIRS.flatMap((dir) => [
 
 // Collision policy: payload wins, warn on a shadowed local file. Keyed by the
 // destination-relative path so a flat `foo.md` and a `loops/foo.md` are
-// distinct entries.
+// distinct entries. A workflow whose frontmatter carries `command: false`
+// (#4482 — dual-use audit lens files with a host-native standalone
+// equivalent) is excluded from projection entirely: it never enters
+// `sourceSet`, so any previously projected copy is reaped below.
 const byRel = new Map();
 for (const e of entries) {
   if (byRel.has(e.rel)) {
     Logger.warn(`  shadowed  ${e.rel} (local copy ignored; payload wins)`);
     continue;
   }
+  if (isCommandExcluded(fs.readFileSync(path.join(e.dir, e.rel), 'utf8'))) {
+    Logger.info(`  excluded ${e.rel} (frontmatter command: false)`);
+    continue;
+  }
   byRel.set(e.rel, e);
 }
 

package/.agents/skills/core/knowledge-transfer/SKILL.md

@@ -151,13 +151,17 @@ host's equivalent structured-choice surface.
 
 This skill is the engine behind two operator-facing entry points:
 
-- [`/explain`](../../../workflows/explain.md) — runs the loop over a realized
-  change (a PR, branch, or diff).
-- [`/plan`](../../../workflows/helpers/plan-epic.md) **Phase 11 — Plan
-  Comprehension Gate** — runs the loop over a freshly planned backlog before
-  the operator hands off to `/deliver`. That phase decides *whether* to
-  run via an LM-judgment predicate; this skill owns *how* it runs once
-  invoked.
+- **An ad-hoc conversational walkthrough** of a realized change (a PR,
+  branch, or diff) — the host's native mode. Read this skill and run the
+  loop directly when the operator asks to be walked through a change.
+  (The former `/explain` workflow wrapper was retired in #4482.)
+- **A post-plan backlog walkthrough** — run the loop over a freshly planned
+  backlog (the Epic body's Tech Spec sections, the Stories, the wave table)
+  before the operator hands off to `/deliver`. Offer it by LM judgment on
+  non-trivial plans; it is no longer a wired phase of
+  [`/plan`](../../../workflows/helpers/plan-epic.md) (the comprehension gate
+  was unwired from the pipeline in Epic #4474), always advisory, and never
+  blocks the hand-off.
 
 It is discovered through the standard skill-activation contract in
 [`.agents/instructions.md` § 1.B](../../../instructions.md) — no separate

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

@@ -283,14 +283,12 @@ 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
 recurring cadence so the drift is caught before it compounds:
 
-- **Cron loop** — [`loops:nightly-audit`](loops/nightly-audit.md)
-  runs the audit sweep unattended each night; the host (`/schedule` or a
-  cron-driven `/loop`) owns the cadence. Point it at this lens full-scope
-  (no `--paths`, no change-set filter — the `{{changedFiles}}` block renders
-  the literal token, so the whole target-set union is audited).
 - **Scheduled invocation** — `/schedule` running `/audit-documentation`
-  full-scope on a daily/weekly cron is the equivalent one-shot form when a
-  standing loop is not wired up.
+  full-scope on a daily/weekly cron. Point it at this lens full-scope
+  (no `--paths`, no change-set filter — the `{{changedFiles}}` block renders
+  the literal token, so the whole target-set union is audited). The nightly
+  sweep-then-route recipe lives in
+  [`audit-to-stories.md` § Scheduling a nightly sweep](audit-to-stories.md#scheduling-a-nightly-sweep).
 
 Route the resulting `audit-documentation-results.md` through
 [`/audit-to-stories`](audit-to-stories.md), which groups the findings,

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

@@ -1,5 +1,6 @@
 ---
 description: Run a Lighthouse audit (Performance / Accessibility / Best Practices / SEO) and produce a structured findings report
+command: false
 ---
 
 # Lighthouse Audit & Analysis

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

@@ -1,5 +1,6 @@
 ---
 description: Audit dependency CVEs, input-validation gaps, secrets handling, and auth boundaries; emit a structured High/Medium/Low findings report.
+command: false
 ---
 
 # Security & Vulnerability Audit