mandrel 1.57.0

package/.agents/scripts/lib/config/retro.js

@@ -0,0 +1,77 @@
+/**
+ * Retro accessor (Story #3042 / Task #3043 — Epic #3019).
+ *
+ * Resolves `.agentrc.json → delivery.retro` into the canonical shape the
+ * retro-runner consumes. Currently exposes only `perfThresholds`, the
+ * operator-tunable gates for the perf-signals classifier in
+ * `lib/orchestration/retro-perf-heuristics.js`.
+ *
+ * Defaults mirror `DEFAULT_RETRO_PERF_THRESHOLDS` in the heuristics module
+ * (single source of behavioural truth; this resolver is a thin merge layer).
+ */
+
+/**
+ * Default perf-threshold trio applied when `.agentrc.json` omits
+ * `delivery.retro.perfThresholds` (or any of its sub-keys). Frozen so
+ * downstream callers cannot accidentally mutate the resolver's defaults
+ * across processes.
+ *
+ * Keep in lockstep with `DEFAULT_RETRO_PERF_THRESHOLDS` in
+ * `lib/orchestration/retro-perf-heuristics.js` and the schema mirror in
+ * `agentrc.schema.json → $defs.retro.properties.perfThresholds`.
+ */
+export const DEFAULT_RETRO = Object.freeze({
+  perfThresholds: Object.freeze({
+    utilisation: 0.6,
+    bootstrapShare: 0.4,
+    capBindingRunLength: 2,
+  }),
+});
+
+/**
+ * Read the merged retro block. Returns the canonical shape:
+ *
+ *   {
+ *     perfThresholds: {
+ *       utilisation: number,
+ *       bootstrapShare: number,
+ *       capBindingRunLength: number,
+ *     },
+ *   }
+ *
+ * Each sub-key falls back to its documented default when the resolved
+ * `.agentrc.json` omits it. Out-of-range values fall back to defaults too —
+ * the AJV schema rejects them before they reach this accessor, but the
+ * resolver stays defensive so unit-test fixtures and degraded configs
+ * never produce nonsensical thresholds.
+ *
+ * @param {object | null | undefined} config
+ * @returns {{ perfThresholds: { utilisation: number, bootstrapShare: number, capBindingRunLength: number } }}
+ */
+export function getRetro(config) {
+  const user = config?.delivery?.retro?.perfThresholds ?? {};
+  const defaults = DEFAULT_RETRO.perfThresholds;
+  return {
+    perfThresholds: {
+      utilisation: resolveUnit(user.utilisation, defaults.utilisation),
+      bootstrapShare: resolveUnit(user.bootstrapShare, defaults.bootstrapShare),
+      capBindingRunLength: resolvePositiveInt(
+        user.capBindingRunLength,
+        defaults.capBindingRunLength,
+      ),
+    },
+  };
+}
+
+function resolveUnit(value, fallback) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
+  if (value < 0 || value > 1) return fallback;
+  return value;
+}
+
+function resolvePositiveInt(value, fallback) {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+    return fallback;
+  }
+  return value;
+}

package/.agents/scripts/lib/config/runners.js

@@ -0,0 +1,105 @@
+/**
+ * Runner accessor (Epic #1720 Story #1739 — top-level reshape).
+ *
+ * Post-reshape, only `delivery.deliverRunner`, `delivery.epicAudit`, and
+ * `delivery.codeReview` are configurable; everything else lives in
+ * framework-internal constants exported alongside (`DEFAULT_STORY_MERGE_RETRY`,
+ * `DEFAULT_DECOMPOSER`).
+ */
+
+/** Hardcoded story-merge retry policy (was `orchestration.runners.storyMergeRetry`). */
+export const DEFAULT_STORY_MERGE_RETRY = Object.freeze({
+  maxAttempts: 3,
+  backoffMs: Object.freeze([250, 500, 1000]),
+});
+
+/** Hardcoded decomposer concurrency cap (was `orchestration.runners.decomposer.concurrencyCap`). */
+export const DEFAULT_DECOMPOSER = Object.freeze({
+  concurrencyCap: 3,
+});
+
+/**
+ * Hardcoded deliver-runner defaults. Operators override via
+ * `delivery.deliverRunner.*` in `.agentrc.json`.
+ *
+ * **Throughput tradeoff — `concurrencyCap`.**
+ * The default of 3 is intentionally conservative: it keeps host-quota
+ * consumption low for Epics with small waves and avoids saturating the
+ * GitHub API with concurrent label writes. For wide-wave Epics where the
+ * host has adequate parallel-agent quota, operators should raise
+ * `delivery.deliverRunner.concurrencyCap` — wall-clock time falls
+ * proportionally to the extra concurrency. The safe default is a tuning
+ * knob, not a performance ceiling. See `epic-deliver.md` § Phase 2b and
+ * `agentrc-reference.json` `delivery.deliverRunner.concurrencyCap` for details.
+ *
+ * **`verifyConcurrencyCap`** (Epic #3019 Tech Spec §1.4 / Story #3024) is a
+ * separate knob that bounds the `verifyWaveResults` loop independently of
+ * Story-dispatch concurrency, so operators can tune ticket-verify parallelism
+ * without raising the wave fan-out. Default 4.
+ */
+const DEFAULT_DELIVER_RUNNER = Object.freeze({
+  concurrencyCap: 3,
+  progressReportIntervalSec: 120,
+  verifyConcurrencyCap: 4,
+});
+
+/**
+ * Default auto-fix loop ceilings for /epic-deliver Phase 4 (epic-audit)
+ * and Phase 5 (code-review). Operators override via
+ * `delivery.epicAudit.*` and `delivery.codeReview.*` in `.agentrc.json`
+ * (Story #2611, Epic #2586).
+ */
+export const DEFAULT_EPIC_AUDIT = Object.freeze({
+  maxFixAttempts: 3,
+  maxFixScopeFiles: 5,
+});
+
+export const DEFAULT_CODE_REVIEW = Object.freeze({
+  maxFixAttempts: 3,
+  maxFixScopeFiles: 5,
+});
+
+/**
+ * Read the merged deliver-runner block.
+ *
+ * @param {object | null | undefined} config
+ * @returns {{
+ *   deliverRunner: { concurrencyCap: number, progressReportIntervalSec: number, verifyConcurrencyCap: number },
+ *   epicAudit: { maxFixAttempts: number, maxFixScopeFiles: number },
+ *   codeReview: { maxFixAttempts: number, maxFixScopeFiles: number },
+ *   storyMergeRetry: { maxAttempts: number, backoffMs: readonly number[] },
+ *   decomposer: { concurrencyCap: number },
+ * }}
+ */
+export function getRunners(config) {
+  const deliverRunnerUser = config?.delivery?.deliverRunner ?? {};
+  const epicAuditUser = config?.delivery?.epicAudit ?? {};
+  const codeReviewUser = config?.delivery?.codeReview ?? {};
+  return {
+    deliverRunner: {
+      concurrencyCap:
+        deliverRunnerUser.concurrencyCap ??
+        DEFAULT_DELIVER_RUNNER.concurrencyCap,
+      progressReportIntervalSec:
+        deliverRunnerUser.progressReportIntervalSec ??
+        DEFAULT_DELIVER_RUNNER.progressReportIntervalSec,
+      verifyConcurrencyCap:
+        deliverRunnerUser.verifyConcurrencyCap ??
+        DEFAULT_DELIVER_RUNNER.verifyConcurrencyCap,
+    },
+    epicAudit: {
+      maxFixAttempts:
+        epicAuditUser.maxFixAttempts ?? DEFAULT_EPIC_AUDIT.maxFixAttempts,
+      maxFixScopeFiles:
+        epicAuditUser.maxFixScopeFiles ?? DEFAULT_EPIC_AUDIT.maxFixScopeFiles,
+    },
+    codeReview: {
+      maxFixAttempts:
+        codeReviewUser.maxFixAttempts ?? DEFAULT_CODE_REVIEW.maxFixAttempts,
+      maxFixScopeFiles:
+        codeReviewUser.maxFixScopeFiles ?? DEFAULT_CODE_REVIEW.maxFixScopeFiles,
+    },
+    storyMergeRetry: DEFAULT_STORY_MERGE_RETRY,
+    decomposer: DEFAULT_DECOMPOSER,
+  };
+}

package/.agents/scripts/lib/config/runtime.js

@@ -0,0 +1,167 @@
+/**
+ * Runtime-environment resolution helpers (Epic #773 Story 6 — split out of
+ * config-resolver.js). Reads `process.env` to determine worktree-isolation
+ * state, the per-process session id, and the canonical working path the
+ * agent should `cd` into for a given Story.
+ */
+
+import crypto from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+
+const SESSION_ID_LENGTH = 12;
+const SESSION_ID_ALLOWED_CHAR_RE = /[^a-z0-9]/g;
+
+/**
+ * Resolve whether worktree isolation is enabled for this process, with strict
+ * environment-variable precedence that outranks the committed config value.
+ *
+ * Precedence:
+ *   1. `env.AP_WORKTREE_ENABLED === 'true'`  → true   (explicit operator override)
+ *   2. `env.AP_WORKTREE_ENABLED === 'false'` → false  (explicit operator override)
+ *   3. `env.CLAUDE_CODE_REMOTE === 'true'`   → false  (web session auto-detect)
+ *   4. else                                  → Boolean(config.delivery.worktreeIsolation.enabled)
+ *
+ * String matching on `AP_WORKTREE_ENABLED` is deliberate: `""`, `"0"`, or any
+ * other truthy-ish shell expansion must not flip the flag.
+ *
+ * @param {{ config?: { delivery?: { worktreeIsolation?: { enabled?: boolean } } | null } }} [opts]
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {boolean}
+ */
+export function resolveWorktreeEnabled(opts = {}, env = process.env) {
+  if (env.AP_WORKTREE_ENABLED === 'true') return true;
+  if (env.AP_WORKTREE_ENABLED === 'false') return false;
+  if (env.CLAUDE_CODE_REMOTE === 'true') return false;
+  return Boolean(opts.config?.delivery?.worktreeIsolation?.enabled);
+}
+
+/**
+ * Resolve the absolute working path the agent should `cd` into for a given
+ * Story. When worktree isolation is on, returns the per-story worktree path
+ * (`<repoRoot>/<wtRoot>/story-<id>`). When off, returns the repo root so
+ * init, close, and recovery converge on a single canonical path with no
+ * undefined-path access on the off-branch.
+ *
+ * Pure helper — no fs / git side effects. Path-traversal containment for
+ * `worktreeRoot` is enforced earlier by `validateOrchestrationConfig`.
+ *
+ * @param {object} opts
+ * @param {boolean} opts.worktreeEnabled
+ * @param {string} opts.repoRoot          Absolute path to the main checkout.
+ * @param {number|string} [opts.storyId]  Required when `worktreeEnabled` is true.
+ * @param {string} [opts.worktreeRoot]    Worktree root relative to repoRoot. Defaults to `.worktrees`.
+ * @returns {string} Absolute path the agent should work from.
+ */
+export function resolveWorkingPath({
+  worktreeEnabled,
+  repoRoot,
+  storyId,
+  worktreeRoot = '.worktrees',
+} = {}) {
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) {
+    throw new Error('resolveWorkingPath: repoRoot is required');
+  }
+  // Caller is responsible for passing an already-absolute repoRoot (every
+  // production caller threads `path.resolve(...)` upstream). We do not
+  // re-resolve here so unit-test fixtures that pass sentinel paths like
+  // `/repo` keep their semantics on Windows.
+  if (!worktreeEnabled) return repoRoot;
+  if (storyId == null) {
+    throw new Error(
+      'resolveWorkingPath: storyId is required when worktreeEnabled is true',
+    );
+  }
+  return path.join(repoRoot, worktreeRoot, `story-${storyId}`);
+}
+
+/**
+ * One-shot environment-aware runtime resolution. Returns the trio of runtime
+ * signals consumed across `/epic-deliver`: whether worktree isolation is on
+ * for this process, the session id for claim labels, and whether we're in a
+ * Claude Code web session. Each signal also records its **source** so the
+ * `story-init` startup log can name why the value is what it is.
+ *
+ * @param {{ config?: object }} [opts]
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {{
+ *   worktreeEnabled: boolean,
+ *   worktreeEnabledSource: 'env-override' | 'remote-auto' | 'config',
+ *   sessionId: string,
+ *   sessionIdSource: 'remote' | 'local',
+ *   isRemote: boolean,
+ * }}
+ */
+export function resolveRuntime(opts = {}, env = process.env) {
+  const worktreeEnabled = resolveWorktreeEnabled(opts, env);
+  const worktreeEnabledSource =
+    env.AP_WORKTREE_ENABLED === 'true' || env.AP_WORKTREE_ENABLED === 'false'
+      ? 'env-override'
+      : env.CLAUDE_CODE_REMOTE === 'true'
+        ? 'remote-auto'
+        : 'config';
+
+  const remoteId = env.CLAUDE_CODE_REMOTE_SESSION_ID;
+  const remoteUsable =
+    typeof remoteId === 'string' &&
+    remoteId.toLowerCase().replace(SESSION_ID_ALLOWED_CHAR_RE, '').length > 0;
+  const sessionId = resolveSessionId(env);
+  const sessionIdSource = remoteUsable ? 'remote' : 'local';
+
+  return {
+    worktreeEnabled,
+    worktreeEnabledSource,
+    sessionId,
+    sessionIdSource,
+    isRemote: env.CLAUDE_CODE_REMOTE === 'true',
+  };
+}
+
+/**
+ * Resolve the per-process session-id used for claim labels and structured
+ * comments. Prefers the Anthropic-provided `CLAUDE_CODE_REMOTE_SESSION_ID`
+ * (sanitised and truncated) and falls back to a locally-generated short id
+ * derived from hostname + pid + random entropy.
+ *
+ * Sanitisation for the remote id:
+ *   1. Lower-case.
+ *   2. Strip every character outside `[a-z0-9]`.
+ *   3. Truncate to {@link SESSION_ID_LENGTH} (12) chars.
+ *   4. If the sanitised result is empty, fall back to the locally-generated id
+ *      — an all-symbol remote id is not a usable label suffix.
+ *
+ * The return value is always a string of 1..12 chars matching `[a-z0-9]+`,
+ * suitable for inclusion in log lines and any future label suffixes without
+ * further escaping. See tech spec #670 § Security — Env-var injection.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string}
+ */
+export function resolveSessionId(env = process.env) {
+  const remote = env.CLAUDE_CODE_REMOTE_SESSION_ID;
+  if (typeof remote === 'string' && remote.length > 0) {
+    const sanitised = remote
+      .toLowerCase()
+      .replace(SESSION_ID_ALLOWED_CHAR_RE, '')
+      .slice(0, SESSION_ID_LENGTH);
+    if (sanitised.length > 0) return sanitised;
+  }
+  return generateLocalSessionId();
+}
+
+function generateLocalSessionId() {
+  // Layout: 2 host chars + 2 pid chars + 8 random hex chars = 12 chars. The
+  // random suffix is load-bearing for uniqueness; host/pid hints are
+  // operator-friendly context, not identifiers.
+  const host = (os.hostname() || 'h')
+    .toLowerCase()
+    .replace(SESSION_ID_ALLOWED_CHAR_RE, '')
+    .slice(0, 2)
+    .padEnd(2, '0');
+  const pid = String(process.pid)
+    .replace(SESSION_ID_ALLOWED_CHAR_RE, '')
+    .slice(-2)
+    .padStart(2, '0');
+  const rand = crypto.randomBytes(4).toString('hex'); // 8 hex chars
+  return `${host}${pid}${rand}`.slice(0, SESSION_ID_LENGTH);
+}

package/.agents/scripts/lib/config/shared.js

@@ -0,0 +1,46 @@
+/**
+ * Cross-block helpers for the lib/config/* sub-modules (Epic #773 Story 6).
+ *
+ * Lives outside the per-sub-block files because more than one resolver needs
+ * the same merge primitives. Adding a helper here is appropriate when ≥ 2
+ * sub-block resolvers would otherwise duplicate the same logic; keep
+ * single-use helpers private to their own sub-block.
+ */
+
+/**
+ * Deep-merge a list-valued config key with its framework default.
+ *
+ * Accepts:
+ *   - `undefined`           → return a copy of `defaultList`
+ *   - plain array           → replace wholesale (returns a copy)
+ *   - `{ append, prepend }` → extend `defaultList`; items already present in
+ *                             the result are deduped so a consumer appending
+ *                             a framework entry does not produce a duplicate.
+ *
+ * @param {readonly string[]} defaultList
+ * @param {unknown} userValue
+ * @returns {string[]}
+ */
+export function resolveListValue(defaultList, userValue) {
+  if (userValue === undefined) return [...defaultList];
+  if (Array.isArray(userValue)) return [...userValue];
+  if (userValue !== null && typeof userValue === 'object') {
+    const result = [];
+    const seen = new Set();
+    const push = (item) => {
+      if (!seen.has(item)) {
+        result.push(item);
+        seen.add(item);
+      }
+    };
+    if (Array.isArray(userValue.prepend)) {
+      for (const item of userValue.prepend) push(item);
+    }
+    for (const item of defaultList) push(item);
+    if (Array.isArray(userValue.append)) {
+      for (const item of userValue.append) push(item);
+    }
+    return result;
+  }
+  return [...defaultList];
+}

package/.agents/scripts/lib/config/sync-agentrc.js

@@ -0,0 +1,243 @@
+/**
+ * sync-agentrc — default-aware `.agentrc.json` reconciliation (Story #1995).
+ *
+ * Replaces the template-diff merge the helper procedure previously
+ * described. The new contract:
+ *
+ *   1. Validate the project config against the framework schema. Any
+ *      failure aborts the run with a diagnostic — never silently strip.
+ *   2. Never auto-fill optional keys from the template. The runtime
+ *      already layers `*_DEFAULTS` underneath the project config at
+ *      read time, so an absent key resolves to the framework default
+ *      without needing to be written into `.agentrc.json`.
+ *   3. For every project leaf whose value deep-equals the framework
+ *      default at that path, emit a `[REDUNDANT]` advisory row.
+ *      Advisories are informational only — the project file is left
+ *      untouched. Operators who want a leaner config can prune the
+ *      redundant keys by hand.
+ *
+ * Outcome: after `/agents-update`, `.agentrc.json` contains only keys
+ * that materially diverge from framework defaults, plus the
+ * consumer-identity keys with no sensible framework default (owner,
+ * repo, operatorHandle).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { AGENTRC_SCHEMA, getAgentrcValidator } from '../config-schema.js';
+import { deepEqual } from '../json-utils.js';
+import {
+  getAgentrcDefaults,
+  IDENTITY_PLACEHOLDER_PATHS,
+  iterDefaultLeaves,
+  lookupPath,
+} from './defaults.js';
+
+/**
+ * @typedef {Object} SyncChange
+ * @property {'REDUNDANT'|'ADDED'|'ERROR'} op
+ * @property {string} path
+ * @property {unknown} [value]
+ * @property {string} [reason]
+ */
+
+/**
+ * @typedef {Object} SyncResult
+ * @property {'noop'|'updated'|'invalid'|'missing-config'} status
+ * @property {SyncChange[]} changes
+ * @property {string[]} errors
+ * @property {string} configPath
+ * @property {boolean} wrote whether `.agentrc.json` was rewritten
+ */
+
+const IDENTITY_SET = new Set(IDENTITY_PLACEHOLDER_PATHS);
+
+/**
+ * Run the reconciliation against a project root.
+ *
+ * @param {{ projectRoot: string, defaults?: object, fsImpl?: typeof fs }} opts
+ * @returns {SyncResult}
+ */
+export function syncAgentrc(opts) {
+  const projectRoot = path.resolve(opts.projectRoot);
+  const fsImpl = opts.fsImpl ?? fs;
+  const configPath = path.join(projectRoot, '.agentrc.json');
+  const defaults = opts.defaults ?? getAgentrcDefaults();
+
+  if (!fsImpl.existsSync(configPath)) {
+    return {
+      status: 'missing-config',
+      changes: [],
+      errors: [
+        `No .agentrc.json at ${configPath}. Run /agents-bootstrap-project first.`,
+      ],
+      configPath,
+      wrote: false,
+    };
+  }
+
+  let raw;
+  try {
+    raw = JSON.parse(fsImpl.readFileSync(configPath, 'utf8'));
+  } catch (err) {
+    return {
+      status: 'invalid',
+      changes: [],
+      errors: [`Failed to parse .agentrc.json: ${err.message}`],
+      configPath,
+      wrote: false,
+    };
+  }
+
+  const validate = getAgentrcValidator();
+  if (!validate(raw)) {
+    const errors = (validate.errors || []).map(
+      (e) => `${e.instancePath || '(root)'} ${e.message}`,
+    );
+    return {
+      status: 'invalid',
+      changes: [],
+      errors,
+      configPath,
+      wrote: false,
+    };
+  }
+
+  const changes = collectRedundantAdvisories(raw, defaults);
+
+  return {
+    status: 'noop',
+    changes,
+    errors: [],
+    configPath,
+    wrote: false,
+  };
+}
+
+/**
+ * Walk every default leaf path. When the project carries the same path
+ * with a deep-equal value, emit a `[REDUNDANT]` advisory. Skip identity
+ * placeholder paths (those have no usable default) and skip leaves the
+ * schema requires at their immediate parent (deleting them would
+ * invalidate the config).
+ *
+ * @param {object} project
+ * @param {object} defaults
+ * @param {object} [schema] — schema to consult for `required` arrays.
+ *   Defaults to the runtime AJV schema. Tests can inject a synthetic
+ *   schema to exercise the walk in isolation.
+ * @returns {SyncChange[]}
+ */
+export function collectRedundantAdvisories(
+  project,
+  defaults,
+  schema = AGENTRC_SCHEMA,
+) {
+  const out = [];
+  for (const [dotted, defValue] of iterDefaultLeaves(defaults)) {
+    if (IDENTITY_SET.has(dotted)) continue;
+    if (!isLeafSchemaRemovable(schema, dotted)) continue;
+    const found = lookupPath(project, dotted);
+    if (!found.present) continue;
+    if (deepEqual(found.value, defValue)) {
+      out.push({
+        op: 'REDUNDANT',
+        path: dotted,
+        value: defValue,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Walk a (pre-resolved, $ref-free) JSON Schema along a dotted path and
+ * report whether the leaf can be removed without invalidating its
+ * immediate parent. A leaf is schema-removable when it does NOT appear
+ * in its immediate-parent object's `required[]`.
+ *
+ * Only the leaf segment's membership in its parent's `required[]`
+ * matters. An ancestor being listed as required at a higher level
+ * (e.g. root requires `project`) does NOT prevent removing a
+ * non-required descendant (e.g. `project.baseBranch`) — the ancestor
+ * stays present, only the optional leaf disappears.
+ *
+ * The runtime AJV schema (`AGENTRC_SCHEMA`) is already fully inlined —
+ * no `$ref` indirection — so a simple `properties[key]` descent
+ * suffices. When the walk falls off the schema (the path isn't covered
+ * by any `properties` entry), the leaf is treated as removable: the
+ * advisory layer is purely informational and would-be advisories for
+ * keys the schema doesn't constrain are harmless.
+ *
+ * @param {object} rootSchema
+ * @param {string} dottedPath
+ * @returns {boolean}
+ */
+export function isLeafSchemaRemovable(rootSchema, dottedPath) {
+  if (!rootSchema || typeof rootSchema !== 'object') return true;
+  const parts = dottedPath.split('.');
+  let cursor = rootSchema;
+  for (let i = 0; i < parts.length; i += 1) {
+    const key = parts[i];
+    if (!cursor || typeof cursor !== 'object') return true;
+    const props = cursor.properties;
+    if (!props || !Object.hasOwn(props, key)) return true;
+    const isLeafSegment = i === parts.length - 1;
+    if (
+      isLeafSegment &&
+      Array.isArray(cursor.required) &&
+      cursor.required.includes(key)
+    ) {
+      return false;
+    }
+    cursor = props[key];
+  }
+  return true;
+}
+
+/**
+ * Format a sync result for terminal display.
+ *
+ * @param {SyncResult} result
+ * @returns {string}
+ */
+export function formatSyncReport(result) {
+  const lines = [];
+  if (result.status === 'missing-config') {
+    lines.push('[sync-agentrc] ❌ No project config found.');
+    for (const err of result.errors) lines.push(`  - ${err}`);
+    return lines.join('\n');
+  }
+  if (result.status === 'invalid') {
+    lines.push('[sync-agentrc] ❌ Validation failed:');
+    for (const err of result.errors) lines.push(`  - ${err}`);
+    return lines.join('\n');
+  }
+  const redundant = result.changes.filter((c) => c.op === 'REDUNDANT');
+  if (redundant.length === 0) {
+    lines.push('[sync-agentrc] ✅ No changes required.');
+    return lines.join('\n');
+  }
+  lines.push('[sync-agentrc] ✅ No changes required.');
+  lines.push(
+    `[sync-agentrc] Advisories: ${redundant.length} project key(s) match framework defaults — informational only.`,
+  );
+  for (const c of redundant) {
+    lines.push(`  [REDUNDANT] ${c.path} = ${previewValue(c.value)}`);
+  }
+  lines.push(
+    '[sync-agentrc] Redundant keys are safe to delete — the runtime layers framework defaults at read time.',
+  );
+  return lines.join('\n');
+}
+
+function previewValue(value) {
+  let s;
+  try {
+    s = JSON.stringify(value);
+  } catch {
+    s = String(value);
+  }
+  if (s == null) return 'undefined';
+  return s.length > 80 ? `${s.slice(0, 77)}...` : s;
+}