mandrel 2.59.0 → 2.61.0

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

@@ -1,69 +1,30 @@
-/**
- * Runner accessor (Epic #1720 Story #1739 — top-level reshape).
- *
- * Post-reshape, only `delivery.deliverRunner` and `delivery.codeReview` are
- * configurable via this accessor; everything else lives in framework-internal
- * constants exported alongside (`DEFAULT_DECOMPOSER`).
- * `delivery.epicAudit` was removed on v2 (Story-only delivery — no
- * epic-audit runner; remediation policy lives on `delivery.codeReview`).
- */
+/** `delivery.deliverRunner` / `delivery.codeReview` accessor. */
 
-/** 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 moderate: it keeps host-quota
- * consumption predictable for multi-Story plan-runs and avoids saturating
- * the GitHub API with concurrent label writes, while still allowing a
- * small ready-set fan-out. Operators who want strictly sequential delivery
- * should set `delivery.deliverRunner.concurrencyCap: 1`. Raising the cap
- * reduces wall-clock time where dependencies allow. See `mandrel-deliver.md` and
- * `agentrc-reference.json` `delivery.deliverRunner.concurrencyCap`.
- *
- * Story #4545 removed the sibling `verifyConcurrencyCap`: the
- * `verifyWaveResults` loop it claimed to bound never existed in the tree, and
- * its only reader was the retired execution-analysis CLI, which echoed the
- * number into a report rather than bounding anything.
- *
- * **Serialization tradeoff — `footprintGuard`.** `enforce` is the default and
- * stays it: the file-overlap guard encodes delivery-time-only knowledge (which
- * implementation windows are open, which Stories a foreign lease holds) that no
- * plan-time `depends_on` edge can carry, so demoting it by default would trade
- * a real merge-conflict class for throughput nobody asked for. `advisory`
- * detects collisions and reports every would-be withhold but lets dispatch
- * follow the declared edges alone — for runs whose ordering is fully declared
- * (Story #5044).
+ * `concurrencyCap` 3 keeps host quota and concurrent GitHub label writes
+ * predictable. `footprintGuard: 'enforce'` stays the default: the overlap
+ * guard knows delivery-time state (open windows, foreign leases) no plan-time
+ * `depends_on` edge can carry; `advisory` reports would-be withholds but
+ * dispatches on declared edges alone.
  */
 const DEFAULT_DELIVER_RUNNER = Object.freeze({
   concurrencyCap: 3,
   footprintGuard: 'enforce',
 });
 
-/**
- * Default auto-fix loop ceilings for /mandrel-deliver code-review. Operators
- * override via `delivery.codeReview.*` in `.agentrc.json` (Story #2611,
- * Epic #2586; `autoFixSeverity` default `'medium'` per Story #4399).
- * `maxFixScopeFiles` was retired in Story #5313 — it bounded a fix by file
- * count rather than by risk.
- */
 export const DEFAULT_CODE_REVIEW = Object.freeze({
-  maxFixAttempts: 3,
   autoFixSeverity: 'medium',
 });
 
 /**
- * Read the merged deliver-runner block.
- *
  * @param {object | null | undefined} config
  * @returns {{
  *   deliverRunner: { concurrencyCap: number, footprintGuard: 'enforce'|'advisory' },
- *   codeReview: { maxFixAttempts: number, autoFixSeverity: 'high'|'medium' },
+ *   codeReview: { autoFixSeverity: 'high'|'medium' },
  *   decomposer: { concurrencyCap: number },
  * }}
  */
@@ -79,18 +40,13 @@ export function getRunners(config) {
 }
 
 /**
- * Overlay an operator's block onto the framework defaults — the per-key `??`
- * fallback these accessors have always applied, written once.
- *
- * Iterating the **defaults'** keys rather than the user's is what keeps the
- * returned shape closed: a key the framework does not define cannot reach a
- * consumer through here even if one somehow survived AJV, so a typo degrades to
- * the default rather than to an undefined a caller would read as configuration.
+ * Iterates the defaults' keys, so the shape stays closed: an unknown key
+ * never reaches a caller even if it survived AJV.
  *
  * @template {Record<string, unknown>} T
- * @param {T} defaults      Frozen framework defaults.
- * @param {object|null|undefined} user Operator block from `.agentrc`.
- * @returns {T} A fresh object; the frozen defaults are never mutated.
+ * @param {T} defaults
+ * @param {object|null|undefined} user
+ * @returns {T}
  */
 function withDefaults(defaults, user) {
   const out = { ...defaults };

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

@@ -1,9 +1,4 @@
-/**
- * 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.
- */
+/** Env-derived runtime state: worktree isolation, session id, working path. */
 
 import crypto from 'node:crypto';
 import os from 'node:os';
@@ -13,17 +8,7 @@ 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.
+ * Exact-string env matching is deliberate: `""` or `"0"` must not flip it.
  *
  * @param {{ config?: { delivery?: { worktreeIsolation?: { enabled?: boolean } } | null } }} [opts]
  * @param {NodeJS.ProcessEnv} [env]
@@ -37,21 +22,14 @@ export function resolveWorktreeEnabled(opts = {}, env = process.env) {
 }
 
 /**
- * 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`.
+ * Pure. `worktreeRoot` containment is enforced 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.
+ * @param {string} opts.repoRoot — absolute.
+ * @param {number|string} [opts.storyId] — required when `worktreeEnabled`.
+ * @param {string} [opts.worktreeRoot]
+ * @returns {string}
  */
 export function resolveWorkingPath({
   worktreeEnabled,
@@ -62,10 +40,7 @@ export function resolveWorkingPath({
   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.
+  // Not re-resolved, so sentinel paths like `/repo` survive on Windows.
   if (!worktreeEnabled) return repoRoot;
   if (storyId == null) {
     throw new Error(
@@ -76,11 +51,7 @@ export function resolveWorkingPath({
 }
 
 /**
- * One-shot environment-aware runtime resolution. Returns the trio of runtime
- * signals consumed across `/mandrel-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.
+ * Each signal carries its source so the startup log can explain it.
  *
  * @param {{ config?: object }} [opts]
  * @param {NodeJS.ProcessEnv} [env]
@@ -118,21 +89,8 @@ export function resolveRuntime(opts = {}, env = process.env) {
 }
 
 /**
- * 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.
+ * Always 1..12 chars of `[a-z0-9]`, safe in labels and logs unescaped (env
+ * injection guard). A remote id that sanitises to empty falls back to local.
  *
  * @param {NodeJS.ProcessEnv} [env]
  * @returns {string}
@@ -150,9 +108,7 @@ export function resolveSessionId(env = process.env) {
 }
 
 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.
+  // 2 host + 2 pid + 8 random hex; only the random part guarantees uniqueness.
   const host = (os.hostname() || 'h')
     .toLowerCase()
     .replace(SESSION_ID_ALLOWED_CHAR_RE, '')
@@ -162,6 +118,6 @@ function generateLocalSessionId() {
     .replace(SESSION_ID_ALLOWED_CHAR_RE, '')
     .slice(-2)
     .padStart(2, '0');
-  const rand = crypto.randomBytes(4).toString('hex'); // 8 hex chars
+  const rand = crypto.randomBytes(4).toString('hex');
   return `${host}${pid}${rand}`.slice(0, SESSION_ID_LENGTH);
 }

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

@@ -1,21 +1,7 @@
-/**
- * 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.
- */
+/** Merge primitives shared by two or more config resolvers. */
 
 /**
- * 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.
+ * An array replaces the default; `{ append, prepend }` extends it, deduped.
  *
  * @param {readonly string[]} defaultList
  * @param {unknown} userValue

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

@@ -1,25 +1,7 @@
 /**
- * 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 `/mandrel-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).
+ * Read-only `.agentrc.json` reconciliation: validate against the schema
+ * (never silently strip), never auto-fill defaults (the runtime layers them
+ * at read time), and flag leaves equal to their default as `[REDUNDANT]`.
  */
 
 import fs from 'node:fs';
@@ -53,8 +35,6 @@ import {
 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}
  */
@@ -115,17 +95,12 @@ export function syncAgentrc(opts) {
 }
 
 /**
- * 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).
+ * Skips identity placeholders and leaves their parent schema requires
+ * (deleting those 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.
+ * @param {object} [schema]
  * @returns {SyncChange[]}
  */
 export function collectRedundantAdvisories(
@@ -151,23 +126,9 @@ export function collectRedundantAdvisories(
 }
 
 /**
- * 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.
+ * Only the leaf's membership in its immediate parent's `required[]` counts;
+ * a required ancestor stays present. Assumes a `$ref`-free schema. A path
+ * off the schema is removable (the advisory is informational).
  *
  * @param {object} rootSchema
  * @param {string} dottedPath
@@ -196,8 +157,6 @@ function isLeafSchemaRemovable(rootSchema, dottedPath) {
 }
 
 /**
- * Format a sync result for terminal display.
- *
  * @param {SyncResult} result
  * @returns {string}
  */