mandrel 2.59.0 → 2.61.0

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

@@ -2,35 +2,13 @@
 
 import { SHELL_INJECTION_PATTERN_STRING } from '../../config-schema-shared.js';
 
-/**
- * Shared sub-schema fragments for `delivery.quality.gates.<tier>`.
- *
- * Every gate shares the same four-field base:
- *
- *   - `enabled`      — when `false`, the checker exits 0 with a skip line.
- *   - `baselinePath` — repo-root-relative path to the gate's baseline file.
- *   - `tolerance`    — `{ kind: 'absolute' | 'percent', value: number }`.
- *   - `floors`       — workspace-keyed `{ "*": { ... } }` absolute floor object.
- *
- * Gate-specific extras (targetDirs for crap/MI, routes for lighthouse,
- * bundles for bundle-size, coveragePath for coverage) layer on top via the
- * per-gate schemas in sibling files. Split out of
- * `config-settings-schema.js` (Story #1737) and then split again
- * (Story #2987) to keep each module under the maintainability ceiling —
- * schema literals score low on MI because they're long and flat.
- */
+/** Shared sub-schema fragments for `delivery.quality.gates.<tier>`. */
 
 export const SAFE_STRING = {
   type: 'string',
   not: { pattern: SHELL_INJECTION_PATTERN_STRING },
 };
 
-export const NULLABLE_NONEMPTY_SAFE_STRING = {
-  type: ['string', 'null'],
-  minLength: 1,
-  not: { type: 'string', pattern: SHELL_INJECTION_PATTERN_STRING },
-};
-
 export const LIST_OR_EXTENDER_OF_STRINGS = {
   oneOf: [
     { type: 'array', items: { type: 'string' } },
@@ -45,7 +23,6 @@ export const LIST_OR_EXTENDER_OF_STRINGS = {
   ],
 };
 
-/** Object-shaped tolerance: `{ kind: 'absolute' | 'percent', value: number }`. */
 export const TOLERANCE_SCHEMA = {
   type: 'object',
   description:
@@ -68,30 +45,7 @@ export const TOLERANCE_SCHEMA = {
 };
 
 /**
- * Workspace-keyed floors object — `"*"` catch-all optional.
- *
- * Each value is a per-component floor object whose keys are the metric
- * names the gate consumes. The metric name keyset is intentionally open
- * (`additionalProperties: { type: 'number' }`) so per-kind rollup keys
- * (e.g. `p95`, `perMethod`, `min`, `p50`, `score`, `errorCount`,
- * `warningCount`) flow through without each per-gate sub-schema having
- * to enumerate them. Story #1892 / Task #1894 affirmed this contract:
- * the open-keyset shape is what unblocks the per-rollup floors that
- * land in S6.
- *
- * Story #2032 / Task #2041: `*` is no longer required. When omitted, the
- * framework-default floor (lines:90 branches:85 functions:90 for
- * coverage, MI ≥ 70, CRAP ≤ 20) is injected by the resolver
- * (`lib/config/quality.js`, Story #2125). Operators may pin a
- * project-wide `*` floor explicitly when they want a value other than
- * the framework default, or declare named non-`*` workspaces for
- * monorepo consumers.
- *
- * The legacy `paths` escape-valve (Story #2029) and its per-row
- * enforcement machinery were removed in Story #2125 after Story #2119
- * verified the per-row path was decorative — the unified gate
- * (`check-baselines.js`, Epic #1943) only enforces project-wide
- * rollup floors.
+ * `"*"` is optional: the resolver injects the framework default when absent.
  */
 export const FLOORS_SCHEMA = {
   type: 'object',
@@ -103,16 +57,6 @@ export const FLOORS_SCHEMA = {
   },
 };
 
-/**
- * Per-gate `components` map — name → glob list. Defaulted to
- * `{ '*': ['**'] }` at the resolver layer (see
- * `.agents/scripts/lib/baselines/components.js`); the schema only
- * constrains the shape when an operator declares it explicitly.
- *
- * Story #1892 / Task #1894: introduced as the shared seam between the
- * reader and writer so per-component rollups + floors can land
- * independently of any one gate.
- */
 export const COMPONENTS_SCHEMA = {
   type: 'object',
   description:
@@ -124,15 +68,11 @@ export const COMPONENTS_SCHEMA = {
 };
 
 /**
- * Build the shared four-field gate base with per-gate `default` annotations
- * layered on (Story #5007). The base fields are identical in shape across
- * every gate but their defaults are not — each gate ships its own
- * `baselinePath`, tolerance, and floors — so the defaults are supplied by the
- * calling gate module rather than baked in here.
+ * Shape is shared; each gate supplies its own `default` annotations.
  *
  * @param {{ enabled?: boolean, baselinePath?: string,
  *   tolerance?: object, floors?: object }} [defaults]
- * @returns {object} A fresh `properties` fragment; never a shared reference.
+ * @returns {object} A fresh fragment.
  */
 export function gateBase(defaults = {}) {
   return {

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

@@ -1,24 +1,9 @@
 /**
- * `github.*` accessor (Epic #1720 Story #1739 — top-level reshape).
- *
- * GitHub identity, branch protection, merge methods, and notifications all
- * live under the top-level `github` block post-reshape.
- *
- * `branchProtection.requiredChecks` is the single source of truth that
- * drives both:
- *
- *   - `/agents-bootstrap-github` — registers GitHub required-status checks.
+ * `github.*` accessor. `branchProtection.requiredChecks` is the SSOT
+ * `/agents-bootstrap-github` registers as required-status checks.
  */
 
-/**
- * Default required-check suite. Mirrors the live CI required-check set
- * (`lint` + `test` + `baselines`); consumers override via
- * `github.branchProtection.requiredChecks` in `.agentrc.json`. Kept in sync
- * with the CI job names in
- * `.github/workflows/ci.yml` — the retired `format:check` folded into `lint`
- * (Story #1829) and `lifecycle-doc-drift` collapsed into `lint`/`docs:check`
- * (Epic #1943), so neither belongs in the default set.
- */
+/** Keep in sync with the job names in `.github/workflows/ci.yml`. */
 export const DEFAULT_REQUIRED_CHECKS = Object.freeze([
   Object.freeze({
     name: 'lint',
@@ -65,10 +50,7 @@ export const NOTIFICATIONS_DEFAULTS = Object.freeze({
 });
 
 /**
- * Read the merged `github.*` block. Accepts the full resolved config or
- * the bare github bag. Operator-supplied keys shallow-overlay framework
- * defaults; the required-checks list is replaced wholesale when present
- * (no extender semantics).
+ * Shallow overlay; `requiredChecks` is replaced wholesale when present.
  *
  * @param {object | null | undefined} config
  * @returns {{

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

@@ -1,66 +1,13 @@
-/**
- * Limits accessors (Epic #1720 Story #1739 — top-level reshape).
- *
- * Pre-reshape, every runtime ceiling lived under the legacy `agentSettings.limits.*` bag.
- * Post-reshape, the surviving operator-configurable key is
- * `delivery.execution.timeoutMs` (per-process execution timeout).
- *
- * Dropped entirely: `maxTickets` (Story #5312 — the reviewability budget
- * never fired on a real plan and duplicated the default-single split policy),
- * `delivery.signals.{rework, retry}` with `SIGNALS_DEFAULTS` (Story #5313 —
- * the detector thresholds bounded execution by count, not by risk),
- * `maxInstructionSteps`, `friction.*`, `executionMaxBuffer`,
- * `signals.{churn, idle, hotspot}`, `delivery.preflight`,
- * `delivery.lease.ttlMs` (Story #5006 deleted the lease TTL: with no
- * heartbeat source every foreign claim read live, so the window decided
- * nothing), `delivery.maxTokenBudget` (planning no longer sizes against a
- * token-budget envelope), and `planning.context.{maxBytes, summaryMode}`
- * (Story #4541 — the `applyBudget` pass they fed lost its last caller in the
- * v2 cutover; the live bound on planner-context size is the fixed
- * `PLAN_CONTEXT_ENVELOPE_BYTE_CEILING` in `lib/orchestration/plan-context.js`).
- *
- * The historic combined accessor `getLimits(config)` is preserved as a
- * compatibility surface: it returns a wrapper carrying the surviving
- * subset so existing call sites that destructured `getLimits` keep
- * working. New call sites should prefer the specific accessors below.
- */
+/** Fixed runtime limits; none is operator-configurable. */
 
-/**
- * Framework defaults for the surviving limits surface.
- */
+/** Timeout (ms) for delivery's long-running spawns. */
 export const LIMITS_DEFAULTS = Object.freeze({
   executionTimeoutMs: 600000,
 });
 
 /**
- * Resolve the surviving limits surface against a `.agentrc.json` shape
- * (post-reshape): `executionTimeoutMs` from `delivery.execution.*`.
- *
- * @param {object|undefined} config
  * @returns {{ executionTimeoutMs: number }}
  */
-export function resolveLimits(config) {
-  const delivery =
-    config?.delivery && typeof config.delivery === 'object'
-      ? config.delivery
-      : {};
-  const execution =
-    delivery.execution && typeof delivery.execution === 'object'
-      ? delivery.execution
-      : {};
-  return {
-    executionTimeoutMs:
-      execution.timeoutMs ?? LIMITS_DEFAULTS.executionTimeoutMs,
-  };
-}
-
-/**
- * Read the merged limits surface. Accepts the full resolved config bag.
- * Returns the wrapper described in `resolveLimits`.
- *
- * @param {object | null | undefined} config
- * @returns {ReturnType<typeof resolveLimits>}
- */
-export function getLimits(config) {
-  return resolveLimits(config ?? undefined);
+export function getLimits() {
+  return { executionTimeoutMs: LIMITS_DEFAULTS.executionTimeoutMs };
 }

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

@@ -1,18 +1,8 @@
 /**
- * `project.paths` accessor (Epic #1720 Story #1739 — top-level reshape).
- *
- * The seven legacy `*Root` subdirectory keys and the legacy `auditOutputDir`
- * were dropped — every `${dir}Root` is derived at runtime as
- * `${agentRoot}/<dir>`, and `auditOutputDir` is derived as `${tempRoot}/audits`.
+ * `project.paths` accessor; every `*Root` subdirectory and `auditOutputDir`
+ * is derived from `agentRoot` / `tempRoot`.
  */
 
-/**
- * Framework defaults for the derived path keys. `agentRoot`, `docsRoot`, and
- * `tempRoot` are schema-required (no defaults — the resolver never silently
- * fills them in); everything else is derived from the required roots and
- * exposed here so call sites that previously read e.g.
- * `paths.scriptsRoot` keep working byte-identically.
- */
 export const PATHS_DEFAULTS = Object.freeze({
   agentRoot: '.agents',
   docsRoot: 'docs',
@@ -20,10 +10,6 @@ export const PATHS_DEFAULTS = Object.freeze({
 });
 
 /**
- * Resolve the merged `project.paths` block, deriving the legacy `*Root`
- * subdirectory keys at runtime so existing call sites keep reading the
- * same shape.
- *
  * @param {object|undefined} userPaths
  * @returns {{
  *   agentRoot: string,
@@ -47,8 +33,6 @@ export function resolvePaths(userPaths) {
     agentRoot,
     docsRoot,
     tempRoot,
-    // Derived: every `${dir}Root` lives directly under the framework's
-    // `agentRoot`; `auditOutputDir` lives under `tempRoot/audits`.
     auditOutputDir: `${tempRoot}/audits`,
     scriptsRoot: `${agentRoot}/scripts`,
     workflowsRoot: `${agentRoot}/workflows`,
@@ -60,9 +44,6 @@ export function resolvePaths(userPaths) {
 }
 
 /**
- * Read the merged `project.paths` block. Accepts the full resolved config
- * or a bare `{ project }` bag.
- *
  * @param {object | null | undefined} config
  * @returns {ReturnType<typeof resolvePaths>}
  */

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

@@ -1,46 +1,21 @@
 /**
- * `qa.gherkinLint` accessor — the static Gherkin corpus gate's contract.
- *
- * The gate is **opt-in**: absent this block, `check-gherkin-corpus.js` reports
- * that it is not configured and exits 0. That is not politeness. `.agents/`
- * reaches a consumer by plain file copy, so every framework upgrade lands this
- * gate in every project at once; a default-on corpus lint would redden the
- * `lint` required check of every repo that happens to own a `.feature` file it
- * never asked the framework to police.
- *
- * Inside the opt-in the posture inverts and the gate fails **closed** — an
- * unresolvable parser or a scope that resolves no step definitions is an
- * error, never a quiet pass. Both are the same blackout the gate exists to
- * catch, wearing a different costume.
- *
- * Scopes are the load-bearing shape. Pooling every step root into one matcher
- * list makes a cross-app false bind possible: a step defined only in app B's
- * suite silently vouches for app A's feature, and the gate reports green on a
- * corpus that cannot generate. Resolving each feature against **its own**
- * scope's step roots makes that structurally impossible rather than merely
- * unlikely.
+ * `qa.gherkinLint`. Opt-in, because an upgrade lands in every consumer at
+ * once and default-on would redden repos that never asked; once opted in it
+ * fails closed. Each feature resolves against its own scope's step roots so
+ * one app's steps cannot vouch for another's feature.
  */
 
-/**
- * Framework defaults for the two escape hatches. `@skip` is the conventional
- * "not meant to run" tag across cucumber-js and playwright-bdd, so it is the
- * default exemption; the waiver list starts empty because every entry is a
- * project-specific admission that the step index guessed wrong.
- */
 const GHERKIN_LINT_DEFAULTS = Object.freeze({
   exemptionTags: Object.freeze(['@skip']),
   stepWaivers: Object.freeze([]),
 });
 
-/** Coerce a value to an array of non-empty strings. */
 function stringArray(value, fallback) {
   if (!Array.isArray(value)) return [...fallback];
   return value.filter((item) => typeof item === 'string' && item.length > 0);
 }
 
 /**
- * Normalize one scope entry into `{ name, featureRoots, stepRoots }`.
- *
  * @param {string} name
  * @param {object} raw
  * @returns {{ name: string, featureRoots: string[], stepRoots: string[] }}
@@ -54,8 +29,6 @@ function normalizeScope(name, raw) {
 }
 
 /**
- * Normalize a raw `qa.gherkinLint` block.
- *
  * @param {object | null | undefined} raw
  * @returns {{
  *   scopes: Array<{ name: string, featureRoots: string[], stepRoots: string[] }>,
@@ -85,8 +58,6 @@ function resolveGherkinLint(raw) {
 }
 
 /**
- * Read the normalized `qa.gherkinLint` contract off a resolved config.
- *
  * @param {object | null | undefined} config
  * @returns {ReturnType<typeof resolveGherkinLint>}
  */
@@ -94,11 +65,6 @@ export function getGherkinLint(config) {
   return resolveGherkinLint(config?.qa?.gherkinLint);
 }
 
-/**
- * Module-private surface the suite drives directly, bundled behind one export
- * for the same reason as `bdd-step-index.js`: `getGherkinLint` is the whole
- * public API, and the normalizer and its defaults are how it is built.
- */
 export const __testing = Object.freeze({
   GHERKIN_LINT_DEFAULTS,
   resolveGherkinLint,