mandrel 2.122.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 +10 -7
- package/.agents/runtime-deps.json +2 -2
- package/.agents/schemas/agentrc.schema.json +26 -4
- 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/close-validation/gates.js +16 -3
- package/.agents/scripts/lib/close-validation/test-delta.js +9 -4
- package/.agents/scripts/lib/config/gates/coverage.schema.js +2 -2
- 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 +8 -4
- 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/handoff-suite-of-record.js +15 -7
- package/.agents/scripts/lib/orchestration/merge-queue.js +36 -10
- 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 +23 -24
- package/.agents/workflows/helpers/deliver-reference.md +62 -26
- 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 +23 -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,23 +99,21 @@ 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
|
-
|
|
118
|
-
3. **One depositor**, by the one predicate close registers `coverage-capture`
|
|
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.
|
|
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** →
|
|
121
119
|
`node <main-repo>/.agents/scripts/coverage-capture.js --cwd <workCwd>`,
|
|
@@ -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
|
|
@@ -518,6 +530,10 @@ Digest § 5 states the rule and both invocations; this is what surrounds them.
|
|
|
518
530
|
`testChanged` or an unreadable merge-base falls back to the full
|
|
519
531
|
`project.commands.test`, logging which reason applied. An exit 76 from any
|
|
520
532
|
`test` form settles by `coverage.onOverBudget`, as the capture's does.
|
|
533
|
+
Under `coverage.suiteOfRecord: "ci"` none of this runs: the `test`
|
|
534
|
+
depositor is deferred to CI like the capture (no lock, no credit, the
|
|
535
|
+
`Coverage-deferred:` marker), after the changed-tests guard when
|
|
536
|
+
`testChanged` is set.
|
|
521
537
|
- **Runner shapes.** A bare `npm test` earns the `test` credit **only** where
|
|
522
538
|
the project's test script routes through mandrel's own runner, which prints
|
|
523
539
|
the outcome. On any other runner it deposits nothing and prints nothing, so
|
|
@@ -631,13 +647,16 @@ review; post-seat checks wait for a real run, because it seats nothing.
|
|
|
631
647
|
## Held review at hand-off {#held-review}
|
|
632
648
|
|
|
633
649
|
The one home of this rule; the digest and the worker contract point here.
|
|
634
|
-
`story-handoff.js` starts the Story-scope code review once
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
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
|
|
641
660
|
`suiteTimings`. The same computation stands alone for a manual re-run:
|
|
642
661
|
|
|
643
662
|
```bash
|
|
@@ -657,20 +676,36 @@ node <main-repo>/.agents/scripts/story-review-compute.js --story <storyId> --cwd
|
|
|
657
676
|
raw diff. It never stops the handoff on a provider throw — the step reports
|
|
658
677
|
`error` and close computes the review itself.
|
|
659
678
|
- **A CRITICAL is the worker's to fix.** The handoff settles `fix-required`
|
|
660
|
-
naming the deposit.
|
|
661
|
-
own result. One that has landed before the credited run
|
|
662
|
-
the handoff there — no `test`-depositor seat, no run, no
|
|
663
|
-
no credit, no push. One that lands while the run is in
|
|
664
|
-
(the SIGTERM a Ctrl-C sends; the child frees the
|
|
665
|
-
no credit and pushes nothing; a CRITICAL after the
|
|
666
|
-
the push. Any earlier stop still awaits the review
|
|
667
|
-
to `steps[]` once, so no provider is orphaned and one
|
|
668
|
-
findings, each with its own evidence path; `status`
|
|
669
|
-
the first stop's
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
`
|
|
673
|
-
|
|
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.
|
|
674
709
|
- **Close adopts, else computes — and deposits.** When the deposit's digest
|
|
675
710
|
equals the digest of the diff at close's held-review start, close starts no
|
|
676
711
|
review and posts the deposit after PR-open. A base-sync merge that moves
|
|
@@ -714,8 +749,9 @@ line naming host contention — neither is reported as failing tests. A
|
|
|
714
749
|
coverage-capture exiting `76` (the consumer's capture script declared its
|
|
715
750
|
slice over this host's budget, so nothing ran) follows
|
|
716
751
|
`delivery.quality.gates.coverage.onOverBudget`, and under
|
|
717
|
-
`coverage.suiteOfRecord: "ci"` the
|
|
718
|
-
|
|
752
|
+
`coverage.suiteOfRecord: "ci"` the credited suite — the capture or the
|
|
753
|
+
`test` depositor — is deferred before anything spawns (no lock, no
|
|
754
|
+
credit). A deferral reports the gate `deferred`, the
|
|
719
755
|
coverage-reading gates `skipped` (`coverage-deferred-ci`), settles the
|
|
720
756
|
handoff `ready` with a `coverage` field, and puts a `Coverage-deferred:
|
|
721
757
|
<reason>` key line in the PR body. CI's `ciRatchetCheck` job then runs
|
|
@@ -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,29 @@ 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
|
+
|
|
33
|
+
## [2.123.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.122.0...mandrel-v2.123.0) (2026-11-17)
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
### Fixed
|
|
37
|
+
|
|
38
|
+
* merge wait reads a fail-fast-cancelled queue run as an own ejection ([#6086](https://github.com/dsj1984/mandrel/issues/6086)) ([#6088](https://github.com/dsj1984/mandrel/issues/6088)) ([4f94261](https://github.com/dsj1984/mandrel/commit/4f94261818494b76208e6828fca0fd74d319e5eb))
|
|
39
|
+
* under suiteOfRecord ci, the test depositor defers to CI too, so a Story with no change under the CRAP target dirs runs no full local suite ([#6087](https://github.com/dsj1984/mandrel/issues/6087)) ([#6090](https://github.com/dsj1984/mandrel/issues/6090)) ([7a184a9](https://github.com/dsj1984/mandrel/commit/7a184a92bd535ae54a3d7760ae6076a5a9f200b4))
|
|
40
|
+
|
|
18
41
|
## [2.122.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.121.0...mandrel-v2.122.0) (2026-11-13)
|
|
19
42
|
|
|
20
43
|
|
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
|
},
|