mandrel 2.110.0 → 2.111.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/audit-checklists/state-machines.md +21 -0
- package/.agents/docs/agentrc-reference.json +2 -1
- package/.agents/docs/configuration.md +33 -0
- package/.agents/docs/workflows.md +2 -1
- package/.agents/rules/ci-remediation.md +28 -4
- package/.agents/schemas/agentrc.schema.json +6 -0
- package/.agents/schemas/audit-rules.json +28 -0
- package/.agents/schemas/story-deliver-terminal.schema.json +9 -2
- package/.agents/scripts/coverage-capture.js +3 -1
- package/.agents/scripts/file-ci-gap.js +220 -10
- package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
- package/.agents/scripts/lib/close-validation/gates.js +48 -0
- package/.agents/scripts/lib/close-validation/runner.js +118 -31
- package/.agents/scripts/lib/config/gates/coverage.schema.js +9 -0
- package/.agents/scripts/lib/config/quality.js +3 -0
- package/.agents/scripts/lib/coverage-capture-usage.js +1 -1
- package/.agents/scripts/lib/coverage-capture.js +16 -0
- package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
- package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +124 -23
- package/.agents/scripts/lib/orchestration/handoff-gates.js +108 -2
- 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/single-story-close/phases/close-validation.js +3 -0
- package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +7 -1
- package/.agents/scripts/lib/orchestration/single-story-close/phases/normalize-pr-title.js +20 -2
- package/.agents/scripts/lib/orchestration/single-story-close/phases/open-pr.js +21 -13
- package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +1 -0
- package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js +3 -0
- package/.agents/scripts/lib/orchestration/single-story-close/result.js +13 -0
- package/.agents/scripts/lib/orchestration/single-story-close/runner.js +1 -0
- package/.agents/scripts/lib/orchestration/story-handoff.js +22 -7
- package/.agents/workflows/audit-state-machines.md +213 -0
- package/.agents/workflows/helpers/deliver-reference.md +8 -1
- package/.agents/workflows/helpers/plan-reference.md +10 -2
- package/docs/CHANGELOG.md +10 -0
- package/package.json +1 -1
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
<!-- GENERATED FILE — do not edit by hand.
|
|
2
|
+
Source of truth: .agents/workflows/audit-state-machines.md
|
|
3
|
+
Regenerate: node .agents/scripts/generate-lens-checklists.js
|
|
4
|
+
Drift is gated by: npm run docs:check
|
|
5
|
+
-->
|
|
6
|
+
|
|
7
|
+
# State Machine Audit — authoring checklist
|
|
8
|
+
|
|
9
|
+
> Audit implicit state machines — co-varying flags, status sidecar fields, scattered transitions, state split across systems — and report only the impossible or unhandled combinations the code can reach, each with a traced write path and a sketch of the explicit form.
|
|
10
|
+
|
|
11
|
+
Self-check your change against this lens's concerns before you ship:
|
|
12
|
+
|
|
13
|
+
- [ ] Shape: the variables move together.
|
|
14
|
+
- [ ] Consequence: a bad combination is reachable.
|
|
15
|
+
- [ ] Flags that encode one enum
|
|
16
|
+
- [ ] Fields valid only in some statuses
|
|
17
|
+
- [ ] Transitions with no single guard
|
|
18
|
+
- [ ] Consumers that miss a value
|
|
19
|
+
- [ ] One state, two stores
|
|
20
|
+
- [ ] Second read of the write order.
|
|
21
|
+
- [ ] Severity calibration.
|
|
@@ -181,6 +181,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
|
|
|
181
181
|
| `quality.gates.coverage.captureScript` | No | `string` | `"test:coverage"` | `package.json` script (never a shell command) the coverage gate's capture runs, spawned as `<pm> run <script>` under the detected package manager (npm, pnpm, yarn or bun). Close registers the coverage-capture gate when the coverage or CRAP gate is enabled and this script exists; the full-suite lock's workload identity and `mandrel doctor`'s `test-credit-path` check follow it. Default `test:coverage`. |
|
|
182
182
|
| `quality.gates.coverage.captureScope` | No | `"full"` \| `"affected"` | `"full"` | What coverage-capture runs. `full` (default) runs `captureScript`. `affected` runs the consumer-owned `test:coverage:affected` script with the base ref in `MANDREL_COVERAGE_BASE_REF`, merges its rows over the prior artifact and stamps it `affected`; baseline rows the scoped run did not measure are treated as unmeasured, never removed. Falls back to `full` with a warning when the script is absent. Meant for consumers whose CI already enforces coverage on the full suite. |
|
|
183
183
|
| `quality.gates.coverage.timeoutMs` | No | `integer` | `600000` | Kill bound (ms) for one full-suite run — the coverage capture, the close-validation full-suite gate and the full-suite lock-wait budget all read it. The clock starts at spawn, never while queued on the host lock; a suite that signals `MANDREL_SUITE_READY_FILE` gets a fresh bound for its test phase, so worst-case wall is lock wait + 2 × timeoutMs. On expiry the run exits 124 so callers can tell a hang from a failure. |
|
|
184
|
+
| `quality.gates.coverage.onOverBudget` | No | `"block"` \| `"defer-to-ci"` | `"block"` | What handoff and close do when the capture script exits 76 — the consumer-declared signal that the selected slice is over this host's budget and no test ran. `block` (default) stops the handoff (`blocked`) and fails close, naming this key. `defer-to-ci` settles the coverage gate as deferred to CI: no artifact is written or stamped and no credit is recorded, the coverage-reading gates (CRAP preview, coverage and CRAP baselines) are skipped, and handoff and close proceed — the terminal envelope and the PR body say coverage was deferred. Set it only when the consumer's CI runs the deferred suite with a coverage floor. A timeout (124) is never deferred, under either value. |
|
|
184
185
|
| `quality.gates.crap` | No | `object` | — | CRAP (Change Risk Anti-Pattern) ratchet — per-method cyclomatic complexity joined against per-method coverage. |
|
|
185
186
|
| `quality.gates.crap.enabled` | No | `boolean` | `true` | When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted. |
|
|
186
187
|
| `quality.gates.crap.baselinePath` | No | `string` | `"baselines/crap.json"` | Repo-root-relative path to the gate's committed baseline artifact. |
|
|
@@ -474,6 +475,38 @@ verdict (`fresh`, `stale`, `scope-mismatch`, `missing`, or `delta-refresh`
|
|
|
474
475
|
with the delta's file count), so an unexpected full re-run is explainable
|
|
475
476
|
from the log alone. `captureScope: "full"` is unaffected.
|
|
476
477
|
|
|
478
|
+
#### `delivery.quality.gates.coverage.onOverBudget` — deferring to CI
|
|
479
|
+
|
|
480
|
+
A hub change on a small host (a 4-core cloud VM, say) can select a capture
|
|
481
|
+
slice that cannot finish inside `timeoutMs`, and the handoff then ends in
|
|
482
|
+
exit 124. When the consumer's CI already runs that suite, a local run is a
|
|
483
|
+
duplicate the host cannot finish. Exit `76` and this key let the consumer
|
|
484
|
+
say so.
|
|
485
|
+
|
|
486
|
+
- **The signal is the consumer's.** Its `captureScript`,
|
|
487
|
+
`affectedCaptureScript` or `crap.captureScript` exits **76** to mean "the
|
|
488
|
+
selected slice is over this host's budget; no test ran". Mandrel never
|
|
489
|
+
sizes a slice or predicts its runtime. `coverage-capture.js` passes 76
|
|
490
|
+
through unchanged: it writes and stamps no artifact, and runs no later
|
|
491
|
+
capture pass.
|
|
492
|
+
- **`block` (default).** The handoff settles `blocked` and close fails, each
|
|
493
|
+
naming this key. Nothing changes for a consumer that never emits 76.
|
|
494
|
+
- **`defer-to-ci`.** The handoff settles `ready` with
|
|
495
|
+
`coverage: { status: "deferred", reason: "over-budget", policy:
|
|
496
|
+
"defer-to-ci" }` and records no credit. It skips the CRAP `--seat-missing`
|
|
497
|
+
pass and the gates that read the artifact (`quality-preview-crap`,
|
|
498
|
+
`check-baselines-coverage`). Close re-runs the capture, reports
|
|
499
|
+
`coverage-capture: "deferred"` and those gates as `skipped`
|
|
500
|
+
(`coverage-deferred-ci`), and opens the PR with a line saying coverage was
|
|
501
|
+
deferred to CI. Every other gate still runs.
|
|
502
|
+
- **CI owns the deferred run.** Set `defer-to-ci` only when the consumer's
|
|
503
|
+
CI runs the suite with a coverage floor. Nothing local checks coverage or
|
|
504
|
+
CRAP for a deferred Story, and CRAP rows for its new methods stay unseated.
|
|
505
|
+
- **Nothing sticks.** A deferral writes no artifact, stamp or credit, so a
|
|
506
|
+
later run on a bigger host captures, seats and scores as usual.
|
|
507
|
+
- **A timeout is not a deferral.** Exit 124 can hide a hang, so it keeps its
|
|
508
|
+
current handling under either value.
|
|
509
|
+
|
|
477
510
|
#### `delivery.worktreeIsolation` — node_modules strategies
|
|
478
511
|
|
|
479
512
|
When `enabled: true`, each Story runs in its own worktree under
|
|
@@ -51,7 +51,7 @@ by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`
|
|
|
51
51
|
fails when it drifts from the on-disk workflow set. To change a command’s
|
|
52
52
|
description, edit the workflow file’s front-matter and regenerate.
|
|
53
53
|
|
|
54
|
-
## Commands (
|
|
54
|
+
## Commands (38)
|
|
55
55
|
|
|
56
56
|
| Command | Description |
|
|
57
57
|
| --- | --- |
|
|
@@ -77,6 +77,7 @@ description, edit the workflow file’s front-matter and regenerate.
|
|
|
77
77
|
| `/audit-security` | Audit dependency CVEs, input-validation gaps, secrets handling, auth boundaries, and the trust-boundary attack classes the baseline is silent on (business logic, SSRF/traversal, deserialization, crypto misuse, feature abuse, LLM tool-binding); emit a structured High/Medium/Low findings report. |
|
|
78
78
|
| `/audit-seo` | Audit SEO fundamentals and Generative Engine Optimization signals (meta, structured data, crawlability); only relevant for web targets. |
|
|
79
79
|
| `/audit-sre` | "Audit production-readiness for a release candidate: SLOs, observability, runbooks, error budgets, and rollback paths." |
|
|
80
|
+
| `/audit-state-machines` | Audit implicit state machines — co-varying flags, status sidecar fields, scattered transitions, state split across systems — and report only the impossible or unhandled combinations the code can reach, each with a traced write path and a sketch of the explicit form. |
|
|
80
81
|
| `/audit-to-stories` | Convert findings produced by the audit-\* workflows into actionable GitHub Stories. Reads temp/audits/audit-results/audit-\*-results.md, groups findings cross-audit, deduplicates against existing Issues by fingerprint, and either chains into /mandrel-plan --seed-file or opens standalone Stories. |
|
|
81
82
|
| `/audit-ux-ui` | Audit UX/UI consistency and design system adherence |
|
|
82
83
|
| `/clean-git` | Tidy the local checkout in four phases: fast-forward `main`, prune stale remote-tracking refs, sweep merged branches (squash-aware), and triage `git stash` entries — each step gated by operator confirmation. |
|
|
@@ -68,6 +68,7 @@ the two options above. Name the verdict you reached in the `friction` comment.
|
|
|
68
68
|
| **pre-existing** | The same check fails on an unmodified `main` too | Option 2 — `file-ci-gap.js --verdict pre-existing`; remediate here only if it blocks this delivery |
|
|
69
69
|
| **capacity** | Proven exhaustion of a runner resource, not a property of the diff (see below) | Option 2 — `file-ci-gap.js --verdict capacity` (`meta::framework-gap` unless `--owner` routes it elsewhere) **and** escalate to the operator |
|
|
70
70
|
| **unreproducible-tier** | The tier cannot be exercised in this sandbox at all, proven by an attempted attach (see below) | Option 2 — `file-ci-gap.js --verdict unreproducible-tier` (`meta::framework-gap` unless `--owner` routes it elsewhere) **and** escalate on first encounter |
|
|
71
|
+
| **governance-label** | The red was a governance check awaiting an operator-approved label; adding it started a fresh run on the same head, which passed | Recovery, not a gap — `file-ci-gap.js --verdict governance-label --label <name>` (§ Governance-label recovery); files nothing |
|
|
71
72
|
|
|
72
73
|
Why the verdict set carries these last two is recorded in
|
|
73
74
|
[`docs/decisions.md` ADR 20260906-5160a](../../docs/decisions.md).
|
|
@@ -158,11 +159,31 @@ it names a real defect someone owns and a rerun cannot remove it. Skipping,
|
|
|
158
159
|
quarantining or loosening a test to reach green stays forbidden under every
|
|
159
160
|
verdict, always.
|
|
160
161
|
|
|
162
|
+
### Governance-label recovery
|
|
163
|
+
|
|
164
|
+
Some checks are designed to stay red until an authorized person approves a
|
|
165
|
+
governance label, such as `migration:destructive-ok`. Adding the label starts a
|
|
166
|
+
**fresh** workflow run on the same head SHA. That run gets a new run ID; it is
|
|
167
|
+
not a rerun of the failed job. Its green is still on the red head, so the
|
|
168
|
+
guard reads it as a forbidden rerun. Record the audited recovery instead:
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
node .agents/scripts/file-ci-gap.js --story <id> --verdict governance-label --label <name>
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
It reads the PR's issue events and refuses (non-zero exit, nothing written)
|
|
175
|
+
unless the label is still on the PR **and** a `labeled` event for it is newer
|
|
176
|
+
than the red. On proof it stamps the one-green allowance on the digest. It
|
|
177
|
+
then posts a `friction` comment recording the label, who added it, when, and
|
|
178
|
+
the red and green run links. It files **no** intake issue and applies no
|
|
179
|
+
`friction::*` label: the CI did what it was built to do. Nothing is faked and
|
|
180
|
+
no check is loosened. Resume the watch; the same-SHA green is admitted once.
|
|
181
|
+
|
|
161
182
|
## Verifier
|
|
162
183
|
|
|
163
184
|
The check is resolved only when it is **green with no rerun of the failed job**
|
|
164
|
-
— save the one a recorded `capacity` / `unreproducible-tier` verdict buys
|
|
165
|
-
above) — and the diff carries **no `.skip` / `.only`, no quarantine, and no
|
|
185
|
+
— save the one a recorded `capacity` / `unreproducible-tier` verdict buys,
|
|
186
|
+
or the fresh run a recorded `governance-label` recovery admits (§§ above) — and the diff carries **no `.skip` / `.only`, no quarantine, and no
|
|
166
187
|
deleted or loosened assertion** introduced to reach green. You may **not**
|
|
167
188
|
re-run a failed job to "see if it goes green," and you may **not** skip,
|
|
168
189
|
`.only`, or quarantine a flaky test to get a green bar. Both mask the defect
|
|
@@ -174,7 +195,8 @@ on the **first red** — GitHub's native auto-merge fires server-side, so it
|
|
|
174
195
|
races any attempt to detect a rerun-green and block it after the fact. On the
|
|
175
196
|
first red the watcher **disarms native auto-merge** (a disarm failure is a
|
|
176
197
|
blocker, not a warning) and records the PR **head SHA** in the digest
|
|
177
|
-
alongside the failing check-run identity
|
|
198
|
+
alongside the failing check-run identity: the **failed** run of that
|
|
199
|
+
check, never a same-name green run from another workflow run on the head. On green it adjudicates:
|
|
178
200
|
|
|
179
201
|
- **Same head SHA, with a recorded allowance** → the one rerun the section
|
|
180
202
|
above buys. The digest is retired (spending the allowance), auto-merge is
|
|
@@ -183,7 +205,9 @@ alongside the failing check-run identity. On green it adjudicates:
|
|
|
183
205
|
job. The watcher exits non-zero, flips the Story to `agent::blocked` with a
|
|
184
206
|
`friction` comment, and requires the CI-gap intake issue
|
|
185
207
|
(`file-ci-gap.js` — run link and failure signature are already in the
|
|
186
|
-
digest) before the delivery proceeds.
|
|
208
|
+
digest) before the delivery proceeds. When the green came from a fresh run
|
|
209
|
+
an operator-approved label started, record `--verdict governance-label`
|
|
210
|
+
instead (§ Governance-label recovery).
|
|
187
211
|
- **New head SHA** → fix at source. The digest is retired, auto-merge is
|
|
188
212
|
re-armed, and the delivery continues unobstructed.
|
|
189
213
|
- **Same head SHA, every recorded failure advisory, each now green**
|
|
@@ -710,6 +710,12 @@
|
|
|
710
710
|
"maximum": 7200000,
|
|
711
711
|
"description": "Kill bound (ms) for one full-suite run — the coverage capture, the close-validation full-suite gate and the full-suite lock-wait budget all read it. The clock starts at spawn, never while queued on the host lock; a suite that signals `MANDREL_SUITE_READY_FILE` gets a fresh bound for its test phase, so worst-case wall is lock wait + 2 × timeoutMs. On expiry the run exits 124 so callers can tell a hang from a failure.",
|
|
712
712
|
"default": 600000
|
|
713
|
+
},
|
|
714
|
+
"onOverBudget": {
|
|
715
|
+
"type": "string",
|
|
716
|
+
"enum": ["block", "defer-to-ci"],
|
|
717
|
+
"description": "What handoff and close do when the capture script exits 76 — the consumer-declared signal that the selected slice is over this host's budget and no test ran. `block` (default) stops the handoff (`blocked`) and fails close, naming this key. `defer-to-ci` settles the coverage gate as deferred to CI: no artifact is written or stamped and no credit is recorded, the coverage-reading gates (CRAP preview, coverage and CRAP baselines) are skipped, and handoff and close proceed — the terminal envelope and the PR body say coverage was deferred. Set it only when the consumer's CI runs the deferred suite with a coverage floor. A timeout (124) is never deferred, under either value.",
|
|
718
|
+
"default": "block"
|
|
713
719
|
}
|
|
714
720
|
},
|
|
715
721
|
"additionalProperties": false
|
|
@@ -288,6 +288,34 @@
|
|
|
288
288
|
"scope": "cumulative",
|
|
289
289
|
"substitutionKeys": []
|
|
290
290
|
},
|
|
291
|
+
"audit-state-machines": {
|
|
292
|
+
"triggers": {
|
|
293
|
+
"gates": ["gate1", "gate3"],
|
|
294
|
+
"keywords": [
|
|
295
|
+
"state machine",
|
|
296
|
+
"state transition",
|
|
297
|
+
"lifecycle",
|
|
298
|
+
"impossible state",
|
|
299
|
+
"illegal state",
|
|
300
|
+
"discriminated union",
|
|
301
|
+
"tagged union",
|
|
302
|
+
"exhaustive",
|
|
303
|
+
"isLoading"
|
|
304
|
+
],
|
|
305
|
+
"filePatterns": [
|
|
306
|
+
"**/*.{js,mjs,cjs,jsx,ts,tsx}",
|
|
307
|
+
"**/*.py",
|
|
308
|
+
"**/*.go",
|
|
309
|
+
"**/*.rs",
|
|
310
|
+
"**/*.java",
|
|
311
|
+
"**/*.kt",
|
|
312
|
+
"**/*.swift",
|
|
313
|
+
"**/*.rb"
|
|
314
|
+
]
|
|
315
|
+
},
|
|
316
|
+
"scope": "cumulative",
|
|
317
|
+
"substitutionKeys": []
|
|
318
|
+
},
|
|
291
319
|
"audit-documentation": {
|
|
292
320
|
"triggers": {
|
|
293
321
|
"gates": ["gate1", "gate3"],
|
|
@@ -77,10 +77,17 @@
|
|
|
77
77
|
},
|
|
78
78
|
"gates": {
|
|
79
79
|
"type": "object",
|
|
80
|
-
"description": "Outcome of each close gate this invocation was responsible for. A gate the run skipped (--skip-validation, or a phase it never reached) reports \"skipped\" rather than being omitted, so a missing gate is never mistaken for a passing one. \"overridden\" is distinct from both: the gate ran, it FAILED, and an operator authorized delivery anyway via --override-review-block with a recorded reason. Reporting that as \"passed\" would erase the one fact a reader of this envelope most needs, and reporting it as \"skipped\" would claim the gate never ran. \"degraded\" (codeReview only, Story #5663) means a review surface ran but produced no verdict (CLI not logged in, out of quota, unparseable output); it is reported, not blocking, and ranks below \"overridden\".",
|
|
80
|
+
"description": "Outcome of each close gate this invocation was responsible for. A gate the run skipped (--skip-validation, or a phase it never reached) reports \"skipped\" rather than being omitted, so a missing gate is never mistaken for a passing one. \"overridden\" is distinct from both: the gate ran, it FAILED, and an operator authorized delivery anyway via --override-review-block with a recorded reason. Reporting that as \"passed\" would erase the one fact a reader of this envelope most needs, and reporting it as \"skipped\" would claim the gate never ran. \"degraded\" (codeReview only, Story #5663) means a review surface ran but produced no verdict (CLI not logged in, out of quota, unparseable output); it is reported, not blocking, and ranks below \"overridden\". \"deferred\" (coverage-capture only, Story #5949) means the capture script declared its slice over this host's budget (exit 76) under coverage.onOverBudget: defer-to-ci — no suite ran, the coverage-reading gates report \"skipped\", and CI owns the run.",
|
|
81
81
|
"additionalProperties": {
|
|
82
82
|
"type": "string",
|
|
83
|
-
"enum": [
|
|
83
|
+
"enum": [
|
|
84
|
+
"passed",
|
|
85
|
+
"failed",
|
|
86
|
+
"skipped",
|
|
87
|
+
"overridden",
|
|
88
|
+
"degraded",
|
|
89
|
+
"deferred"
|
|
90
|
+
]
|
|
84
91
|
}
|
|
85
92
|
},
|
|
86
93
|
"tail": {
|
|
@@ -14,7 +14,9 @@
|
|
|
14
14
|
* it also refused the depositing run, leaving no path that could deposit.
|
|
15
15
|
*
|
|
16
16
|
* Exit codes: 0 fresh/skipped/captured; 1 capture failed or refused (callers
|
|
17
|
-
* MUST surface it); 75 lock wait expired, nothing spawned;
|
|
17
|
+
* MUST surface it); 75 lock wait expired, nothing spawned; 76 the capture
|
|
18
|
+
* script declared its slice over this host's budget, nothing ran or was
|
|
19
|
+
* stamped (callers settle it by `coverage.onOverBudget`); 124 suite timed out.
|
|
18
20
|
*/
|
|
19
21
|
import { getChangedFiles } from './lib/changed-files.js';
|
|
20
22
|
import { isDirectInvocation } from './lib/cli-utils.js';
|
|
@@ -4,6 +4,8 @@
|
|
|
4
4
|
* delivery's to fix, files (or updates, by fingerprint) an intake issue in
|
|
5
5
|
* the owning repo, comments `friction` on the Story, and optionally blocks it.
|
|
6
6
|
* It files intake, never a Story, so delivery never blocks on planning.
|
|
7
|
+
* `governance-label` is the one non-filing verdict: an audited recovery for
|
|
8
|
+
* a fresh green run an operator-approved label started on the red head.
|
|
7
9
|
*/
|
|
8
10
|
|
|
9
11
|
import { parseArgs } from 'node:util';
|
|
@@ -16,6 +18,7 @@ import {
|
|
|
16
18
|
updateFollowUpIssue,
|
|
17
19
|
} from './lib/feedback-loop/graduator-core.js';
|
|
18
20
|
import { issueNumberFromUrl } from './lib/feedback-loop/retro-proposals-graduator.js';
|
|
21
|
+
import { runGh } from './lib/gh-exec.js';
|
|
19
22
|
import {
|
|
20
23
|
resolveOwnershipRepos,
|
|
21
24
|
routeOwnership,
|
|
@@ -27,9 +30,10 @@ import {
|
|
|
27
30
|
REFUSED_VERDICT,
|
|
28
31
|
} from './lib/orchestration/ci-gap-intake.js';
|
|
29
32
|
import {
|
|
30
|
-
|
|
33
|
+
GOVERNANCE_LABEL_VERDICT,
|
|
31
34
|
readCiDigest,
|
|
32
35
|
recordRerunAllowance,
|
|
36
|
+
resolvePassingCheckRun,
|
|
33
37
|
} from './lib/orchestration/ci-rerun-guard.js';
|
|
34
38
|
import {
|
|
35
39
|
STATE_LABELS,
|
|
@@ -40,7 +44,7 @@ import { createProvider } from './lib/provider-factory.js';
|
|
|
40
44
|
|
|
41
45
|
const USAGE = {
|
|
42
46
|
invocation:
|
|
43
|
-
'node .agents/scripts/file-ci-gap.js --story <id> --verdict <verdict> --owner <bucket> [--evidence "<proof reading>"] [--pr <n>] [--block] [--dry-run]',
|
|
47
|
+
'node .agents/scripts/file-ci-gap.js --story <id> --verdict <verdict> --owner <bucket> [--evidence "<proof reading>"] [--pr <n>] [--block] [--dry-run]\n node .agents/scripts/file-ci-gap.js --story <id> --verdict governance-label --label <name> [--pr <n>] [--dry-run]',
|
|
44
48
|
summary:
|
|
45
49
|
'File (or update) the CI-gap intake issue for an Option-2 verdict in .agents/rules/ci-remediation.md, routed to the repository that owns the fault and deduped by failure signature.',
|
|
46
50
|
flags: [
|
|
@@ -50,7 +54,11 @@ const USAGE = {
|
|
|
50
54
|
],
|
|
51
55
|
[
|
|
52
56
|
'--verdict <verdict>',
|
|
53
|
-
`One of ${INTAKE_VERDICTS.join(' | ')}. "${REFUSED_VERDICT}" is refused: it routes to Option 1, fix at source.
|
|
57
|
+
`One of ${INTAKE_VERDICTS.join(' | ')} | ${GOVERNANCE_LABEL_VERDICT}. "${REFUSED_VERDICT}" is refused: it routes to Option 1, fix at source. capacity / unreproducible-tier also record the one-rerun allowance on the CI digest. ${GOVERNANCE_LABEL_VERDICT} files nothing: it proves --label was added after the red and records the allowance for that fresh run.`,
|
|
58
|
+
],
|
|
59
|
+
[
|
|
60
|
+
'--label <name>',
|
|
61
|
+
`The operator-approved governance label (${GOVERNANCE_LABEL_VERDICT} only).`,
|
|
54
62
|
],
|
|
55
63
|
[
|
|
56
64
|
'--owner <bucket>',
|
|
@@ -60,7 +68,10 @@ const USAGE = {
|
|
|
60
68
|
'--evidence <text>',
|
|
61
69
|
"The verdict's proof reading (the exhausted-limit log line, the failed attach). Recorded in the body.",
|
|
62
70
|
],
|
|
63
|
-
[
|
|
71
|
+
[
|
|
72
|
+
'--pr <n>',
|
|
73
|
+
'PR number the red check ran on; recorded as an occurrence. Defaults to the digest PR.',
|
|
74
|
+
],
|
|
64
75
|
[
|
|
65
76
|
'--block',
|
|
66
77
|
'Also flip the Story to agent::blocked. Without it the friction comment is posted but the Story is left where it is.',
|
|
@@ -166,6 +177,18 @@ function renderRerunLine(rerunAllowance) {
|
|
|
166
177
|
: 'This verdict does **not** license a re-run of the failed job.';
|
|
167
178
|
}
|
|
168
179
|
|
|
180
|
+
/** The injected digest, else the Story's on-disk one; throws when absent. */
|
|
181
|
+
function loadCiDigest({ sid, digest, digestRoot, cwd }) {
|
|
182
|
+
const ciDigest =
|
|
183
|
+
digest ?? readCiDigest({ storyId: sid, tempRoot: digestRoot, cwd });
|
|
184
|
+
if (!ciDigest) {
|
|
185
|
+
throw new Error(
|
|
186
|
+
`no CI digest for Story #${sid}. The digest is written by \`pr-watch-with-update.js --story ${sid}\` on the first red; without it there is no run link or failure signature to file.`,
|
|
187
|
+
);
|
|
188
|
+
}
|
|
189
|
+
return ciDigest;
|
|
190
|
+
}
|
|
191
|
+
|
|
169
192
|
/**
|
|
170
193
|
* @param {object} opts
|
|
171
194
|
* @returns {Promise<object>}
|
|
@@ -186,6 +209,9 @@ export async function runFileCiGap({
|
|
|
186
209
|
cwd = process.cwd(),
|
|
187
210
|
logger = Logger,
|
|
188
211
|
now,
|
|
212
|
+
label = null,
|
|
213
|
+
labelHistoryFn = readPrLabelHistory,
|
|
214
|
+
greenRunFn = resolvePassingCheckRun,
|
|
189
215
|
} = {}) {
|
|
190
216
|
const sid = Number(storyId);
|
|
191
217
|
if (!Number.isInteger(sid) || sid <= 0) {
|
|
@@ -194,12 +220,22 @@ export async function runFileCiGap({
|
|
|
194
220
|
const resolved = config ?? resolveConfig();
|
|
195
221
|
// Must resolve exactly as `pr-watch-with-update.js` does when writing it.
|
|
196
222
|
const digestRoot = tempRoot ?? resolved?.project?.paths?.tempRoot ?? 'temp';
|
|
197
|
-
const ciDigest =
|
|
198
|
-
|
|
199
|
-
if (
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
223
|
+
const ciDigest = loadCiDigest({ sid, digest, digestRoot, cwd });
|
|
224
|
+
|
|
225
|
+
if (verdict === GOVERNANCE_LABEL_VERDICT) {
|
|
226
|
+
return runGovernanceRecovery({
|
|
227
|
+
sid,
|
|
228
|
+
label,
|
|
229
|
+
prNumber,
|
|
230
|
+
digest: ciDigest,
|
|
231
|
+
digestRoot,
|
|
232
|
+
cwd,
|
|
233
|
+
dryRun,
|
|
234
|
+
provider,
|
|
235
|
+
config: resolved,
|
|
236
|
+
labelHistoryFn,
|
|
237
|
+
greenRunFn,
|
|
238
|
+
});
|
|
203
239
|
}
|
|
204
240
|
|
|
205
241
|
const repos = resolveOwnershipRepos(resolved);
|
|
@@ -273,6 +309,178 @@ export async function runFileCiGap({
|
|
|
273
309
|
return { storyId: sid, verdict, ...result, actions, rerunAllowance };
|
|
274
310
|
}
|
|
275
311
|
|
|
312
|
+
/** Parsed JSON of a `gh api` read; `null` on a failed or unparseable one. */
|
|
313
|
+
function readGhApi(args, cwd) {
|
|
314
|
+
const res = runGh(['api', ...args], { cwd });
|
|
315
|
+
if ((res?.status ?? 1) !== 0) return null;
|
|
316
|
+
try {
|
|
317
|
+
return JSON.parse((res.stdout ?? '').trim() || 'null');
|
|
318
|
+
} catch {
|
|
319
|
+
return null;
|
|
320
|
+
}
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
/**
|
|
324
|
+
* The PR's current label names and every issue event; `null` when a read
|
|
325
|
+
* fails (the recovery then refuses).
|
|
326
|
+
*
|
|
327
|
+
* @returns {{ labels: string[], events: object[] } | null}
|
|
328
|
+
*/
|
|
329
|
+
function readPrLabelHistory({ prNumber, cwd }) {
|
|
330
|
+
const labels = readGhApi(
|
|
331
|
+
[`repos/{owner}/{repo}/issues/${prNumber}/labels?per_page=100`],
|
|
332
|
+
cwd,
|
|
333
|
+
);
|
|
334
|
+
const pages = readGhApi(
|
|
335
|
+
[
|
|
336
|
+
'--paginate',
|
|
337
|
+
'--slurp',
|
|
338
|
+
`repos/{owner}/{repo}/issues/${prNumber}/events?per_page=100`,
|
|
339
|
+
],
|
|
340
|
+
cwd,
|
|
341
|
+
);
|
|
342
|
+
if (!Array.isArray(labels) || !Array.isArray(pages)) return null;
|
|
343
|
+
return {
|
|
344
|
+
labels: labels.map((l) => l?.name).filter(Boolean),
|
|
345
|
+
events: pages.flat(),
|
|
346
|
+
};
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
/**
|
|
350
|
+
* The newest `labeled` event for `label` after `since`, while the label is
|
|
351
|
+
* still on the PR; `null` when the transition is unproven.
|
|
352
|
+
*
|
|
353
|
+
* @returns {{ label: string, actor: string|null, labeledAt: string } | null}
|
|
354
|
+
*/
|
|
355
|
+
export function proveLabelTransition({ history, label, since }) {
|
|
356
|
+
const sinceMs = Date.parse(since ?? '');
|
|
357
|
+
if (!history || !Number.isFinite(sinceMs)) return null;
|
|
358
|
+
if (!history.labels.includes(label)) return null;
|
|
359
|
+
const hits = history.events.filter(
|
|
360
|
+
(e) =>
|
|
361
|
+
e?.event === 'labeled' &&
|
|
362
|
+
e?.label?.name === label &&
|
|
363
|
+
Date.parse(e?.created_at ?? '') > sinceMs,
|
|
364
|
+
);
|
|
365
|
+
const latest = hits.sort(
|
|
366
|
+
(a, b) => Date.parse(b.created_at) - Date.parse(a.created_at),
|
|
367
|
+
)[0];
|
|
368
|
+
return latest
|
|
369
|
+
? {
|
|
370
|
+
label,
|
|
371
|
+
actor: latest.actor?.login ?? null,
|
|
372
|
+
labeledAt: latest.created_at,
|
|
373
|
+
}
|
|
374
|
+
: null;
|
|
375
|
+
}
|
|
376
|
+
|
|
377
|
+
/**
|
|
378
|
+
* @param {{ digest: object, evidence: object }} opts
|
|
379
|
+
* @returns {string}
|
|
380
|
+
*/
|
|
381
|
+
export function renderGovernanceComment({ digest, evidence }) {
|
|
382
|
+
const red = digest?.runUrl ?? `run id ${digest?.runId ?? 'unresolved'}`;
|
|
383
|
+
const green =
|
|
384
|
+
evidence.greenRun?.url ??
|
|
385
|
+
`run id ${evidence.greenRun?.runId ?? 'unresolved'}`;
|
|
386
|
+
return [
|
|
387
|
+
`### CI recovery recorded — verdict \`${GOVERNANCE_LABEL_VERDICT}\``,
|
|
388
|
+
'',
|
|
389
|
+
`- **Failing check:** \`${digest?.failingCheck ?? 'unknown'}\``,
|
|
390
|
+
`- **Red run:** ${red}`,
|
|
391
|
+
`- **Green run:** ${green}`,
|
|
392
|
+
`- **Label:** \`${evidence.label}\` added by ${evidence.actor ? `@${evidence.actor}` : 'an unknown actor'} at ${evidence.labeledAt} (PR #${evidence.prNumber})`,
|
|
393
|
+
`- **Head SHA:** \`${digest?.headSha ?? 'unresolved'}\``,
|
|
394
|
+
'',
|
|
395
|
+
'An operator-approved governance label started a fresh run on the red head,',
|
|
396
|
+
'so **one** green on that head is admitted. No intake issue was filed: this',
|
|
397
|
+
'is a recovery, not a CI gap. A second red after it is real and routes to',
|
|
398
|
+
'Option 1.',
|
|
399
|
+
].join('\n');
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
/**
|
|
403
|
+
* `governance-label`: prove the label transition, record the allowance and
|
|
404
|
+
* post the audit comment. Throws (non-zero exit, nothing written) when the
|
|
405
|
+
* transition is unproven.
|
|
406
|
+
*
|
|
407
|
+
* @returns {Promise<object>}
|
|
408
|
+
*/
|
|
409
|
+
async function runGovernanceRecovery({
|
|
410
|
+
sid,
|
|
411
|
+
label,
|
|
412
|
+
prNumber: prFlag,
|
|
413
|
+
digest,
|
|
414
|
+
digestRoot,
|
|
415
|
+
cwd,
|
|
416
|
+
dryRun,
|
|
417
|
+
provider,
|
|
418
|
+
config,
|
|
419
|
+
labelHistoryFn,
|
|
420
|
+
greenRunFn,
|
|
421
|
+
}) {
|
|
422
|
+
const prNumber = prFlag ?? digest.prNumber ?? null;
|
|
423
|
+
if (!label) {
|
|
424
|
+
throw new Error(
|
|
425
|
+
`--verdict ${GOVERNANCE_LABEL_VERDICT} requires --label <name>: the operator-approved label that started the fresh run.`,
|
|
426
|
+
);
|
|
427
|
+
}
|
|
428
|
+
if (!prNumber) {
|
|
429
|
+
throw new Error('no PR number: pass --pr <n> (the digest records none).');
|
|
430
|
+
}
|
|
431
|
+
const proof = proveLabelTransition({
|
|
432
|
+
history: labelHistoryFn({ prNumber, cwd }),
|
|
433
|
+
label,
|
|
434
|
+
since: digest.generatedAt,
|
|
435
|
+
});
|
|
436
|
+
if (!proof) {
|
|
437
|
+
throw new Error(
|
|
438
|
+
`refused: PR #${prNumber} shows no \`labeled\` event for "${label}" after the red (${digest.generatedAt ?? 'unrecorded'}), or the label is no longer on it — nothing recorded.`,
|
|
439
|
+
);
|
|
440
|
+
}
|
|
441
|
+
const greenRun = greenRunFn({
|
|
442
|
+
prRef: String(prNumber),
|
|
443
|
+
checkName: digest.failingCheck,
|
|
444
|
+
cwd,
|
|
445
|
+
});
|
|
446
|
+
const evidence = { ...proof, prNumber, greenRun };
|
|
447
|
+
const body = renderGovernanceComment({ digest, evidence });
|
|
448
|
+
const result = {
|
|
449
|
+
storyId: sid,
|
|
450
|
+
verdict: GOVERNANCE_LABEL_VERDICT,
|
|
451
|
+
decision: dryRun ? 'dry-run' : 'recovered',
|
|
452
|
+
issue: null,
|
|
453
|
+
errors: [],
|
|
454
|
+
actions: { commented: false, blocked: false },
|
|
455
|
+
rerunAllowance: null,
|
|
456
|
+
evidence,
|
|
457
|
+
comment: body,
|
|
458
|
+
};
|
|
459
|
+
if (dryRun) return result;
|
|
460
|
+
result.rerunAllowance = recordRerunAllowance({
|
|
461
|
+
storyId: sid,
|
|
462
|
+
verdict: GOVERNANCE_LABEL_VERDICT,
|
|
463
|
+
tempRoot: digestRoot,
|
|
464
|
+
cwd,
|
|
465
|
+
evidence,
|
|
466
|
+
});
|
|
467
|
+
if (!result.rerunAllowance) {
|
|
468
|
+
throw new Error(
|
|
469
|
+
`could not record the allowance on the CI digest for Story #${sid}.`,
|
|
470
|
+
);
|
|
471
|
+
}
|
|
472
|
+
const ticketing = provider ?? createProvider(config);
|
|
473
|
+
if (ticketing) {
|
|
474
|
+
try {
|
|
475
|
+
await upsertStructuredComment(ticketing, sid, 'friction', body);
|
|
476
|
+
result.actions.commented = true;
|
|
477
|
+
} catch (err) {
|
|
478
|
+
result.errors.push(`friction comment failed: ${err?.message ?? err}`);
|
|
479
|
+
}
|
|
480
|
+
}
|
|
481
|
+
return result;
|
|
482
|
+
}
|
|
483
|
+
|
|
276
484
|
/**
|
|
277
485
|
* @returns {Promise<void>}
|
|
278
486
|
*/
|
|
@@ -285,6 +493,7 @@ async function main() {
|
|
|
285
493
|
owner: { type: 'string' },
|
|
286
494
|
evidence: { type: 'string' },
|
|
287
495
|
pr: { type: 'string' },
|
|
496
|
+
label: { type: 'string' },
|
|
288
497
|
block: { type: 'boolean', default: false },
|
|
289
498
|
'dry-run': { type: 'boolean', default: false },
|
|
290
499
|
},
|
|
@@ -298,6 +507,7 @@ async function main() {
|
|
|
298
507
|
prNumber: values.pr ? Number(values.pr) : null,
|
|
299
508
|
dryRun: values['dry-run'],
|
|
300
509
|
block: values.block,
|
|
510
|
+
label: values.label ?? null,
|
|
301
511
|
});
|
|
302
512
|
|
|
303
513
|
process.stdout.write(`${JSON.stringify(result)}\n`);
|
|
@@ -35,6 +35,8 @@ import {
|
|
|
35
35
|
* @property {{ reason: string }} [skip] - Pre-decided skip: recorded, never spawned.
|
|
36
36
|
* @property {Record<string, string>} [env] - Overlay merged over `process.env` for this gate's child only.
|
|
37
37
|
* @property {boolean} [lockEventChannel] - The child reports on close's lock-event channel.
|
|
38
|
+
* @property {boolean} [deferOnOverBudget] - An exit 76 defers to CI instead of failing.
|
|
39
|
+
* @property {boolean} [readsCoverageArtifact] - Skipped once the capture deferred.
|
|
38
40
|
* @property {{ cmd: string, args: string[] }} [evidenceIdentity] - Evidence argv, if not the spawned one.
|
|
39
41
|
* @property {{ scope: 'delta', since: string }} [evidenceNote]
|
|
40
42
|
* @property {string} [label]
|
|
@@ -89,6 +91,30 @@ function captureQuality(config) {
|
|
|
89
91
|
return resolveQuality({ gates: { crap, coverage } });
|
|
90
92
|
}
|
|
91
93
|
|
|
94
|
+
/**
|
|
95
|
+
* What a capture script's over-budget exit (76) means here and in the handoff.
|
|
96
|
+
*
|
|
97
|
+
* @param {object|undefined|null} config - Canonical resolved config.
|
|
98
|
+
* @returns {'block'|'defer-to-ci'}
|
|
99
|
+
*/
|
|
100
|
+
export function overBudgetPolicy(config) {
|
|
101
|
+
return captureQuality(config).coverage.onOverBudget;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/** @param {object|undefined|null} config @returns {{ deferOnOverBudget?: true }} */
|
|
105
|
+
function overBudgetFlag(config) {
|
|
106
|
+
return overBudgetPolicy(config) === 'defer-to-ci'
|
|
107
|
+
? { deferOnOverBudget: true }
|
|
108
|
+
: {};
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/** Skip reason for a gate that would read the artifact a deferral never wrote. */
|
|
112
|
+
export const COVERAGE_DEFERRED_SKIP_REASON = 'coverage-deferred-ci';
|
|
113
|
+
|
|
114
|
+
/** Shown when a capture exits 76 and the policy blocks. */
|
|
115
|
+
export const OVER_BUDGET_BLOCK_HINT =
|
|
116
|
+
'The capture script declared its slice over this host\'s budget (exit 76) and ran no tests. Run the delivery on a larger host, or — when CI runs the suite with a coverage floor — set `delivery.quality.gates.coverage.onOverBudget: "defer-to-ci"`.';
|
|
117
|
+
|
|
92
118
|
/**
|
|
93
119
|
* Coverage-capture registers when the coverage or CRAP gate is on AND the
|
|
94
120
|
* primary capture script exists (the coverage gate's `captureScript`, or an
|
|
@@ -235,6 +261,19 @@ function probeBaselinesGate({
|
|
|
235
261
|
* @param {{ decision: { register: boolean, hint?: string }, kinds: string[]|null, env: { BASELINE_REF: string }|null }} args
|
|
236
262
|
* @returns {Gate[]}
|
|
237
263
|
*/
|
|
264
|
+
/**
|
|
265
|
+
* The unsplit gate (`null` kinds) scores every kind, coverage ones included.
|
|
266
|
+
*
|
|
267
|
+
* @param {string[]|null} gateKinds
|
|
268
|
+
* @returns {{ readsCoverageArtifact?: true }}
|
|
269
|
+
*/
|
|
270
|
+
function coverageReaderFlag(gateKinds) {
|
|
271
|
+
const reads =
|
|
272
|
+
gateKinds === null ||
|
|
273
|
+
gateKinds.some((k) => COVERAGE_CONSUMING_KINDS.has(k));
|
|
274
|
+
return reads ? { readsCoverageArtifact: true } : {};
|
|
275
|
+
}
|
|
276
|
+
|
|
238
277
|
function buildBaselinesGateEntries({ decision, kinds, env }) {
|
|
239
278
|
if (!decision.register) return [];
|
|
240
279
|
const entry = (name, gateKinds) => ({
|
|
@@ -248,6 +287,7 @@ function buildBaselinesGateEntries({ decision, kinds, env }) {
|
|
|
248
287
|
],
|
|
249
288
|
hint: decision.hint ?? CHECK_BASELINES_HINT,
|
|
250
289
|
...(env ? { env } : {}),
|
|
290
|
+
...coverageReaderFlag(gateKinds),
|
|
251
291
|
});
|
|
252
292
|
if (!Array.isArray(kinds) || kinds.length === 0) {
|
|
253
293
|
return [entry(BASELINES_GATE_NAMES.single, null)];
|
|
@@ -401,6 +441,12 @@ export const QUALITY_PREVIEW_GATE_NAMES = Object.freeze({
|
|
|
401
441
|
crap: 'quality-preview-crap',
|
|
402
442
|
});
|
|
403
443
|
|
|
444
|
+
/** The CRAP half reads the coverage artifact; the MI half does not. */
|
|
445
|
+
const PREVIEW_ARTIFACT_FLAGS = Object.freeze({
|
|
446
|
+
maintainability: {},
|
|
447
|
+
crap: { readsCoverageArtifact: true },
|
|
448
|
+
});
|
|
449
|
+
|
|
404
450
|
const QUALITY_PREVIEW_HINTS = Object.freeze({
|
|
405
451
|
maintainability:
|
|
406
452
|
'Maintainability preview failed — the per-file MI check the `pre-push` hook runs, scored against the base branch. Simplify the flagged file(s), then re-run close; this gate runs before coverage-capture, so no suite was spent.',
|
|
@@ -430,6 +476,7 @@ function buildQualityPreviewGateEntries({ coverageCaptureActive, baseBranch }) {
|
|
|
430
476
|
ref,
|
|
431
477
|
],
|
|
432
478
|
hint: QUALITY_PREVIEW_HINTS[half],
|
|
479
|
+
...PREVIEW_ARTIFACT_FLAGS[half],
|
|
433
480
|
},
|
|
434
481
|
];
|
|
435
482
|
return {
|
|
@@ -564,6 +611,7 @@ export function buildDefaultGates({
|
|
|
564
611
|
args: [...COVERAGE_CAPTURE_ARGS],
|
|
565
612
|
hint: coverageCaptureHint(config),
|
|
566
613
|
lockEventChannel: true,
|
|
614
|
+
...overBudgetFlag(config),
|
|
567
615
|
...(captureSkipPredicted
|
|
568
616
|
? { skip: { reason: 'incremental-no-crap-changes' } }
|
|
569
617
|
: {}),
|