mandrel 2.123.0 → 2.124.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 +1 -0
- package/.agents/docs/configuration.md +4 -3
- package/.agents/runtime-deps.json +2 -2
- package/.agents/schemas/agentrc.schema.json +25 -3
- package/.agents/schemas/audit-rules.schema.json +1 -1
- package/.agents/schemas/story-deliver-terminal.schema.json +7 -2
- package/.agents/scripts/check-doc-links.js +4 -4
- 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/close-validation/base-sync-revalidation.js +2 -2
- 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-settings-schema-delivery.js +19 -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/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/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/story-deliver-terminal.js +8 -1
- package/.agents/scripts/lib/orchestration/story-handoff.js +216 -54
- 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/single-story-init.js +3 -3
- package/.agents/workflows/helpers/code-review.md +8 -1
- package/.agents/workflows/helpers/deliver-digest.md +22 -23
- 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/mandrel-deliver.md +8 -2
- package/docs/CHANGELOG.md +15 -0
- package/package.json +2 -2
|
@@ -23,6 +23,7 @@ import { fileURLToPath } from 'node:url';
|
|
|
23
23
|
import { assertNoReservedIdStreams } from './check-test-temp-hygiene.js';
|
|
24
24
|
import { cleanupRepoTestTempArtifacts } from './cleanup-repo-test-temp.js';
|
|
25
25
|
import { runAsCli } from './lib/cli-utils.js';
|
|
26
|
+
import { armGitGuard } from './lib/git-test-guard.js';
|
|
26
27
|
import { buildWebhookSafeTestEnv } from './lib/test-env.js';
|
|
27
28
|
import { reportTestRunCredit } from './lib/test-run-credit.js';
|
|
28
29
|
import {
|
|
@@ -224,7 +225,7 @@ export async function runTestSuite({
|
|
|
224
225
|
...options,
|
|
225
226
|
files,
|
|
226
227
|
cwd,
|
|
227
|
-
env: buildWebhookSafeTestEnv(process.env),
|
|
228
|
+
env: armGitGuard(buildWebhookSafeTestEnv(process.env), process.env),
|
|
228
229
|
stdout,
|
|
229
230
|
});
|
|
230
231
|
} finally {
|
|
@@ -57,7 +57,7 @@ import { createProvider } from './lib/provider-factory.js';
|
|
|
57
57
|
import { buildProtectionCtx } from './lib/single-story-sweep/protection-ctx.js';
|
|
58
58
|
import { resolveSweepLockPath } from './lib/single-story-sweep/sweep-lock.js';
|
|
59
59
|
// `sweepMergedStoryBranches` is imported dynamically: its graph reaches
|
|
60
|
-
// `
|
|
60
|
+
// `minimatch`, which would crash before `assertDepsInstalled()` can report.
|
|
61
61
|
import { WorktreeManager } from './lib/worktree-manager.js';
|
|
62
62
|
|
|
63
63
|
export { handleRemoteVerificationFailure } from './lib/orchestration/story-init-remote.js';
|
|
@@ -68,11 +68,11 @@ export { makeGhRunner } from './lib/single-story-sweep/protection-ctx.js';
|
|
|
68
68
|
* opaque `ERR_MODULE_NOT_FOUND` from deep in the sweep graph. Builtins only.
|
|
69
69
|
*/
|
|
70
70
|
function assertDepsInstalled(projectRoot) {
|
|
71
|
-
const probe = path.join(projectRoot, 'node_modules', '
|
|
71
|
+
const probe = path.join(projectRoot, 'node_modules', 'minimatch');
|
|
72
72
|
if (!existsSync(probe)) {
|
|
73
73
|
throw new Error(
|
|
74
74
|
[
|
|
75
|
-
'Project dependencies are not installed (missing node_modules/
|
|
75
|
+
'Project dependencies are not installed (missing node_modules/minimatch).',
|
|
76
76
|
`Run \`npm install\` from ${projectRoot} before invoking this script.`,
|
|
77
77
|
].join(' '),
|
|
78
78
|
);
|
|
@@ -87,6 +87,13 @@ The `code-review` provider also maps depth to `claude --effort`: `low` at
|
|
|
87
87
|
`light` and `standard`, `high` at `deep`. `delivery.codeReview.effortByDepth`
|
|
88
88
|
overrides that per depth (`low`/`medium`/`high`/`xhigh`/`max`).
|
|
89
89
|
|
|
90
|
+
A Story's **first pass** (its review history holds no run) is always `deep`
|
|
91
|
+
and carries `exhaustive: true`: the LLM-backed providers append one shared
|
|
92
|
+
directive asking the reviewer to sweep every changed file for every instance
|
|
93
|
+
of each defect class it raises, and every added read, write and response path
|
|
94
|
+
for an access or role-narrowing class. The history marks that run
|
|
95
|
+
`exhaustive`. A review with no history seam is never a first pass.
|
|
96
|
+
|
|
90
97
|
The LLM-backed review providers (code-review, codex, security-review,
|
|
91
98
|
ultrareview) render the resolved `depth` into the prompt/instructions they emit so the underlying
|
|
92
99
|
model actually changes thoroughness. The native provider deliberately ignores
|
|
@@ -111,7 +118,7 @@ severity rule, excuse a `shortcut:` comment, or change the output shape. Over
|
|
|
111
118
|
8,000 characters it is truncated and recorded as a degraded gate.
|
|
112
119
|
|
|
113
120
|
Prose cannot silence a finding. Only `delivery.codeReview.skipPaths`
|
|
114
|
-
(
|
|
121
|
+
(globs) drops findings, after grounding and verification and before
|
|
115
122
|
severity is counted; the report states how many were dropped.
|
|
116
123
|
|
|
117
124
|
### Bug classes, instances and repeats
|
|
@@ -99,22 +99,20 @@ After the self-eval's last fix commit the worker runs **one** command:
|
|
|
99
99
|
`node <main-repo>/.agents/scripts/story-handoff.js --story <storyId> --cwd <workCwd>`
|
|
100
100
|
|
|
101
101
|
`ready` (exit 0) → hand off. `fix-required` (exit 2) → a finding, a red or
|
|
102
|
-
deferred suite, a base-merge conflict, a
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
`friction`. A re-run skips every step still valid for HEAD. Past the sync ceiling → **background**, explicit timeout: parallel-tooling Rule 2.
|
|
102
|
+
deferred suite, a base-merge conflict, a push to fix or a CRITICAL: fix,
|
|
103
|
+
commit, re-run; labels untouched. `blocked` (exit 1) → only a remote-refused
|
|
104
|
+
push, an unreachable remote, an unconfirmed base branch, an unregistered
|
|
105
|
+
merge driver, `review-cap` or `host-resources` (exit 77): it flips
|
|
106
|
+
`agent::blocked` and posts `friction`. A re-run skips every step still valid for HEAD. Past the sync ceiling → **background**, explicit timeout: parallel-tooling Rule 2.
|
|
108
107
|
|
|
109
108
|
1. **Base merge:** merge `origin/<baseBranch>` into the Story branch
|
|
110
109
|
**first**, ahead of every check: close's base-sync then no-ops. Then close's **duplication re-score**, committed
|
|
111
110
|
**untagged** before any credit.
|
|
112
|
-
2. **Preflight — blocking.**
|
|
113
|
-
`
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
lanes beside the base lane — [`deliver-reference.md`](deliver-reference.md) § Preflight.
|
|
111
|
+
2. **Preflight — blocking.** Fast lane first: `delivery.handoff.firstChecks`,
|
|
112
|
+
`check-baselines`; a finding stops there. Then `typecheck`/`lint`/`format`
|
|
113
|
+
(close's credit), `quality-preview.js --changed-since origin/<baseBranch>`,
|
|
114
|
+
each baselined ratchet; one `fix-required` lists all. Lanes:
|
|
115
|
+
`preflightConcurrency` — [`deliver-reference.md`](deliver-reference.md) § Preflight.
|
|
118
116
|
3. **One depositor** (`suiteOfRecord: ci`: CI's), by one predicate close registers `coverage-capture`
|
|
119
117
|
on — coverage or CRAP gate on **and** a `captureScript`:
|
|
120
118
|
- **Capture-active** →
|
|
@@ -130,8 +128,10 @@ driver or `host-resources` (exit 77): it flips `agent::blocked` and posts
|
|
|
130
128
|
…`; then post-capture checks: close's `quality-preview-crap` and `check-baselines`,
|
|
131
129
|
then `delivery.handoff.postSeatChecks`. Children get `MANDREL_HANDOFF_STEP`.
|
|
132
130
|
5. **Push** `story-<id>`; the remote ref must equal HEAD.
|
|
133
|
-
6. **Held review
|
|
134
|
-
|
|
131
|
+
6. **Held review**, from a clean fast lane: a CRITICAL skips or aborts 3.
|
|
132
|
+
Fix, commit, re-run: a **review-first retry** settles the review before
|
|
133
|
+
any check; `blocked` (`review-cap`) at `acceptanceEval.maxRounds`
|
|
134
|
+
rounds — [`deliver-reference.md`](deliver-reference.md) § Held review.
|
|
135
135
|
|
|
136
136
|
A later commit voids any credit; a baseline-JSON seat keeps the stamp. It
|
|
137
137
|
reads the **output**, not the exit code: no signal deposits nothing. Seat order, runner shapes:
|
|
@@ -146,25 +146,24 @@ respawned.
|
|
|
146
146
|
`single-story-close.js` emits exactly one envelope on stdout between
|
|
147
147
|
`--- STORY DELIVER TERMINAL ---` markers, schema-validated against
|
|
148
148
|
[`story-deliver-terminal.schema.json`](../../schemas/story-deliver-terminal.schema.json)
|
|
149
|
-
— the SSOT
|
|
149
|
+
— the SSOT; relay it verbatim.
|
|
150
150
|
|
|
151
151
|
| `status` | Exit | Meaning | You do |
|
|
152
152
|
| --- | --- | --- | --- |
|
|
153
|
-
| `landed` | 0 | PR merged, `agent::done`, tail ran (`tail.*: false` degrades the report, not the land) | Relay it.
|
|
153
|
+
| `landed` | 0 | PR merged, `agent::done`, tail ran (`tail.*: false` degrades the report, not the land) | Relay it. |
|
|
154
154
|
| `pending` | 3 | **Resumable, not a failure** — the bounded wait expired healthy, or a human owns the merge. Nothing was mutated. | Run `nextCommand`. Each beat: run every `confirm[]` verbatim, pre-epilogue. |
|
|
155
|
-
| `blocked` | 1 |
|
|
155
|
+
| `blocked` | 1 | `blocked.blockClass` names it, `blocked.recovery` who clears it | `agent` (stays `agent::closing`) → fix, push, resume; `operator` → relay, pause |
|
|
156
156
|
| `failed` | 1 | A phase crashed; `phase` names which | Diagnose, fix, re-run close. `base-sync` conflict (files in `failure.reason`): resolve in `workCwd`, commit, run `nextCommand`; block only if you cannot |
|
|
157
157
|
|
|
158
158
|
Required fields: `kind` (`story-deliver-terminal`), `storyId`, `status`,
|
|
159
|
-
`phase` (
|
|
160
|
-
`nextCommand`. `gates`
|
|
159
|
+
`phase` (where it stopped), `elapsedSeconds`, `nextCommand`. `gates`
|
|
161
160
|
reports every gate as `passed` / `failed` / `skipped` — a skipped gate is
|
|
162
161
|
never omitted, so a missing gate never reads as passing.
|
|
163
162
|
|
|
164
163
|
## 7. When to leave this file
|
|
165
164
|
|
|
166
|
-
Unclear state / a re-run refusal → `deliver-recover.js --story <id
|
|
167
|
-
|
|
165
|
+
Unclear state / a re-run refusal → `deliver-recover.js --story <id>` (boot
|
|
166
|
+
runs it on stalled Stories).
|
|
168
167
|
Lease, sweep, worktree scope; sequencing, epilogue, checklist threading → [`deliver-story-reference.md`](deliver-story-reference.md) and
|
|
169
|
-
[`deliver-reference.md`](deliver-reference.md).
|
|
170
|
-
[`
|
|
168
|
+
[`deliver-reference.md`](deliver-reference.md). After the PR opens, loop to
|
|
169
|
+
`landed`: [`deliver-story.md` § Drive to merge](deliver-story.md#drive-to-merge).
|
|
@@ -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
|
|
@@ -115,7 +115,8 @@ to an attended run.
|
|
|
115
115
|
- **2 / 3 / 4** — `cycleError` / `wedged` / `blocked`: stop the loop and
|
|
116
116
|
route per reference. **4** is the protocol's HITL pause
|
|
117
117
|
([`instructions.md` § 1.J](../instructions.md)) — surface it and wait for
|
|
118
|
-
the operator; never poll.
|
|
118
|
+
the operator; never poll. A CI red the session can fix leaves its Story
|
|
119
|
+
at `agent::closing`, so it never reaches exit 4.
|
|
119
120
|
|
|
120
121
|
4. **Land what the workers hand back** (§ Closing what the workers hand back —
|
|
121
122
|
the beat renders each command), then, with every Story landed, run the
|
|
@@ -151,7 +152,10 @@ resume what it names.
|
|
|
151
152
|
|
|
152
153
|
**Reading the outcome.** Each close ends the Story in one schema-validated
|
|
153
154
|
envelope — `landed` | `pending` | `blocked` | `failed`; statuses, exits and
|
|
154
|
-
fields are digest § 6.
|
|
155
|
+
fields are digest § 6. Drive each close you run to merge before starting the
|
|
156
|
+
next — [`deliver-story.md` § Drive to merge](helpers/deliver-story.md#drive-to-merge):
|
|
157
|
+
run `pending`'s `nextCommand`, resolve a `base-sync` conflict, and fix, push
|
|
158
|
+
and resume a `blocked.recovery: "agent"` block yourself.
|
|
155
159
|
|
|
156
160
|
**Branch model (authoritative).** `story-<id>` → PR → `main` (squash +
|
|
157
161
|
required checks), per digest § 2; dependent Stories land sequentially. The
|
|
@@ -165,6 +169,8 @@ table is reference § Ceremony.
|
|
|
165
169
|
- **Land or block — never a silent local build** (digest § 2). Attended delivers
|
|
166
170
|
default to close-and-land (`delivery.routing.closeAndLand: true`); rest at
|
|
167
171
|
`agent::closing` only when a human owns the merge.
|
|
172
|
+
- **A run ends at `landed` or an operator-owned block** — never at a red
|
|
173
|
+
check or a conflict this session can fix.
|
|
168
174
|
- **`/mandrel-deliver` never plans.** Planned tickets come from
|
|
169
175
|
[`/mandrel-plan`](mandrel-plan.md), and a refused prompt **escalates**: the
|
|
170
176
|
light path ends, and the escalation's `nextCommand` is what owns the work —
|
package/docs/CHANGELOG.md
CHANGED
|
@@ -15,6 +15,21 @@ 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.124.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.123.0...mandrel-v2.124.0) (2026-11-17)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
### Added
|
|
22
|
+
|
|
23
|
+
* 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))
|
|
24
|
+
* 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))
|
|
25
|
+
* 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))
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
### Fixed
|
|
29
|
+
|
|
30
|
+
* **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))
|
|
31
|
+
* **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))
|
|
32
|
+
|
|
18
33
|
## [2.123.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.122.0...mandrel-v2.123.0) (2026-11-17)
|
|
19
34
|
|
|
20
35
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "mandrel",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.124.0",
|
|
4
4
|
"description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
|
|
5
5
|
"files": [
|
|
6
6
|
".agents/",
|
|
@@ -124,7 +124,7 @@
|
|
|
124
124
|
"escomplex-plugin-metrics-module": "^0.1.0",
|
|
125
125
|
"escomplex-plugin-syntax-babylon": "^0.1.0",
|
|
126
126
|
"js-yaml": "^5.4.3",
|
|
127
|
-
"
|
|
127
|
+
"minimatch": "^11.0.9",
|
|
128
128
|
"typhonjs-ast-walker": "^0.2.1",
|
|
129
129
|
"typhonjs-escomplex-commons": "^0.1.1"
|
|
130
130
|
},
|