mandrel 1.57.0

package/.agents/schemas/qa-ledger.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mandrel.dev/schemas/qa-ledger.schema.json",
+  "title": "QaLedgerItem",
+  "description": "Structured exploratory-QA ledger item (`f3-qa-explore-core`, Feature #3710, Epic #3686). One object per observation captured while exploring a consumer surface — distinct from a `qa-finding` (the browser-sweep `F#` finding): a ledger item classifies a broader exploratory signal (product bug, environment-setup friction, tooling/DX gap, test-coverage gap, or enhancement idea), records the evidence and coverage context, names any missing test, and carries the operator disposition so Triage can parse a whole session. A ledger item has a two-phase lifecycle: the read-only **Capture** phase appends an item with the Capture-phase fields populated (`id`, `class`, `severity`, `evidence`, `coverage`, `missingTest`) but no resolved `disposition`; the **Triage** phase later assigns the `disposition`. The schema therefore validates BOTH the captured-but-untriaged shape (`disposition` absent, `null`, or a `pending`/`untriaged` sentinel — the rolling backlog `.agents/scripts/lib/qa/qa-session.js` reads back on resume) AND the fully-triaged shape (`disposition` resolved to `file`/`defer`/`dismiss`), while still rejecting genuinely malformed items. Evidence MUST already be scrubbed of secrets, session tokens, and PII per `.agents/rules/security-baseline.md` before it is rendered here.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "class",
+    "severity",
+    "evidence",
+    "coverage",
+    "missingTest"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Stable ledger-item identifier, assigned `L1`, `L2`, … in capture order across an exploratory session.",
+      "pattern": "^L[0-9]+$"
+    },
+    "class": {
+      "type": "string",
+      "description": "The kind of exploratory signal this item represents. `product-bug` is a genuine defect in the product under test; `environment-setup` is friction standing up or seeding the environment; `tooling-dx` is a developer-experience or tooling gap; `test-gap` is a missing or insufficient automated test; `enhancement` is a non-defect improvement idea.",
+      "enum": [
+        "product-bug",
+        "environment-setup",
+        "tooling-dx",
+        "test-gap",
+        "enhancement"
+      ]
+    },
+    "severity": {
+      "type": "string",
+      "description": "Operator-assigned severity of the item, used to order Triage attention.",
+      "enum": ["critical", "high", "medium", "low", "info"]
+    },
+    "evidence": {
+      "type": "string",
+      "description": "A one-line, scrubbed description of the observed signal supporting the item (what was seen, where). Captured detail MUST be free of tokens, session cookies, and PII per `.agents/rules/security-baseline.md`.",
+      "minLength": 1
+    },
+    "coverage": {
+      "type": "string",
+      "description": "The surface, scenario, or area of the product the exploration was covering when this item surfaced (e.g. a route label or feature name). Falls back to `unknown` when the explorer cannot resolve a coverage label.",
+      "minLength": 1
+    },
+    "missingTest": {
+      "type": ["string", "null"],
+      "description": "A description of the automated test that, if present, would have caught this signal — or `null` when no test gap applies (e.g. a pure enhancement idea)."
+    },
+    "disposition": {
+      "type": ["string", "null"],
+      "description": "Triage output. Once an item is triaged, this resolves to what Triage should do with it: `file` to promote it to a follow-up ticket, `defer` to park it for a later session, or `dismiss` to close it as non-actionable. While the item is still in the read-only Capture phase (captured-but-untriaged), `disposition` is `null`, absent, or carries a `pending`/`untriaged` sentinel — the rolling-backlog state `.agents/scripts/lib/qa/qa-session.js` reads back on resume. Any non-sentinel string value MUST be one of the triaged enum values; an out-of-enum value (e.g. `maybe`) is still rejected.",
+      "enum": ["file", "defer", "dismiss", "pending", "untriaged", null]
+    },
+    "relates": {
+      "type": "array",
+      "description": "Optional. The ids of other ledger items this item relates to or folds into during session triage. Omit (or leave empty) for a standalone item.",
+      "items": {
+        "type": "string",
+        "pattern": "^L[0-9]+$"
+      }
+    },
+    "routedTo": {
+      "type": "object",
+      "description": "Optional finding-to-issue link recording where Triage routed this item. Populated only after the item is promoted to a follow-up ticket (`disposition: file`); omit while the item is still in Capture or was deferred/dismissed. The same link shape is mirrored on `qa-finding.schema.json`.",
+      "additionalProperties": false,
+      "required": ["issue", "url", "kind"],
+      "properties": {
+        "issue": {
+          "type": "integer",
+          "description": "The GitHub issue number the item was routed to.",
+          "minimum": 1
+        },
+        "url": {
+          "type": "string",
+          "description": "The canonical URL of the routed issue.",
+          "minLength": 1
+        },
+        "kind": {
+          "type": "string",
+          "description": "The kind of ticket the item was routed to: a `story`, an `epic`, or a bare `issue`.",
+          "enum": ["story", "epic", "issue"]
+        }
+      }
+    }
+  }
+}

package/.agents/schemas/risk-verdict.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "risk-verdict",
+  "title": "Planning Risk Verdict",
+  "description": "Planner-authored risk judgment for an Epic, produced by the epic-plan-spec-author Skill as the fourth planning artifact (risk-verdict.json) alongside the PRD, Tech Spec, and Acceptance Spec (Epic #3865). epic-plan-spec.js validates the verdict against this schema, derives the deterministic planningRisk envelope via deriveRiskEnvelope (lib/orchestration/planning-risk.js), and records the verdict as a risk-verdict structured comment plus the epic-plan-state checkpoint riskVerdict field. The model supplies the judgment input (axes); the harness owns the gate decision. A malformed verdict fails closed to the validation-error path — it is never silently coerced.",
+  "type": "object",
+  "required": ["axes", "summary"],
+  "properties": {
+    "axes": {
+      "type": "array",
+      "description": "Risk axes the planner judges to genuinely apply to the Epic. An empty array asserts no recognized risk axis applies (derives an all-low envelope). Every entry must use the fixed axis vocabulary mirrored from REQUIRED_AXES / NOT_APPLICABLE_AXES in lib/orchestration/planning-risk.js.",
+      "items": {
+        "type": "object",
+        "required": ["axis", "level", "rationale"],
+        "properties": {
+          "axis": {
+            "type": "string",
+            "enum": [
+              "visible-behavior",
+              "public-api",
+              "security",
+              "data-migration",
+              "billing",
+              "destructive-mutation",
+              "critical-workflow",
+              "docs-only",
+              "test-harness",
+              "internal-refactor"
+            ],
+            "description": "Risk axis identifier. The first seven force a required acceptance disposition when present (REQUIRED_AXES); the last three waive the acceptance spec when they are the only signals (NOT_APPLICABLE_AXES)."
+          },
+          "level": {
+            "type": "string",
+            "enum": ["low", "medium", "high"],
+            "description": "Planner-judged severity of this axis for the Epic's actual change, not keyword presence — e.g. a PRD sentence saying 'out of scope: billing' is not a billing change."
+          },
+          "rationale": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Concrete, reviewer-readable justification grounded in the PRD / Tech Spec the planner just authored. Never an empty self-attestation."
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1,
+      "description": "One-paragraph overall risk narrative for the audit trail (the rationale the retired regex classifier could never produce)."
+    }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/signal-event.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/signal-event.schema.json",
+  "title": "SignalEvent",
+  "description": "One NDJSON line emitted by the signals writer (Epic #1030). Runtime events live in append-only NDJSON on local disk under temp/epic-<eid>/stories/story-<sid>/signals.ndjson; tickets carry only summaries (story-perf-summary, epic-perf-report). `kind: trace` is the raw tool-call trace; the named kinds are derived signals.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["ts", "kind", "source", "epicId", "storyId"],
+  "properties": {
+    "ts": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Event timestamp in ISO-8601 UTC."
+    },
+    "kind": {
+      "type": "string",
+      "enum": [
+        "friction",
+        "hotspot",
+        "rework",
+        "churn",
+        "idle",
+        "retry",
+        "acceptance-eval",
+        "trace"
+      ]
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tool"],
+      "properties": {
+        "tool": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Originating tool or surface (Bash, Edit, Write, Read, Grep, Glob, or a script name for derived signals)."
+        },
+        "script": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Script that emitted the signal, when applicable (e.g. diagnose-friction.js)."
+        }
+      }
+    },
+    "epicId": { "type": ["integer", "null"], "minimum": 1 },
+    "storyId": { "type": "integer", "minimum": 1 },
+    "phase": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "description": "Execution phase the event was sampled inside (bootstrap, implement, test, close, ...). Null when not applicable (e.g. raw traces outside a phase boundary)."
+    },
+    "details": {
+      "type": "object",
+      "description": "Kind-specific payload. Free-form for forward compatibility; common keys include category, command, elapsedMs, targetHash.",
+      "additionalProperties": true
+    }
+  }
+}

package/.agents/schemas/skill.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mandrel.dev/schemas/skill.schema.json",
+  "title": "SkillFrontmatter",
+  "description": "Canonical YAML frontmatter contract for every SKILL.md under .agents/skills/{core,stack}/. Validated by the skills index generator and the skills validator.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "description"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Skill identifier. MUST equal the parent directory name of the SKILL.md file."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "description": "One-paragraph human description of when to use this skill."
+    },
+    "allowed_tools": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Optional tool allowlist that scopes the skill's execution surface."
+    },
+    "vendor": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Optional vendor / library / product tag for stack skills (e.g. 'playwright', 'tailwind')."
+    }
+  }
+}

package/.agents/schemas/skills-index.schema.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mandrel.dev/schemas/skills-index.schema.json",
+  "title": "SkillsIndex",
+  "description": "Shape of the generated .agents/skills/skills.index.json manifest. Produced by the skills index generator from every SKILL.md under .agents/skills/{core,stack}/.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["generatedAt", "generator", "skills"],
+  "properties": {
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 UTC timestamp at which the index was generated."
+    },
+    "generator": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Identifier of the tool that produced the index (e.g. script path + version)."
+    },
+    "skills": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/skill" }
+    }
+  },
+  "definitions": {
+    "skill": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "tier",
+        "category",
+        "path",
+        "description",
+        "policyCapsuleBullets"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Skill identifier (matches the parent directory name and frontmatter.name)."
+        },
+        "tier": {
+          "type": "string",
+          "enum": ["core", "stack"]
+        },
+        "category": {
+          "type": "string",
+          "minLength": 1,
+          "description": "For tier=core, the bucket name (typically 'core'). For tier=stack, the subcategory (e.g. 'backend', 'frontend', 'qa')."
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Repo-relative POSIX path to the SKILL.md file."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Mirror of the frontmatter description field."
+        },
+        "policyCapsuleBullets": {
+          "type": "integer",
+          "minimum": 5,
+          "maximum": 12,
+          "description": "Number of top-level bullets in the '## Policy Capsule' section. Bounded to keep capsules scannable."
+        },
+        "allowedTools": {
+          "type": ["array", "null"],
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Optional mirror of frontmatter.allowed_tools; null when the SKILL declines to scope tools."
+        },
+        "vendor": {
+          "type": ["string", "null"],
+          "minLength": 1,
+          "description": "Optional mirror of frontmatter.vendor; null for non-vendored skills."
+        }
+      }
+    }
+  }
+}

package/.agents/schemas/story-perf-summary.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/story-perf-summary.schema.json",
+  "title": "StoryPerfSummary",
+  "description": "Payload of the <!-- structured:story-perf-summary --> comment posted once per Story at close (Epic #1030). Replaces the per-Task friction comment fanout and the standalone phase-timings comment.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "kind",
+    "storyId",
+    "epicId",
+    "closedAt",
+    "frictionByCategory",
+    "phaseTimingsMs",
+    "topSlowPhasesVsBaseline",
+    "reworkScore",
+    "retryDensity"
+  ],
+  "properties": {
+    "kind": { "type": "string", "const": "story-perf-summary" },
+    "storyId": { "type": "integer", "minimum": 1 },
+    "epicId": { "type": "integer", "minimum": 1 },
+    "closedAt": { "type": "string", "format": "date-time" },
+    "frictionByCategory": {
+      "type": "object",
+      "description": "Counts of friction signals bucketed by category for this Story.",
+      "additionalProperties": { "type": "integer", "minimum": 0 }
+    },
+    "phaseTimingsMs": {
+      "type": "object",
+      "description": "Elapsed ms per phase, sourced from phase-timer.js in-process record.",
+      "additionalProperties": { "type": "integer", "minimum": 0 }
+    },
+    "topSlowPhasesVsBaseline": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["phase", "elapsedMs", "baselineP95Ms", "ratio"],
+        "properties": {
+          "phase": { "type": "string", "minLength": 1 },
+          "elapsedMs": { "type": "integer", "minimum": 0 },
+          "baselineP95Ms": { "type": "integer", "minimum": 0 },
+          "ratio": { "type": "number", "minimum": 0 }
+        }
+      }
+    },
+    "reworkScore": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["filesEditedBeyondThreshold"],
+      "properties": {
+        "filesEditedBeyondThreshold": { "type": "integer", "minimum": 0 },
+        "topPath": { "type": ["string", "null"], "minLength": 1 },
+        "topPathEdits": { "type": ["integer", "null"], "minimum": 0 }
+      }
+    },
+    "retryDensity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["retries", "uniqueCommands"],
+      "properties": {
+        "retries": { "type": "integer", "minimum": 0 },
+        "uniqueCommands": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "ghSpawnCount": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Throw-away measurement field (Story #1795 / Epic #1788): the in-process `gh` spawn counter snapshot at end of close validation. Used to verify the ≥100 fewer-spawns acceptance criterion against the baseline recorded under `temp/epic-1788/`. Removed in a follow-up cleanup commit before the Story merges to the Epic branch."
+    }
+  }
+}

package/.agents/schemas/validation-evidence.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "validation-evidence",
+  "title": "Validation Evidence",
+  "description": "Per-scope record of which validation gates have passed against which commit SHA. Written by lib/validation-evidence.js under the per-Epic temp tree at temp/epic-<epicId>/validation-evidence.json (Epic-scoped) or temp/epic-<epicId>/stories/story-<storyId>/validation-evidence.json (Story-scoped); both are gitignored via temp/. Consumed by close-validation, epic-code-review, and /epic-deliver Phase 3 (close-validation) to skip identical re-runs against an already-validated tree. The `storyId` field carries the scope id and equals the epic id for Epic-scoped records.",
+  "type": "object",
+  "required": ["storyId", "schemaVersion", "records"],
+  "properties": {
+    "storyId": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "GitHub Issue number of the Story this evidence file belongs to."
+    },
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1,
+      "description": "Evidence-record schema version. Bumped on breaking changes to the record shape."
+    },
+    "records": {
+      "type": "array",
+      "description": "One record per gate that has passed. Each subsequent successful run replaces the prior record for that gate.",
+      "items": {
+        "type": "object",
+        "required": [
+          "gateName",
+          "commitSha",
+          "commandConfigHash",
+          "exitCode",
+          "timestamp"
+        ],
+        "properties": {
+          "gateName": {
+            "type": "string",
+            "enum": [
+              "lint",
+              "test",
+              "format",
+              "check-maintainability",
+              "check-crap"
+            ],
+            "description": "Stable gate identifier. Closed enum — additions require a schema bump."
+          },
+          "commitSha": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{7,64}$",
+            "description": "Output of `git rev-parse HEAD` at the moment the gate passed."
+          },
+          "commandConfigHash": {
+            "type": "string",
+            "pattern": "^sha256:[0-9a-f]{64}$",
+            "description": "sha256 of the canonical JSON of { cmd, args, cwd } used to invoke the gate. Skip is gated on exact-match with the current invocation."
+          },
+          "exitCode": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Exit code recorded for the passing run. Always 0 today; reserved for future non-zero soft-pass semantics."
+          },
+          "durationMs": {
+            "type": ["integer", "null"],
+            "minimum": 0,
+            "description": "Wall-clock duration of the passing run, in milliseconds. Optional."
+          },
+          "inputFingerprint": {
+            "type": ["string", "null"],
+            "description": "Optional sha256 (or other stable digest) of the byte-identical inputs the gate consumed. When present, shouldSkip() will match on this even if the commit SHA has moved — letting docs-only or whitespace-only commits skip an unchanged gate."
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO-8601 timestamp recorded when the gate passed."
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/.agents/scripts/README.md

@@ -0,0 +1,93 @@
+# `.agents/scripts/` — Script Catalog
+
+The orchestration runtime lives under this directory. Most scripts are
+invoked indirectly by `npm run …`, slash-command workflows
+(`.agents/workflows/*.md`), or Husky / GitHub Actions hooks; you rarely
+need to call them by hand.
+
+This file is **not** an exhaustive index of the ~90 top-level entrypoints.
+It documents the **operator-facing scripts** that operators may want to
+run by hand and that are **not** wired into the standard quality / CI
+surface. For everything else, search `package.json` scripts and
+`.agents/workflows/` first.
+
+## Operator Scripts
+
+These scripts are kept in the distributed product but are intentionally
+not invoked by `npm test`, `npm run verify`, CI, or any Husky hook. They
+are optional operator tools; run them by hand when you need them.
+
+### `loc-delta.js`
+
+**Purpose.** Verify the Skills-migration LOC budget — the signed line
+delta between `main` and `HEAD` across the four SSOT directories
+(`.agents/scripts/`, `.agents/skills/`, `.agents/workflows/`,
+`.agents/README.md`) must be `< 0`.
+
+**When to run.** Optional spot-check during framework refactors that
+claim to retire code rather than add it. Originally an acceptance
+criterion of Epic #1181 / Story #1441; kept available because the same
+"net-negative LOC" check is occasionally useful when reviewing
+maintenance Epics.
+
+**Usage.**
+
+```bash
+node .agents/scripts/loc-delta.js                 # main...HEAD
+node .agents/scripts/loc-delta.js --base main     # explicit base
+node .agents/scripts/loc-delta.js --json          # machine output
+```
+
+Exits `0` iff total LOC delta `< 0`; exits `1` otherwise.
+
+### `validate-docs-freshness.js`
+
+**Purpose.** Per-Epic documentation freshness gate. For each doc in
+`delivery.docsFreshness.paths` + `project.docsContextFiles`, asserts
+that the file was meaningfully updated during this Epic's lifecycle
+(commit message references `#<epicId>` or the file body does).
+
+**When to run.** Optional. Useful as a pre-merge spot check when an
+Epic should have produced documentation updates; the standard
+`/epic-deliver` flow does **not** invoke this gate today.
+
+**Usage.**
+
+```bash
+node .agents/scripts/validate-docs-freshness.js --epic <id> \
+  [--base main] [--docs <comma-separated>] [--json]
+```
+
+### `update-mutation-baseline.js`
+
+**Purpose.** Refresh `baselines/mutation.json` from a fresh Stryker
+run. Reads `delivery.quality.gates.mutation` from `.agentrc.json`,
+invokes the in-repo Stryker runner, and atomically rewrites the
+baseline.
+
+**When to run.** Optional. Mutation testing is opt-in per consumer;
+this is the equivalent of `npm run coverage:update` /
+`npm run crap:update` / `npm run maintainability:update` for the
+mutation gate. It is intentionally not wired into `package.json`
+because most consumers do not configure Stryker.
+
+**Usage.**
+
+```bash
+node .agents/scripts/update-mutation-baseline.js [--full-scope]
+```
+
+Exits `0` whether or not the baseline changed; exits `0` (with a
+stderr explainer) when no Stryker config is present; exits `1` only
+when Stryker itself fails to run.
+
+## See Also
+
+- [`/.agents/README.md`](../README.md) — consumer user guide.
+- [`/docs/architecture.md`](../../docs/architecture.md) — system
+  architecture; the "Key Scripts" section lists the standard
+  orchestration entrypoints.
+- [`/docs/quality-gates.md`](../../docs/quality-gates.md) — coverage,
+  CRAP, and maintainability baselines + floors.
+- `package.json` `scripts` — the canonical list of standard CLIs
+  (`test`, `verify`, `coverage:update`, …).