mandrel 1.88.0 → 1.89.0

package/.agents/personas/architect.md

@@ -17,10 +17,12 @@ Before permitting any code generation, you must enforce this workflow:
 1. **Interrogate Context:** Read the Epic body — including its `## User
    Stories` section and the folded Tech Spec sections (`## Delivery
    Slicing` onward; Story #4324 retired the separate Tech Spec ticket) —
-   plus every file listed in
-   `project.docsContextFiles` (typically `architecture.md` and
-   `data-dictionary.md`). Ask clarifying questions about scale, budget, or
-   edge cases.
+   plus the project's docs digest (digest-first with pull-on-demand for
+   `architecture.md`, `data-dictionary.md`, and the rest of
+   `project.docsContextFiles`; see
+   [`.agents/instructions.md` § 3](../instructions.md) — there is no
+   read-every-file mandate). Ask clarifying questions about scale, budget,
+   or edge cases.
 2. **Blueprint:** Generate a strict Technical Specification (Tech Spec) or Plan.
 3. **Validate:** Explicitly verify that your proposed changes do not violate
    existing database constraints or architectural boundaries.
@@ -54,9 +56,10 @@ Before permitting any code generation, you must enforce this workflow:
 
 - **Friction Analysis:** During the retro phase (Phase 5 of
   `/deliver`, driven by `lib/orchestration/retro-runner.js`), you
-  MUST analyze the
-  `agent-friction-log.json` to identify systemic bottlenecks, repetitive tool
-  failures, or prompt ambiguities.
+  MUST analyze the aggregated friction signals — the `kind: friction`
+  records on the per-Epic/per-Story `signals.ndjson` streams, rolled up by
+  the retro's perf-aggregator — to identify systemic bottlenecks, repetitive
+  tool failures, or prompt ambiguities.
 - **Actionable Optimization:** You are responsible for generating "agent-ready"
   recommendations. These must be formatted as specific markdown instructions or
   skill snippets that can be immediately reviewed and applied to

package/.agents/personas/engineer.md

@@ -19,9 +19,10 @@ plan, stop and ask. Do not invent business logic.
 1. **Read Context:** Before writing a single line, read the parent Epic
    body — the single planning document, including its `## User Stories`
    section and the folded Tech Spec sections (`## Delivery Slicing`
-   onward; Story #4324 retired the separate Tech Spec ticket) — plus
-   every file listed in `project.docsContextFiles` (typically
-   `architecture.md` and the project's architectural guidelines).
+   onward; Story #4324 retired the separate Tech Spec ticket) — plus the
+   docs digest (digest-first with pull-on-demand; see
+   [`.agents/instructions.md` § 3](../instructions.md) — there is no
+   read-every-`project.docsContextFiles`-file mandate).
 2. **Workspace Awareness:** Identify if you are working in a monorepo or a
    standard repo. Ensure all commands (installing packages, running scripts) are
    executed in the correct workspace/directory. Check `package.json` or the

package/.agents/personas/project-manager.md

@@ -20,8 +20,11 @@ SQL, or UI components — stop immediately.
 1. **Gather Context:** Read the parent Epic body — including its
    `## User Stories` section and the folded Tech Spec sections
    (`## Delivery Slicing` onward; Story #4324 retired the separate Tech
-   Spec ticket) — plus every file listed in `project.docsContextFiles`
-   (typically `architecture.md` and the data dictionary).
+   Spec ticket) — plus the project's docs digest (digest-first with
+   pull-on-demand for `architecture.md`, the data dictionary, and the rest
+   of `project.docsContextFiles`; see
+   [`.agents/instructions.md` § 3](../instructions.md) — there is no
+   read-every-file mandate).
 2. **Decompose:** Break the Epic into **Stories** that carry their own
    inline acceptance criteria and verification steps. Aim for roughly
    five acceptance bullets per Story as a soft atomicity heuristic; if

package/.agents/personas/refactorer.md

@@ -24,9 +24,11 @@ red tests green by "refactoring".
 
 1. **Read Context:** Before touching anything, confirm the suite is green
    and the quality gates currently pass. Read the parent Epic body —
-   including its folded Tech Spec sections (Story #4324) — plus every file
-   listed in
-   `project.docsContextFiles` so you know the conventions the code must keep
+   including its folded Tech Spec sections (Story #4324) — plus the
+   project's docs digest (digest-first with pull-on-demand across
+   `project.docsContextFiles`; see
+   [`.agents/instructions.md` § 3](../instructions.md) — there is no
+   read-every-file mandate) so you know the conventions the code must keep
    matching.
 2. **Establish the baseline:** Capture the current CRAP and maintainability
    numbers (e.g. `node .agents/scripts/check-baselines.js`) and the set of

package/.agents/rules/git-conventions.md

@@ -165,6 +165,83 @@ operator intervention:
   owning flow's hygiene step regressed — fix the flow, do not codify the manual
   sweep.
 
+### Shared-checkout contention (Story #4460)
+
+`story-close.js`'s merge phase runs `git checkout <epic-branch>` directly in
+the **shared main repo checkout** (`close-inputs.js` resolves `mainCwd` to
+`PROJECT_ROOT`), not an isolated worktree. `lib/epic-merge-lock.js` guards
+that checkout with a **per-Epic** filesystem lock
+(`epic-<epicId>.merge.lock`) so two `story-close.js` runs for the **same**
+Epic serialize against each other — but nothing stops a **different**
+Epic's concurrently-running `story-close.js` from treating the same shared
+checkout as scratch space at the same time.
+
+- **Recognition signature**: a `git checkout`/`git switch` failure during
+  the merge phase whose message is `error: Your local changes ... would be
+  overwritten by checkout`, where the shared checkout is parked on a
+  **different** epic's branch (e.g. `epic/4405`) than the one the current
+  `story-close.js` run is trying to merge (e.g. `epic/4425`), with
+  uncommitted edits that belong to that other Epic's delivery. This was
+  observed live during Epic #4425 delivery (Stories #4427/#4428) colliding
+  with a concurrently-running Epic #4405 session, and had to be worked
+  around by hand via `git stash push -u`.
+- **The fix — `assertSharedCheckoutAvailable`**
+  (`lib/orchestration/story-close/shared-checkout-guard.js`), called from
+  `runFinalizeMerge` in `lib/orchestration/story-close/merge-runner.js`
+  immediately before the merge-phase `git checkout <epicBranch>`. It
+  **composes with, not replaces,** the per-Epic lock:
+  - It first checks the shared common `.git/` dir for a **foreign**
+    (different-epic) `epic-*.merge.lock` file whose recorded PID is still
+    alive (`findForeignActiveEpicLock` in `lib/epic-merge-lock.js`). If
+    found, the merge phase fails fast with a diagnostic naming the holding
+    epic id, its lock-file path, and its PID/acquired-at timestamp —
+    instead of surfacing the raw git checkout error.
+  - It then checks whether the shared checkout is simply dirty (via `git
+    status --porcelain`), regardless of whose branch is checked out, and
+    reports the dirty file list plus the currently-checked-out branch in
+    the failure diagnostic.
+  - It never inspects the **caller's own** epic-id lock namespace, so
+    same-epic concurrent `story-close.js` runs continue to serialize
+    solely through `withEpicMergeLock` (the existing per-Epic lock) before
+    this guard ever executes — this guard only ever refuses on a truly
+    _foreign_ epic's live lock or unrelated dirt.
+- **Not fixed by this guard**: the guard reports the contention early and
+  actionably; it does not redesign the merge phase to use an isolated
+  worktree, and it does not change `restoreStartingBranch`'s existing
+  dirty-tree refusal behavior (`phases/branch-restore.js`) — both remain
+  out of scope. Resolution of an actual collision is still manual: wait for
+  the other Epic's story-close run to finish, or — only once you have
+  independently confirmed that process is no longer running — remove the
+  stale lock file and resolve the dirty tree by hand (stash/commit/reset;
+  never `git reset --hard` or `git checkout --force`).
+
+## Documentation Freshness Gate
+
+The `validate-docs-freshness.js` gate (run during `/deliver`) asks a
+falsifiable question of every doc in `delivery.docsFreshness.paths` +
+`project.docsContextFiles`: **was this doc actually updated for the Epic?**
+A doc passes on either of two conditions, but they are not
+interchangeable:
+
+- **Living docs are satisfied by being rewritten, not annotated.** For
+  any non-changelog doc (architecture, decisions, README, guides, …) the
+  gate passes **only** when an Epic-referencing commit touched the file —
+  a commit whose message references `#<epicId>` and changes the doc.
+  Rewrite the doc as part of the Epic's work; do not sprinkle `#<epicId>`
+  into its prose to satisfy the check. An appended `#<epicId>` annotation
+  alone **fails** the gate for these files, and the failure message names
+  the file and the rewrite-not-append contract.
+- **`#<epicId>` body annotations pass only for changelog files.** A
+  changelog-class file (basename matches `/changelog/i`, e.g.
+  `docs/CHANGELOG.md`) may pass on a body annotation, because an appended
+  release note keyed to the Epic is the legitimate, expected update there.
+  This is the single sanctioned annotation path; every other doc must use
+  the rewrite path above.
+
+This restriction exists to remove the perverse incentive by which the
+gate would otherwise reward manufacturing fake provenance — appending
+Epic-ID history into living docs purely to clear the check.
+
 ## Meta Labels (Retrospective Signal Routing)
 
 Two `meta::*` labels route retrospective signals into durable substrates so

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

@@ -546,8 +546,8 @@
         "autoFixSeverity": {
           "type": "string",
           "enum": ["high", "medium"],
-          "default": "medium",
-          "description": "Severity threshold for on-branch remediation in /deliver Phase 4 (epic-audit). `medium` (default) routes 🔴/🟠/🟡 findings into the host-LLM remediation loop (Mediums batched per lens: one commit per lens, a single validation + overlapping-lens rescan at the end) while 🟢 suggestions still graduate to follow-up issues; `high` reproduces the pre-4399 Critical/High-only routing. Hard cutover — no back-compat flag."
+          "default": "high",
+          "description": "Severity threshold for on-branch remediation of the Epic-close lens findings walked inside the /deliver Phase 5 code-review pass (Story #4412 folded the former Phase 4 lens walk into that single cumulative-diff pass). `high` (default) routes only 🔴 Critical / 🟠 High lens findings into the host-LLM remediation loop while 🟡 Medium and 🟢 Suggestion findings graduate to follow-up issues (🟡 Medium concerns are already remediated shift-left at the write-time and Story-scope tiers); `medium` opts back into routing 🔴/🟠/🟡 (Mediums batched per lens). Hard cutover — no back-compat flag."
         }
       },
       "additionalProperties": false
@@ -1493,15 +1493,15 @@
         "feedbackLoop": {
           "type": "object",
           "properties": {
-            "codeReviewAutoFile": {
+            "auditResultsAutoFile": {
               "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."
+              "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."
             },
-            "auditResultsAutoFile": {
+            "retroProposals": {
               "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."
+              "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."
             }
           },
           "additionalProperties": false

package/.agents/schemas/audit-rules.json

@@ -2,11 +2,13 @@
   "version": 1,
   "audits": {
     "audit-clean-code": {
-      "triggers": { "gates": ["gate1", "gate3"], "alwaysRun": true },
+      "triggers": { "gates": ["gate1", "gate3"], "filePatterns": ["**/*"] },
+      "scope": "local",
       "substitutionKeys": []
     },
     "audit-architecture": {
-      "triggers": { "gates": ["gate1", "gate3"], "alwaysRun": true },
+      "triggers": { "gates": ["gate1", "gate3"] },
+      "scope": "cumulative",
       "substitutionKeys": []
     },
     "audit-security": {
@@ -22,6 +24,7 @@
         ],
         "filePatterns": ["**/*.lock", "**/auth/*.js", "**/crypto/*.js"]
       },
+      "scope": "local",
       "substitutionKeys": []
     },
     "audit-privacy": {
@@ -30,6 +33,7 @@
         "keywords": ["privacy", "pii", "gdpr", "cookie", "tracking"],
         "filePatterns": ["**/user-profile/**/*.js"]
       },
+      "scope": "local",
       "substitutionKeys": []
     },
     "audit-lighthouse": {
@@ -54,6 +58,7 @@
           "**/frontend/**/*.js"
         ]
       },
+      "scope": "local",
       "substitutionKeys": []
     },
     "audit-devops": {
@@ -67,10 +72,12 @@
           "**/*.tf"
         ]
       },
+      "scope": "cumulative",
       "substitutionKeys": []
     },
     "audit-sre": {
       "triggers": { "gates": ["gate4"] },
+      "scope": "global",
       "substitutionKeys": []
     },
     "audit-documentation": {
@@ -91,6 +98,7 @@
           ".agents/workflows/**"
         ]
       },
+      "scope": "cumulative",
       "substitutionKeys": []
     },
     "audit-dependencies": {
@@ -112,6 +120,7 @@
           "**/yarn.lock"
         ]
       },
+      "scope": "cumulative",
       "substitutionKeys": []
     },
     "audit-performance": {
@@ -120,6 +129,7 @@
         "keywords": ["performance", "n+1", "hot path", "latency", "throughput"],
         "filePatterns": [".agents/scripts/**", "src/**/*.{ts,js}"]
       },
+      "scope": "local",
       "substitutionKeys": []
     },
     "audit-quality": {
@@ -128,6 +138,7 @@
         "keywords": ["test", "coverage", "flaky", "assertion"],
         "filePatterns": ["tests/**", "**/*.test.{ts,js}", "**/*.spec.{ts,js}"]
       },
+      "scope": "local",
       "substitutionKeys": []
     },
     "audit-seo": {
@@ -136,6 +147,7 @@
         "keywords": ["seo", "meta", "structured data", "schema.org", "sitemap"],
         "filePatterns": ["**/*.html", "**/sitemap*", "**/robots.txt"]
       },
+      "scope": "local",
       "substitutionKeys": []
     },
     "audit-ux-ui": {
@@ -148,6 +160,7 @@
           "**/*.css"
         ]
       },
+      "scope": "local",
       "substitutionKeys": []
     },
     "audit-navigability": {
@@ -160,6 +173,7 @@
           "route tree"
         ]
       },
+      "scope": "global",
       "substitutionKeys": []
     }
   }

package/.agents/schemas/audit-rules.schema.json

@@ -24,10 +24,15 @@
   "definitions": {
     "auditEntry": {
       "type": "object",
-      "required": ["triggers"],
+      "required": ["triggers", "scope"],
       "additionalProperties": false,
       "properties": {
         "triggers": { "$ref": "#/definitions/triggers" },
+        "scope": {
+          "type": "string",
+          "enum": ["local", "cumulative", "global"],
+          "description": "Concern-ownership tier declaring the widest scope at which this lens's concern becomes decidable. `local` — decidable from a single Story's diff (verified at write-time + Story-scope review). `cumulative` — only decidable across the Epic's combined diff (verified at Epic close). `global` — evaluates a whole-product property regardless of the diff (verified at Epic close; exempt from change-set narrowing). All tier routing derives from this one field via resolveLensTier()."
+        },
         "substitutionKeys": {
           "type": "array",
           "description": "Substitution keys this audit accepts via run-audit-suite --substitution. Empty array means no caller-supplied keys are allowed.",
@@ -38,7 +43,7 @@
     },
     "triggers": {
       "type": "object",
-      "description": "Selection criteria for whether this audit runs against a given ticket / changeset. At least one of `gates` or `alwaysRun: true` must be set for select-audits.js to ever pick the audit.",
+      "description": "Selection criteria for whether this audit runs against a given ticket / changeset. `gates` must be set for select-audits.js to ever pick the audit; keyword / file-pattern matches then narrow selection within a matched gate.",
       "additionalProperties": false,
       "properties": {
         "gates": {
@@ -47,10 +52,6 @@
           "uniqueItems": true,
           "description": "Quality-gate identifiers (gate1..gateN) that include this audit."
         },
-        "alwaysRun": {
-          "type": "boolean",
-          "description": "If true, the audit is always selected regardless of keyword / file-pattern matches."
-        },
         "keywords": {
           "type": "array",
           "items": { "type": "string", "minLength": 1 },

package/.agents/schemas/lifecycle/merge.unlanded.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/merge.unlanded.schema.json",
+  "title": "merge.unlanded",
+  "description": "Emitted whenever a headless delivery run (the epic-path finalize flow or the standalone single-story-close flow) finishes its work without a confirmed merge, so a work-complete-but-unmerged terminal state is precisely attributable from the lifecycle ledger instead of diffing origin/main after the fact (Epic #4425). scope distinguishes the epic-path (ticketId = epicId) from the standalone story-path (ticketId = storyId); blockClass is produced by the shared classifier in merge-block-class.js.",
+  "type": "object",
+  "required": [
+    "event",
+    "scope",
+    "ticketId",
+    "prNumber",
+    "blockClass",
+    "reason",
+    "elapsedSeconds"
+  ],
+  "properties": {
+    "event": { "type": "string", "const": "merge.unlanded" },
+    "scope": {
+      "type": "string",
+      "enum": ["epic", "story"]
+    },
+    "ticketId": { "type": "integer", "minimum": 1 },
+    "prNumber": { "type": "integer", "minimum": 1 },
+    "blockClass": {
+      "type": "string",
+      "enum": [
+        "checks-pending-timeout",
+        "branch-protection-human-required",
+        "arm-failure",
+        "api-race-other"
+      ]
+    },
+    "reason": { "type": "string", "minLength": 1 },
+    "elapsedSeconds": { "type": "number", "minimum": 0 },
+    "timestamp": { "type": "string", "format": "date-time" }
+  },
+  "additionalProperties": false
+}

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

@@ -2,15 +2,15 @@
   "$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.",
+  "description": "One NDJSON line emitted by the signals writer (Epic #1030; canonical envelope cutover Epic #4406 / Story #4413). Runtime events live in append-only NDJSON on local disk under temp/epic-<eid>/stories/story-<sid>/signals.ndjson (per-Story) and temp/epic-<eid>/signals.ndjson (Epic-level wave lifecycle); tickets carry only summaries (story-perf-summary, epic-perf-report). `kind: trace` is the raw tool-call trace; the named kinds are derived signals. This is the ONLY shape — the legacy `timestamp` / `epic` aliases and the `source: { tool }` provenance object were deleted in the same PR that moved every writer (no read-side compatibility branch).",
   "type": "object",
-  "additionalProperties": false,
-  "required": ["ts", "kind", "source", "epicId", "storyId"],
+  "additionalProperties": true,
+  "required": ["kind", "ts"],
   "properties": {
     "ts": {
       "type": "string",
       "format": "date-time",
-      "description": "Event timestamp in ISO-8601 UTC."
+      "description": "Event timestamp in ISO-8601 UTC. The single canonical timestamp key — the legacy `timestamp` alias is gone."
     },
     "kind": {
       "type": "string",
@@ -22,28 +22,43 @@
         "idle",
         "retry",
         "acceptance-eval",
-        "trace"
+        "trace",
+        "wave-start",
+        "wave-end",
+        "wave-complete",
+        "state-transition",
+        "notification.emitted"
       ]
     },
     "source": {
+      "type": "string",
+      "enum": ["framework", "consumer"],
+      "description": "Framework/consumer classification injected by `tagSignalSource` (signals-writer.js) for records appended via appendSignal/appendEpicSignal. Reserved exclusively for this classifier tag — the originating tool/surface lives in `emitter`."
+    },
+    "emitter": {
       "type": "object",
-      "additionalProperties": false,
-      "required": ["tool"],
+      "additionalProperties": true,
       "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": {
+        "command": {
           "type": "string",
-          "minLength": 1,
-          "description": "Script that emitted the signal, when applicable (e.g. diagnose-friction.js)."
+          "description": "Command line the signal blames, when applicable (e.g. the failed command captured by diagnose-friction.js)."
         }
-      }
+      },
+      "description": "Provenance of the record — the tool/script that produced it. Replaces the pre-cutover `source: { tool }` object; `source` now carries only the framework/consumer classification."
     },
     "epicId": { "type": ["integer", "null"], "minimum": 1 },
-    "storyId": { "type": "integer", "minimum": 1 },
+    "storyId": { "type": ["integer", "null"], "minimum": 1 },
+    "taskId": { "type": ["integer", "null"], "minimum": 1 },
+    "category": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Top-level friction category (e.g. Execution Error, baseline-refresh-regression). Read directly by perf-aggregator frictionByCategory and the retro routed-proposal extraction — never nested under details."
+    },
     "phase": {
       "type": ["string", "null"],
       "minLength": 1,
@@ -51,7 +66,7 @@
     },
     "details": {
       "type": "object",
-      "description": "Kind-specific payload. Free-form for forward compatibility; common keys include category, command, elapsedMs, targetHash.",
+      "description": "Kind-specific payload — always an object, never a bare string. Free-form for forward compatibility; common keys include errorPreview, command, commandHash, targetHash, editCount, failureCount, exitCode, elapsedMs.",
       "additionalProperties": true
     }
   }

package/.agents/scripts/acceptance-spec-reconciler.js

@@ -87,10 +87,12 @@ Options:
 /**
  * Pure: parse stable AC IDs (AC-<n>) out of an acceptance-table section.
  * AC authoring style is "Acceptance Table — Markdown table whose first
- * column is the AC ID" — see ACCEPTANCE_SPEC_SYSTEM_PROMPT in
- * epic-plan-spec.js. We scan the entire section with a permissive regex
- * because operators are free to format the content however they wish
- * around the canonical table.
+ * column is the AC ID" — see the Acceptance Spec system prompt in the
+ * `epic-plan-spec-author` skill body
+ * (`.agents/skills/core/epic-plan-spec-author/SKILL.md`), the sole home for
+ * that prompt. We scan the entire section with a permissive regex because
+ * operators are free to format the content however they wish around the
+ * canonical table.
  *
  * Returns IDs **in document order**, deduplicated, normalised to
  * upper-case (`AC-7`, not `ac-7`).