mandrel 2.31.0 → 2.32.0

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -8,6 +8,12 @@
 // byte-for-byte equivalent in effect).
 // ---------------------------------------------------------------------------
 
+import { ACCEPTANCE_EVAL_DEFAULTS } from './config/acceptance-eval.js';
+import { CI_DELIVERY_DEFAULTS } from './config/ci.js';
+import { DELIVERY_ROUTING_DEFAULTS } from './config/delivery-routing.js';
+import { LIMITS_DEFAULTS } from './config/limits.js';
+import { DEFAULT_CODE_REVIEW } from './config/runners.js';
+import { WORKTREE_ISOLATION_DEFAULTS } from './config/worktree-isolation.js';
 import { SHELL_INJECTION_PATTERN_STRING } from './config-schema-shared.js';
 // `delivery.quality` and `delivery.codeReview` sub-schemas live in a
 // further-split module (refs #3457) so each schema file stays above the
@@ -24,34 +30,30 @@ const SAFE_STRING = {
 
 const EXECUTION_SCHEMA = {
   type: 'object',
+  description: 'Wall-clock bounds on the subprocesses delivery spawns.',
   properties: {
-    timeoutMs: { type: 'integer', minimum: 1 },
-  },
-  additionalProperties: false,
-};
-
-/**
- * `delivery.lease` — assignee-as-lease primitive (Story #3480). `ttlMs` is
- * the staleness window: a ticket claim whose owner's last heartbeat is older
- * than this many milliseconds is reclaimable by another operator. Defaults to
- * 900000 (15 min) in `lib/config/limits.js`. Note the shipped guards fail
- * closed (no live heartbeat source since A22 removed the inert emitter), so
- * a stranded claim is cleared with `--steal` rather than by TTL expiry.
- */
-const LEASE_SCHEMA = {
-  type: 'object',
-  properties: {
-    ttlMs: { type: 'integer', minimum: 1 },
+    timeoutMs: {
+      type: 'integer',
+      minimum: 1,
+      description:
+        'Per-command timeout (ms) for the long-running spawns delivery drives — the close-validation chain and the gate CLIs.',
+      default: LIMITS_DEFAULTS.executionTimeoutMs,
+    },
   },
   additionalProperties: false,
 };
 
 const DOCS_FRESHNESS_SCHEMA = {
   type: 'object',
+  description:
+    'Documentation-freshness scope: the files a change of consequence is expected to touch. Read by the audit-documentation lens to seed its target set; no delivery gate enforces it.',
   properties: {
     paths: {
       type: 'array',
       items: { ...SAFE_STRING, minLength: 1 },
+      description:
+        'Repo-relative documentation paths the audit-documentation lens adds to its target set.',
+      default: ['README.md'],
     },
   },
   additionalProperties: false,
@@ -64,8 +66,17 @@ const DOCS_FRESHNESS_SCHEMA = {
  */
 const DELIVER_RUNNER_SCHEMA = {
   type: 'object',
+  description: 'Bounded-concurrency knob for the /deliver fan-out.',
   properties: {
-    concurrencyCap: { type: 'integer', minimum: 1 },
+    concurrencyCap: {
+      type: 'integer',
+      minimum: 1,
+      description:
+        'Maximum ready Stories dispatched by /deliver at once. Default 3. Moderate by design — keeps host-quota consumption predictable while allowing a small ready-set fan-out. Set 1 for strictly sequential delivery; raise further on hosts with adequate parallel-agent quota. See deliver.md for the sequencing model and throughput tradeoff.',
+      // getRunners() resolves this inline rather than from an exported
+      // constant; the rewritten parity suite asserts the two agree.
+      default: 3,
+    },
   },
   additionalProperties: false,
 };
@@ -75,25 +86,57 @@ const DELIVER_RUNNER_SCHEMA = {
  */
 const WORKTREE_ISOLATION_SCHEMA = {
   type: 'object',
+  description:
+    'Per-Story git worktree provisioning. Each Story is implemented in its own checkout so concurrent siblings never share a working tree.',
   properties: {
-    enabled: { type: 'boolean' },
-    root: { type: 'string', minLength: 1 },
+    enabled: {
+      type: 'boolean',
+      description:
+        'When true, `single-story-init.js` materializes a worktree per Story. False implements every Story in the main checkout, which is only safe for strictly serial delivery.',
+      default: WORKTREE_ISOLATION_DEFAULTS.enabled,
+    },
+    root: {
+      type: 'string',
+      minLength: 1,
+      description:
+        'Repo-relative directory the per-Story worktrees are created under. Required whenever `enabled` is explicitly true.',
+      default: WORKTREE_ISOLATION_DEFAULTS.root,
+    },
     nodeModulesStrategy: {
       type: 'string',
       enum: ['per-worktree', 'clone', 'symlink', 'pnpm-store'],
+      description:
+        'How each worktree gets its dependencies. `clone` copy-on-writes the main checkout tree (fast, cross-platform); `per-worktree` runs a full install; `symlink` links the shared tree (POSIX only unless `allowSymlinkOnWindows`); `pnpm-store` re-links from the pnpm content store.',
+      // Pinned to the cross-platform documented default. The runtime constant
+      // is evaluated at import time and resolves to `per-worktree` on win32,
+      // so it must not be imported here.
+      default: 'clone',
+    },
+    primeFromPath: {
+      type: ['string', 'null'],
+      minLength: 1,
+      description:
+        'Absolute path to an existing `node_modules` tree to prime new worktrees from, instead of the main checkout. `null` uses the main checkout.',
+      default: WORKTREE_ISOLATION_DEFAULTS.primeFromPath,
+    },
+    allowSymlinkOnWindows: {
+      type: 'boolean',
+      description:
+        'Permit the `symlink` strategy on win32, where it needs Developer Mode or elevation. Off by default so a Windows consumer fails over to a strategy that works.',
+      default: WORKTREE_ISOLATION_DEFAULTS.allowSymlinkOnWindows,
+    },
+    reapOnSuccess: {
+      type: 'boolean',
+      description:
+        "Remove the Story's worktree once its PR merges. False keeps it for post-mortem inspection.",
+      default: WORKTREE_ISOLATION_DEFAULTS.reapOnSuccess,
     },
-    primeFromPath: { type: ['string', 'null'], minLength: 1 },
-    allowSymlinkOnWindows: { type: 'boolean' },
-    reapOnSuccess: { type: 'boolean' },
     bootstrapFiles: {
       type: 'array',
       items: { type: 'string', minLength: 1 },
-      default: [
-        '.env',
-        '.mcp.json',
-        '.agentrc.local.json',
-        '.agents/instructions.local.md',
-      ],
+      description:
+        'Gitignored files copied from the main checkout into every new worktree. A worktree checks out tracked files only, so local secrets and overrides would otherwise be missing.',
+      default: [...WORKTREE_ISOLATION_DEFAULTS.bootstrapFiles],
     },
   },
   additionalProperties: false,
@@ -118,18 +161,34 @@ const WORKTREE_ISOLATION_SCHEMA = {
  */
 const SIGNALS_SCHEMA = {
   type: 'object',
+  description:
+    'Detector thresholds for the surviving performance-signal categories. Each block is shallow-merged by the resolver.',
   properties: {
     rework: {
       type: 'object',
+      description: 'Rework detector — repeated edits to one file in a run.',
       properties: {
-        editsPerFile: { type: 'integer', minimum: 1 },
+        editsPerFile: {
+          type: 'integer',
+          minimum: 1,
+          description:
+            'Edits to a single file within one run that trip the rework signal.',
+          default: LIMITS_DEFAULTS.signals.rework.editsPerFile,
+        },
       },
       additionalProperties: false,
     },
     retry: {
       type: 'object',
+      description: 'Retry detector — the same command failing repeatedly.',
       properties: {
-        repeatCount: { type: 'integer', minimum: 1 },
+        repeatCount: {
+          type: 'integer',
+          minimum: 1,
+          description:
+            'Repeats of an identical failing command that trip the retry signal.',
+          default: LIMITS_DEFAULTS.signals.retry.repeatCount,
+        },
       },
       additionalProperties: false,
     },
@@ -171,12 +230,40 @@ const SIGNALS_SCHEMA = {
  */
 const MERGE_WATCH_SCHEMA = {
   type: 'object',
+  description:
+    "Knobs consumed by the close-and-land merge wait (Story #4543; defaults in `lib/orchestration/merge-poll.js`). `mode` (Story #4698) selects the close-time merge posture. `intervalSeconds` is the poll cadence between `gh pr view` probes after the arm. `maxWaitSeconds` bounds ONE invocation of the merge wait and its expiry returns a resumable `pending` terminal with no label mutation; `maxBudgetSeconds` bounds the CUMULATIVE wait across resumes (anchored at the PR's createdAt, so a resume does not restart the clock) and exhausting it is the genuine give-up that classifies and blocks. `updateAttempts` caps the bounded update of a behind-the-base PR.",
   properties: {
-    mode: { type: 'string', enum: ['sync', 'async'] },
-    intervalSeconds: { type: 'integer', minimum: 1 },
-    maxWaitSeconds: { type: 'integer', minimum: 1 },
-    maxBudgetSeconds: { type: 'integer', minimum: 1 },
-    updateAttempts: { type: 'integer', minimum: 0 },
+    mode: {
+      type: 'string',
+      enum: ['sync', 'async'],
+      description:
+        'Close-time merge-wait posture (Story #4698). `sync` (default) keeps the in-close foreground merge wait unchanged. `async` caps the per-invocation wait to a short ~60s probe window — long enough to catch an instant merge and, via the head-anchored required-check predicate, an instantly-red required check — then returns the resumable `pending` terminal (exit 3) with a `nextCommand`. Opt in when slow CI makes the foreground wait routinely expire: the worker launches `nextCommand` in the background instead of burning the host tool slot polling. `maxBudgetSeconds` (the cumulative give-up) is unchanged.',
+    },
+    intervalSeconds: {
+      type: 'integer',
+      minimum: 1,
+      description: 'Seconds between merge-wait polls. Default 30.',
+      default: 30,
+    },
+    maxWaitSeconds: {
+      type: 'integer',
+      minimum: 1,
+      description:
+        'Per-invocation merge-wait bound (seconds). Default 300 (5 minutes) — chosen to fit inside a single host tool invocation (~10 min ceiling) alongside the close gates that precede the wait. Expiry yields `pending` (exit 3), never a block. Headless callers with no host ceiling raise this to land in one block.',
+    },
+    maxBudgetSeconds: {
+      type: 'integer',
+      minimum: 1,
+      description:
+        "Cumulative wall-clock budget (seconds) across merge-wait resumes, anchored at the PR's createdAt. Default 3600 (60 minutes). Exhausting this classifies the block and transitions the Story to agent::blocked.",
+      default: 3600,
+    },
+    updateAttempts: {
+      type: 'integer',
+      minimum: 0,
+      description:
+        'Maximum times the merge wait will bring a behind-the-base PR up to date before giving up on the branch. Default 3. Set 0 to disable the update.',
+    },
   },
   additionalProperties: false,
 };
@@ -198,14 +285,36 @@ const MERGE_WATCH_SCHEMA = {
 // acceptance clusters through a fresh critic.
 const ROUTING_SCHEMA = {
   type: 'object',
+  description:
+    'v2 delivery-spawn routing: role-scoped boot contexts and maker-checker sampling. The v1 singleDelivery epic-route kill-switch was removed in Stage 6.',
   properties: {
-    roleScopedAgents: { type: 'boolean' },
-    freshCriticSampleRate: { type: 'number', minimum: 0, maximum: 1 },
+    roleScopedAgents: {
+      type: 'boolean',
+      description:
+        'Epic #4478 (M7-B). Kill-switch for the role-scoped boot contexts. When true (default), a converted delivery spawn (`story-worker`, `acceptance-critic`) boots on its own `.claude/agents/<role>.md` system prompt instead of re-paying the full CLAUDE.md @-import closure. When false, every converted spawn falls back to `subagent_type: general-purpose` — the instant, code-rollback-free per-consumer revert, and the universal escape for hosts that ignore `.claude/agents/`. The fallback is the full-closure agent that ran before M7-B, so flipping it off never drops a gate.',
+      default: DELIVERY_ROUTING_DEFAULTS.roleScopedAgents,
+    },
+    freshCriticSampleRate: {
+      type: 'number',
+      minimum: 0,
+      maximum: 1,
+      description:
+        'Epic #4478 (M7-B, Part 2). Maker-checker sampling floor. Under the standard profile, a change set touching no sensitive path routes its acceptance clusters down the contract-identical inline critic path, but this fraction of them is still forced through a fresh-context critic so a low derived level never means zero independent checking. Clamped to [0, 1]; 0 disables the floor, 1 forces every cluster fresh. Consumed by resolveCeremonyForRisk (lib/orchestration/ceremony-routing.js).',
+      default: DELIVERY_ROUTING_DEFAULTS.freshCriticSampleRate,
+    },
     ceremonyProfile: {
       type: 'string',
       enum: ['minimal', 'standard', 'strict'],
+      description:
+        'Acceptance-ceremony depth. minimal = always inline critic; strict = always fresh-context critic; standard (default) = routed off the change level derived from the Story diff, with the maker-checker sampling floor.',
+      default: DELIVERY_ROUTING_DEFAULTS.ceremonyProfile,
+    },
+    closeAndLand: {
+      type: 'boolean',
+      description:
+        'When true (default), single-story-close lands through merge in one close. Opt out per-run with --no-wait-merge.',
+      default: DELIVERY_ROUTING_DEFAULTS.closeAndLand,
     },
-    closeAndLand: { type: 'boolean' },
   },
   additionalProperties: false,
 };
@@ -218,22 +327,60 @@ const ROUTING_SCHEMA = {
 // EMPTY required-check set before it stops waiting for one. This block is
 // `additionalProperties: false`, so the knob is inert unless it lands here AND
 // in the `.agents/schemas/agentrc.schema.json` mirror.
+// The four `watch.*` defaults below mirror WATCH_DEFAULTS in
+// `pr-watch-with-update.js`. Restated rather than imported: that module is a
+// CLI, and importing it behind a schema declaration would drag its
+// `runAsCli` wiring into every config read. The rewritten parity suite
+// asserts the two agree.
 const CI_WATCH_SCHEMA = {
   type: 'object',
+  description:
+    'Story #4356 (Epic #4355). Poll-loop tuning for the merge/CI watch. pollIntervalMs is the cadence between check probes; maxPolls caps total probes before the watcher gives up; maxResumes caps how many times the watcher may resume after a transient stall; attachWindowMs bounds the wait for a required context to attach at all.',
   properties: {
-    pollIntervalMs: { type: 'integer', minimum: 1 },
-    maxPolls: { type: 'integer', minimum: 1 },
-    maxResumes: { type: 'integer', minimum: 0 },
-    attachWindowMs: { type: 'integer', minimum: 1 },
+    pollIntervalMs: {
+      type: 'integer',
+      minimum: 1,
+      description: 'Milliseconds between check probes.',
+      default: 10000,
+    },
+    maxPolls: {
+      type: 'integer',
+      minimum: 1,
+      description:
+        'Total probes before the watcher gives up on one invocation.',
+      default: 180,
+    },
+    maxResumes: {
+      type: 'integer',
+      minimum: 0,
+      description:
+        'How many times the watcher may resume after a transient stall. 0 disables resuming.',
+      default: 3,
+    },
+    attachWindowMs: {
+      type: 'integer',
+      minimum: 1,
+      description:
+        'Story #4890. How long (ms) the watch keeps re-resolving an EMPTY `gh pr checks --required` set before it stops waiting for a required context to attach. A ruleset attaches its contexts asynchronously and the arrival latency is set by the slowest one, so a required context that is an aggregator job gated on every other tier is the last to appear — measured at 16m52s on this repository. Default 1200000 (20 minutes). Raise it for a repository whose contexts arrive later still; exhausting the window is never reported as a red check (the watch exits 2, not-yet-started).',
+      default: 1200000,
+    },
   },
   additionalProperties: false,
 };
 
 const CI_DELIVERY_SCHEMA = {
   type: 'object',
+  description:
+    'CI-aware delivery namespace (Story #4356, Epic #4355): the merge/CI watch poll loop and the merge posture.',
   properties: {
     watch: CI_WATCH_SCHEMA,
-    autoMerge: { type: 'string', enum: ['trust-ci', 'strict'] },
+    autoMerge: {
+      type: 'string',
+      enum: ['trust-ci', 'strict'],
+      description:
+        "Story #4356 (Epic #4355). Merge posture. 'trust-ci' (default) merges once required checks pass; 'strict' additionally requires a clean review gate.",
+      default: CI_DELIVERY_DEFAULTS.autoMerge,
+    },
   },
   additionalProperties: false,
 };
@@ -249,11 +396,14 @@ const CI_DELIVERY_SCHEMA = {
  */
 const REFACTOR_STAGE_SCHEMA = {
   type: 'object',
+  description:
+    'Opt-in, config-gated post-green refactor checkpoint wired into story-deliver (Story #3430, Epic #3418). Strictly additive and default-OFF: when disabled, story-deliver behaves exactly as before. Advisory only — never changes existing close-validation gate semantics.',
   properties: {
     enabled: {
       type: 'boolean',
       description:
         'When true, story-deliver runs an advisory post-green refactor stage (core/code-review-and-quality skill, Post-Green Refactor Pass) after the suite is green. Default false — when unset the stage is skipped and close-validation gate semantics are unchanged.',
+      default: false,
     },
   },
   additionalProperties: false,
@@ -277,18 +427,15 @@ const REFACTOR_STAGE_SCHEMA = {
  */
 const ACCEPTANCE_EVAL_SCHEMA = {
   type: 'object',
+  description:
+    'Story #3819. Bounded per-Story acceptance self-eval loop. After the implementation commits land and before the Story-implementation phase flips to `closing`, an independent (fresh-context) critic pass scores the caller-injected change set against each inline `acceptance[]` item, redrafts the unmet items, and re-evaluates — capped at `maxRounds` redraft rounds, then escalates to `agent::blocked` when criteria remain unmet. There is no `enabled` flag: the loop is a hard cutover (always on).',
   properties: {
     maxRounds: {
       type: 'integer',
       minimum: 1,
       description:
-        'Maximum number of redraft rounds the acceptance self-eval loop runs before escalating to agent::blocked when criteria remain unmet. Default 2; clamped into [1, hard ceiling] by the resolver so the cap can never be disabled.',
-    },
-    clusterCeiling: {
-      type: 'integer',
-      minimum: 1,
-      description:
-        'Epic #4475 (M4-B). Max acceptance criteria one single-delivery acceptance critic scores in a single fresh-context pass. Single delivery clusters the Epic ## Acceptance Table ACs into ceil(totalACs / clusterCeiling) groups and spawns one maker-blind critic per cluster, restoring the distributed acceptance coverage the per-Story critic fan-out gave for free. Default 4; clamped into [1, 8] by the resolver so a large value cannot collapse the fan-out to a single diluted critic. Ignored on the fan-out route.',
+        'Maximum number of redraft rounds before escalation. Default 2; clamped into [1, hard ceiling] by lib/config/acceptance-eval.js so the cap can never be disabled (maxRounds: 0 clamps up to 1).',
+      default: ACCEPTANCE_EVAL_DEFAULTS.maxRounds,
     },
   },
   additionalProperties: false,
@@ -303,6 +450,8 @@ const ACCEPTANCE_EVAL_SCHEMA = {
  */
 const REVIEW_SCHEMA = {
   type: 'object',
+  description:
+    'Close-scope review tuning (Story #4699). Governs the Story-scope local-lens pass that runs inside the close subprocess; the maker-blind code-review pass and all hard gates are unaffected.',
   properties: {
     lensDiffFloor: {
       type: 'integer',
@@ -337,10 +486,27 @@ const REVIEW_SCHEMA = {
  */
 const FEEDBACK_LOOP_SCHEMA = {
   type: 'object',
+  description:
+    'Opt-out toggles for the close-time auto-file graduators. All default to auto-filing on.',
   properties: {
-    auditResultsAutoFile: { type: 'boolean' },
-    retroProposals: { type: 'boolean' },
-    frictionWindowDays: { type: 'integer', minimum: 1 },
+    auditResultsAutoFile: {
+      type: 'boolean',
+      description:
+        'When true (default), the close-time audit-results graduator auto-files non-blocking audit-results findings as follow-up issues routed by source classification. Set to false to suppress auto-filing; findings remain accessible in the structured comments on the Story.',
+      default: true,
+    },
+    retroProposals: {
+      type: 'boolean',
+      description:
+        'When true (default), the retro auto-files its actionable routed proposals as meta::<framework-gap|consumer-improvement> + friction::<category> issues via the graduator pre-parsed-findings seam, and the rendered retro sections list the filed issue numbers instead of paste-ready gh command stanzas. Set to false to fall back to the command stanzas.',
+      default: true,
+    },
+    frictionWindowDays: {
+      type: 'integer',
+      minimum: 1,
+      description:
+        "How many days back the run-scope friction recurrence window reaches (Story #4850). The window spans every surviving per-Story signal stream rather than the triggering run's own Stories, so that a defect firing once per Story can reach the actionable threshold; this bounds it by age so a defect fixed weeks ago stops re-routing. Rows older than the bound — and rows carrying no readable timestamp — are excluded and counted on the roll-up step result. Default 30.",
+    },
   },
   additionalProperties: false,
 };
@@ -355,12 +521,20 @@ const FEEDBACK_LOOP_SCHEMA = {
  */
 const AUDIT_TO_STORIES_SCHEMA = {
   type: 'object',
+  description:
+    'Knobs for the `/audit-to-stories` unattended (`--auto`) sweep (Story #4626).',
   properties: {
     severityFloor: {
       type: 'string',
       enum: ['critical', 'high', 'medium', 'low', 'all'],
+      description:
+        'Minimum severity a finding must meet to be proposed as a Story on an unattended `/audit-to-stories --auto` sweep (Story #4626). Default high.',
+    },
+    autoComment: {
+      type: 'boolean',
+      description:
+        'When true (default), `/audit-to-stories --auto` posts a re-detected comment on an already-open matched Issue instead of silently skipping it.',
     },
-    autoComment: { type: 'boolean' },
   },
   additionalProperties: false,
 };
@@ -388,6 +562,7 @@ const TEMP_RETENTION_SCHEMA = {
         "Master switch. Default true — reclaiming a landed Story's gate " +
         'transcripts and validation evidence is the behaviour, and this knob ' +
         'turns it off. When false every purge path is a reported no-op.',
+      default: true,
     },
     staleDays: {
       type: 'integer',
@@ -397,6 +572,7 @@ const TEMP_RETENTION_SCHEMA = {
         'recovered from — roster-level audit reports and abandoned ' +
         'plan-<slug>/ dirs. Story-keyed artifacts do not wait for it: they are ' +
         'purged as soon as their merge is confirmed.',
+      default: 7,
     },
     classes: {
       type: 'object',
@@ -409,22 +585,26 @@ const TEMP_RETENTION_SCHEMA = {
           description:
             '<tempRoot>/orchestration/*.log — close gate transcripts and ' +
             'terse-result detail dumps.',
+          default: true,
         },
         validationEvidence: {
           type: 'boolean',
           description:
             'Per-Story validation-evidence.json, lifecycle.ndjson, and ' +
             'manifest.md under the standalone and per-run story trees.',
+          default: true,
         },
         auditResults: {
           type: 'boolean',
           description: '<tempRoot>/audits/ — audit lens reports.',
+          default: true,
         },
         planDirs: {
           type: 'boolean',
           description:
             '<tempRoot>/plan-<slug>/ — abandoned plan authoring dirs. ' +
             'Age-floored only; the current run is always excluded.',
+          default: true,
         },
       },
       additionalProperties: false,
@@ -435,9 +615,10 @@ const TEMP_RETENTION_SCHEMA = {
 
 export const DELIVERY_SCHEMA = {
   type: 'object',
+  description:
+    'Everything `/deliver` and `single-story-close` consume: execution timeouts, worktree isolation, runner concurrency, docs freshness, signals, quality gates, merge/CI watch, review ceremony, and the feedback loop.',
   properties: {
     execution: EXECUTION_SCHEMA,
-    lease: LEASE_SCHEMA,
     docsFreshness: DOCS_FRESHNESS_SCHEMA,
     tempRetention: TEMP_RETENTION_SCHEMA,
     deliverRunner: DELIVER_RUNNER_SCHEMA,