mandrel 2.31.0 → 2.33.0

package/.agents/README.md

@@ -293,7 +293,7 @@ a single vendored manifest that ships inside the bundle:
 
 - **[`runtime-deps.json`](runtime-deps.json)** — the single source of
   truth. Its `dependencies` block lists the **required** packages (`ajv`,
-  `ajv-formats`, `js-yaml`, `minimatch`, `picomatch`, `string-argv`,
+  `ajv-formats`, `js-yaml`, `minimatch`, `picomatch`,
   `typhonjs-escomplex`); its `optionalDependencies` block lists packages
   used behind graceful-degradation paths (`typescript` for TS-source
   scoring in the maintainability engine, `chokidar` for `quality:watch`,
@@ -360,7 +360,6 @@ refused by `/deliver`. The execution-model contract is owned by
 | Every `.agentrc.json` key, default, and override | [`docs/configuration.md`](docs/configuration.md) (under `.agents/`) |
 | Quality-gate runbooks (CRAP, MI, lint, friction) plus the baseline envelope, component model, and writer/reader contract | [`.agents/docs/quality-gates.md`](docs/quality-gates.md) |
 | Slash-command workflow definitions | [`workflows/`](workflows/) |
-| Render the signals span-tree (debug helper) | [`workflows/helpers/signals.md`](workflows/helpers/signals.md) |
 | Role-scoped spawn boot contexts | [`agents/`](agents/) |
 | Domain-agnostic baseline rules | [`rules/`](rules/) |
 | Skill library (core process + stack guardrails) | [`skills/core/`](skills/core/) · [`skills/stack/`](skills/stack/) |
@@ -687,27 +686,24 @@ The lease primitive lives in
 [`scripts/lib/orchestration/ticket-lease.js`](scripts/lib/orchestration/ticket-lease.js).
 Rather than inventing a new state column, the lease rides the ticket's
 existing **assignees** field: the single assignee *is* the lease owner.
-Liveness is decided by the owner's last-heartbeat timestamp compared against
-a configurable TTL (`delivery.lease.ttlMs`).
-
-> **In practice the lease always fails closed.** There is no live heartbeat
-> source — the `story.heartbeat` emitter was structurally inert and has been
-> deleted (A22) — so every guard anchors the owner's heartbeat to *now*,
-> making **any** foreign claim read as live. The **stale-claim reclaim** row
-> below is therefore unreachable in normal operation: a stranded claim is
-> cleared with `--steal`, never by TTL expiry. The TTL and the reclaim branch
-> remain as a seam for a caller that supplies its own `heartbeatAt`.
-
-The model has five behaviours, all expressed through `acquireLease` /
+
+> **The lease fails closed.** It shipped with a TTL (`delivery.lease.ttlMs`)
+> that reclaimed a claim whose owner's heartbeat had gone stale — but the
+> `story.heartbeat` emitter was structurally inert and was deleted (A22),
+> after which every guard anchored the heartbeat to *now* so **any** foreign
+> claim read as live. Story #5006 deleted the TTL, the heartbeat parameter
+> and the reclaim branch: a foreign claim now refuses unconditionally, and a
+> stranded one is cleared with `--steal`.
+
+The model has four behaviours, all expressed through `acquireLease` /
 `releaseLease`:
 
 | Behaviour | When it fires | Outcome |
 | --------- | ------------- | ------- |
 | **Acquire by self-assign** | The ticket is unassigned. | The operator is written to `assignees`; the run proceeds (`reason: 'unclaimed'`). |
 | **Re-affirm a self-held claim** | The operator already holds the lease. | No write; the run proceeds (`reason: 'already-held'`). |
-| **Refuse-if-foreign** | A *different* operator holds the lease and their heartbeat is within the TTL (the claim is **live**). | The acquire **fails closed** — the run refuses to start and names the current owner so you know who to coordinate with (`reason: 'held'`). |
-| **Stale-claim reclaim** *(unreachable — see above)* | A foreign claim exists but the caller supplied a `heartbeatAt` older than the TTL. | The lease is reassigned to the operator (`reason: 'reclaimed'`). No shipped caller supplies one, so this never fires today. |
-| **`--steal` override** | A foreign claim is *live* and the operator passes `--steal`. | The live claim is forcibly transferred (`reason: 'stolen'`). This is the **only** way past a live foreign claim. |
+| **Refuse-if-foreign** | A *different* operator holds the lease. | The acquire **fails closed** — the run refuses to start and names the current owner so you know who to coordinate with (`reason: 'held'`). |
+| **`--steal` override** | A foreign claim exists and the operator passes `--steal`. | The claim is forcibly transferred (`reason: 'stolen'`). This is the **only** way past a foreign claim. |
 
 On a clean completion the holder **releases** the lease (clears the
 assignment), but only when it still holds it — a late release on a ticket

package/.agents/agents/acceptance-critic.md

@@ -81,8 +81,7 @@ from the evidence.
 You are handed **one cluster** of acceptance criteria to score. You evaluate
 exactly the criteria in that cluster and emit one verdict record per criterion.
 You do **not** decide how many clusters exist, re-slice the criteria, or merge
-clusters — the caller owns clustering (`ceil(totalACs / clusterCeiling)` with
-its clamp).
+clusters — the caller owns clustering.
 
 ## Per-criterion evaluation
 

package/.agents/docs/SDLC.md

@@ -44,14 +44,17 @@ From zero to shipped:
    resolves their dependency graph from live state — body edges union native
    GitHub `blocked_by` edges, every blocker checked against its real issue
    state, so a Story whose blocker landed in an earlier plan run is simply
-   ready. `/deliver` owns input resolution and `depends_on` sequencing only;
+   ready. `/deliver` owns input resolution and dispatch order — the declared
+   `depends_on` edges plus a delivery-time file-overlap guard that withholds
+   two Stories whose footprints would race the same path (see
+   [`architecture.md` § Scheduler safety mechanics](../../docs/architecture.md));
    every Story runs through the single v2 delivery engine
    [`helpers/deliver-story`](../workflows/helpers/deliver-story.md) —
    init → implement → acceptance self-eval → ceremony → close → CI watch →
    confirm-merge — which owns its own per-step detail. For a multi-Story run,
-   `/deliver` sequences ready Stories by `depends_on` and runs the per-run
-   epilogue (audit roster · follow-up roll-up · sibling coherence) once after
-   the last Story lands.
+   `/deliver` sequences ready Stories by `depends_on` — plus that footprint
+   guard — and runs the per-run epilogue (audit roster · follow-up roll-up ·
+   sibling coherence) once after the last Story lands.
 
 That is the whole happy path. Everything below is **detail** — branching
 conventions, HITL escalation, audit lenses — that you only need when the
@@ -62,9 +65,9 @@ rather than re-documenting the ceremony they own.
 ## Core Principles
 
 - **Layered state stores with explicit precedence.** Ticket status lives
-  in GitHub Issues and Labels; the lifecycle bus
-  (`temp/run-<id>/lifecycle.ndjson`) is the canonical resume target for
-  in-flight runs; structured comments (`verification-results`, retro) are
+  in GitHub Issues and Labels; the lifecycle ledger
+  (`lifecycle.ndjson`) records merge-terminal outcomes for post-hoc
+  attribution; structured comments (`verification-results`, retro) are
   the operator-visible rollup. The
   stores, their owners, and their conflict-resolution rules are listed in
   [§ State stores](#state-stores) — that matrix is the single source of
@@ -109,7 +112,7 @@ on-disk layout resolved by
 | --- | --- | --- | --- | --- |
 | GitHub labels | `transitionTicketState` via `ticketing.js` | `gh issue edit --add-label / --remove-label`, wrapped in `update-ticket-state.js` | `(ticketId, label-set)` — set-equality before write | Authoritative for current ticket lifecycle state; if a label disagrees with the lifecycle ledger, the **ledger wins on resume** and the label is re-derived. |
 | `verification-results` comment | `lib/orchestration/code-review.js` | `post-structured-comment.js` (upsert by `kind`) | `(storyId, kind='verification-results')` | Authoritative for the Story-scope review + lens findings; critical findings block close. |
-| Lifecycle ledger NDJSON | `LedgerWriter` (`lib/orchestration/lifecycle/ledger-writer.js`, registered as the first listener on every bus event — single append-only writer per run) | Append-only line write to `temp/run-<id>/lifecycle.ndjson` | `(runId, eventId)` — `eventId` is a content hash of `{type, ts, payload}` | **Canonical resume target.** When labels / comments disagree with the ledger, the ledger wins and the others are re-derived. |
+| Lifecycle ledger NDJSON | `appendLedgerEvent` (`lib/orchestration/lifecycle/emit-ledger-event.js`) — a bare `appendFileSync` from the close path; Story #5024 retired the `LedgerWriter` listener that preceded it | Append-only line write to the scope-resolved `lifecycle.ndjson` | `(storyId, event)` — one record per merge-terminal outcome | Records the two merge-terminal outcomes (`merge.unlanded`, `merge.flip-failed`) for post-hoc attribution. Labels remain authoritative for current ticket state. |
 | Validation evidence cache | `evidence-gate.js` | JSON cache file under the run temp tree, keyed by HEAD SHA | `(gate, git rev-parse HEAD)` | Pure cache: a missing entry triggers a re-run; presence is a fast-path skip. Cache eviction is safe. |
 | PR / auto-merge state | `single-story-close.js` (sole authorized caller of `gh pr merge`) | `gh pr merge --auto --squash --delete-branch`; PR open via the close pipeline's `gh pr create` | `(prNumber, head-branch SHA)` — `gh pr list --head` probes before create | GitHub is authoritative for PR + auto-merge arming state; the ledger records the *intent* to arm, GitHub records the outcome. |
 | Worktree cleanup state | `WorktreeManager.reap` (via `single-story-close.js` / `git-cleanup.js`) | `git worktree remove` + on-disk pending-cleanup JSON under the run temp tree | `(storyId, worktree-path)` | Filesystem is authoritative for "is the worktree gone?"; the pending-cleanup JSON only tracks stale-registry entries needing a follow-up sweep. |
@@ -239,7 +242,7 @@ self-eval, ceremony, close, CI watch, confirm-merge, cleanup) lives in the
 | Mode | Entry point | When to use |
 | --- | --- | --- |
 | **Single Story** | `/deliver <storyId>` | Deliver one Story end-to-end; ends with a PR open to `main`. |
-| **Story set** | `/deliver <storyId> [<storyId>…]` | Deliver multiple Stories in `depends_on` order (default concurrency **3**), resolved from live state so edges may point at Stories from earlier plan runs; each lands through its own PR, and the per-run epilogue runs after the set lands. |
+| **Story set** | `/deliver <storyId> [<storyId>…]` | Deliver multiple Stories in `depends_on` order (default concurrency **3**), resolved from live state so edges may point at Stories from earlier plan runs; a delivery-time file-overlap guard additionally withholds two Stories whose footprints would race the same path (`delivery.deliverRunner.footprintGuard`). Each lands through its own PR, and the per-run epilogue runs after the set lands. |
 | **Story worker (internal)** | *helper* `helpers/deliver-story <storyId>` | Per-Story engine invoked internally by `/deliver`; not an operator slash command. |
 
 The single operator-facing entry point is `/deliver`. It performs no

package/.agents/docs/agentrc-reference.json

@@ -14,7 +14,6 @@
       "patterns.md"
     ],
     "commands": {
-      "lintBaseline": "npx eslint . --format json",
       "test": "npm test",
       "typecheck": null,
       "formatCheck": "npx biome format .",
@@ -61,8 +60,7 @@
         "story-closing",
         "operator-message",
         "merge.unlanded",
-        "merge.flip-failed",
-        "loop.tick"
+        "merge.flip-failed"
       ]
     }
   },
@@ -76,14 +74,14 @@
     ],
     "failOnSharedEditors": false,
     "requireExplicitCrossStoryDeps": false,
-    "failOnRegistryConflicts": false,
-    "failOnLargeFanOut": false,
-    "largeFanOutThreshold": 10,
     "crossCuttingRegistries": [
       "lib/orchestration/lifecycle/listeners/index.js",
       "**/listeners/index.js",
       "**/handlers/index.js"
     ],
+    "failOnRegistryConflicts": false,
+    "failOnLargeFanOut": false,
+    "largeFanOutThreshold": 10,
     "navigation": {
       "routeGlobs": [],
       "navRegistry": []
@@ -93,18 +91,6 @@
     "execution": {
       "timeoutMs": 600000
     },
-    "lease": {
-      "ttlMs": 900000
-    },
-    "ci": {
-      "watch": {
-        "pollIntervalMs": 10000,
-        "maxPolls": 180,
-        "maxResumes": 3,
-        "attachWindowMs": 1200000
-      },
-      "autoMerge": "trust-ci"
-    },
     "docsFreshness": {
       "paths": ["README.md"]
     },
@@ -119,7 +105,8 @@
       }
     },
     "deliverRunner": {
-      "concurrencyCap": 3
+      "concurrencyCap": 3,
+      "footprintGuard": "enforce"
     },
     "worktreeIsolation": {
       "enabled": true,
@@ -143,43 +130,6 @@
         "repeatCount": 3
       }
     },
-    "mergeWatch": {
-      "intervalSeconds": 30,
-      "maxBudgetSeconds": 3600
-    },
-    "codeReview": {
-      "providers": [
-        {
-          "name": "native"
-        },
-        {
-          "name": "security-review",
-          "scopes": ["story"],
-          "optional": true
-        },
-        {
-          "name": "ultrareview",
-          "scopes": ["story"],
-          "manualPrompt": true,
-          "when": {
-            "label": "risk::high"
-          }
-        }
-      ],
-      "maxFixAttempts": 3,
-      "maxFixScopeFiles": 5,
-      "autoFixSeverity": "medium"
-    },
-    "routing": {
-      "roleScopedAgents": true,
-      "freshCriticSampleRate": 0.2,
-      "ceremonyProfile": "standard",
-      "closeAndLand": true
-    },
-    "feedbackLoop": {
-      "auditResultsAutoFile": true,
-      "retroProposals": true
-    },
     "quality": {
       "gateScoping": {
         "scope": "diff",
@@ -346,12 +296,57 @@
         "navRegistry": []
       }
     },
+    "mergeWatch": {
+      "intervalSeconds": 30,
+      "maxBudgetSeconds": 3600
+    },
+    "codeReview": {
+      "providers": [
+        {
+          "name": "native"
+        },
+        {
+          "name": "security-review",
+          "scopes": ["story"],
+          "optional": true
+        },
+        {
+          "name": "ultrareview",
+          "scopes": ["story"],
+          "manualPrompt": true,
+          "when": {
+            "label": "risk::high"
+          }
+        }
+      ],
+      "maxFixAttempts": 3,
+      "maxFixScopeFiles": 5,
+      "autoFixSeverity": "medium"
+    },
     "refactorStage": {
       "enabled": false
     },
     "acceptanceEval": {
-      "maxRounds": 2,
-      "clusterCeiling": 4
+      "maxRounds": 2
+    },
+    "feedbackLoop": {
+      "auditResultsAutoFile": true,
+      "retroProposals": true
+    },
+    "ci": {
+      "watch": {
+        "pollIntervalMs": 10000,
+        "maxPolls": 180,
+        "maxResumes": 3,
+        "attachWindowMs": 1200000
+      },
+      "autoMerge": "trust-ci"
+    },
+    "routing": {
+      "roleScopedAgents": true,
+      "freshCriticSampleRate": 0.2,
+      "ceremonyProfile": "standard",
+      "closeAndLand": true
     }
   },
   "qa": {
@@ -380,6 +375,16 @@
         "signInSkill": "stack/qa/sign-in-member"
       }
     },
+    "gherkinLint": {
+      "scopes": {
+        "web": {
+          "featureRoots": ["apps/web/tests/features"],
+          "stepRoots": ["apps/web/tests/steps"]
+        }
+      },
+      "exemptionTags": ["@skip"],
+      "stepWaivers": []
+    },
     "consoleAllowlist": ["Download the React DevTools", "[HMR]"],
     "designTokens": "src/styles/tokens.css"
   }