mandrel 1.57.0

package/.agents/schemas/agentrc.schema.json

@@ -0,0 +1,1583 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/agentrc.schema.json",
+  "title": "Mandrel .agentrc",
+  "description": "Static JSON Schema mirror of the authoritative AJV schema in .agents/scripts/lib/config-settings-schema.js. The AJV schema is the runtime source of truth; this file exists for editor tooling and human readers. A drift test (tests/config-schema-mirror-drift.test.js) keeps the two in sync. Top-level reshape: Epic #1720 Story #1739 pivoted from {agentSettings, orchestration} to {project, github, planning, delivery}. Quality gate reshape: Epic #1720 Story #1737 introduced the uniform delivery.quality.gates.<tier> shape with seven gates (lint, coverage, crap, maintainability, mutation, lighthouse, bundleSize), object-shaped { kind, value } tolerances, and workspace-keyed floors objects. Story #2687 (Epic #2646) confirmed that the schema carries no field whose sole purpose is to keep pre-cutover documents validating \u2014 every property exposed here corresponds to a canonical reader in the post-reshape config layer. Epic #2880 Story #2935 finalized the cutover by deleting the resolver-side output shim that surfaced agentSettings/orchestration pointers; legacy-shaped documents are rejected by root additionalProperties:false and the canonical blocks are the only supported reads.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["project"],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "project": {
+      "$ref": "#/$defs/project"
+    },
+    "github": {
+      "$ref": "#/$defs/github"
+    },
+    "planning": {
+      "$ref": "#/$defs/planning"
+    },
+    "delivery": {
+      "$ref": "#/$defs/delivery"
+    },
+    "qa": {
+      "$ref": "#/$defs/qa"
+    }
+  },
+  "$defs": {
+    "safeString": {
+      "type": "string",
+      "not": {
+        "pattern": "[;&|`$<>]"
+      }
+    },
+    "nullableSafeString": {
+      "type": ["string", "null"],
+      "not": {
+        "type": "string",
+        "pattern": "[;&|`$<>]"
+      }
+    },
+    "nullableNonEmptySafeString": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "not": {
+        "type": "string",
+        "pattern": "[;&|`$<>]"
+      }
+    },
+    "listOrExtenderOfStrings": {
+      "oneOf": [
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        {
+          "type": "object",
+          "properties": {
+            "append": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "prepend": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "paths": {
+      "type": "object",
+      "required": ["agentRoot", "docsRoot", "tempRoot"],
+      "properties": {
+        "agentRoot": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/safeString"
+            },
+            {
+              "minLength": 1
+            }
+          ]
+        },
+        "docsRoot": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/safeString"
+            },
+            {
+              "minLength": 1
+            }
+          ]
+        },
+        "tempRoot": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/safeString"
+            },
+            {
+              "minLength": 1
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "commands": {
+      "type": "object",
+      "properties": {
+        "lintBaseline": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/safeString"
+            },
+            {
+              "minLength": 1
+            }
+          ]
+        },
+        "test": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/safeString"
+            },
+            {
+              "minLength": 1
+            }
+          ]
+        },
+        "typecheck": {
+          "$ref": "#/$defs/nullableNonEmptySafeString"
+        },
+        "formatCheck": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/safeString"
+            },
+            {
+              "minLength": 1
+            }
+          ]
+        },
+        "formatWrite": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/safeString"
+            },
+            {
+              "minLength": 1
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "project": {
+      "type": "object",
+      "required": ["paths"],
+      "properties": {
+        "baseBranch": {
+          "$ref": "#/$defs/safeString"
+        },
+        "paths": {
+          "$ref": "#/$defs/paths"
+        },
+        "docsContextFiles": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "commands": {
+          "$ref": "#/$defs/commands"
+        }
+      },
+      "additionalProperties": false
+    },
+    "branchProtectionCheck": {
+      "type": "object",
+      "required": ["name", "cmd"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "cmd": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "branchProtection": {
+      "type": "object",
+      "properties": {
+        "enforce": {
+          "type": "boolean"
+        },
+        "requiredChecks": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/branchProtectionCheck"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "mergeMethods": {
+      "type": "object",
+      "properties": {
+        "allow_squash_merge": {
+          "type": "boolean"
+        },
+        "allow_rebase_merge": {
+          "type": "boolean"
+        },
+        "allow_merge_commit": {
+          "type": "boolean"
+        },
+        "allow_auto_merge": {
+          "type": "boolean"
+        },
+        "delete_branch_on_merge": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
+    "notifications": {
+      "type": "object",
+      "properties": {
+        "mentionOperator": {
+          "type": "boolean"
+        },
+        "commentEvents": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["state-transition", "story-merged", "operator-message"]
+          },
+          "uniqueItems": true
+        },
+        "webhookEvents": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "epic-started",
+              "epic-progress",
+              "epic-blocked",
+              "epic-unblocked",
+              "epic-complete"
+            ]
+          },
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "github": {
+      "type": "object",
+      "required": ["owner", "repo", "operatorHandle"],
+      "properties": {
+        "owner": {
+          "type": "string",
+          "minLength": 1
+        },
+        "repo": {
+          "type": "string",
+          "minLength": 1
+        },
+        "projectNumber": {
+          "type": ["integer", "null"],
+          "minimum": 1
+        },
+        "projectOwner": {
+          "type": ["string", "null"],
+          "minLength": 1
+        },
+        "operatorHandle": {
+          "type": "string",
+          "pattern": "^@.+"
+        },
+        "defaultTimeoutMs": {
+          "type": "integer",
+          "minimum": 1000,
+          "description": "Default `timeoutMs` (in milliseconds) applied to every `gh` subprocess spawned by the GitHub provider facade. Caps any single `gh api` / `gh issue ...` / `gh pr ...` invocation so a stalled TCP socket or long-poll cannot hang an orchestration indefinitely. A `GhExecTimeoutError` from a hit ceiling is classified `transient` and retried by `withTransientRetry`. Recommended floor 1000ms; recommended default 60000 (60s). Omit to use the in-code default of 60000. Story #2860."
+        },
+        "branchProtection": {
+          "$ref": "#/$defs/branchProtection"
+        },
+        "mergeMethods": {
+          "$ref": "#/$defs/mergeMethods"
+        },
+        "notifications": {
+          "$ref": "#/$defs/notifications"
+        }
+      },
+      "additionalProperties": false
+    },
+    "planningContext": {
+      "type": "object",
+      "properties": {
+        "maxBytes": {
+          "type": "integer",
+          "minimum": 1024
+        },
+        "summaryMode": {
+          "type": "string",
+          "enum": ["auto", "always", "never"]
+        }
+      },
+      "additionalProperties": false
+    },
+    "taskSizing": {
+      "type": "object",
+      "description": "Story-sizing thresholds consumed by ticket-validator-sizing.js. Operator overrides shallow-merge with DEFAULT_TASK_SIZING defaults. Story #3760 collapsed the per-profile matrix and the parallel testSurface axis into a flat set of knobs; the sizingProfile enum was replaced by an optional body-level `wide` declaration that lifts the hardFiles rejection. Story #3874 cut over to one uniform relaxed profile sized for capability slices a frontier model delivers and self-verifies in one pass.",
+      "properties": {
+        "softFiles": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "File-count soft-warn threshold above which a typical-Story width finding fires (default 8)."
+        },
+        "hardFiles": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "File-count hard ceiling: a Story exceeding it is rejected unless it declares `wide` with a reason (default 30)."
+        },
+        "maxAcceptance": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Hard ceiling on acceptance[] item count (default 14)."
+        },
+        "softAcceptanceCount": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Soft-warn threshold on acceptance[] item count (default 10)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "planning": {
+      "type": "object",
+      "properties": {
+        "riskHeuristics": {
+          "$ref": "#/$defs/listOrExtenderOfStrings"
+        },
+        "maxTickets": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "context": {
+          "$ref": "#/$defs/planningContext"
+        },
+        "codebaseSnapshot": {
+          "$ref": "#/$defs/codebaseSnapshot"
+        },
+        "taskSizing": {
+          "$ref": "#/$defs/taskSizing"
+        },
+        "failOnSharedEditors": {
+          "type": "boolean"
+        },
+        "requireExplicitCrossStoryDeps": {
+          "type": "boolean"
+        },
+        "failOnRegistryConflicts": {
+          "type": "boolean"
+        },
+        "failOnLargeFanOut": {
+          "type": "boolean"
+        },
+        "largeFanOutThreshold": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "crossCuttingRegistries": {
+          "$ref": "#/$defs/listOrExtenderOfStrings"
+        }
+      },
+      "additionalProperties": false
+    },
+    "codebaseSnapshot": {
+      "type": "object",
+      "properties": {
+        "tier": {
+          "type": "string",
+          "enum": ["skinny", "medium"]
+        },
+        "include": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "exclude": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "recentCommitWindow": {
+          "type": "integer",
+          "minimum": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "execution": {
+      "type": "object",
+      "properties": {
+        "timeoutMs": {
+          "type": "integer",
+          "minimum": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "lease": {
+      "type": "object",
+      "description": "Story #3480 (Epic #3457). Assignee-as-lease primitive. ttlMs is the staleness window \u2014 a ticket claim whose owner has not emitted a story.heartbeat within this many milliseconds is reclaimable by another operator. Defaults to 900000 (15 min) in lib/config/limits.js.",
+      "properties": {
+        "ttlMs": {
+          "type": "integer",
+          "minimum": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "docsFreshness": {
+      "type": "object",
+      "properties": {
+        "paths": {
+          "type": "array",
+          "items": {
+            "allOf": [
+              {
+                "$ref": "#/$defs/safeString"
+              },
+              {
+                "minLength": 1
+              }
+            ]
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "deliverRunner": {
+      "type": "object",
+      "properties": {
+        "concurrencyCap": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum Stories dispatched in parallel within one wave. Default 3. Conservative by design \u2014 keeps host-quota consumption predictable on small waves and avoids GitHub API saturation. Operators running wide-wave Epics on hosts with adequate parallel-agent quota should raise this value to reduce wall-clock time proportionally. See epic-deliver.md \u00a7 Phase 2b for the dispatch model and the throughput tradeoff discussion."
+        },
+        "progressReportIntervalSec": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "verifyConcurrencyCap": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Bounded-concurrency cap for the per-wave verifyWaveResults loop (Epic #3019 Tech Spec \u00a71.4). Separate from the wave-execution `concurrencyCap` so operators can tune ticket-verification parallelism independently of Story dispatch parallelism. Default 4."
+        }
+      },
+      "additionalProperties": false
+    },
+    "retro": {
+      "type": "object",
+      "description": "Story #3042 (Epic #3019). Operator-tunable retro behaviour. Currently exposes `perfThresholds`, the gates the retro perf-signals classifier uses to decide which signals to surface in the `## Performance Signals` / `## Recommended Follow-Ons` retro sections.",
+      "properties": {
+        "perfThresholds": {
+          "type": "object",
+          "description": "Gates for `classifyPerfSignals` (lib/orchestration/retro-perf-heuristics.js). Defaults are 0.6 / 0.4 / 2.",
+          "properties": {
+            "utilisation": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "description": "Per-wave utilisation threshold. Waves whose `utilisation` is strictly below this value emit a `low-utilisation` signal. Default 0.6."
+            },
+            "bootstrapShare": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "description": "Maximum acceptable share of cumulative Story execution time spent in the story-init phase. When exceeded the retro emits a `high-bootstrap-share` signal. Default 0.4."
+            },
+            "capBindingRunLength": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Minimum run length of consecutive cap-binding waves before the retro emits a `cap-binding-run` signal. Default 2."
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "epicAudit": {
+      "type": "object",
+      "properties": {
+        "maxFixAttempts": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Maximum auto-fix retry attempts per finding in /epic-deliver Phase 4 (epic-audit). 0 disables auto-fix. Default 3."
+        },
+        "maxFixScopeFiles": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum file count a single auto-fix may modify before escalating to agent::blocked. Default 5."
+        }
+      },
+      "additionalProperties": false
+    },
+    "codeReview": {
+      "type": "object",
+      "properties": {
+        "provider": {
+          "type": "string",
+          "enum": ["native", "codex", "security-review"],
+          "default": "native",
+          "description": "Legacy single-adapter selection. ReviewProvider that produces the Finding[] consumed by runCodeReview(). Story #2833 registered `native` (in-process maintainability/lint); Story #2830 added `codex` (invokes `/codex:review` plugin); Story #2871 added `security-review` (shells out to `claude --print /security-review`). When `providers` (chain shape) is set this field is ignored with a warning. Selecting an adapter whose probe fails hard-fails at factory construction unless declared `optional: true` in the chain."
+        },
+        "providers": {
+          "type": "array",
+          "description": "Multi-provider chain (Story #2871). When set and non-empty, takes precedence over the legacy `provider` field. The orchestrator iterates inline entries in declaration order and merges their Finding[] before posting one structured comment; manual-prompt entries (e.g. ultrareview) contribute a trailing 'Manual review suggestions' section.",
+          "items": {
+            "type": "object",
+            "required": ["name"],
+            "properties": {
+              "name": {
+                "type": "string",
+                "enum": ["native", "codex", "security-review", "ultrareview"],
+                "description": "Registered provider key. Inline: native, codex, security-review. Manual-prompt: ultrareview."
+              },
+              "scopes": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "enum": ["story", "epic"]
+                },
+                "description": "Invocation scopes this entry fires on. Default (omitted) is both."
+              },
+              "optional": {
+                "type": "boolean",
+                "default": false,
+                "description": "When true, construction failure (host missing CLI/plugin) is logged and the entry is skipped instead of hard-failing the chain. Use for cross-runtime portability."
+              },
+              "manualPrompt": {
+                "type": "boolean",
+                "default": false,
+                "description": "When true, the entry is loaded from the manual-prompt registry: contributes a one-line operator suggestion via `renderPrompt()` instead of running a review via `runReview()`. Does not affect severity counts or `halted`."
+              },
+              "when": {
+                "type": "object",
+                "description": "Optional label-gated invocation predicate. Evaluated against the ticket's current labels at invocation time; when false, the entry is silently skipped for this run.",
+                "properties": {
+                  "label": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Single label that MUST be present on the ticket."
+                  },
+                  "labelAny": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "minItems": 1,
+                    "description": "Run when ANY of the listed labels is present."
+                  }
+                },
+                "additionalProperties": false
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "providerConfig": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Optional escape hatch for adapter-specific configuration. No documented keys in Epic #2815; reserved so future adapters can be configured without another schema migration."
+        },
+        "maxFixAttempts": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Maximum auto-fix retry attempts per finding in /epic-deliver Phase 5 (code-review). 0 disables auto-fix. Default 3."
+        },
+        "maxFixScopeFiles": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum file count a single auto-fix may modify before escalating to agent::blocked. Default 5."
+        }
+      },
+      "additionalProperties": false
+    },
+    "worktreeIsolation": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "root": {
+          "type": "string",
+          "minLength": 1
+        },
+        "nodeModulesStrategy": {
+          "type": "string",
+          "enum": ["per-worktree", "symlink", "pnpm-store"]
+        },
+        "primeFromPath": {
+          "type": ["string", "null"],
+          "minLength": 1
+        },
+        "allowSymlinkOnWindows": {
+          "type": "boolean"
+        },
+        "reapOnSuccess": {
+          "type": "boolean"
+        },
+        "reapOnCancel": {
+          "type": "boolean"
+        },
+        "bootstrapFiles": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "default": [".env", ".mcp.json"]
+        }
+      },
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "enabled": {
+                "const": true
+              }
+            },
+            "required": ["enabled"]
+          },
+          "then": {
+            "required": ["root"]
+          }
+        }
+      ]
+    },
+    "signals": {
+      "type": "object",
+      "properties": {
+        "hotspot": {
+          "type": "object",
+          "properties": {
+            "p95Multiplier": {
+              "type": "number",
+              "minimum": 0
+            }
+          },
+          "additionalProperties": false
+        },
+        "rework": {
+          "type": "object",
+          "properties": {
+            "editsPerFile": {
+              "type": "integer",
+              "minimum": 1
+            }
+          },
+          "additionalProperties": false
+        },
+        "retry": {
+          "type": "object",
+          "properties": {
+            "repeatCount": {
+              "type": "integer",
+              "minimum": 1
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "tolerance": {
+      "type": "object",
+      "required": ["kind", "value"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": ["absolute", "percent"]
+        },
+        "value": {
+          "type": "number",
+          "minimum": 0
+        }
+      },
+      "additionalProperties": false
+    },
+    "floors": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "number"
+        }
+      }
+    },
+    "components": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "lintGate": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "baselinePath": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/safeString"
+            },
+            {
+              "minLength": 1
+            }
+          ]
+        },
+        "tolerance": {
+          "$ref": "#/$defs/tolerance"
+        },
+        "floors": {
+          "$ref": "#/$defs/floors"
+        },
+        "components": {
+          "$ref": "#/$defs/components"
+        }
+      },
+      "additionalProperties": false
+    },
+    "coverageGate": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "baselinePath": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/safeString"
+            },
+            {
+              "minLength": 1
+            }
+          ]
+        },
+        "tolerance": {
+          "$ref": "#/$defs/tolerance"
+        },
+        "floors": {
+          "$ref": "#/$defs/floors"
+        },
+        "components": {
+          "$ref": "#/$defs/components"
+        },
+        "coveragePath": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/safeString"
+            },
+            {
+              "minLength": 1
+            }
+          ]
+        },
+        "timeoutMs": {
+          "type": "integer",
+          "minimum": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "crapGate": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "baselinePath": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/safeString"
+            },
+            {
+              "minLength": 1
+            }
+          ]
+        },
+        "tolerance": {
+          "$ref": "#/$defs/tolerance"
+        },
+        "floors": {
+          "$ref": "#/$defs/floors"
+        },
+        "components": {
+          "$ref": "#/$defs/components"
+        },
+        "targetDirs": {
+          "$ref": "#/$defs/listOrExtenderOfStrings",
+          "description": "Directories whose JS sources the CRAP gate scores. Mandrel ships a `src/`-centric default; projects whose executable code lives elsewhere (e.g. this repo's `.agents/scripts/`) override here. The framework default is intentionally not auto-discovered, so an override is the explicit, auditable signal."
+        },
+        "newMethodCeiling": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "requireCoverage": {
+          "type": "boolean"
+        },
+        "friction": {
+          "type": "object",
+          "properties": {
+            "markerKey": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "additionalProperties": false
+        },
+        "refreshTag": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/safeString"
+            },
+            {
+              "minLength": 1
+            }
+          ]
+        },
+        "refreshTimeoutMs": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Bounded timeout (ms) for `npm run crap:update` spawned by the baseline-attribution refresh path. Mirrors `coverage.timeoutMs`: a SIGKILL fired at the budget boundary maps to exit 124 so the close orchestrator can flip the Story to `agent::blocked`. Default 60000 (Story #2165)."
+        },
+        "ignoreGlobs": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Minimatch glob patterns matched against the canonicalised repo-relative path of each discovered file. Files matching any pattern are excluded from CRAP discovery before scoring. Orthogonal to `components` (grouping) \u2014 a file excluded here never appears in any component bucket. Absent or empty preserves the existing IGNORED_DIRS-only behaviour (Story #3217)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "maintainabilityGate": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "baselinePath": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/safeString"
+            },
+            {
+              "minLength": 1
+            }
+          ]
+        },
+        "tolerance": {
+          "$ref": "#/$defs/tolerance"
+        },
+        "floors": {
+          "$ref": "#/$defs/floors"
+        },
+        "components": {
+          "$ref": "#/$defs/components"
+        },
+        "targetDirs": {
+          "$ref": "#/$defs/listOrExtenderOfStrings",
+          "description": "Directories whose JS sources the maintainability gate scores. Mandrel ships a `src/`-centric default; projects whose executable code lives elsewhere (e.g. this repo's `.agents/scripts/` plus `tests/`) override here. The framework default is intentionally not auto-discovered, so an override is the explicit, auditable signal."
+        },
+        "refreshTimeoutMs": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Bounded timeout (ms) for `npm run maintainability:update` spawned by the baseline-attribution refresh path. Mirrors `coverage.timeoutMs`: a SIGKILL fired at the budget boundary maps to exit 124 so the close orchestrator can flip the Story to `agent::blocked`. Default 60000 (Story #2165)."
+        },
+        "ignoreGlobs": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Minimatch glob patterns matched against the canonicalised repo-relative path of each discovered file. Files matching any pattern are excluded from MI discovery before scoring. Orthogonal to `components` (grouping) \u2014 a file excluded here never appears in any component bucket. Absent or empty preserves the existing IGNORED_DIRS-only behaviour (Story #3217)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "mutationGate": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "baselinePath": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/safeString"
+            },
+            {
+              "minLength": 1
+            }
+          ]
+        },
+        "tolerance": {
+          "$ref": "#/$defs/tolerance"
+        },
+        "floors": {
+          "$ref": "#/$defs/floors"
+        },
+        "components": {
+          "$ref": "#/$defs/components"
+        },
+        "strykerConfigPath": {
+          "$ref": "#/$defs/nullableNonEmptySafeString"
+        }
+      },
+      "additionalProperties": false
+    },
+    "lighthouseRoute": {
+      "type": "object",
+      "required": ["path"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "formFactor": {
+          "type": "string",
+          "enum": ["mobile", "desktop"]
+        }
+      },
+      "additionalProperties": false
+    },
+    "lighthouseGate": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "baselinePath": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/safeString"
+            },
+            {
+              "minLength": 1
+            }
+          ]
+        },
+        "tolerance": {
+          "$ref": "#/$defs/tolerance"
+        },
+        "floors": {
+          "$ref": "#/$defs/floors"
+        },
+        "components": {
+          "$ref": "#/$defs/components"
+        },
+        "baseUrl": {
+          "$ref": "#/$defs/nullableNonEmptySafeString"
+        },
+        "routes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/lighthouseRoute"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "bundleDeclaration": {
+      "type": "object",
+      "required": ["name", "path", "limit"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "limit": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "bundleSizeGate": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "baselinePath": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/safeString"
+            },
+            {
+              "minLength": 1
+            }
+          ]
+        },
+        "tolerance": {
+          "$ref": "#/$defs/tolerance"
+        },
+        "floors": {
+          "$ref": "#/$defs/floors"
+        },
+        "components": {
+          "$ref": "#/$defs/components"
+        },
+        "bundles": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/bundleDeclaration"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "duplicationGate": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "baselinePath": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/safeString"
+            },
+            {
+              "minLength": 1
+            }
+          ]
+        },
+        "tolerance": {
+          "$ref": "#/$defs/tolerance"
+        },
+        "floors": {
+          "$ref": "#/$defs/floors"
+        },
+        "components": {
+          "$ref": "#/$defs/components"
+        },
+        "targetDirs": {
+          "$ref": "#/$defs/listOrExtenderOfStrings",
+          "description": "Directories whose JS sources the duplication (DRY) gate scans for copy-paste clones. Mandrel ships a `src/`-centric default; projects whose executable code lives elsewhere (e.g. this repo's `.agents/scripts/`) override here. The framework default is intentionally not auto-discovered, so an override is the explicit, auditable signal (Story #3664)."
+        },
+        "refreshTimeoutMs": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Bounded timeout (ms) for `npm run duplication:update` spawned by the baseline-attribution refresh path. Mirrors `crap.refreshTimeoutMs` / `coverage.timeoutMs`: a SIGKILL fired at the budget boundary maps to exit 124. Default 60000 (Story #3664)."
+        },
+        "ignoreGlobs": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Minimatch glob patterns matched against the canonicalised repo-relative path of each discovered file. Files matching any pattern are excluded from duplication discovery before scanning. Orthogonal to `components` (grouping). Absent or empty preserves the existing behaviour (Story #3664)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "gates": {
+      "type": "object",
+      "properties": {
+        "lint": {
+          "$ref": "#/$defs/lintGate"
+        },
+        "coverage": {
+          "$ref": "#/$defs/coverageGate"
+        },
+        "crap": {
+          "$ref": "#/$defs/crapGate"
+        },
+        "maintainability": {
+          "$ref": "#/$defs/maintainabilityGate"
+        },
+        "mutation": {
+          "$ref": "#/$defs/mutationGate"
+        },
+        "lighthouse": {
+          "$ref": "#/$defs/lighthouseGate"
+        },
+        "bundle-size": {
+          "$ref": "#/$defs/bundleSizeGate"
+        },
+        "duplication": {
+          "$ref": "#/$defs/duplicationGate"
+        }
+      },
+      "additionalProperties": false
+    },
+    "codingGuardrails": {
+      "type": "object",
+      "properties": {
+        "cyclomaticFlag": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "cyclomaticMustFix": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "miDropMustRefactor": {
+          "type": "number",
+          "minimum": 0
+        },
+        "requireSiblingTest": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
+    "autoRefresh": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "miDropCap": {
+          "type": "number",
+          "minimum": 0
+        },
+        "crapJumpCap": {
+          "type": "number",
+          "minimum": 0
+        },
+        "scope": {
+          "type": "string",
+          "enum": ["diff", "full"]
+        }
+      },
+      "additionalProperties": false
+    },
+    "baselineEpsilon": {
+      "type": "object",
+      "description": "Per-kind epsilon for s-stability-epsilon (Story #1964). Sub-epsilon row deltas resolve to prior bytes so env variance does not rewrite the on-disk baseline.",
+      "properties": {
+        "maintainability": {
+          "type": "number",
+          "minimum": 0
+        },
+        "crap": {
+          "type": "number",
+          "minimum": 0
+        },
+        "coverage": {
+          "type": "number",
+          "minimum": 0
+        },
+        "mutation": {
+          "type": "number",
+          "minimum": 0
+        },
+        "lint": {
+          "type": "number",
+          "minimum": 0
+        },
+        "lighthouse": {
+          "type": "number",
+          "minimum": 0
+        },
+        "bundle-size": {
+          "type": "number",
+          "minimum": 0
+        },
+        "duplication": {
+          "type": "number",
+          "minimum": 0
+        }
+      },
+      "additionalProperties": false
+    },
+    "gateScoping": {
+      "type": "object",
+      "properties": {
+        "scope": {
+          "type": "string",
+          "enum": ["diff", "full"]
+        },
+        "diffRef": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "formatAutofix": {
+      "type": "object",
+      "description": "Bounded-timeout knob for the close-time `npx biome format --write` spawn (Story #2165). A SIGKILL fired at the budget boundary maps to exit 124 so the close orchestrator can flip the Story to `agent::blocked` with a friction comment.",
+      "properties": {
+        "timeoutMs": {
+          "type": "integer",
+          "minimum": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "lifecycle": {
+      "type": "object",
+      "description": "Knobs consumed by the lifecycle event bus (Epic #2172). `timeouts` is a per-event budget map (eventName \u2192 seconds) used by `TimeoutWatchdog`; missing entries fall back to in-listener defaults. `heartbeatWarnSeconds` is the no-progress threshold consumed by `HeartbeatMonitor`. Story #2227 lays down the keys; consumers land in later stories.",
+      "properties": {
+        "timeouts": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": 1
+          }
+        },
+        "heartbeatWarnSeconds": {
+          "type": "integer",
+          "minimum": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "mergeWatch": {
+      "type": "object",
+      "description": "Knobs consumed by the MergeWatcher lifecycle listener (Story #2896, Epic #2880). `intervalSeconds` is the poll cadence between `gh pr view --json mergeCommit,mergedAt` probes after epic.merge.armed; `maxBudgetSeconds` is the total wall-clock budget before the watcher surfaces `agent::blocked` with reason `budget-exceeded`.",
+      "properties": {
+        "intervalSeconds": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 30,
+          "description": "Seconds between MergeWatcher polls. Default 30."
+        },
+        "maxBudgetSeconds": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 3600,
+          "description": "Total wall-clock budget (seconds) for the MergeWatcher poll loop. Default 3600 (60 minutes)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "quality": {
+      "type": "object",
+      "properties": {
+        "gateScoping": {
+          "$ref": "#/$defs/gateScoping"
+        },
+        "gates": {
+          "$ref": "#/$defs/gates"
+        },
+        "formatAutofix": {
+          "$ref": "#/$defs/formatAutofix"
+        },
+        "codingGuardrails": {
+          "$ref": "#/$defs/codingGuardrails"
+        },
+        "autoRefresh": {
+          "$ref": "#/$defs/autoRefresh"
+        },
+        "baselineEpsilon": {
+          "$ref": "#/$defs/baselineEpsilon"
+        }
+      },
+      "additionalProperties": false
+    },
+    "refactorStage": {
+      "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 \u2014 never changes existing close-validation gate semantics.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "When true, story-deliver runs an advisory post-green refactor stage (refactorer persona + core/refactoring-discipline skill) after the suite is green. Default false \u2014 when unset the stage is skipped and close-validation gate semantics are unchanged."
+        }
+      },
+      "additionalProperties": false
+    },
+    "acceptanceEval": {
+      "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 working diff against each inline `acceptance[]` item, redrafts the unmet items, and re-evaluates \u2014 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 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)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "delivery": {
+      "type": "object",
+      "properties": {
+        "execution": {
+          "$ref": "#/$defs/execution"
+        },
+        "maxTokenBudget": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "lease": {
+          "$ref": "#/$defs/lease"
+        },
+        "docsFreshness": {
+          "$ref": "#/$defs/docsFreshness"
+        },
+        "deliverRunner": {
+          "$ref": "#/$defs/deliverRunner"
+        },
+        "worktreeIsolation": {
+          "$ref": "#/$defs/worktreeIsolation"
+        },
+        "signals": {
+          "$ref": "#/$defs/signals"
+        },
+        "quality": {
+          "$ref": "#/$defs/quality"
+        },
+        "lifecycle": {
+          "$ref": "#/$defs/lifecycle"
+        },
+        "mergeWatch": {
+          "$ref": "#/$defs/mergeWatch"
+        },
+        "epicAudit": {
+          "$ref": "#/$defs/epicAudit"
+        },
+        "codeReview": {
+          "$ref": "#/$defs/codeReview"
+        },
+        "retro": {
+          "$ref": "#/$defs/retro"
+        },
+        "refactorStage": {
+          "$ref": "#/$defs/refactorStage"
+        },
+        "acceptanceEval": {
+          "$ref": "#/$defs/acceptanceEval"
+        },
+        "ci": {
+          "type": "object",
+          "properties": {
+            "skipForStoryPushes": {
+              "type": "boolean",
+              "description": "Story #2899 (Epic #2880, F13). When true (default), pre-push tooling appends a '[skip ci]' trailer to Story-branch commit subjects so intermediate pushes do not stampede the CI fleet. The Epic-branch merge commit produced by story-close.js never carries the marker, regardless of this flag."
+            }
+          },
+          "additionalProperties": false
+        },
+        "preflight": {
+          "type": "object",
+          "description": "Story #2899 (Epic #2880, F13). Thresholds consumed by `.agents/scripts/epic-deliver-preflight.js`. When any value is exceeded the preflight envelope flags a breach and /epic-deliver Phase 1 surfaces it via agent::blocked.",
+          "properties": {
+            "maxStories": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "maxWaves": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "maxInstallCostSeconds": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "maxGithubApiRequests": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "maxClaudeQuotaTokens": {
+              "type": "integer",
+              "minimum": 1
+            }
+          },
+          "additionalProperties": false
+        },
+        "failOnConcurrencyHazards": {
+          "type": "boolean"
+        },
+        "feedbackLoop": {
+          "type": "object",
+          "properties": {
+            "codeReviewAutoFile": {
+              "type": "boolean",
+              "default": true,
+              "description": "When true (default), the Epic finalize listener auto-files non-blocking code-review 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 Epic."
+            },
+            "auditResultsAutoFile": {
+              "type": "boolean",
+              "default": true,
+              "description": "When true (default), the Epic finalize listener 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 Epic."
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "qaSignInSeam": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["urlTemplate"],
+          "additionalProperties": false,
+          "properties": {
+            "urlTemplate": {
+              "allOf": [
+                {
+                  "$ref": "#/$defs/safeString"
+                },
+                {
+                  "minLength": 1
+                }
+              ]
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["skill"],
+          "additionalProperties": false,
+          "properties": {
+            "skill": {
+              "allOf": [
+                {
+                  "$ref": "#/$defs/safeString"
+                },
+                {
+                  "minLength": 1
+                }
+              ]
+            }
+          }
+        }
+      ]
+    },
+    "qaPersonas": {
+      "description": "Personas the QA-harness sign-in seam accepts. Two accepted shapes: (1) a plain array of persona names \u2014 the honest shape for a `urlTemplate` dev-impersonation seam, where the persona name is the sole input the workflow consumes; (2) the object-map form keyed by persona name, where each entry carries per-persona auth material (`credentialRef` or `signInSkill`) consulted only under a `skill`/credential seam.",
+      "oneOf": [
+        {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "allOf": [
+              {
+                "$ref": "#/$defs/safeString"
+              },
+              {
+                "minLength": 1
+              }
+            ]
+          }
+        },
+        {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": {
+            "oneOf": [
+              {
+                "type": "object",
+                "required": ["credentialRef"],
+                "additionalProperties": false,
+                "properties": {
+                  "credentialRef": {
+                    "allOf": [
+                      {
+                        "$ref": "#/$defs/safeString"
+                      },
+                      {
+                        "minLength": 1
+                      }
+                    ]
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "required": ["signInSkill"],
+                "additionalProperties": false,
+                "properties": {
+                  "signInSkill": {
+                    "allOf": [
+                      {
+                        "$ref": "#/$defs/safeString"
+                      },
+                      {
+                        "minLength": 1
+                      }
+                    ]
+                  }
+                }
+              }
+            ]
+          }
+        }
+      ]
+    },
+    "qa": {
+      "type": "object",
+      "description": "Agent-driven QA harness contract (Epic #3214). Optional top-level block. All filesystem-pointer fields (featureRoot, fixturesManifest, designTokens) carry safeString guards rejecting shell-injection metacharacters. signInSeam is a url-template/skill union; personas resolve to a stored credential reference or a sign-in skill, never an inline secret.",
+      "additionalProperties": false,
+      "properties": {
+        "featureRoot": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/safeString"
+            },
+            {
+              "minLength": 1
+            }
+          ]
+        },
+        "fixturesManifest": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/safeString"
+            },
+            {
+              "minLength": 1
+            }
+          ]
+        },
+        "signInSeam": {
+          "$ref": "#/$defs/qaSignInSeam"
+        },
+        "personas": {
+          "$ref": "#/$defs/qaPersonas"
+        },
+        "consoleAllowlist": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "designTokens": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/safeString"
+            },
+            {
+              "minLength": 1
+            }
+          ]
+        }
+      }
+    }
+  }
+}