mandrel 2.123.0 → 2.125.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/README.md +1 -1
- package/.agents/docs/agentrc-reference.json +2 -0
- package/.agents/docs/configuration.md +6 -3
- package/.agents/docs/runbooks/dispatch-board.md +174 -0
- package/.agents/docs/runbooks/dispatch.md +219 -0
- package/.agents/docs/runbooks/session-titles.md +52 -0
- package/.agents/runtime-deps.json +2 -2
- package/.agents/schemas/agentrc.schema.json +85 -3
- package/.agents/schemas/audit-rules.schema.json +1 -1
- package/.agents/schemas/story-deliver-terminal.schema.json +7 -2
- package/.agents/scripts/acceptance-eval.js +11 -2
- package/.agents/scripts/check-doc-links.js +4 -4
- package/.agents/scripts/dispatch.js +400 -0
- package/.agents/scripts/lib/audit-baselines/surface-entry.js +2 -2
- package/.agents/scripts/lib/audit-exceptions/globs.js +2 -2
- package/.agents/scripts/lib/audit-exceptions/scope.js +2 -2
- package/.agents/scripts/lib/audit-suite/selector.js +3 -3
- package/.agents/scripts/lib/baselines/bundle-size-scorer.js +3 -3
- package/.agents/scripts/lib/baselines/components.js +2 -2
- package/.agents/scripts/lib/baselines/kinds/_crap-new-method-gate.js +2 -2
- package/.agents/scripts/lib/bdd-runner-detect.js +3 -4
- package/.agents/scripts/lib/child-detached.js +48 -0
- package/.agents/scripts/lib/child-exec.js +11 -0
- package/.agents/scripts/lib/close-validation/base-sync-revalidation.js +2 -2
- package/.agents/scripts/lib/config/delivery-routing.js +15 -12
- package/.agents/scripts/lib/config/gates/coverage.schema.js +1 -1
- package/.agents/scripts/lib/config/handoff.js +21 -6
- package/.agents/scripts/lib/config/temp-paths.js +26 -0
- package/.agents/scripts/lib/config-settings-schema-delivery.js +64 -10
- package/.agents/scripts/lib/config-settings-schema-quality.js +1 -1
- package/.agents/scripts/lib/coverage-baseline.js +3 -3
- package/.agents/scripts/lib/coverage-capture-delta.js +2 -2
- package/.agents/scripts/lib/coverage-capture-own-fix.js +2 -2
- package/.agents/scripts/lib/dispatch/environments.js +135 -0
- package/.agents/scripts/lib/dispatch/launch-cloud.js +164 -0
- package/.agents/scripts/lib/dispatch/launch-local.js +77 -0
- package/.agents/scripts/lib/dispatch/liveness.js +21 -0
- package/.agents/scripts/lib/dispatch/record.js +54 -0
- package/.agents/scripts/lib/dispatch/status.js +285 -0
- package/.agents/scripts/lib/dispatch/targets.js +101 -0
- package/.agents/scripts/lib/dispatch/verdict.js +207 -0
- package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
- package/.agents/scripts/lib/git-test-guard.js +119 -0
- package/.agents/scripts/lib/git-utils.js +3 -0
- package/.agents/scripts/lib/maintainability-utils.js +4 -4
- package/.agents/scripts/lib/observability/handoff-telemetry.js +2 -0
- package/.agents/scripts/lib/observability/source-classifier.js +2 -0
- package/.agents/scripts/lib/orchestration/acceptance-eval-decision.js +3 -2
- package/.agents/scripts/lib/orchestration/block-class-recovery.js +44 -0
- package/.agents/scripts/lib/orchestration/code-review.js +35 -19
- package/.agents/scripts/lib/orchestration/diff-magnitude.js +1 -1
- package/.agents/scripts/lib/orchestration/git-cleanup/phases/filters.js +3 -3
- package/.agents/scripts/lib/orchestration/plan-persist/audit-attribution.js +3 -4
- package/.agents/scripts/lib/orchestration/review-history.js +9 -10
- package/.agents/scripts/lib/orchestration/review-providers/code-review.js +9 -2
- package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +8 -5
- package/.agents/scripts/lib/orchestration/review-providers/codex.js +3 -11
- package/.agents/scripts/lib/orchestration/review-providers/mi-exemptions.js +2 -2
- package/.agents/scripts/lib/orchestration/review-providers/review-depth.js +22 -0
- package/.agents/scripts/lib/orchestration/review-providers/security-review.js +10 -2
- package/.agents/scripts/lib/orchestration/review-providers/types.js +2 -0
- package/.agents/scripts/lib/orchestration/review-providers/ultrareview.js +13 -2
- package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +40 -15
- package/.agents/scripts/lib/orchestration/single-story-close/runner.js +2 -0
- package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +8 -1
- package/.agents/scripts/lib/orchestration/story-handoff.js +222 -54
- package/.agents/scripts/lib/orchestration/story-stage-publish.js +147 -0
- package/.agents/scripts/lib/orchestration/ticketing/reads.js +2 -0
- package/.agents/scripts/lib/test-temp.js +5 -5
- package/.agents/scripts/lib/test-tiers.js +3 -3
- package/.agents/scripts/lib/util/glob-match.js +64 -0
- package/.agents/scripts/lib/wave-runner/footprint.js +3 -3
- package/.agents/scripts/run-tests.js +2 -1
- package/.agents/scripts/session-title.js +187 -0
- package/.agents/scripts/single-story-confirm-merge.js +7 -0
- package/.agents/scripts/single-story-init.js +6 -3
- package/.agents/workflows/helpers/audit-lens-core.md +4 -0
- package/.agents/workflows/helpers/code-review.md +8 -1
- package/.agents/workflows/helpers/deliver-digest.md +22 -23
- package/.agents/workflows/helpers/deliver-light.md +4 -1
- package/.agents/workflows/helpers/deliver-reference.md +55 -24
- package/.agents/workflows/helpers/deliver-story-reference.md +10 -3
- package/.agents/workflows/helpers/deliver-story.md +27 -7
- package/.agents/workflows/helpers/qa-core.md +2 -0
- package/.agents/workflows/mandrel-deliver.md +14 -4
- package/.agents/workflows/mandrel-orchestrate.md +2 -0
- package/.agents/workflows/mandrel-plan.md +4 -0
- package/README.md +8 -0
- package/bin/mandrel.js +35 -13
- package/docs/CHANGELOG.md +29 -0
- package/lib/cli/dispatch.js +27 -0
- package/lib/cli/ui/accounts.js +81 -0
- package/lib/cli/ui/board-model.js +372 -0
- package/lib/cli/ui/board.css +525 -0
- package/lib/cli/ui/board.html +80 -0
- package/lib/cli/ui/board.js +676 -0
- package/lib/cli/ui/log-tail.js +89 -0
- package/lib/cli/ui/panel-model.js +100 -0
- package/lib/cli/ui/preferences.js +136 -0
- package/lib/cli/ui/request-guard.js +108 -0
- package/lib/cli/ui/server.js +211 -0
- package/lib/cli/ui/sources.js +202 -0
- package/lib/cli/ui/story-detail.js +92 -0
- package/lib/cli/ui.js +114 -0
- package/package.json +2 -2
|
@@ -71,7 +71,9 @@ dispatchable and nothing in flight, with the undone Stories and their unmet
|
|
|
71
71
|
blockers named; land a blocker or add it to `--ids`. **4** — `blocked`: a Story
|
|
72
72
|
carries `agent::blocked` with `blockedReason`, the protocol's HITL pause
|
|
73
73
|
([`instructions.md` § 1.J](../../instructions.md)). Blocked outranks a wedge,
|
|
74
|
-
but not a cycle.
|
|
74
|
+
but not a cycle. Only an operator-owned block lands here: a close that ends
|
|
75
|
+
`blocked.recovery: "agent"` leaves its Story `agent::closing` (in flight), and
|
|
76
|
+
you fix and resume it before the next close.
|
|
75
77
|
|
|
76
78
|
**Resuming an exit-4 `blocked`.** Read the friction comment with
|
|
77
79
|
`gh issue view <id> --comments`, and resume only once the operator has
|
|
@@ -419,8 +421,18 @@ then the shipped standalone ratchets CI's `baselines` job runs —
|
|
|
419
421
|
and `check-cyclomatic.js` — in the worktree. It runs **before** the credited
|
|
420
422
|
run because a fix commit afterwards would void that run's credit.
|
|
421
423
|
|
|
422
|
-
- **
|
|
423
|
-
|
|
424
|
+
- **The fast lane runs first.** Each `delivery.handoff.firstChecks` entry,
|
|
425
|
+
in config order, then close's independent baseline compare
|
|
426
|
+
(`check-baselines`, scoring committed rows, so under admitted lanes it waits
|
|
427
|
+
for the overlapped duplication re-score to join; the first checks run beside
|
|
428
|
+
that scan). A finding there settles `fix-required` naming the check and
|
|
429
|
+
quoting its failure rows, and none of typecheck, lint, format,
|
|
430
|
+
quality-preview, the ratchets or the held review starts; `--report-all`
|
|
431
|
+
lists it and runs the rest. A clean lane starts the held review, then the
|
|
432
|
+
checks below.
|
|
433
|
+
- **One pass, every finding.** After the fast lane, every check runs, even
|
|
434
|
+
after a finding. Any finding settles one `fix-required` whose `detail` lists
|
|
435
|
+
each finding on its
|
|
424
436
|
own line, in check order, and whose `findings[]` carries `{ check, detail,
|
|
425
437
|
evidencePath }` per failing check; the envelope's `evidencePath` is the
|
|
426
438
|
first one's in check order. No suite runs before the credited run. Only a
|
|
@@ -635,13 +647,16 @@ review; post-seat checks wait for a real run, because it seats nothing.
|
|
|
635
647
|
## Held review at hand-off {#held-review}
|
|
636
648
|
|
|
637
649
|
The one home of this rule; the digest and the worker contract point here.
|
|
638
|
-
`story-handoff.js` starts the Story-scope code review once
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
650
|
+
`story-handoff.js` starts the Story-scope code review once preflight's fast
|
|
651
|
+
lane passes — the `delivery.handoff.firstChecks` entries and close's
|
|
652
|
+
independent baseline compare — before its first credited check (and before a
|
|
653
|
+
`test`-depositor seat, whose generated-only commit keeps the digest), so it
|
|
654
|
+
runs alongside the rest of preflight, and awaits it after the push, skipping
|
|
655
|
+
the computation when a deposit already matches the diff digest. A fast-lane
|
|
656
|
+
finding starts no review: its fix changes the diff, so that review would be
|
|
657
|
+
thrown away. A precheck refusal, a base merge that does not settle (conflict,
|
|
658
|
+
failed fetch, missing merge driver) or any stop before preflight starts no
|
|
659
|
+
review either. The envelope's `reviewMs` sits beside the run's
|
|
645
660
|
`suiteTimings`. The same computation stands alone for a manual re-run:
|
|
646
661
|
|
|
647
662
|
```bash
|
|
@@ -661,20 +676,36 @@ node <main-repo>/.agents/scripts/story-review-compute.js --story <storyId> --cwd
|
|
|
661
676
|
raw diff. It never stops the handoff on a provider throw — the step reports
|
|
662
677
|
`error` and close computes the review itself.
|
|
663
678
|
- **A CRITICAL is the worker's to fix.** The handoff settles `fix-required`
|
|
664
|
-
naming the deposit.
|
|
665
|
-
own result. One that has landed before the credited run
|
|
666
|
-
the handoff there — no `test`-depositor seat, no run, no
|
|
667
|
-
no credit, no push. One that lands while the run is in
|
|
668
|
-
(the SIGTERM a Ctrl-C sends; the child frees the
|
|
669
|
-
no credit and pushes nothing; a CRITICAL after the
|
|
670
|
-
the push. Any earlier stop still awaits the review
|
|
671
|
-
to `steps[]` once, so no provider is orphaned and one
|
|
672
|
-
findings, each with its own evidence path; `status`
|
|
673
|
-
the first stop's
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
`
|
|
677
|
-
|
|
679
|
+
naming the deposit. On a first run it never cuts preflight short: every
|
|
680
|
+
check runs to its own result. One that has landed before the credited run
|
|
681
|
+
would begin stops the handoff there — no `test`-depositor seat, no run, no
|
|
682
|
+
full-suite lock, no credit, no push. One that lands while the run is in
|
|
683
|
+
flight aborts it (the SIGTERM a Ctrl-C sends; the child frees the
|
|
684
|
+
full-suite lock), records no credit and pushes nothing; a CRITICAL after the
|
|
685
|
+
run still settles after the push. Any earlier stop still awaits the review
|
|
686
|
+
and appends its result to `steps[]` once, so no provider is orphaned and one
|
|
687
|
+
envelope carries both findings, each with its own evidence path; `status`
|
|
688
|
+
and `failedStep` stay the first stop's unless the review blocks, and a
|
|
689
|
+
review `error` never blocks. Fix, commit, and re-run the handoff.
|
|
690
|
+
- **The fix is retried review-first.** When the previous run (its state file
|
|
691
|
+
holds `{ state, envelope }`) stopped on `review-critical` and its preflight
|
|
692
|
+
had passed at that run's head, the next run merges the base, then awaits
|
|
693
|
+
the held review before the duplication re-score, the static seat and
|
|
694
|
+
preflight. Still CRITICAL → it settles at once and lists every step it did
|
|
695
|
+
not run as `skipped` (`review-first retry: held review still CRITICAL`).
|
|
696
|
+
Clean → it continues as a normal handoff, and close adopts the deposit. Any
|
|
697
|
+
other prior stop, no state file, and `--report-all` run as before.
|
|
698
|
+
- **The round cap is script-enforced.** A *CRITICAL round* is a run in
|
|
699
|
+
`story-review-history-<id>.json` holding a CRITICAL that is not
|
|
700
|
+
`unverified`, not `ungrounded` and not overridden; an adopted deposit adds
|
|
701
|
+
no run. When the review settles CRITICAL, the envelope carries
|
|
702
|
+
`reviewRound: { round, cap }`, where `cap` is
|
|
703
|
+
`delivery.acceptanceEval.maxRounds` read by the acceptance gate's own rule
|
|
704
|
+
(below 1 counts as 1). At `round >= cap` the handoff settles `blocked`
|
|
705
|
+
(cause `review-cap`), flips `agent::blocked` and posts a `friction` comment
|
|
706
|
+
listing each open CRITICAL's title. The cap is checked only on a CRITICAL,
|
|
707
|
+
so once an operator clears the block a fix that reviews clean hands off.
|
|
708
|
+
Anything else goes in the hand-off as the severity tally.
|
|
678
709
|
- **Close adopts, else computes — and deposits.** When the deposit's digest
|
|
679
710
|
equals the digest of the diff at close's held-review start, close starts no
|
|
680
711
|
review and posts the deposit after PR-open. A base-sync merge that moves
|
|
@@ -381,9 +381,16 @@ PR, and not when the CI digest recorded a red against that head.
|
|
|
381
381
|
|
|
382
382
|
## Step 4 — CI watch + fix recovery
|
|
383
383
|
|
|
384
|
-
Enter this step
|
|
385
|
-
`
|
|
386
|
-
|
|
384
|
+
Enter this step when Step 3 returned `blocked` with `blocked.recovery:
|
|
385
|
+
"agent"` — `checks-failed` (a required check went red), `queue-ejected`,
|
|
386
|
+
`checks-pending-timeout`, an advisory-gate red or `api-race-other` — or when
|
|
387
|
+
a `--no-wait-merge` run left the PR for you to shepherd. Those blocks leave
|
|
388
|
+
the Story at `agent::closing` (`merged-flip-failed` is also `agent`, but the
|
|
389
|
+
merge already landed: re-run its `nextCommand`). The fix is this session's,
|
|
390
|
+
in this turn ([`deliver-story.md` § Drive to merge](deliver-story.md#drive-to-merge)).
|
|
391
|
+
An `operator` class (`branch-protection-human-required`, `arm-failure`,
|
|
392
|
+
`predicate-refused`, `merge-queue-rest-unsupported`) carries `agent::blocked`
|
|
393
|
+
and waits for a human. When a required check is
|
|
387
394
|
red, the agent owns the green-CI outcome, not just the push: CI runs on a
|
|
388
395
|
different OS and concurrency, and coverage rounding, platform-conditional
|
|
389
396
|
branches, and timing-sensitive tests routinely drift from the dev host.
|
|
@@ -137,12 +137,31 @@ child, and never end your turn while it is still running: "close is running"
|
|
|
137
137
|
is not a return value. On a host that limits background commands (cloud,
|
|
138
138
|
`-p`, Agent SDK, CI) a one-Story close still runs in the foreground but adds
|
|
139
139
|
`--merge-watch-mode async`, so its merge wait moves into the background
|
|
140
|
-
confirm (reference § Async merge-confirm mode).
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
140
|
+
confirm (reference § Async merge-confirm mode). Gate output is captured.
|
|
141
|
+
|
|
142
|
+
### Drive to merge {#drive-to-merge}
|
|
143
|
+
|
|
144
|
+
**Once the PR is open, the land is yours until it merges.** A red check, a
|
|
145
|
+
conflict or a slow CI run is the next step of the delivery, not where it
|
|
146
|
+
ends. Loop on the envelope's `status` (**digest § 6**) until `landed`:
|
|
147
|
+
|
|
148
|
+
1. **`landed`** → Step 7.
|
|
149
|
+
2. **`pending`** → run `nextCommand`. When it can outlive the host's
|
|
150
|
+
foreground ceiling, run it in the background and resume when it exits;
|
|
151
|
+
never end the turn on prose over an unconfirmed merge.
|
|
152
|
+
3. **`failed`** → diagnose, fix, re-run close; a `phase: base-sync`
|
|
153
|
+
conflict comes back with labels untouched — resolve it in `workCwd`,
|
|
154
|
+
commit, run `nextCommand`, and take the blocked path only if you cannot.
|
|
155
|
+
4. **`blocked`, `blocked.recovery: "agent"`** (the Story stays
|
|
156
|
+
`agent::closing`) → apply the friction comment's remedy in this turn:
|
|
157
|
+
read the CI digest, fix at source per
|
|
158
|
+
[`rules/ci-remediation.md`](../../rules/ci-remediation.md), commit, push,
|
|
159
|
+
re-watch, then run `nextCommand` (reference § Step 4).
|
|
160
|
+
5. **Pause only** on `blocked.recovery: "operator"` (close already set
|
|
161
|
+
`agent::blocked`), a PR a human closed, a `capacity` /
|
|
162
|
+
`unreproducible-tier` verdict filed with `--block`, or the third failure
|
|
163
|
+
with the same fix shape ([`instructions.md` § 1.I](../../instructions.md)) — for the last two, flip
|
|
164
|
+
`agent::blocked` with `update-ticket-state.js` and say why.
|
|
146
165
|
|
|
147
166
|
Internals, merge-wait budgets, the slow-CI **async** confirm mode, the
|
|
148
167
|
`autoMerge` policy and every close flag: reference § Step 3.
|
|
@@ -158,7 +177,8 @@ shipped [schema](../../schemas/story-deliver-terminal.schema.json)).
|
|
|
158
177
|
## Steps 4–6 — Recovery (**recovery-only**) {#recover}
|
|
159
178
|
|
|
160
179
|
A `landed` envelope means everything ran — go to Step 7. Enter recovery **only**
|
|
161
|
-
when
|
|
180
|
+
when [§ Drive to merge](#drive-to-merge) routes you there; procedures are
|
|
181
|
+
reference §§ Step 4–6.
|
|
162
182
|
Two rules the spine keeps: a red **disarms auto-merge**,
|
|
163
183
|
so only a green on a NEW head SHA re-arms it — a re-run is refused; fix at source
|
|
164
184
|
and push ([`rules/ci-remediation.md`](../../rules/ci-remediation.md)). And a
|
|
@@ -56,6 +56,8 @@ resolves to an empty record), `consoleAllowlist` (default `[]`), and
|
|
|
56
56
|
|
|
57
57
|
## Session & ledger (temp/qa/)
|
|
58
58
|
|
|
59
|
+
Title the session `node .agents/scripts/session-title.js --event qa --summary "<surface>"` when it starts and `--event qa-done` with the same summary at the `/mandrel-plan` hand-off ([runbook](../../docs/runbooks/session-titles.md)).
|
|
60
|
+
|
|
59
61
|
Resolve the session and its ledger path **once**, up front, via
|
|
60
62
|
[`qa-session.js`](../../scripts/lib/qa/qa-session.js):
|
|
61
63
|
|
|
@@ -76,7 +76,8 @@ to an attended run.
|
|
|
76
76
|
Stories first — **announce it**. It hard-errors (exit 1) on an id that is
|
|
77
77
|
neither a Story nor an Epic, on an Epic with no open children, or on edges
|
|
78
78
|
it cannot read — a missing gate would co-dispatch against an unlanded
|
|
79
|
-
blocker.
|
|
79
|
+
blocker. Then title the session `node .agents/scripts/session-title.js --event deliver --ids <ids>` with the
|
|
80
|
+
ids as typed (the Epic id for an Epic), again on a resume ([runbook](../docs/runbooks/session-titles.md)).
|
|
80
81
|
|
|
81
82
|
2. **Announce (N>1).** Present the resolved order and proceed — do not wait
|
|
82
83
|
for confirmation; the operator can interject mid-run to change it.
|
|
@@ -115,14 +116,18 @@ to an attended run.
|
|
|
115
116
|
- **2 / 3 / 4** — `cycleError` / `wedged` / `blocked`: stop the loop and
|
|
116
117
|
route per reference. **4** is the protocol's HITL pause
|
|
117
118
|
([`instructions.md` § 1.J](../instructions.md)) — surface it and wait for
|
|
118
|
-
the operator; never poll.
|
|
119
|
+
the operator; never poll. On exit 4, a `blocked` envelope or any HITL
|
|
120
|
+
pause, title the session `--event blocked --ids <blocked ids>`. A CI red the session can fix leaves its Story
|
|
121
|
+
at `agent::closing`, so it never reaches exit 4.
|
|
119
122
|
|
|
120
123
|
4. **Land what the workers hand back** (§ Closing what the workers hand back —
|
|
121
124
|
the beat renders each command), then, with every Story landed, run the
|
|
122
125
|
**per-run epilogue (N>1)**:
|
|
123
126
|
`node .agents/scripts/plan-run-epilogue.js --stories 101,102`; N=1 has none
|
|
124
127
|
([reference](helpers/deliver-reference.md)). Every close rolls its container
|
|
125
|
-
Epic up from its children.
|
|
128
|
+
Epic up from its children. With every Story landed (an N=1 `landed`
|
|
129
|
+
envelope, an N>1 `done: true`), title the session `--event delivered` with
|
|
130
|
+
the step 1 ids.
|
|
126
131
|
|
|
127
132
|
5. **Correct what the change invalidated.** If a memory you recalled this
|
|
128
133
|
session is now wrong — a trap this landed, a budget it moved — fix that entry
|
|
@@ -151,7 +156,10 @@ resume what it names.
|
|
|
151
156
|
|
|
152
157
|
**Reading the outcome.** Each close ends the Story in one schema-validated
|
|
153
158
|
envelope — `landed` | `pending` | `blocked` | `failed`; statuses, exits and
|
|
154
|
-
fields are digest § 6.
|
|
159
|
+
fields are digest § 6. Drive each close you run to merge before starting the
|
|
160
|
+
next — [`deliver-story.md` § Drive to merge](helpers/deliver-story.md#drive-to-merge):
|
|
161
|
+
run `pending`'s `nextCommand`, resolve a `base-sync` conflict, and fix, push
|
|
162
|
+
and resume a `blocked.recovery: "agent"` block yourself.
|
|
155
163
|
|
|
156
164
|
**Branch model (authoritative).** `story-<id>` → PR → `main` (squash +
|
|
157
165
|
required checks), per digest § 2; dependent Stories land sequentially. The
|
|
@@ -165,6 +173,8 @@ table is reference § Ceremony.
|
|
|
165
173
|
- **Land or block — never a silent local build** (digest § 2). Attended delivers
|
|
166
174
|
default to close-and-land (`delivery.routing.closeAndLand: true`); rest at
|
|
167
175
|
`agent::closing` only when a human owns the merge.
|
|
176
|
+
- **A run ends at `landed` or an operator-owned block** — never at a red
|
|
177
|
+
check or a conflict this session can fix.
|
|
168
178
|
- **`/mandrel-deliver` never plans.** Planned tickets come from
|
|
169
179
|
[`/mandrel-plan`](mandrel-plan.md), and a refused prompt **escalates**: the
|
|
170
180
|
light path ends, and the escalation's `nextCommand` is what owns the work —
|
|
@@ -43,6 +43,8 @@ annotation, which the inventory already carries.
|
|
|
43
43
|
|
|
44
44
|
## Start — record authority before the first sweep
|
|
45
45
|
|
|
46
|
+
Title the session `node .agents/scripts/session-title.js --event orchestrate` ([runbook](../docs/runbooks/session-titles.md)).
|
|
47
|
+
|
|
46
48
|
1. Ask the operator which actions this run may take unattended, using the
|
|
47
49
|
host's question idiom (`.agents/instructions.md` § 1.A), offering each
|
|
48
50
|
action with its default:
|
|
@@ -51,6 +51,8 @@ node .agents/scripts/plan-context.js --seed "<seed>"
|
|
|
51
51
|
# or: --seed-file <path> | --tickets 123,456 | --amends #<id>
|
|
52
52
|
```
|
|
53
53
|
|
|
54
|
+
**Title the session** ([runbook](../docs/runbooks/session-titles.md)): `node .agents/scripts/session-title.js --event plan-seed --summary "<3–6 words>"` in seed / seed-file mode, `--event plan-ticket --ids <ids>` in tickets / amends mode.
|
|
55
|
+
|
|
54
56
|
It writes the envelope and **`stories.template.json`** (step 2's skeleton) to
|
|
55
57
|
`<tempRoot>/plan-<slug>/` and prints a digest naming both; `--out` overrides
|
|
56
58
|
the path. Persist auto-discovers the envelope from `--plan-dir` and derives
|
|
@@ -159,6 +161,8 @@ is the **terminal** flip after receipts land; stdout is pure JSON. Tickets mode
|
|
|
159
161
|
rewrites a one-for-one source in place, else comments on and closes each
|
|
160
162
|
source id ([ref](helpers/plan-reference.md)).
|
|
161
163
|
|
|
164
|
+
After a clean persist, title the session `node .agents/scripts/session-title.js --event planned --ids <ids>`: the Epic id when one was created or adopted, else the created Story ids ([runbook](../docs/runbooks/session-titles.md)).
|
|
165
|
+
|
|
162
166
|
## Constraints
|
|
163
167
|
|
|
164
168
|
- `/mandrel-plan` never starts delivery — its Stories land via
|
package/README.md
CHANGED
|
@@ -81,6 +81,14 @@ unplanned work: it authors a receipt Story on the fly and escalates to
|
|
|
81
81
|
The full process — labels, state, review, troubleshooting — is in
|
|
82
82
|
[`docs/SDLC.md`](docs/SDLC.md).
|
|
83
83
|
|
|
84
|
+
### The dispatch board
|
|
85
|
+
|
|
86
|
+
`npx mandrel ui` serves a local board on `http://127.0.0.1:4319/` that shows
|
|
87
|
+
every Story's column and environment, and dispatches, resumes or stops a
|
|
88
|
+
delivery when you drag a card (the same actions as `mandrel dispatch`). It is
|
|
89
|
+
bound to your machine and guarded by a per-run token; see the
|
|
90
|
+
[dispatch board runbook](.agents/docs/runbooks/dispatch-board.md).
|
|
91
|
+
|
|
84
92
|
## Audits
|
|
85
93
|
|
|
86
94
|
The `/audit-*` workflows are read-only lenses that examine the codebase along
|
package/bin/mandrel.js
CHANGED
|
@@ -13,7 +13,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
|
|
|
13
13
|
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
|
14
14
|
|
|
15
15
|
/**
|
|
16
|
-
* @typedef {{ description: string, knownFlags:
|
|
16
|
+
* @typedef {{ description: string, knownFlags: string[] }} SubcommandMeta
|
|
17
17
|
* @type {Map<string, SubcommandMeta>}
|
|
18
18
|
*/
|
|
19
19
|
const SUBCOMMANDS = new Map([
|
|
@@ -21,7 +21,7 @@ const SUBCOMMANDS = new Map([
|
|
|
21
21
|
'init',
|
|
22
22
|
{
|
|
23
23
|
description: 'install and configure mandrel in the current project',
|
|
24
|
-
knownFlags:
|
|
24
|
+
knownFlags: [
|
|
25
25
|
'--assume-yes',
|
|
26
26
|
'--skip-github',
|
|
27
27
|
'--owner',
|
|
@@ -30,14 +30,14 @@ const SUBCOMMANDS = new Map([
|
|
|
30
30
|
'--project-number',
|
|
31
31
|
'--operator-handle',
|
|
32
32
|
'--dry-run',
|
|
33
|
-
]
|
|
33
|
+
],
|
|
34
34
|
},
|
|
35
35
|
],
|
|
36
36
|
[
|
|
37
37
|
'sync',
|
|
38
38
|
{
|
|
39
39
|
description: 'materialize .agents/ payload from installed package',
|
|
40
|
-
knownFlags:
|
|
40
|
+
knownFlags: ['--dry-run'],
|
|
41
41
|
},
|
|
42
42
|
],
|
|
43
43
|
[
|
|
@@ -47,7 +47,7 @@ const SUBCOMMANDS = new Map([
|
|
|
47
47
|
// No --dry-run: the projection scripts have no preview mode, and
|
|
48
48
|
// accepting the flag while syncing for real overwrote .claude/ on an
|
|
49
49
|
// operator who asked for a preview. Reject it at the dispatcher.
|
|
50
|
-
knownFlags:
|
|
50
|
+
knownFlags: [],
|
|
51
51
|
},
|
|
52
52
|
],
|
|
53
53
|
[
|
|
@@ -55,42 +55,64 @@ const SUBCOMMANDS = new Map([
|
|
|
55
55
|
{
|
|
56
56
|
description: 'regenerate .claude/agents/ from .agents/agents/',
|
|
57
57
|
// Same contract as sync-commands: no preview mode, so no --dry-run.
|
|
58
|
-
knownFlags:
|
|
58
|
+
knownFlags: [],
|
|
59
59
|
},
|
|
60
60
|
],
|
|
61
61
|
[
|
|
62
62
|
'doctor',
|
|
63
63
|
{
|
|
64
64
|
description: 'run readiness checks and report remedies',
|
|
65
|
-
knownFlags:
|
|
65
|
+
knownFlags: [],
|
|
66
66
|
},
|
|
67
67
|
],
|
|
68
68
|
[
|
|
69
69
|
'update',
|
|
70
70
|
{
|
|
71
71
|
description: 'upgrade mandrel to the newest published version',
|
|
72
|
-
knownFlags:
|
|
72
|
+
knownFlags: ['--dry-run', '--install-cmd'],
|
|
73
73
|
},
|
|
74
74
|
],
|
|
75
75
|
[
|
|
76
76
|
'migrate',
|
|
77
77
|
{
|
|
78
78
|
description: 'apply version-keyed migrations for a version range',
|
|
79
|
-
knownFlags:
|
|
79
|
+
knownFlags: ['--from', '--to', '--dry-run'],
|
|
80
80
|
},
|
|
81
81
|
],
|
|
82
82
|
[
|
|
83
83
|
'explain',
|
|
84
84
|
{
|
|
85
85
|
description: 'print resolved config values and their sources',
|
|
86
|
-
knownFlags:
|
|
86
|
+
knownFlags: ['--json'],
|
|
87
|
+
},
|
|
88
|
+
],
|
|
89
|
+
[
|
|
90
|
+
'dispatch',
|
|
91
|
+
{
|
|
92
|
+
description: 'start, resume or stop a Story in a named environment',
|
|
93
|
+
knownFlags: [
|
|
94
|
+
'--env',
|
|
95
|
+
'--resume',
|
|
96
|
+
'--stop',
|
|
97
|
+
'--status',
|
|
98
|
+
'--json',
|
|
99
|
+
'--done-limit',
|
|
100
|
+
'--dry-run',
|
|
101
|
+
],
|
|
102
|
+
},
|
|
103
|
+
],
|
|
104
|
+
[
|
|
105
|
+
'ui',
|
|
106
|
+
{
|
|
107
|
+
description: 'serve the local dispatch board on 127.0.0.1',
|
|
108
|
+
knownFlags: ['--port'],
|
|
87
109
|
},
|
|
88
110
|
],
|
|
89
111
|
[
|
|
90
112
|
'uninstall',
|
|
91
113
|
{
|
|
92
114
|
description: 'reverse a recorded install using the install ledger',
|
|
93
|
-
knownFlags:
|
|
115
|
+
knownFlags: ['--include-github', '--dry-run'],
|
|
94
116
|
},
|
|
95
117
|
],
|
|
96
118
|
]);
|
|
@@ -165,7 +187,7 @@ const UNIVERSAL_FLAGS = new Set(['--help', '-h']);
|
|
|
165
187
|
* Only flag names are checked (`--flag=value` is split).
|
|
166
188
|
*
|
|
167
189
|
* @param {string} subName
|
|
168
|
-
* @param {
|
|
190
|
+
* @param {string[]} knownFlags
|
|
169
191
|
* @param {string[]} argv
|
|
170
192
|
* @returns {string | null}
|
|
171
193
|
*/
|
|
@@ -174,7 +196,7 @@ function findUnknownFlag(subName, knownFlags, argv) {
|
|
|
174
196
|
if (!arg.startsWith('-')) continue;
|
|
175
197
|
const flagName = arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg;
|
|
176
198
|
if (UNIVERSAL_FLAGS.has(flagName)) continue;
|
|
177
|
-
if (!knownFlags.
|
|
199
|
+
if (!knownFlags.includes(flagName)) {
|
|
178
200
|
const names = [...knownFlags].sort().join(', ');
|
|
179
201
|
const hint = names.length > 0 ? ` Known flags: ${names}\n` : '';
|
|
180
202
|
return (
|
package/docs/CHANGELOG.md
CHANGED
|
@@ -15,6 +15,35 @@ All notable changes to this project will be documented in this file.
|
|
|
15
15
|
-->
|
|
16
16
|
<!-- markdownlint-disable-file MD004 MD012 MD037 -->
|
|
17
17
|
|
|
18
|
+
## [2.125.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.124.0...mandrel-v2.125.0) (2026-11-19)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
### Added
|
|
22
|
+
|
|
23
|
+
* add `mandrel ui`: a local board that shows every Story and dispatches by drag ([#6111](https://github.com/dsj1984/mandrel/issues/6111)) ([#6118](https://github.com/dsj1984/mandrel/issues/6118)) ([94cfb12](https://github.com/dsj1984/mandrel/commit/94cfb12f2ddf88f38fe63462532c9607788241d7))
|
|
24
|
+
* dispatch a Story to a named environment with `mandrel dispatch` (local launch) ([#6108](https://github.com/dsj1984/mandrel/issues/6108)) ([#6116](https://github.com/dsj1984/mandrel/issues/6116)) ([90f0576](https://github.com/dsj1984/mandrel/commit/90f05766e57a6371ae1aec6a06d86a3e6af9805c))
|
|
25
|
+
* dispatch a Story to an Anthropic cloud environment by firing a Claude routine ([#6110](https://github.com/dsj1984/mandrel/issues/6110)) ([#6117](https://github.com/dsj1984/mandrel/issues/6117)) ([d3d286c](https://github.com/dsj1984/mandrel/commit/d3d286cf24f253cd96645858b8d131820d4d37f3))
|
|
26
|
+
* dispatch board Settings: a gear icon opens per-browser board preferences, including how many Done Stories to show ([#6123](https://github.com/dsj1984/mandrel/issues/6123)) ([#6126](https://github.com/dsj1984/mandrel/issues/6126)) ([6ea0360](https://github.com/dsj1984/mandrel/commit/6ea0360e64dc9407e4929d1f8046be713e0c2772))
|
|
27
|
+
* dispatch board shows which GitHub and Claude accounts it uses, and opens Environments and Connections in the side panel from header icons ([#6122](https://github.com/dsj1984/mandrel/issues/6122)) ([#6125](https://github.com/dsj1984/mandrel/issues/6125)) ([4aecdca](https://github.com/dsj1984/mandrel/commit/4aecdca2fcd01bbac2447e4acea3e21d1e6f4acb))
|
|
28
|
+
* publish a Story's delivery stage to GitHub so remote runs show their progress ([#6109](https://github.com/dsj1984/mandrel/issues/6109)) ([#6114](https://github.com/dsj1984/mandrel/issues/6114)) ([430c8ec](https://github.com/dsj1984/mandrel/commit/430c8eca1e989cd01cc30ad02d785a80ee57b1c3))
|
|
29
|
+
* show on each dispatch-board card whether its delivery is alive and where it stands, with a detail popout per Story ([#6121](https://github.com/dsj1984/mandrel/issues/6121)) ([#6124](https://github.com/dsj1984/mandrel/issues/6124)) ([8c6e2dd](https://github.com/dsj1984/mandrel/commit/8c6e2dd1150b50985841bbd0119307330ddf0b74))
|
|
30
|
+
* title the host session with a state glyph as plan, deliver, orchestrate, audit and QA runs progress ([#6119](https://github.com/dsj1984/mandrel/issues/6119)) ([#6120](https://github.com/dsj1984/mandrel/issues/6120)) ([a0ebec9](https://github.com/dsj1984/mandrel/commit/a0ebec92ebb9364a26f98446633f2e6e603ad191))
|
|
31
|
+
|
|
32
|
+
## [2.124.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.123.0...mandrel-v2.124.0) (2026-11-17)
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
### Added
|
|
36
|
+
|
|
37
|
+
* a Story's first held review is an exhaustive deep pass that sweeps every instance of each defect class ([#6100](https://github.com/dsj1984/mandrel/issues/6100)) ([#6102](https://github.com/dsj1984/mandrel/issues/6102)) ([ba0b87f](https://github.com/dsj1984/mandrel/commit/ba0b87f20709a37152885826f04493ae7ddddf16))
|
|
38
|
+
* deliver drives the PR to merge: agent-recoverable CI reds and conflicts are fixed in-session, only operator-owned blocks pause ([#6091](https://github.com/dsj1984/mandrel/issues/6091)) ([#6092](https://github.com/dsj1984/mandrel/issues/6092)) ([07caf64](https://github.com/dsj1984/mandrel/commit/07caf6459d1ffd8e266b530529f0f28670837226))
|
|
39
|
+
* story-handoff bounds the held-review loop, retries a review-critical fix review-first, and fails fast on cheap blocking gates ([#6099](https://github.com/dsj1984/mandrel/issues/6099)) ([#6103](https://github.com/dsj1984/mandrel/issues/6103)) ([9a4db8a](https://github.com/dsj1984/mandrel/commit/9a4db8aca84b54c1b4b518e8a8f4a6c911a1c580))
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
### Fixed
|
|
43
|
+
|
|
44
|
+
* **deps:** replace picomatch with minimatch behind one glob seam ([#6093](https://github.com/dsj1984/mandrel/issues/6093)) ([2db3b96](https://github.com/dsj1984/mandrel/commit/2db3b969e15f7b749f0bac1502c590a8ccdbf035))
|
|
45
|
+
* **test:** give suite-admission AC-6's first backfiller its own window (refs [#6105](https://github.com/dsj1984/mandrel/issues/6105)) ([#6106](https://github.com/dsj1984/mandrel/issues/6106)) ([896851e](https://github.com/dsj1984/mandrel/commit/896851e220733a242ad32773e37b52005cbfd2f9))
|
|
46
|
+
|
|
18
47
|
## [2.123.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.122.0...mandrel-v2.123.0) (2026-11-17)
|
|
19
48
|
|
|
20
49
|
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
// lib/cli/dispatch.js
|
|
2
|
+
/**
|
|
3
|
+
* `mandrel dispatch` subcommand: the operator-facing face of
|
|
4
|
+
* `.agents/scripts/dispatch.js`. Both call `runDispatch`, so they share one
|
|
5
|
+
* envelope and one set of exit codes; this module only maps the code onto
|
|
6
|
+
* the process.
|
|
7
|
+
*
|
|
8
|
+
* Injectable seams (used by tests): `exit` replaces setting
|
|
9
|
+
* `process.exitCode`; every other key is passed to `runDispatch`.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
import { runDispatch } from '../../.agents/scripts/dispatch.js';
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* @param {string[]} argv
|
|
16
|
+
* @param {{ exit?: (code: number) => void } & Parameters<typeof runDispatch>[1]} [deps]
|
|
17
|
+
* @returns {Promise<void>}
|
|
18
|
+
*/
|
|
19
|
+
export default async function run(argv, deps = {}) {
|
|
20
|
+
const {
|
|
21
|
+
exit = (code) => {
|
|
22
|
+
process.exitCode = code;
|
|
23
|
+
},
|
|
24
|
+
...rest
|
|
25
|
+
} = deps;
|
|
26
|
+
exit(await runDispatch(argv, rest));
|
|
27
|
+
}
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
// lib/cli/ui/accounts.js
|
|
2
|
+
/**
|
|
3
|
+
* Which GitHub login and Claude account the board and its local launches
|
|
4
|
+
* act as. Both probes run in parallel, the result is reused for `ttlMs`, and
|
|
5
|
+
* nothing here logs a value: account fields leave only in the response.
|
|
6
|
+
*
|
|
7
|
+
* @module cli/ui/accounts
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import { runGh } from '../../../.agents/scripts/lib/gh-exec.js';
|
|
11
|
+
|
|
12
|
+
const TIMEOUT_MS = 10_000;
|
|
13
|
+
const LOGIN_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
|
|
14
|
+
const ACCOUNT_FIELDS = ['email', 'orgName', 'subscriptionType', 'authMethod'];
|
|
15
|
+
const FIRST_PARTY = 'firstParty';
|
|
16
|
+
|
|
17
|
+
async function githubLogin(env, runner) {
|
|
18
|
+
const r = await runGh(
|
|
19
|
+
['api', 'user', '--jq', '.login'],
|
|
20
|
+
{ env, timeout: TIMEOUT_MS },
|
|
21
|
+
runner,
|
|
22
|
+
);
|
|
23
|
+
const login = !r.error && r.status === 0 ? (r.stdout ?? '').trim() : '';
|
|
24
|
+
return LOGIN_RE.test(login)
|
|
25
|
+
? { login }
|
|
26
|
+
: { login: null, reason: 'login-unavailable' };
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
function parseJson(text) {
|
|
30
|
+
try {
|
|
31
|
+
return JSON.parse(text);
|
|
32
|
+
} catch {
|
|
33
|
+
return null;
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** The whitelisted account summary from `claude auth status --json`, or `null`. */
|
|
38
|
+
function accountOf(status) {
|
|
39
|
+
if (status?.loggedIn !== true) return null;
|
|
40
|
+
const account = {};
|
|
41
|
+
for (const field of ACCOUNT_FIELDS) {
|
|
42
|
+
if (typeof status[field] === 'string') account[field] = status[field];
|
|
43
|
+
}
|
|
44
|
+
const provider = status.apiProvider;
|
|
45
|
+
if (typeof provider === 'string' && provider !== FIRST_PARTY) {
|
|
46
|
+
account.apiProvider = provider;
|
|
47
|
+
}
|
|
48
|
+
return account;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
async function claudeAccount(runner) {
|
|
52
|
+
const r = await runner('claude', ['auth', 'status', '--json'], {
|
|
53
|
+
shell: process.platform === 'win32',
|
|
54
|
+
timeout: TIMEOUT_MS,
|
|
55
|
+
});
|
|
56
|
+
return !r.error && r.status === 0 ? accountOf(parseJson(r.stdout)) : null;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* @param {{ env: Record<string, string|undefined>, runner: Function,
|
|
61
|
+
* ttlMs?: number, now?: () => number }} deps
|
|
62
|
+
* @returns {() => Promise<{ github: { login: string|null, reason?: string },
|
|
63
|
+
* claude: object|null }>}
|
|
64
|
+
*/
|
|
65
|
+
export function createAccountProbe({
|
|
66
|
+
env,
|
|
67
|
+
runner,
|
|
68
|
+
ttlMs = 60_000,
|
|
69
|
+
now = Date.now,
|
|
70
|
+
}) {
|
|
71
|
+
let cached = null;
|
|
72
|
+
return () => {
|
|
73
|
+
if (cached && now() - cached.at < ttlMs) return cached.promise;
|
|
74
|
+
const promise = Promise.all([
|
|
75
|
+
githubLogin(env, runner),
|
|
76
|
+
claudeAccount(runner),
|
|
77
|
+
]).then(([github, claude]) => ({ github, claude }));
|
|
78
|
+
cached = { at: now(), promise };
|
|
79
|
+
return promise;
|
|
80
|
+
};
|
|
81
|
+
}
|