mandrel 2.111.0 → 2.113.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/docs/agentrc-reference.json +22 -10
- package/.agents/docs/configuration.md +367 -37
- package/.agents/docs/execution-reference.md +11 -0
- package/.agents/rules/git-conventions-reference.md +7 -0
- package/.agents/schemas/agentrc.schema.json +174 -14
- 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 +41 -2
- 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 +37 -3
- package/.agents/scripts/coverage-ratchet.js +106 -0
- package/.agents/scripts/evidence-gate.js +84 -21
- package/.agents/scripts/lib/audit-baselines/read.js +8 -1
- package/.agents/scripts/lib/audit-baselines/trend.js +2 -1
- 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/merge-envelopes.js +46 -1
- 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 +93 -21
- 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 +111 -35
- 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 +55 -23
- 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 +45 -1
- 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 +26 -13
- 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 +15 -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/error-redactor.js +20 -0
- 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/baseline-conflict-rows.js +60 -0
- package/.agents/scripts/lib/git/sync-from-base.js +18 -9
- 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/code-review.js +223 -19
- package/.agents/scripts/lib/orchestration/handoff-gates.js +129 -62
- package/.agents/scripts/lib/orchestration/handoff-rescore.js +170 -0
- package/.agents/scripts/lib/orchestration/handoff-suite-of-record.js +45 -0
- 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 +41 -12
- package/.agents/scripts/lib/orchestration/review-providers/code-review.js +90 -39
- package/.agents/scripts/lib/orchestration/review-providers/critical-verifier.js +64 -11
- package/.agents/scripts/lib/orchestration/review-providers/degraded-gates.js +102 -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 +16 -3
- 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 +6 -0
- 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 +9 -12
- package/.agents/scripts/lib/orchestration/single-story-close/phases/open-pr.js +26 -12
- package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +51 -26
- package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-gate-steps.js +2 -1
- package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +3 -2
- package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js +50 -17
- 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 +30 -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 -3
- package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +3 -2
- package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +77 -15
- package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +7 -0
- package/.agents/scripts/lib/orchestration/story-handoff.js +796 -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/helpers/code-review.md +63 -9
- package/.agents/workflows/helpers/deliver-digest.md +53 -54
- package/.agents/workflows/helpers/deliver-reference.md +233 -67
- 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/docs/CHANGELOG.md +55 -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
|
@@ -8,11 +8,10 @@ description: >-
|
|
|
8
8
|
# Deliver digest (read once per session)
|
|
9
9
|
|
|
10
10
|
> **Bundle, not a procedure.** [`deliver-story.md`](deliver-story.md) is still
|
|
11
|
-
> the steps; this file
|
|
12
|
-
>
|
|
13
|
-
> routers, merge-wait budgets, CI remediation) stays on demand in
|
|
11
|
+
> the steps; this file bundles the material they reference. Situational
|
|
12
|
+
> material stays on demand in
|
|
14
13
|
> [`deliver-story-reference.md`](deliver-story-reference.md) and
|
|
15
|
-
> [`deliver-reference.md`](deliver-reference.md)
|
|
14
|
+
> [`deliver-reference.md`](deliver-reference.md), read only when routed.
|
|
16
15
|
|
|
17
16
|
## 1. Dispatch — where the engine runs
|
|
18
17
|
|
|
@@ -21,12 +20,12 @@ rule produces it:
|
|
|
21
20
|
|
|
22
21
|
1. **Run topology.** A one-Story run is `inline` (the router's own session)
|
|
23
22
|
whatever its shape — isolation only matters against a *concurrent*
|
|
24
|
-
sibling
|
|
25
|
-
2. **Every other run is `subagent`**,
|
|
23
|
+
sibling.
|
|
24
|
+
2. **Every other run is `subagent`**, whatever each Story's shape.
|
|
26
25
|
|
|
27
26
|
`inline` drops only the `story-worker` boot — not the verdict owner, which
|
|
28
27
|
the profile alone names (§ 3). **`subagent` and `inline` run the same engine**: same gates,
|
|
29
|
-
same PR to `main`, same
|
|
28
|
+
same PR to `main`, same envelope.
|
|
30
29
|
|
|
31
30
|
## 2. Engine invariants
|
|
32
31
|
|
|
@@ -44,43 +43,41 @@ the only sanctioned landing.
|
|
|
44
43
|
|
|
45
44
|
## 3. Change set — computed once, handed to everyone
|
|
46
45
|
|
|
47
|
-
One enumeration per Story: a critic
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
46
|
+
One enumeration per Story: a critic re-running `git diff` can score
|
|
47
|
+
another set. **One script** derives the change set, the level and the
|
|
48
|
+
ceremony (close and critic hand-offs call it; the worker gets it from § 4's
|
|
49
|
+
`--init`):
|
|
51
50
|
|
|
52
51
|
```bash
|
|
53
52
|
node <main-repo>/.agents/scripts/ceremony-derive.js --story <storyId> --cwd <workCwd>
|
|
54
53
|
```
|
|
55
54
|
|
|
56
|
-
It prints one
|
|
57
|
-
|
|
55
|
+
It prints one object: `files` — the one change set handed to the verdict
|
|
56
|
+
owner (`null` when the diff is unenumerable) — plus `level` and
|
|
58
57
|
`classes` from `review-depth.js`, and `mode`, `reason` and `verdictOwner`
|
|
59
|
-
from `ceremony-routing.js`. Level
|
|
60
|
-
`audit-rules.json` → `high`,
|
|
61
|
-
The level drives **review depth** only (close reads
|
|
58
|
+
from `ceremony-routing.js`. Level: a sensitive
|
|
59
|
+
`audit-rules.json` path → `high`, else `low`; unenumerable → `null`.
|
|
60
|
+
The level drives **review depth** only (close reads it too): a
|
|
62
61
|
sensitive footprint buys a **deep review**, not a fresh acceptance critic.
|
|
63
62
|
|
|
64
63
|
> **The ceremony rule, stated once.** The **profile alone** names the verdict
|
|
65
64
|
> owner: `minimal` / `standard` → `inline`, `strict` → `fresh`. Nothing else
|
|
66
65
|
> moves it — not the change level, not sensitivity, **not the dispatch
|
|
67
|
-
> mode**: an `inline` Story under `strict` still spawns the fresh critic
|
|
68
|
-
>
|
|
69
|
-
> [`acceptance-self-eval.md`](acceptance-self-eval.md), noted in any friction
|
|
70
|
-
> comment.
|
|
66
|
+
> mode**: an `inline` Story under `strict` still spawns the fresh critic,
|
|
67
|
+
> bar the harness fallback in [`acceptance-self-eval.md`](acceptance-self-eval.md).
|
|
71
68
|
|
|
72
69
|
## 4. Acceptance self-eval (Step 1a, required)
|
|
73
70
|
|
|
74
71
|
**One verdict owner per Story** — named by `verdictOwner`: the inline
|
|
75
72
|
self-eval under `minimal` / `standard` (the default), a fresh maker-blind
|
|
76
|
-
critic under `strict`. Never both
|
|
73
|
+
critic under `strict`. Never both. Start from the
|
|
77
74
|
skeleton — it derives § 3's `files` and `verdictOwner` with the same function:
|
|
78
75
|
|
|
79
76
|
`node <main-repo>/.agents/scripts/acceptance-eval.js --story <storyId> --init
|
|
80
77
|
--cwd <workCwd>`
|
|
81
78
|
|
|
82
|
-
It writes one empty record per `acceptance[]` item
|
|
83
|
-
|
|
79
|
+
It writes one empty record per `acceptance[]` item and prints its
|
|
80
|
+
path. The owner fills **every** record,
|
|
84
81
|
scored against that change set with `verify[]` output as evidence, and scores
|
|
85
82
|
it in **one** gate call. Bounded by `delivery.acceptanceEval.maxRounds`
|
|
86
83
|
(default 2; `0` scores once with no redraft).
|
|
@@ -90,8 +87,7 @@ it in **one** gate call. Bounded by `delivery.acceptanceEval.maxRounds`
|
|
|
90
87
|
|
|
91
88
|
The gate reads the Story's `acceptance[]` count itself and rejects, **before**
|
|
92
89
|
scoring and consuming no round, a verdict whose `criteria[]` length differs
|
|
93
|
-
or with an unfilled record (naming its indices).
|
|
94
|
-
same round wastes it and races the Story ledger.
|
|
90
|
+
or with an unfilled record (naming its indices).
|
|
95
91
|
|
|
96
92
|
`proceed` → § 5. `redraft` → one more round inside the cap. `block` → **do
|
|
97
93
|
not close**: post a `friction` comment and flip `agent::blocked`.
|
|
@@ -99,44 +95,47 @@ Per-round mechanics: [`acceptance-self-eval.md`](acceptance-self-eval.md).
|
|
|
99
95
|
|
|
100
96
|
## 5. The one credited run — `story-handoff.js`
|
|
101
97
|
|
|
102
|
-
After the self-eval
|
|
103
|
-
which runs this section in order and prints one envelope:
|
|
98
|
+
After the self-eval's last fix commit the worker runs **one** command:
|
|
104
99
|
|
|
105
100
|
`node <main-repo>/.agents/scripts/story-handoff.js --story <storyId> --cwd <workCwd>`
|
|
106
101
|
|
|
107
102
|
`ready` (exit 0) → hand off. `fix-required` (exit 2) → a finding, a red or
|
|
108
|
-
deferred suite, a base-merge conflict
|
|
109
|
-
or a CRITICAL: fix, commit,
|
|
110
|
-
only a remote-refused push,
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
**
|
|
118
|
-
2. **Preflight — blocking.** `lint`/`format` (close's credit),
|
|
103
|
+
deferred suite, a base-merge conflict, a non-fast-forward push,
|
|
104
|
+
a `commit_refs_rules` push stepping missed or a CRITICAL: fix, commit,
|
|
105
|
+
re-run; labels untouched. `blocked` (exit 1) → only a remote-refused push,
|
|
106
|
+
an unreachable remote, an unconfirmed base branch, an unregistered merge
|
|
107
|
+
driver or `host-resources` (exit 77): it flips `agent::blocked` and posts
|
|
108
|
+
`friction`. A re-run skips every step still valid for HEAD. Past the sync ceiling → **background**, explicit timeout: parallel-tooling Rule 2.
|
|
109
|
+
|
|
110
|
+
1. **Base merge:** merge `origin/<baseBranch>` into the Story branch
|
|
111
|
+
**first**, ahead of every check: close's base-sync then no-ops. Then close's **duplication re-score**, committed
|
|
112
|
+
**untagged** before any credit.
|
|
113
|
+
2. **Preflight — blocking.** `typecheck`/`lint`/`format` (close's credit),
|
|
119
114
|
`quality-preview.js --changed-since origin/<baseBranch>`, then each
|
|
120
|
-
baselined ratchet
|
|
115
|
+
baselined ratchet; one `fix-required` lists every finding. Serial unless
|
|
116
|
+
a per-host `.agentrc.local.json` sets `delivery.execution.preflightConcurrency`
|
|
117
|
+
above 1 (default 1): close's independent gates then run in admitted
|
|
118
|
+
lanes beside the base lane — [`deliver-reference.md`](deliver-reference.md) § Preflight.
|
|
121
119
|
3. **One depositor**, by the one predicate close registers `coverage-capture`
|
|
122
120
|
on — coverage or CRAP gate on **and** a `captureScript`:
|
|
123
121
|
- **Capture-active** →
|
|
124
122
|
`node <main-repo>/.agents/scripts/coverage-capture.js --cwd <workCwd>`,
|
|
125
|
-
behind the
|
|
123
|
+
behind the full-suite lock. Signal: `Wrote content-digest capture
|
|
126
124
|
stamp`. No second `npm test`.
|
|
127
125
|
- **Otherwise** → `node <main-repo>/.agents/scripts/evidence-gate.js
|
|
128
|
-
--standalone --scope-id <storyId> --gate test --worktree <workCwd> -- npm test
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
126
|
+
--standalone --scope-id <storyId> --gate test --worktree <workCwd> -- npm test`;
|
|
127
|
+
a predicted capture skip runs `testChanged --changed-since` the
|
|
128
|
+
merge-base, else says why. Signal: `✓ test passed`.
|
|
129
|
+
4. **Seat.** `--seat-missing` (`seated: N`): MI before step 2, CRAP and
|
|
130
|
+
capture-path coverage here, committed `chore(baselines): baseline-refresh:
|
|
131
|
+
…`; then post-capture checks: close's `quality-preview-crap` and `check-baselines`,
|
|
132
|
+
then `delivery.handoff.postSeatChecks`. Children get `MANDREL_HANDOFF_STEP`.
|
|
133
133
|
5. **Push** `story-<id>`; the remote ref must equal HEAD.
|
|
134
|
-
6. **Held review**
|
|
135
|
-
[`deliver-reference.md`](deliver-reference.md) § Held review.
|
|
134
|
+
6. **Held review** from step 1, beside 2: a CRITICAL skips or aborts 3,
|
|
135
|
+
one envelope with any finding — [`deliver-reference.md`](deliver-reference.md) § Held review.
|
|
136
136
|
|
|
137
137
|
A later commit voids any credit; a baseline-JSON seat keeps the stamp. It
|
|
138
|
-
reads the **output**, not the exit code:
|
|
139
|
-
deposits nothing. Seat order, runner shapes, redraft rounds:
|
|
138
|
+
reads the **output**, not the exit code: no signal deposits nothing. Seat order, runner shapes:
|
|
140
139
|
[`deliver-reference.md`](deliver-reference.md) § Credited run.
|
|
141
140
|
|
|
142
141
|
`verify[]` is scoped entries **plus** this one run: an entry that is a
|
|
@@ -148,7 +147,7 @@ respawned.
|
|
|
148
147
|
`single-story-close.js` emits exactly one envelope on stdout between
|
|
149
148
|
`--- STORY DELIVER TERMINAL ---` markers, schema-validated against
|
|
150
149
|
[`story-deliver-terminal.schema.json`](../../schemas/story-deliver-terminal.schema.json)
|
|
151
|
-
— the SSOT. Relay it verbatim; never hand-compose one
|
|
150
|
+
— the SSOT. Relay it verbatim; never hand-compose one.
|
|
152
151
|
|
|
153
152
|
| `status` | Exit | Meaning | You do |
|
|
154
153
|
| --- | --- | --- | --- |
|
|
@@ -161,12 +160,12 @@ Required fields: `kind` (`story-deliver-terminal`), `storyId`, `status`,
|
|
|
161
160
|
`phase` (the schema's enum names where it stopped), `elapsedSeconds`,
|
|
162
161
|
`nextCommand`. `gates`
|
|
163
162
|
reports every gate as `passed` / `failed` / `skipped` — a skipped gate is
|
|
164
|
-
|
|
163
|
+
never omitted, so a missing gate never reads as passing.
|
|
165
164
|
|
|
166
165
|
## 7. When to leave this file
|
|
167
166
|
|
|
168
|
-
Unclear state / a re-run refusal → `deliver-recover.js --story <id
|
|
169
|
-
|
|
170
|
-
threading → [`deliver-story-reference.md`](deliver-story-reference.md) and
|
|
167
|
+
Unclear state / a re-run refusal → `deliver-recover.js --story <id>`; boot
|
|
168
|
+
auto-lists stalled `agent::executing` Stories with it (read-only, advisory).
|
|
169
|
+
Lease, sweep, worktree scope; sequencing, epilogue, checklist threading → [`deliver-story-reference.md`](deliver-story-reference.md) and
|
|
171
170
|
[`deliver-reference.md`](deliver-reference.md). CI red after the PR opens →
|
|
172
171
|
[`rules/ci-remediation.md`](../../rules/ci-remediation.md).
|
|
@@ -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
|
|
|
@@ -513,11 +660,25 @@ full-suite lock wait expired) logs a deferred line and the close settles
|
|
|
513
660
|
line naming host contention — neither is reported as failing tests. A
|
|
514
661
|
coverage-capture exiting `76` (the consumer's capture script declared its
|
|
515
662
|
slice over this host's budget, so nothing ran) follows
|
|
516
|
-
`delivery.quality.gates.coverage.onOverBudget
|
|
517
|
-
|
|
518
|
-
(
|
|
519
|
-
|
|
520
|
-
`
|
|
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.
|
|
521
682
|
|
|
522
683
|
Every full-suite run ends on `⏲ suite timings: lockWaitMs=… hostWaitMs=…
|
|
523
684
|
testRunMs=…`. The handoff envelope carries its credited run's figures as
|
|
@@ -532,6 +693,11 @@ that writes `$MANDREL_SUITE_READY_FILE` when its tests start (after a
|
|
|
532
693
|
consumer load gate) gets a fresh bound for them, so worst-case wall is lock
|
|
533
694
|
wait + 2 × `timeoutMs`.
|
|
534
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
|
+
|
|
535
701
|
**Delta re-credit after a base move.** When close's base sync merged
|
|
536
702
|
incoming paths (`BASE MOVED`), the `test` gate is the suite gate, the
|
|
537
703
|
pre-sync head holds `test` credit and `project.commands.testChanged` is set,
|