mandrel 2.110.0 → 2.112.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/agents/acceptance-critic.md +14 -0
- package/.agents/agents/auditor.md +14 -0
- package/.agents/agents/plan-critic.md +5 -0
- package/.agents/agents/story-worker.md +4 -1
- package/.agents/audit-checklists/state-machines.md +21 -0
- package/.agents/docs/agentrc-reference.json +23 -10
- package/.agents/docs/configuration.md +362 -15
- package/.agents/docs/execution-reference.md +11 -0
- package/.agents/docs/workflows.md +2 -1
- package/.agents/rules/ci-remediation.md +28 -4
- package/.agents/rules/git-conventions-reference.md +7 -0
- package/.agents/schemas/agentrc.schema.json +179 -13
- package/.agents/schemas/audit-rules.json +28 -0
- package/.agents/schemas/baselines/baseline-envelope.schema.json +16 -4
- package/.agents/schemas/baselines/bundle-size.schema.json +1 -0
- package/.agents/schemas/baselines/coverage.schema.json +1 -0
- package/.agents/schemas/baselines/crap.schema.json +37 -10
- package/.agents/schemas/baselines/duplication.schema.json +1 -0
- package/.agents/schemas/baselines/maintainability.schema.json +1 -0
- package/.agents/schemas/baselines/mutation.schema.json +1 -0
- package/.agents/schemas/crap-report.schema.json +6 -5
- package/.agents/schemas/story-deliver-terminal.schema.json +49 -3
- package/.agents/schemas/story-progress.schema.json +1 -1
- package/.agents/schemas/validation-evidence.schema.json +2 -2
- package/.agents/scripts/boot-sweep.js +41 -3
- package/.agents/scripts/coverage-capture.js +39 -3
- package/.agents/scripts/coverage-ratchet.js +106 -0
- package/.agents/scripts/evidence-gate.js +84 -21
- package/.agents/scripts/file-ci-gap.js +220 -10
- package/.agents/scripts/lib/audit-baselines/read.js +8 -1
- package/.agents/scripts/lib/audit-baselines/trend.js +2 -1
- package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
- package/.agents/scripts/lib/baseline-loader.js +4 -2
- package/.agents/scripts/lib/baselines/codec.js +57 -0
- package/.agents/scripts/lib/baselines/crap-preview-incremental.js +8 -3
- package/.agents/scripts/lib/baselines/crap-preview-scan.js +10 -16
- package/.agents/scripts/lib/baselines/crap-updater-cli.js +4 -13
- package/.agents/scripts/lib/baselines/kernel.js +19 -1
- package/.agents/scripts/lib/baselines/kinds/_crap-codec.js +171 -0
- package/.agents/scripts/lib/baselines/kinds/_crap-read.js +56 -16
- package/.agents/scripts/lib/baselines/kinds/_shared-metric.js +0 -59
- package/.agents/scripts/lib/baselines/kinds/crap.js +283 -319
- package/.agents/scripts/lib/baselines/preview-gates.js +29 -10
- package/.agents/scripts/lib/baselines/reader.js +36 -9
- package/.agents/scripts/lib/baselines/refresh-service.js +79 -18
- package/.agents/scripts/lib/baselines/seat-missing.js +173 -7
- package/.agents/scripts/lib/baselines/writer.js +36 -21
- package/.agents/scripts/lib/changed-files.js +70 -6
- package/.agents/scripts/lib/child-exec.js +10 -0
- package/.agents/scripts/lib/claude/agents-projection.js +5 -5
- package/.agents/scripts/lib/close-lock-events.js +8 -3
- package/.agents/scripts/lib/close-validation/ci-deferral.js +40 -0
- package/.agents/scripts/lib/close-validation/gates.js +156 -32
- package/.agents/scripts/lib/close-validation/process.js +16 -7
- package/.agents/scripts/lib/close-validation/projections/crap.js +43 -10
- package/.agents/scripts/lib/close-validation/runner.js +160 -41
- package/.agents/scripts/lib/close-validation/skip-branch-test.js +144 -0
- package/.agents/scripts/lib/close-validation/test-delta.js +33 -8
- package/.agents/scripts/lib/codex/agents-projection.js +6 -0
- package/.agents/scripts/lib/config/agentrc-overlay.js +9 -5
- package/.agents/scripts/lib/config/explain.js +5 -2
- package/.agents/scripts/lib/config/gates/coverage.schema.js +53 -0
- package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
- package/.agents/scripts/lib/config/git-roots.js +38 -4
- package/.agents/scripts/lib/config/handoff.js +24 -0
- package/.agents/scripts/lib/config/quality.js +28 -12
- package/.agents/scripts/lib/config/worktree-isolation.js +2 -5
- package/.agents/scripts/lib/config-resolver.js +22 -2
- package/.agents/scripts/lib/config-settings-schema-delivery.js +87 -4
- package/.agents/scripts/lib/config-settings-schema-quality.js +36 -1
- package/.agents/scripts/lib/config-settings-schema.js +1 -1
- package/.agents/scripts/lib/coverage-capture-affected.js +1 -0
- package/.agents/scripts/lib/coverage-capture-delta.js +164 -32
- package/.agents/scripts/lib/coverage-capture-own-fix.js +232 -0
- package/.agents/scripts/lib/coverage-capture-usage.js +2 -2
- package/.agents/scripts/lib/coverage-capture.js +31 -0
- package/.agents/scripts/lib/coverage-deferral.js +96 -0
- package/.agents/scripts/lib/coverage-ratchet.js +187 -0
- package/.agents/scripts/lib/crap-baseline-join.js +5 -5
- package/.agents/scripts/lib/crap-engine.js +3 -3
- package/.agents/scripts/lib/crap-method-identity.js +104 -48
- package/.agents/scripts/lib/escomplex-anchor.js +135 -0
- package/.agents/scripts/lib/escomplex-kernel.js +30 -1
- package/.agents/scripts/lib/failure-rows.js +121 -0
- package/.agents/scripts/lib/full-suite-lock.js +44 -4
- package/.agents/scripts/lib/full-suite-queue.js +89 -13
- package/.agents/scripts/lib/generated/agentrc-validator.js +8 -2
- package/.agents/scripts/lib/gh-env.js +3 -6
- package/.agents/scripts/lib/gh-pr-rest.js +1 -0
- package/.agents/scripts/lib/git/base-sync-probe.js +182 -0
- package/.agents/scripts/lib/git-branch-lifecycle.js +9 -0
- package/.agents/scripts/lib/observability/close-telemetry.js +37 -2
- package/.agents/scripts/lib/observability/handoff-telemetry.js +170 -0
- package/.agents/scripts/lib/observability/review-dispositions.js +23 -6
- package/.agents/scripts/lib/observability/runtime-friction.js +17 -4
- package/.agents/scripts/lib/observability/source-classifier.js +3 -0
- package/.agents/scripts/lib/observability/story-outcome.js +393 -0
- package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js +2 -1
- package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js +19 -1
- package/.agents/scripts/lib/orchestration/check-baselines/phases/fail-detail.js +84 -0
- package/.agents/scripts/lib/orchestration/check-baselines/phases/pipeline.js +14 -5
- package/.agents/scripts/lib/orchestration/check-baselines/phases/refresh-ack.js +3 -2
- package/.agents/scripts/lib/orchestration/check-baselines/phases/report.js +26 -6
- package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +124 -23
- package/.agents/scripts/lib/orchestration/code-review.js +223 -19
- package/.agents/scripts/lib/orchestration/handoff-gates.js +217 -44
- package/.agents/scripts/lib/orchestration/handoff-rescore.js +169 -0
- package/.agents/scripts/lib/orchestration/handoff-suite-of-record.js +45 -0
- package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +5 -1
- package/.agents/scripts/lib/orchestration/plan-persist/source-rewrite.js +76 -4
- package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +2 -2
- package/.agents/scripts/lib/orchestration/preflight-lanes.js +208 -0
- package/.agents/scripts/lib/orchestration/review-base-ref.js +40 -17
- package/.agents/scripts/lib/orchestration/review-deposit.js +38 -12
- package/.agents/scripts/lib/orchestration/review-depth.js +21 -0
- package/.agents/scripts/lib/orchestration/review-history.js +124 -20
- package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +23 -8
- package/.agents/scripts/lib/orchestration/review-providers/code-review.js +82 -39
- package/.agents/scripts/lib/orchestration/review-providers/critical-verifier.js +64 -11
- package/.agents/scripts/lib/orchestration/review-providers/degraded-gates.js +98 -3
- package/.agents/scripts/lib/orchestration/review-providers/finding-identity.js +6 -2
- package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js +55 -8
- package/.agents/scripts/lib/orchestration/review-providers/review-guidance.js +1 -0
- package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +42 -15
- package/.agents/scripts/lib/orchestration/review-providers/types.js +6 -0
- package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js +10 -1
- package/.agents/scripts/lib/orchestration/single-story-close/gate-log.js +10 -0
- package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +7 -4
- package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js +17 -2
- package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js +59 -2
- package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +13 -1
- package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +15 -4
- package/.agents/scripts/lib/orchestration/single-story-close/phases/land-review-record.js +213 -0
- package/.agents/scripts/lib/orchestration/single-story-close/phases/normalize-pr-title.js +17 -2
- package/.agents/scripts/lib/orchestration/single-story-close/phases/open-pr.js +42 -20
- package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +51 -26
- package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +3 -1
- package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js +51 -15
- package/.agents/scripts/lib/orchestration/single-story-close/phases/push.js +59 -11
- package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +1 -0
- package/.agents/scripts/lib/orchestration/single-story-close/phases/review-block.js +31 -13
- package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +29 -6
- package/.agents/scripts/lib/orchestration/single-story-close/phases/review-outcome.js +10 -12
- package/.agents/scripts/lib/orchestration/single-story-close/phases/review-override.js +19 -4
- package/.agents/scripts/lib/orchestration/single-story-close/result.js +43 -13
- package/.agents/scripts/lib/orchestration/single-story-close/review-overlap.js +73 -39
- package/.agents/scripts/lib/orchestration/single-story-close/runner.js +11 -2
- package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +3 -2
- package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +20 -8
- package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +7 -0
- package/.agents/scripts/lib/orchestration/story-handoff.js +789 -196
- package/.agents/scripts/lib/orchestration/ticketing/reads.js +2 -0
- package/.agents/scripts/lib/pr-body-lines.js +32 -0
- package/.agents/scripts/lib/single-story/ci-ratchet-gate.js +140 -0
- package/.agents/scripts/lib/single-story/confirm-and-land.js +17 -7
- package/.agents/scripts/lib/single-story/confirm-merge.js +12 -3
- package/.agents/scripts/lib/single-story-sweep/report-stalled-executing.js +202 -0
- package/.agents/scripts/lib/standalone-ratchets.js +37 -0
- package/.agents/scripts/lib/suite-admission.js +20 -8
- package/.agents/scripts/lib/suite-sizing.js +146 -0
- package/.agents/scripts/lib/workspace-provisioner.js +2 -2
- package/.agents/scripts/merge-baseline.js +14 -3
- package/.agents/scripts/providers/github/comments.js +19 -3
- package/.agents/scripts/providers/github.js +1 -0
- package/.agents/scripts/review-dispositions-report.js +1 -1
- package/.agents/scripts/role-scope-guard.js +267 -0
- package/.agents/scripts/single-story-close.js +4 -4
- package/.agents/scripts/single-story-confirm-merge.js +31 -5
- package/.agents/scripts/single-story-init.js +24 -4
- package/.agents/scripts/story-handoff.js +3 -3
- package/.agents/scripts/story-outcomes-report.js +231 -0
- package/.agents/scripts/story-review-compute.js +9 -5
- package/.agents/scripts/update-coverage-baseline.js +12 -2
- package/.agents/scripts/update-crap-baseline.js +9 -1
- package/.agents/workflows/audit-state-machines.md +213 -0
- package/.agents/workflows/helpers/code-review.md +63 -9
- package/.agents/workflows/helpers/deliver-digest.md +53 -54
- package/.agents/workflows/helpers/deliver-reference.md +236 -63
- package/.agents/workflows/helpers/deliver-story-reference.md +19 -8
- package/.agents/workflows/helpers/deliver-story.md +7 -2
- package/.agents/workflows/helpers/parallel-tooling.md +29 -0
- package/.agents/workflows/helpers/plan-reference.md +10 -2
- package/docs/CHANGELOG.md +56 -0
- package/lib/cli/doctor-checks/coverage-ratchet.js +54 -0
- package/lib/cli/doctor-checks/effective-agentrc.js +23 -0
- package/lib/cli/doctor-checks/llm-review.js +2 -11
- package/lib/cli/doctor-checks/sync-parity.js +5 -1
- package/lib/cli/doctor-checks/test-credit-path.js +7 -2
- package/lib/cli/registry.js +5 -0
- package/package.json +1 -1
|
@@ -344,7 +344,9 @@ shapes poll on inside the ~60s window: checks already **green** (the merge is
|
|
|
344
344
|
imminent — observed at the green cadence, it saves a whole confirm
|
|
345
345
|
invocation) and a red rollup still awaiting its confirming probe. When a close returns that `pending` envelope, launch its
|
|
346
346
|
`nextCommand` (`single-story-confirm-merge.js … --wait`) as a **background**
|
|
347
|
-
invocation
|
|
347
|
+
invocation with the explicit timeout (`timeout: 7200000` on Claude Code —
|
|
348
|
+
[`parallel-tooling.md`](parallel-tooling.md) Rule 2; its completion
|
|
349
|
+
re-invokes the agent) and
|
|
348
350
|
move on to the next Story; `single-story-confirm-merge.js` is idempotent and
|
|
349
351
|
owns the whole tail, and `deliver-recover.js` recovers an orphaned confirm. Do
|
|
350
352
|
not foreground-poll the merge. The cumulative `maxBudgetSeconds` give-up is
|
|
@@ -365,32 +367,74 @@ for the same reason — a foreground wait longer than the host tool ceiling
|
|
|
365
367
|
expires `pending` anyway. Otherwise a one-Story run keeps `sync`: there is no
|
|
366
368
|
sibling to unblock, and the foreground wait is the cheapest path to `landed`.
|
|
367
369
|
|
|
370
|
+
**Exception — a time-limited host.** On a host that limits background
|
|
371
|
+
commands (a cloud session, a `-p` run, an Agent SDK application, CI) a
|
|
372
|
+
one-Story close also runs with `--merge-watch-mode async`. Close itself stays
|
|
373
|
+
in the foreground, now bounded to the gates plus the ~60s probe, and the long
|
|
374
|
+
merge wait moves into the background confirm that carries the explicit
|
|
375
|
+
timeout. A local session need not pass the flag.
|
|
376
|
+
|
|
368
377
|
## Preflight (before close) {#preflight}
|
|
369
378
|
|
|
370
379
|
Digest § 5 states the rule: `story-handoff.js` runs, after the base merge
|
|
371
|
-
and before the credited suite run, close's own `lint` and
|
|
372
|
-
`quality-preview.js --changed-since origin/<baseBranch>`,
|
|
373
|
-
standalone ratchets CI's `baselines` job runs —
|
|
374
|
-
(default and `--production`), `check-arch-cycles.js`
|
|
375
|
-
`check-cyclomatic.js` — in the worktree
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
380
|
+
and before the credited suite run, close's own `typecheck`, `lint` and
|
|
381
|
+
`format` gates, `quality-preview.js --changed-since origin/<baseBranch>`,
|
|
382
|
+
then the shipped standalone ratchets CI's `baselines` job runs —
|
|
383
|
+
`check-dead-exports.js` (default and `--production`), `check-arch-cycles.js`
|
|
384
|
+
and `check-cyclomatic.js` — in the worktree. It runs **before** the credited
|
|
385
|
+
run because a fix commit afterwards would void that run's credit.
|
|
386
|
+
|
|
387
|
+
- **One pass, every finding.** Every check runs, even after a finding. Any
|
|
388
|
+
finding settles one `fix-required` whose `detail` lists each finding on its
|
|
389
|
+
own line, in check order, and whose `findings[]` carries `{ check, detail,
|
|
390
|
+
evidencePath }` per failing check; the envelope's `evidencePath` is the
|
|
391
|
+
first one's in check order. No suite runs before the credited run. Only a
|
|
392
|
+
fully clean preflight is skipped on a re-run at the same HEAD.
|
|
393
|
+
- **Serial by default; admitted lanes per host.** With
|
|
394
|
+
`delivery.execution.preflightConcurrency` at `1` (the default) the checks
|
|
395
|
+
run one after another, exactly as before. A host that can afford overlap
|
|
396
|
+
sets a higher value in its `.agentrc.local.json` (copied into every
|
|
397
|
+
worktree); a host with no overlay, such as a cloud session, stays serial.
|
|
398
|
+
Above 1 the step runs one **base lane**, which takes every check in order
|
|
399
|
+
unadmitted, and up to N − 1 **admitted lanes**. An admitted lane takes only
|
|
400
|
+
a deposited check whose gate close runs in its independent bucket
|
|
401
|
+
(`isIndependentGate`: today `typecheck`, `lint` and `format`, never
|
|
402
|
+
`quality-preview` or a ratchet), admits it through `withSuiteAdmission`
|
|
403
|
+
under close's argv for that gate with no wait, and runs it inside the
|
|
404
|
+
reservation. A miss (exit 75 or 78) hands the check back to the base lane
|
|
405
|
+
in order, records no finding and retires that lane; a check that throws
|
|
406
|
+
once admitted is not a miss and fails the step as it would serially. No
|
|
407
|
+
lane aborts another. The step result gains
|
|
408
|
+
`concurrency: { requested, admitted }`, and each passed deposit missing
|
|
409
|
+
from the evidence store afterwards is re-recorded with close's command
|
|
410
|
+
hash. Suite admission off
|
|
411
|
+
(`fullSuiteLock: false`, `MANDREL_FULL_SUITE_LOCK=0`) or an inherited
|
|
412
|
+
suite reservation keeps the step serial, with one progress line naming
|
|
413
|
+
why.
|
|
414
|
+
- **Ratchets your lint runs.** A ratchet listed in
|
|
415
|
+
`delivery.quality.ratchets.coveredByLint` is skipped (`⏭ <key> covered by
|
|
416
|
+
lint`) only once this pass's whole-tree `lint` exited 0, run or credited
|
|
417
|
+
from fresh evidence; a failing lint spawns no covered ratchet, and an
|
|
418
|
+
absent or changed-file-scoped lint covers nothing.
|
|
419
|
+
- **Typecheck, lint and format are close's credit.** The handoff takes the
|
|
420
|
+
entries from close's `buildDefaultGates` (same config, base branch,
|
|
421
|
+
worktree and evidence root) and runs them through `evidence-gate.js
|
|
422
|
+
--standalone --gate <name>`, so each pass lands in close's evidence store
|
|
423
|
+
keyed to the post-merge HEAD and tree, with close's command hash. A
|
|
424
|
+
disabled gate (`project.commands.typecheck: null`, or `formatCheck`)
|
|
425
|
+
deposits nothing; `format` runs the argv close's runner scopes to the
|
|
426
|
+
changed files and deposits nothing when that scoping skips it. Close on
|
|
427
|
+
the handed-off HEAD skips each as `evidence-match`, and a consumer
|
|
428
|
+
`pre-push` hook running the same argv through `evidence-gate.js --gate
|
|
429
|
+
typecheck` replays the deposit. A baselines-only seat commit re-keys the
|
|
430
|
+
`lint` and `typecheck` records to the seated HEAD (handoff state
|
|
431
|
+
`preflightCredits`); `format` is not carried (its argv names the changed
|
|
432
|
+
files). Any other commit, or a close-time base move, re-runs them.
|
|
433
|
+
- **Why.** Close runs typecheck, lint and the maintainability half of the
|
|
434
|
+
preview (`quality-preview-mi`), but a regression found there still costs a
|
|
435
|
+
close round-trip, and a type error found after the suite costs the whole
|
|
436
|
+
lock-plus-suite phase. Seconds of preflight in the worktree is cheaper than
|
|
437
|
+
either.
|
|
394
438
|
- **The CRAP half never captures.** It scores whatever coverage artifact is
|
|
395
439
|
on disk — the worker's credited capture when one exists — and triggers no
|
|
396
440
|
capture of its own. With no artifact its methods report unscorable; a stale
|
|
@@ -400,6 +444,12 @@ afterwards would void that run's credit.
|
|
|
400
444
|
`arch-cycles.json`, `cyclomatic.json`) exists, and is judged by its exit
|
|
401
445
|
code and `(gate fail)` line; the finding names the offending `+` / `!`
|
|
402
446
|
rows. Close does not run them — CI stays their backstop.
|
|
447
|
+
- **Findings quote their rows.** A non-ratchet finding (lint, format,
|
|
448
|
+
quality-preview) quotes the failing lint, biome or guard lines it parsed —
|
|
449
|
+
at most 10, via `lib/failure-rows.js` — and falls back to the bare
|
|
450
|
+
`<key> finding` text when none parse. A baselines finding, at post-capture
|
|
451
|
+
or close, names its regressed rows and the kind's diff-scoped remedy
|
|
452
|
+
command from the `check-baselines --format text` report.
|
|
403
453
|
- **Close stays authoritative.** Its `quality-preview-crap` gate scores a
|
|
404
454
|
fresh capture after `coverage-capture`; a preflight pass never skips it.
|
|
405
455
|
The handoff's post-capture step (§ Credited run) runs that gate early too.
|
|
@@ -420,42 +470,103 @@ Digest § 5 states the rule and both invocations; this is what surrounds them.
|
|
|
420
470
|
JSON spends it, and close re-captures.
|
|
421
471
|
- **Predicted skip.** With `incrementalCoverage.skipWhenUnchanged` on and no
|
|
422
472
|
changed file under `crap.targetDirs`, the capture would run nothing, so
|
|
423
|
-
the shared predicate (`resolveCreditedDepositor`
|
|
424
|
-
depositor for both close and the handoff. A `no changed
|
|
425
|
-
skipping capture` line is never credit.
|
|
473
|
+
the shared predicate (`resolveCreditedDepositor`, `skipBranch: true`)
|
|
474
|
+
picks the `test` depositor for both close and the handoff. A `no changed
|
|
475
|
+
files … — skipping capture` line is never credit. On this branch the
|
|
476
|
+
depositor is scoped: with `project.commands.testChanged` set, the handoff
|
|
477
|
+
runs `evidence-gate.js … --gate test --changed-since <merge-base> --
|
|
478
|
+
<testChanged>` and close registers the same run as its `test` gate, keyed
|
|
479
|
+
on `git merge-base origin/<baseBranch> HEAD` (substituted for a literal
|
|
480
|
+
`$MANDREL_CHANGED_SINCE` and set in the env). A green run credits close's
|
|
481
|
+
full-suite `test` identity with `scope: delta`, so close at that HEAD skips
|
|
482
|
+
the gate and the base-moved delta re-credit still applies. Unset
|
|
483
|
+
`testChanged` or an unreadable merge-base falls back to the full
|
|
484
|
+
`project.commands.test`, logging which reason applied. An exit 76 from any
|
|
485
|
+
`test` form settles by `coverage.onOverBudget`, as the capture's does.
|
|
426
486
|
- **Runner shapes.** A bare `npm test` earns the `test` credit **only** where
|
|
427
487
|
the project's test script routes through mandrel's own runner, which prints
|
|
428
488
|
the outcome. On any other runner it deposits nothing and prints nothing, so
|
|
429
489
|
silence is never evidence of credit.
|
|
490
|
+
- **Own-fix delta refresh.** A small fix to your own code after the credited
|
|
491
|
+
capture spends the stamp; by default the next capture re-runs the Story's
|
|
492
|
+
whole affected scope. With `coverage.ownFixDeltaMaxFiles` at `N >= 1` and
|
|
493
|
+
`captureScope: affected`, it re-measures only the delta when HEAD's
|
|
494
|
+
first-parent chain splits into base-sync merges sharing no suite input or
|
|
495
|
+
config with the Story and own commits touching at most `N` suite-input
|
|
496
|
+
files, with no config, no deleted or renamed suite input, no net line
|
|
497
|
+
removal in a test file and none reachable from the base. Any other shape
|
|
498
|
+
logs `delta refresh not eligible (own-fix: …)` and captures as before.
|
|
499
|
+
Rows outside the delta are kept and can go stale high, so validate against
|
|
500
|
+
full captures before raising the cap
|
|
501
|
+
([configuration](../../docs/configuration.md)).
|
|
430
502
|
- **Background dispatch.** If the handoff outruns the host's sync Bash ceiling,
|
|
431
|
-
dispatch it in the **background**
|
|
432
|
-
|
|
503
|
+
dispatch it in the **background** with an explicit timeout
|
|
504
|
+
(`timeout: 7200000` on Claude Code, the 2-hour maximum) — its completion
|
|
505
|
+
re-invokes you; never spawn a task to poll or `sleep`-loop against it. On a
|
|
506
|
+
host stop notice, re-run it once; a second stop is the blocked path
|
|
433
507
|
([`parallel-tooling.md`](parallel-tooling.md) Rule 2).
|
|
434
508
|
- **Redraft rounds.** Run the scoped projects for the roots you changed plus
|
|
435
509
|
`verify[]`, not the whole suite; only the one run needs credit.
|
|
436
|
-
- **Seating new
|
|
437
|
-
new methods have no baseline row, so `story-handoff.js`
|
|
438
|
-
`<workCwd>`,
|
|
439
|
-
|
|
510
|
+
- **Seating new rows (`--seat-missing`).** Close fails a Story whose own
|
|
511
|
+
new files or methods have no baseline row, so `story-handoff.js` seats them
|
|
512
|
+
in `<workCwd>`, in two steps. `seat-static`, after the base merge and
|
|
513
|
+
before preflight, runs
|
|
440
514
|
`node .agents/scripts/update-maintainability-baseline.js --seat-missing`
|
|
441
|
-
(MI
|
|
442
|
-
|
|
515
|
+
(MI is static, so it voids no credit) unless the MI gate is disabled.
|
|
516
|
+
`seat`, after the credited capture, runs
|
|
517
|
+
`node .agents/scripts/update-crap-baseline.js --seat-missing` (CRAP gate
|
|
518
|
+
on) and `node .agents/scripts/update-coverage-baseline.js --seat-missing`
|
|
519
|
+
(capture depositor with the coverage gate on; never on the `test` path or
|
|
520
|
+
under a coverage deferral). Each scores the files changed since the
|
|
521
|
+
`origin/<baseBranch>` merge-base — after the base merge that is the base
|
|
522
|
+
tip, so a file only the merge brought in is never seated — and writes
|
|
523
|
+
**only** rows whose key (path, or path and method for CRAP) is absent:
|
|
443
524
|
every existing row stays byte-identical, including rows whose scores moved
|
|
444
525
|
(re-scoring stays close's auto-refresh). It prints `seated: N`; `seated: 0`
|
|
445
|
-
writes nothing.
|
|
446
|
-
baseline-refresh: seat rows for new methods (refs #<id>)
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
526
|
+
writes nothing. Each step commits its rows as `chore(baselines):
|
|
527
|
+
baseline-refresh: seat rows for new methods (refs #<id>)` and skips at an
|
|
528
|
+
unchanged HEAD on a re-run.
|
|
529
|
+
- **Seat refusals.** The CRAP and coverage seats exit non-zero and write
|
|
530
|
+
nothing unless a coverage-capture stamp is fresh for the tree; the CRAP
|
|
531
|
+
seat also needs method resolution over the in-scope files at exactly
|
|
532
|
+
100% — a lower rate means the artifact's coordinates predate the tree. The
|
|
533
|
+
refusal names the fix: re-run the digest § 5 capture, then seat. A changed
|
|
534
|
+
file the fresh artifact did not measure is named in the coverage seat's
|
|
535
|
+
log and never seated at 0%.
|
|
536
|
+
- **Step env (`MANDREL_HANDOFF_STEP`).** Every child the handoff spawns gets
|
|
537
|
+
`MANDREL_HANDOFF_STEP` set to the running step (`base-merge`,
|
|
538
|
+
`seat-static`, `preflight`, `credited-run`, `seat`, `post-capture`,
|
|
539
|
+
`push`), layered over any inherited value. It is the one contract a
|
|
540
|
+
consumer check keys on to downgrade a missing baseline row for change-set
|
|
541
|
+
files during `preflight`, before the seat can write it; stale and extra
|
|
542
|
+
rows stay the consumer's to keep fatal.
|
|
543
|
+
- **Post-seat checks (`delivery.handoff.postSeatChecks`).** After close's
|
|
544
|
+
post-capture gates pass, the handoff runs each declared `{ cmd, args }` in
|
|
545
|
+
`<workCwd>` without a shell, with `MANDREL_HANDOFF_STEP=post-capture`; a
|
|
546
|
+
non-zero exit is `fix-required` naming the check, and nothing is pushed.
|
|
547
|
+
While any is declared, preflight runs close's `lint` argv bare and holds
|
|
548
|
+
its credit: a baselines-only seat commit re-keys it, any other commit drops
|
|
549
|
+
it, and the one `lint` pass record is written only once every post-seat
|
|
550
|
+
check passed at HEAD. Under a coverage deferral the checks are skipped and
|
|
551
|
+
no `lint` record is written, so close runs lint itself. A preflight
|
|
552
|
+
downgrade is sound only with the re-asserting check declared here.
|
|
553
|
+
- **Duplication re-score.** After the base merge and before preflight, the
|
|
554
|
+
handoff runs close's own duplication re-score (`duplication-rescore` in
|
|
555
|
+
`steps[]`) over the same scope close uses, and commits any moved row with
|
|
556
|
+
close's **untagged** subject — never `baseline-refresh:`, which would let
|
|
557
|
+
refresh-ack launder the rise. It precedes every credit, so its commit voids
|
|
558
|
+
no lint/format credit, `test` credit or capture stamp, and close's re-score
|
|
559
|
+
over the same tree and base reports `unchanged`. Best-effort: a failed scan
|
|
560
|
+
or refused commit settles `error` and the run continues; close's re-score
|
|
561
|
+
stays authoritative. A re-run at the HEAD it settled skips it.
|
|
452
562
|
- **Post-capture checks.** After depositor and seat, the handoff runs close's
|
|
453
563
|
`quality-preview-crap` entry — only when the depositor is
|
|
454
564
|
`coverage-capture`, so a project with no capture keeps its CRAP behaviour —
|
|
455
565
|
and every registered `check-baselines` entry (`single`, or `independent`
|
|
456
566
|
plus `coverage`), each with close's argv and env (`BASELINE_REF`). A
|
|
457
567
|
non-zero exit is `fix-required` naming the gate and its kinds, with the log
|
|
458
|
-
as evidence
|
|
568
|
+
as evidence (a duplication-scoring entry also lists each row raised over
|
|
569
|
+
`BASELINE_REF`, base → head, with the re-score's clone partners); nothing is pushed. They are pure scoring: no lock, no suite,
|
|
459
570
|
no evidence, so close re-scores them. A re-run at a credited, unchanged
|
|
460
571
|
HEAD skips them.
|
|
461
572
|
- **Seat order vs credit.** Neither capture-stamp digest reads
|
|
@@ -467,10 +578,13 @@ Digest § 5 states the rule and both invocations; this is what surrounds them.
|
|
|
467
578
|
## Held review at hand-off {#held-review}
|
|
468
579
|
|
|
469
580
|
The one home of this rule; the digest and the worker contract point here.
|
|
470
|
-
`story-handoff.js` starts the Story-scope code review
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
581
|
+
`story-handoff.js` starts the Story-scope code review once base-merge settles
|
|
582
|
+
HEAD — pinned to the post-merge HEAD, before preflight's first check (and
|
|
583
|
+
before a `test`-depositor seat, whose generated-only commit keeps the digest)
|
|
584
|
+
— so it runs alongside preflight, and awaits it after the push, skipping the
|
|
585
|
+
computation when a deposit already matches the diff digest. A precheck
|
|
586
|
+
refusal or a base merge that does not settle (conflict, failed fetch, missing
|
|
587
|
+
merge driver) starts no review. The envelope's `reviewMs` sits beside the run's
|
|
474
588
|
`suiteTimings`. The same computation stands alone for a manual re-run:
|
|
475
589
|
|
|
476
590
|
```bash
|
|
@@ -481,27 +595,60 @@ node <main-repo>/.agents/scripts/story-review-compute.js --story <storyId> --cwd
|
|
|
481
595
|
provider chain) against `origin/<baseBranch>...story-<id>`, posts nothing,
|
|
482
596
|
takes no full-suite lock, and writes
|
|
483
597
|
`temp/orchestration/story-review-<id>.json` beside the terminal envelope,
|
|
484
|
-
keyed on the **diff digest
|
|
485
|
-
`linguist-generated` section removed
|
|
486
|
-
|
|
598
|
+
keyed on the **diff digest**: sha256 of the three-dot diff with every
|
|
599
|
+
`linguist-generated` section removed (a failed attribute lookup keeps them),
|
|
600
|
+
every `index` line dropped and every hunk header reduced to a bare `@@`
|
|
601
|
+
(offsets and function-context trailer gone) — `git patch-id --stable`'s
|
|
602
|
+
sameness. Every `+`, `-`, context, path and mode line still counts, so a
|
|
603
|
+
change a reviewer could see moves it; the reviewer itself still gets the
|
|
604
|
+
raw diff. It never stops the handoff on a provider throw — the step reports
|
|
487
605
|
`error` and close computes the review itself.
|
|
488
606
|
- **A CRITICAL is the worker's to fix.** The handoff settles `fix-required`
|
|
489
|
-
naming the deposit.
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
607
|
+
naming the deposit. It never cuts preflight short: every check runs to its
|
|
608
|
+
own result. One that has landed before the credited run would begin stops
|
|
609
|
+
the handoff there — no `test`-depositor seat, no run, no full-suite lock,
|
|
610
|
+
no credit, no push. One that lands while the run is in flight aborts it
|
|
611
|
+
(the SIGTERM a Ctrl-C sends; the child frees the full-suite lock), records
|
|
612
|
+
no credit and pushes nothing; a CRITICAL after the run still settles after
|
|
613
|
+
the push. Any earlier stop still awaits the review and appends its result
|
|
614
|
+
to `steps[]` once, so no provider is orphaned and one envelope carries both
|
|
615
|
+
findings, each with its own evidence path; `status` and `failedStep` stay
|
|
616
|
+
the first stop's, and a review `error` never blocks. Fix, commit, and re-run the handoff
|
|
494
617
|
(the fix commit voided the credit, so it re-runs the suite, pushes and
|
|
495
618
|
re-computes) — the acceptance loop's redraft discipline, bounded by
|
|
496
619
|
`delivery.acceptanceEval.maxRounds`. Still CRITICAL at the cap → take the
|
|
497
620
|
blocked path. Anything else goes in the hand-off as the severity tally.
|
|
498
|
-
- **Close adopts, else computes.** When the deposit's digest
|
|
499
|
-
digest of the diff at close's held-review start, close starts no
|
|
500
|
-
posts the deposit after PR-open. A
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
621
|
+
- **Close adopts, else computes — and deposits.** When the deposit's digest
|
|
622
|
+
equals the digest of the diff at close's held-review start, close starts no
|
|
623
|
+
review and posts the deposit after PR-open. A base-sync merge that moves
|
|
624
|
+
only offsets or `index` lines, or a seat commit that writes only generated
|
|
625
|
+
baselines, keeps the deposit; a commit that changes a reviewed line does
|
|
626
|
+
not, and close reviews as it would without one. Close deposits every
|
|
627
|
+
non-degraded review it computes, keyed on the SHA it reviewed: the held
|
|
628
|
+
review when it settles (posted or discarded alike) and the serial post-PR
|
|
629
|
+
review before it posts — so a retry on the same diff adopts it. A degraded
|
|
630
|
+
result is never deposited, and a failed write is one `REVIEW` warning. The
|
|
631
|
+
CRITICAL halt and `--override-review-block` apply to an adopted result
|
|
632
|
+
unchanged.
|
|
633
|
+
- **A deposit close never adopts is posted at land.** A Story landed without
|
|
634
|
+
close (push plus confirm-merge, or the boot sweep) gets the deposit matching
|
|
635
|
+
its merged head posted by the land tail before the temp purge, else an
|
|
636
|
+
`Unreviewed` marker naming `no-deposit` or `stale-deposit`, and a
|
|
637
|
+
`review-recorded-at-land` friction signal.
|
|
638
|
+
|
|
639
|
+
## Handoff telemetry {#handoff-telemetry}
|
|
640
|
+
|
|
641
|
+
Every `steps[]` entry carries `durationMs` (the review's is `reviewMs`); a
|
|
642
|
+
skip that reuses a result already recorded for this HEAD adds
|
|
643
|
+
`skippedByCredit: true`. A stopped envelope names a `cause` from a closed set
|
|
644
|
+
beside `failedStep`, and every envelope an `attempt` (`null` on a failed
|
|
645
|
+
read). After the state write, each run appends one record to the Story's
|
|
646
|
+
`signals.ndjson` (`phase: handoff`, `emitter.tool: story-handoff`): a `retry`
|
|
647
|
+
when refused, a `trace` when ready. A step that throws settles
|
|
648
|
+
`fix-required` with cause `other`, so the run still writes both. Details
|
|
649
|
+
carry step names, durations and the cause — never a file path. Close telemetry counts them in its `handoff`
|
|
650
|
+
block, apart from close's own `retries`. Best-effort: a failed write never
|
|
651
|
+
changes the status or exit code.
|
|
505
652
|
|
|
506
653
|
## Gate output {#gate-output}
|
|
507
654
|
|
|
@@ -510,7 +657,28 @@ reports a one-line digest on success; a failed gate replays its tail inline.
|
|
|
510
657
|
`AGENT_LOG_LEVEL=verbose` restores live streaming. A gate exiting `75` (its
|
|
511
658
|
full-suite lock wait expired) logs a deferred line and the close settles
|
|
512
659
|
`pending`; one exiting `124` (the suite outran its timeout) logs a timeout
|
|
513
|
-
line naming host contention — neither is reported as failing tests.
|
|
660
|
+
line naming host contention — neither is reported as failing tests. A
|
|
661
|
+
coverage-capture exiting `76` (the consumer's capture script declared its
|
|
662
|
+
slice over this host's budget, so nothing ran) follows
|
|
663
|
+
`delivery.quality.gates.coverage.onOverBudget`, and under
|
|
664
|
+
`coverage.suiteOfRecord: "ci"` the capture is deferred before anything
|
|
665
|
+
spawns (no lock, no credit). A deferral reports the gate `deferred`, the
|
|
666
|
+
coverage-reading gates `skipped` (`coverage-deferred-ci`), settles the
|
|
667
|
+
handoff `ready` with a `coverage` field, and puts a `Coverage-deferred:
|
|
668
|
+
<reason>` key line in the PR body. CI's `ciRatchetCheck` job then runs
|
|
669
|
+
`node .agents/scripts/coverage-ratchet.js --artifact <path> --head <sha>`,
|
|
670
|
+
and confirm-merge holds `agent::done` until that check is green. Under the
|
|
671
|
+
default `block`, or `suiteOfRecord: "ci"` with no `ciRatchetCheck`, the
|
|
672
|
+
handoff settles `blocked` and close fails, naming the keys.
|
|
673
|
+
A credited suite exiting `77` (the consumer's `test` or capture script
|
|
674
|
+
confirmed it lost workers to host memory and no test failed) is never read
|
|
675
|
+
as failing tests: the handoff settles `blocked` with `reason:
|
|
676
|
+
host-resources`, records no credit, copies any consumer `hostResources`
|
|
677
|
+
counts line into the envelope and appends a `host-resources` friction
|
|
678
|
+
record; close logs the suite gate as `host-resources` with its own hint.
|
|
679
|
+
`onOverBudget` never governs it. A second `124` at the same HEAD stays
|
|
680
|
+
`fix-required` but points at `coverage.timeoutMs`, an exit-76 declaration
|
|
681
|
+
or a quieter host instead of a plain re-run.
|
|
514
682
|
|
|
515
683
|
Every full-suite run ends on `⏲ suite timings: lockWaitMs=… hostWaitMs=…
|
|
516
684
|
testRunMs=…`. The handoff envelope carries its credited run's figures as
|
|
@@ -525,6 +693,11 @@ that writes `$MANDREL_SUITE_READY_FILE` when its tests start (after a
|
|
|
525
693
|
consumer load gate) gets a fresh bound for them, so worst-case wall is lock
|
|
526
694
|
wait + 2 × `timeoutMs`.
|
|
527
695
|
|
|
696
|
+
The close terminal's `pushOutcome` (also on the close result) reads its
|
|
697
|
+
`phaseDurations.push`: `pushed`, or `skipped-already-at-head` when origin
|
|
698
|
+
already held the Story-branch tip, so no `git push` (and no `pre-push`) ran.
|
|
699
|
+
`--skip-validation` always pushes; an unreadable tip or `ls-remote` pushes.
|
|
700
|
+
|
|
528
701
|
**Delta re-credit after a base move.** When close's base sync merged
|
|
529
702
|
incoming paths (`BASE MOVED`), the `test` gate is the suite gate, the
|
|
530
703
|
pre-sync head holds `test` credit and `project.commands.testChanged` is set,
|
|
@@ -277,18 +277,26 @@ judgment that help text cannot carry.
|
|
|
277
277
|
**critical** blocker is one you have read and judged wrong (a false positive,
|
|
278
278
|
or a finding the ratchet correctly exempts). It is the only sanctioned way
|
|
279
279
|
past that halt: reach for it instead of merging the PR by hand, because a
|
|
280
|
-
hand-merge bypasses the gate and records
|
|
280
|
+
hand-merge bypasses the gate and records no override — the land then posts
|
|
281
|
+
the held deposit (a merged CRITICAL raises `review-critical-merged`) or an
|
|
282
|
+
`Unreviewed` marker. The reason is mandatory and
|
|
281
283
|
is written to three places (Story comment, PR comment, a
|
|
282
284
|
`review-block-overridden` friction signal), and the terminal envelope reports
|
|
283
285
|
`gates.codeReview: "overridden"` rather than `"passed"`. If you find yourself
|
|
284
286
|
reaching for it twice for the same shape of finding, the gate is
|
|
285
287
|
miscalibrated — fix the gate, not the run.
|
|
286
|
-
- `gates.codeReview: "degraded"` — not
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
288
|
+
- `gates.codeReview: "unreviewed" | "partial" | "degraded"` — not flags but
|
|
289
|
+
envelope values from the review's degradation kinds: `unreviewed` (any
|
|
290
|
+
`verdict-missing`: no verdict, a skipped optional reviewer, an unresolvable
|
|
291
|
+
base), `partial` (any `coverage-partial`: part of the diff unreviewed),
|
|
292
|
+
`degraded` (only `context-reduced`: reviewed with less context). The
|
|
293
|
+
reviewer is retried once on a transient failure first. Precedence:
|
|
294
|
+
`overridden` > `unreviewed` > `partial` > `degraded` > `passed`. Under the
|
|
295
|
+
default `delivery.codeReview.onNoVerdict: "report"` all three are reported,
|
|
296
|
+
not blocking — read the diff yourself before trusting the merge. Under
|
|
297
|
+
`"block"`, `unreviewed` and `partial` halt the close like a CRITICAL
|
|
298
|
+
(`haltCause: "no-verdict"`, blocker naming the fix and the
|
|
299
|
+
`story-review-compute.js` re-run); `--override-review-block` is the escape.
|
|
292
300
|
- `--max-wait-seconds <n>` — from a headless caller with no host
|
|
293
301
|
tool-invocation ceiling, to keep single-block semantics
|
|
294
302
|
without editing the consumer's config.
|
|
@@ -545,7 +553,10 @@ state, flips `agent::closing → agent::done` on a confirmed merge (closing the
|
|
|
545
553
|
issue) and runs the **same** post-land tail — so the two surfaces cannot
|
|
546
554
|
diverge. It is idempotent, emits the same terminal envelope, and is safe to
|
|
547
555
|
re-run while the PR is still open (returns `pending`). The issue closes exactly
|
|
548
|
-
when the work has merged, never at PR-open.
|
|
556
|
+
when the work has merged, never at PR-open. It also guarantees a review record:
|
|
557
|
+
a PR landed without close gets the handoff deposit matching its merged head, or
|
|
558
|
+
an `Unreviewed` marker, as its `verification-results` comment
|
|
559
|
+
(`tail.reviewRecord`).
|
|
549
560
|
|
|
550
561
|
---
|
|
551
562
|
|
|
@@ -127,12 +127,17 @@ dispatch, pass it as `--worker-tokens <n>` — close records it in its
|
|
|
127
127
|
result's local `telemetry`; omit it when the host reports none. Every close
|
|
128
128
|
command deliver-run renders (a multi-Story run, or a one-Story resume) already
|
|
129
129
|
carries `--worker-model`, plus `--worker-effort` when the worker ran at a
|
|
130
|
-
resume effort.
|
|
130
|
+
resume effort. With `delivery.feedbackLoop.outcomeRecord` on, each close also
|
|
131
|
+
updates the Story's `story-outcome` comment, which
|
|
132
|
+
`node .agents/scripts/story-outcomes-report.js` rolls up.
|
|
131
133
|
|
|
132
134
|
**The whole delivery tail** — gates, PR, merge wait, `agent::done` flip,
|
|
133
135
|
post-land tail in one process. Never background it, never delegate it to a
|
|
134
136
|
child, and never end your turn while it is still running: "close is running"
|
|
135
|
-
is not a return value.
|
|
137
|
+
is not a return value. On a host that limits background commands (cloud,
|
|
138
|
+
`-p`, Agent SDK, CI) a one-Story close still runs in the foreground but adds
|
|
139
|
+
`--merge-watch-mode async`, so its merge wait moves into the background
|
|
140
|
+
confirm (reference § Async merge-confirm mode). Branch on the envelope's `status` per **digest § 6**
|
|
136
141
|
(`landed` → Step 7; `pending` → run `nextCommand`; `blocked`/`checks-failed`
|
|
137
142
|
→ Step 4; `failed` → diagnose, re-run; a `phase: base-sync` conflict comes
|
|
138
143
|
back with labels untouched — resolve it in `workCwd`, commit, run
|
|
@@ -66,6 +66,35 @@ the command exits.
|
|
|
66
66
|
a bracketed pattern (`pgrep -f "[m]y-script.js"`) — and always bound the
|
|
67
67
|
loop with a maximum iteration count so a wrong condition ends the wait
|
|
68
68
|
instead of the agent.
|
|
69
|
+
- **Time-limited hosts: pass an explicit timeout.** A host that runs
|
|
70
|
+
unattended (a cloud session, a `-p` run, an Agent SDK application, CI)
|
|
71
|
+
limits background commands to 30 minutes by default and 2 hours at most,
|
|
72
|
+
then stops them. Every long command started in the background therefore
|
|
73
|
+
passes an explicit timeout sized to its worst case — on Claude Code,
|
|
74
|
+
`timeout: 7200000` (the 2-hour maximum) beside `run_in_background: true`.
|
|
75
|
+
Pass it on **every** host: it is harmless on a local session, and an agent
|
|
76
|
+
cannot reliably tell the two apart. A host whose background shell takes no
|
|
77
|
+
timeout parameter follows its own limit. The host limit is a safety net,
|
|
78
|
+
not the plan — the delivery commands are idempotent and bounded internally
|
|
79
|
+
(`coverage.timeoutMs`, `mergeWatch.maxBudgetSeconds`).
|
|
80
|
+
- **Never rely on the auto-move.** A foreground command that reaches its
|
|
81
|
+
foreground timeout is moved to the background and gets only 30 minutes
|
|
82
|
+
from the move, whatever timeout it carried — start long work in the
|
|
83
|
+
background instead. Close stays foreground; on a time-limited host it
|
|
84
|
+
runs with `--merge-watch-mode async` so its merge wait moves into the
|
|
85
|
+
background `single-story-confirm-merge.js … --wait`
|
|
86
|
+
([`deliver-reference.md`](deliver-reference.md) § Async merge-confirm
|
|
87
|
+
mode).
|
|
88
|
+
- **Worst-case sizing.** A credited capture can reach the full-suite lock
|
|
89
|
+
wait plus 2 × `coverage.timeoutMs`. A consumer whose worst case exceeds
|
|
90
|
+
the host maximum lowers `coverage.timeoutMs` or declares the slice over
|
|
91
|
+
budget (exit 76, `onOverBudget`) — no timeout can exceed the maximum.
|
|
92
|
+
- **A stop notice is not silent.** When the host stops `story-handoff.js`,
|
|
93
|
+
`single-story-close.js` or `single-story-confirm-merge.js` at its
|
|
94
|
+
background limit, re-run the same command once with the explicit
|
|
95
|
+
timeout — each is idempotent and resumes. A second stop is a blocker:
|
|
96
|
+
post a `friction` comment naming the command and the limit, and flip
|
|
97
|
+
`agent::blocked`.
|
|
69
98
|
|
|
70
99
|
## Rule 3 — N parallel `Agent` calls in one turn for N independent units
|
|
71
100
|
|
|
@@ -578,12 +578,20 @@ for a source that was already `agent::ready`:
|
|
|
578
578
|
2. One PATCH sets the new title and body (with the plan fingerprint, so a
|
|
579
579
|
retried persist adopts the rewritten issue instead of duplicating it),
|
|
580
580
|
adds the Story's labels and this run's `plan-run::` label, and removes
|
|
581
|
-
every `agent::*` label and any earlier run's `plan-run::` label.
|
|
581
|
+
every `agent::*` label and any earlier run's `plan-run::` label. When the
|
|
582
|
+
original body's last non-blank line is a single HTML comment — a
|
|
583
|
+
consumer's machine-readable marker such as
|
|
584
|
+
`<!-- design-lab-ship branch=… sha=… -->` — that line is appended
|
|
585
|
+
verbatim after the fingerprint, so it stays the body's last line. It is
|
|
586
|
+
read from the preserved `plan-rewrite` original when one exists, so a
|
|
587
|
+
re-plan keeps exactly one copy; Mandrel's own fingerprint and
|
|
588
|
+
structured-comment markers are never carried.
|
|
582
589
|
3. The `story-plan-state` comment, then the terminal `agent::ready` flip.
|
|
583
590
|
|
|
584
591
|
The supersede phase lists the rewritten id under `supersede.rewritten` and
|
|
585
592
|
neither comments on nor closes it; the result's `rewrite` field names the
|
|
586
|
-
ticket or why there was none.
|
|
593
|
+
ticket or why there was none, and `rewrite.preservedMarker` says whether a
|
|
594
|
+
trailing marker was carried (a dry run reports the same answer).
|
|
587
595
|
|
|
588
596
|
**Falls back to create-and-close** with no warning for any other shape
|
|
589
597
|
(several sources, several Stories), under `--no-rewrite-source`, and under
|
package/docs/CHANGELOG.md
CHANGED
|
@@ -15,6 +15,62 @@ 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.112.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.111.0...mandrel-v2.112.0) (2026-11-07)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
### ⚠ BREAKING CHANGES
|
|
22
|
+
|
|
23
|
+
* gates.codeReview "degraded" now means reviewed with reduced context only. A review that produced no verdict reports "unreviewed", and one that left part of the diff unreviewed reports "partial"; a consumer reading "degraded" as "no verdict" must read "unreviewed".
|
|
24
|
+
* baselines/crap.json moves to the grouped `files` layout (path -> { "<method key>": crap }) with no startLine, coordinateSystem, anonymous or provenanceStamped, stamped scoringSemantics "method-identity-v5". A baseline in the previous rows[] layout or under any other stamp fails closed; re-seed it with `npm run test:coverage` then `npm run crap:update -- --full-scope` and commit the result with a `baseline-refresh:` subject.
|
|
25
|
+
|
|
26
|
+
### Added
|
|
27
|
+
|
|
28
|
+
* a deep held code review runs the reviewer at high effort, and a consumer can set the effort for each review depth ([#5976](https://github.com/dsj1984/mandrel/issues/5976)) ([#5996](https://github.com/dsj1984/mandrel/issues/5996)) ([00a7baa](https://github.com/dsj1984/mandrel/commit/00a7baabb16a6a95996273cb3c43ec0a232a650c))
|
|
29
|
+
* a held review survives a base merge that only shifts hunk offsets, and close deposits every review it computes so a retry adopts it ([#5973](https://github.com/dsj1984/mandrel/issues/5973)) ([#5985](https://github.com/dsj1984/mandrel/issues/5985)) ([5d834dc](https://github.com/dsj1984/mandrel/commit/5d834dc87fb1662ea8262be8a6e12b2c543ba8ae))
|
|
30
|
+
* a held-review CRITICAL reaches the worker during handoff preflight, in the same envelope as preflight's findings ([#5966](https://github.com/dsj1984/mandrel/issues/5966)) ([#6008](https://github.com/dsj1984/mandrel/issues/6008)) ([fb801bd](https://github.com/dsj1984/mandrel/commit/fb801bd2a5497f1286c7727a3d81cb05b3987b4c))
|
|
31
|
+
* a host can make CI the coverage and CRAP ratchet of record, and a deferred PR cannot land without that ratchet green ([#5955](https://github.com/dsj1984/mandrel/issues/5955)) ([#6003](https://github.com/dsj1984/mandrel/issues/6003)) ([c67c2b3](https://github.com/dsj1984/mandrel/commit/c67c2b3072082d4b0a01abd282f567b8aa09d884))
|
|
32
|
+
* a Story with no change under crap.targetDirs earns its handoff and close `test` credit from `testChanged`, not the full suite ([#5961](https://github.com/dsj1984/mandrel/issues/5961)) ([#6006](https://github.com/dsj1984/mandrel/issues/6006)) ([bf76aad](https://github.com/dsj1984/mandrel/commit/bf76aad78822b84d4851a44b7b06b1bead7b886d))
|
|
33
|
+
* a Story worktree reads the operator's live .agentrc.local.json from the main checkout, never a stale init-time snapshot ([#5972](https://github.com/dsj1984/mandrel/issues/5972)) ([#5992](https://github.com/dsj1984/mandrel/issues/5992)) ([80f62b5](https://github.com/dsj1984/mandrel/commit/80f62b595a95425fe88eb10f446613b968a8162c))
|
|
34
|
+
* a Story's own small post-credit fix re-measures only the delta's tests, not the whole affected slice ([#5958](https://github.com/dsj1984/mandrel/issues/5958)) ([#6004](https://github.com/dsj1984/mandrel/issues/6004)) ([8301e84](https://github.com/dsj1984/mandrel/commit/8301e842339f3f17d1ecd48eabc8749be394459f))
|
|
35
|
+
* a verified review CRITICAL stays blocking on later runs until the verifier refutes it at a newer head or an operator overrides it, and the PR comment lists every earlier CRITICAL ([#5974](https://github.com/dsj1984/mandrel/issues/5974)) ([#5987](https://github.com/dsj1984/mandrel/issues/5987)) ([f44a73b](https://github.com/dsj1984/mandrel/commit/f44a73b167ebad6f8c8ec9e9e082aa6ad31e5708))
|
|
36
|
+
* anonymous CRAP rows keep their identity across sibling insert, remove, reorder and line re-wrap ([#5969](https://github.com/dsj1984/mandrel/issues/5969)) ([#5981](https://github.com/dsj1984/mandrel/issues/5981)) ([1ca63df](https://github.com/dsj1984/mandrel/commit/1ca63df17b07ab80d0d2cb2f82e7c7083e39eec0))
|
|
37
|
+
* base moves stop voiding credit: a narrower coverage delta rule and an opt-in conflict-only base sync for merge-queue consumers ([#5954](https://github.com/dsj1984/mandrel/issues/5954)) ([#5984](https://github.com/dsj1984/mandrel/issues/5984)) ([fe5c2db](https://github.com/dsj1984/mandrel/commit/fe5c2dbc68ddd7c482f0e4a392261ab0e93f3491))
|
|
38
|
+
* close skips the Story-branch push when origin already holds the branch tip, so pre-push does not re-run on a pushed SHA ([#5967](https://github.com/dsj1984/mandrel/issues/5967)) ([#6010](https://github.com/dsj1984/mandrel/issues/6010)) ([12f4217](https://github.com/dsj1984/mandrel/commit/12f4217e4cc7c8592845c92dc9762e961f8e25d4))
|
|
39
|
+
* coverage capture and the CRAP preview measure a Story's change against origin/<baseBranch>, so a stale local base cannot widen the slice ([#5962](https://github.com/dsj1984/mandrel/issues/5962)) ([#5988](https://github.com/dsj1984/mandrel/issues/5988)) ([650552d](https://github.com/dsj1984/mandrel/commit/650552d4db225640bce7378ce511c79f38db85b4))
|
|
40
|
+
* CRAP scripts leave a baseline stamped with newer scoring semantics untouched and skip the gate instead of rewriting it or failing closed ([#5991](https://github.com/dsj1984/mandrel/issues/5991)) ([#5994](https://github.com/dsj1984/mandrel/issues/5994)) ([fdc29ea](https://github.com/dsj1984/mandrel/commit/fdc29ea525f8b9cb424a1248a0a1262fc445c965))
|
|
41
|
+
* every landed Story PR carries a code-review record, even when it landed without close ([#5975](https://github.com/dsj1984/mandrel/issues/5975)) ([#5993](https://github.com/dsj1984/mandrel/issues/5993)) ([9f9126f](https://github.com/dsj1984/mandrel/commit/9f9126f30a12c6993524156878d5eeb56dd1b86d))
|
|
42
|
+
* every story-handoff run leaves one signal naming its stopping step, cause and per-step time, and close telemetry counts handoff attempts ([#5970](https://github.com/dsj1984/mandrel/issues/5970)) ([#6013](https://github.com/dsj1984/mandrel/issues/6013)) ([c889f5f](https://github.com/dsj1984/mandrel/commit/c889f5f12ff11a0d54646eec8368acc642f959f1))
|
|
43
|
+
* every workflow boot names the open Stories stalled at agent::executing, with the deliver-recover command for each ([#5980](https://github.com/dsj1984/mandrel/issues/5980)) ([#6001](https://github.com/dsj1984/mandrel/issues/6001)) ([8074597](https://github.com/dsj1984/mandrel/commit/8074597db5920d69325ff11c0ac066706c4c5da9))
|
|
44
|
+
* handoff and close failure findings quote the offending rows and the diff-scoped remedy command ([#5968](https://github.com/dsj1984/mandrel/issues/5968)) ([#6011](https://github.com/dsj1984/mandrel/issues/6011)) ([bd297a9](https://github.com/dsj1984/mandrel/commit/bd297a925217fa2e5ac97c5bc86ba43d32976850))
|
|
45
|
+
* handoff and close settle a suite that lost workers to host memory (consumer exit 77) as blocked host-resources, not failing tests ([#5959](https://github.com/dsj1984/mandrel/issues/5959)) ([#6000](https://github.com/dsj1984/mandrel/issues/6000)) ([4f219fa](https://github.com/dsj1984/mandrel/commit/4f219fab6baf0165c2fd542697e54bca34001559))
|
|
46
|
+
* handoff preflight reports every finding in one pass and deposits close's typecheck credit before the suite ([#5957](https://github.com/dsj1984/mandrel/issues/5957)) ([#5989](https://github.com/dsj1984/mandrel/issues/5989)) ([85e6366](https://github.com/dsj1984/mandrel/commit/85e63668d39113eb53f43bb145268d476a342f7d))
|
|
47
|
+
* handoff preflight runs close's independent checks in admitted parallel lanes when a host opts in, and stays serial by default ([#5997](https://github.com/dsj1984/mandrel/issues/5997)) ([#6014](https://github.com/dsj1984/mandrel/issues/6014)) ([108b53c](https://github.com/dsj1984/mandrel/commit/108b53c1c440f278b8d26bbb6f93c8bf17e33ffe))
|
|
48
|
+
* handoff preflight skips a standalone ratchet the consumer's lint already ran on the same tree ([#5964](https://github.com/dsj1984/mandrel/issues/5964)) ([#6007](https://github.com/dsj1984/mandrel/issues/6007)) ([ccf5c96](https://github.com/dsj1984/mandrel/commit/ccf5c96c3d9541cbaa25950adee7028c2d1d3efa))
|
|
49
|
+
* handoff re-scores duplication rows before any credit, so a new clone is fix-required at handoff and close's re-score no-ops ([#5956](https://github.com/dsj1984/mandrel/issues/5956)) ([#5998](https://github.com/dsj1984/mandrel/issues/5998)) ([ebd1ba2](https://github.com/dsj1984/mandrel/commit/ebd1ba23c1e32b1302e5be4b6ffdc5f14e5794aa))
|
|
50
|
+
* handoff seats a Story's new-file baseline rows (MI before preflight, coverage after the capture) so one run reaches ready ([#5960](https://github.com/dsj1984/mandrel/issues/5960)) ([#6005](https://github.com/dsj1984/mandrel/issues/6005)) ([e235926](https://github.com/dsj1984/mandrel/commit/e23592648a94903ce8983672e78d45f720de4300))
|
|
51
|
+
* size-aware suite admission: a sized capture books its tier weight and a marked small run backfills ahead of a queued larger waiter ([#5963](https://github.com/dsj1984/mandrel/issues/5963)) ([#5990](https://github.com/dsj1984/mandrel/issues/5990)) ([3a5a70a](https://github.com/dsj1984/mandrel/commit/3a5a70af197e444f17e75434b1dc533d05016a6b))
|
|
52
|
+
* story handoff retries a GitHub ruleset-evaluation push failure as a first-parent stepped push instead of blocking ([#5965](https://github.com/dsj1984/mandrel/issues/5965)) ([#5995](https://github.com/dsj1984/mandrel/issues/5995)) ([5a68ce6](https://github.com/dsj1984/mandrel/commit/5a68ce67023efdf984cf6ac20d9bb41bcc6ad0d1))
|
|
53
|
+
* the committed CRAP baseline states each file path once and keys methods without startLine, so it stays far below host push-size limits and an edit above a method no longer rewrites its row ([#5971](https://github.com/dsj1984/mandrel/issues/5971)) ([#6002](https://github.com/dsj1984/mandrel/issues/6002)) ([ac40a9e](https://github.com/dsj1984/mandrel/commit/ac40a9e5e307e731be441fec49c302977b212913))
|
|
54
|
+
* the plan critic runs with only Read, Grep and Glob, and a hook keeps the acceptance critic's and auditor's writes under tempRoot ([#5978](https://github.com/dsj1984/mandrel/issues/5978)) ([#5986](https://github.com/dsj1984/mandrel/issues/5986)) ([ff6879c](https://github.com/dsj1984/mandrel/commit/ff6879c2fb224ab71e781de136d13463dd6d0843))
|
|
55
|
+
* the Story-scope review reports whether it reviewed nothing, part, or all of the diff, and a host can make an unreviewed merge block ([#5982](https://github.com/dsj1984/mandrel/issues/5982)) ([#6015](https://github.com/dsj1984/mandrel/issues/6015)) ([a18f741](https://github.com/dsj1984/mandrel/commit/a18f74191704ac128b2db5d9c98eeb95c8a8b900))
|
|
56
|
+
* with an opt-in key, every close attempt adds to one per-Story outcome record on GitHub, and a read-only report rolls those records up by gate and mandrel version ([#5977](https://github.com/dsj1984/mandrel/issues/5977)) ([#5999](https://github.com/dsj1984/mandrel/issues/5999)) ([4c99013](https://github.com/dsj1984/mandrel/commit/4c99013a7482c55b6fe2baceae763f2cc629d17b))
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
### Fixed
|
|
60
|
+
|
|
61
|
+
* correct 22 defects found reviewing the changes since 2.111.0 ([#6018](https://github.com/dsj1984/mandrel/issues/6018)) ([15b93aa](https://github.com/dsj1984/mandrel/commit/15b93aad60ea3be7c73c36e15bd953b8fa936546))
|
|
62
|
+
* **test:** make suite-admission AC-6 backfill ordering deterministic on slow spawns (refs [#5963](https://github.com/dsj1984/mandrel/issues/5963)) ([#6009](https://github.com/dsj1984/mandrel/issues/6009)) ([0217f3d](https://github.com/dsj1984/mandrel/commit/0217f3d30a4a06e5f7ee75e10428e6dcd356bcf0))
|
|
63
|
+
|
|
64
|
+
## [2.111.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.110.0...mandrel-v2.111.0) (2026-11-06)
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
### Added
|
|
68
|
+
|
|
69
|
+
* add /audit-state-machines: a read-only lens that finds implicit state machines and the impossible states they can reach ([#5952](https://github.com/dsj1984/mandrel/issues/5952)) ([#5953](https://github.com/dsj1984/mandrel/issues/5953)) ([8ef0489](https://github.com/dsj1984/mandrel/commit/8ef0489c4a464726439a4575bb25574baa79694d))
|
|
70
|
+
* CI digest blames the failed run, not a same-name green one; add an audited governance-label recovery verdict ([#5945](https://github.com/dsj1984/mandrel/issues/5945)) ([#5946](https://github.com/dsj1984/mandrel/issues/5946)) ([1839f9d](https://github.com/dsj1984/mandrel/commit/1839f9df7d6d9482f9ad038ce6c11ea102508cf6))
|
|
71
|
+
* coverage-capture: a consumer-declared over-budget slice defers to CI instead of timing out handoff and close ([#5949](https://github.com/dsj1984/mandrel/issues/5949)) ([#5951](https://github.com/dsj1984/mandrel/issues/5951)) ([7ee6b55](https://github.com/dsj1984/mandrel/commit/7ee6b556667e375d6272b91ffc94160f481dfcf8))
|
|
72
|
+
* plan-persist: keep a source ticket's trailing HTML-comment marker line when rewriting it in place ([#5948](https://github.com/dsj1984/mandrel/issues/5948)) ([#5950](https://github.com/dsj1984/mandrel/issues/5950)) ([1afdfa3](https://github.com/dsj1984/mandrel/commit/1afdfa324452c36a44477c50228051e046fc225d))
|
|
73
|
+
|
|
18
74
|
## [2.110.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.109.0...mandrel-v2.110.0) (2026-11-05)
|
|
19
75
|
|
|
20
76
|
|