mandrel 2.106.0 → 2.108.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/docs/configuration.md +32 -0
- package/.agents/schemas/agentrc.schema.json +38 -0
- package/.agents/schemas/story-deliver-terminal.schema.json +4 -0
- package/.agents/scripts/evidence-gate.js +2 -2
- package/.agents/scripts/lib/audit-suite/selector.js +13 -5
- package/.agents/scripts/lib/audit-suite/sensitive-paths.js +39 -0
- package/.agents/scripts/lib/close-validation/process.js +1 -1
- package/.agents/scripts/lib/config-settings-schema-quality.js +31 -0
- package/.agents/scripts/lib/full-suite-lock.js +81 -8
- package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
- package/.agents/scripts/lib/observability/metrics-ledger.js +1 -1
- package/.agents/scripts/lib/observability/review-dispositions.js +208 -0
- package/.agents/scripts/lib/observability/source-classifier.js +1 -0
- package/.agents/scripts/lib/orchestration/code-review.js +77 -13
- package/.agents/scripts/lib/orchestration/review-deposit.js +2 -0
- package/.agents/scripts/lib/orchestration/review-depth.js +9 -3
- package/.agents/scripts/lib/orchestration/review-history.js +182 -0
- package/.agents/scripts/lib/orchestration/review-providers/callers-context.js +22 -2
- package/.agents/scripts/lib/orchestration/review-providers/claim-grounding.js +5 -4
- package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +12 -0
- package/.agents/scripts/lib/orchestration/review-providers/code-review.js +15 -8
- package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +26 -5
- package/.agents/scripts/lib/orchestration/review-providers/codex.js +4 -2
- package/.agents/scripts/lib/orchestration/review-providers/critical-verifier.js +357 -0
- package/.agents/scripts/lib/orchestration/review-providers/finding-identity.js +53 -0
- package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js +85 -15
- package/.agents/scripts/lib/orchestration/review-providers/parse-findings.js +40 -1
- package/.agents/scripts/lib/orchestration/review-providers/review-guidance.js +68 -0
- package/.agents/scripts/lib/orchestration/review-providers/security-review.js +25 -10
- package/.agents/scripts/lib/orchestration/review-providers/types.js +6 -0
- package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js +3 -0
- package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +14 -2
- package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +1 -0
- package/.agents/scripts/lib/orchestration/single-story-close/phases/review-override.js +24 -1
- package/.agents/scripts/lib/suite-admission.js +45 -3
- package/.agents/scripts/review-dispositions-report.js +129 -0
- package/.agents/workflows/helpers/code-review.md +53 -0
- package/docs/CHANGELOG.md +22 -0
- package/package.json +1 -1
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* review-dispositions-report.js — summarize the local review-dispositions
|
|
5
|
+
* ledger: per provider and per severity, the count and rate of each
|
|
6
|
+
* disposition, plus the precision and false-blocker proxies. Read-only;
|
|
7
|
+
* exits 0 on an empty or absent ledger.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import { parseArgs } from 'node:util';
|
|
11
|
+
|
|
12
|
+
import { runAsCli } from './lib/cli-utils.js';
|
|
13
|
+
import { resolveConfig } from './lib/config-resolver.js';
|
|
14
|
+
import {
|
|
15
|
+
DISPOSITIONS,
|
|
16
|
+
readDispositions,
|
|
17
|
+
summarizeDispositions,
|
|
18
|
+
} from './lib/observability/review-dispositions.js';
|
|
19
|
+
|
|
20
|
+
const USAGE = {
|
|
21
|
+
invocation:
|
|
22
|
+
'node .agents/scripts/review-dispositions-report.js [--since <YYYY-MM-DD>] [--json]',
|
|
23
|
+
summary:
|
|
24
|
+
'Summarize the review-dispositions ledger (<tempRoot>/review-dispositions.ndjson): count and rate of each disposition per provider and per severity, with precision ((fixed-on-branch + open-at-merge) / all) and false-blocker ((overridden + refuted-by-verifier + downgraded-ungrounded) / criticals) proxies.',
|
|
25
|
+
flags: [
|
|
26
|
+
['--since <YYYY-MM-DD>', 'Only records written on or after this date.'],
|
|
27
|
+
['--json', 'Emit the summary as JSON instead of a table.'],
|
|
28
|
+
],
|
|
29
|
+
};
|
|
30
|
+
|
|
31
|
+
const DATE = /^\d{4}-\d{2}-\d{2}$/;
|
|
32
|
+
|
|
33
|
+
/** @param {number|null} r */
|
|
34
|
+
const pct = (r) => (r === null ? '-' : `${(r * 100).toFixed(1)}%`);
|
|
35
|
+
|
|
36
|
+
/** @param {string} label @param {Record<string, object>} groups */
|
|
37
|
+
function renderTable(label, groups) {
|
|
38
|
+
const header = [label, 'total', ...DISPOSITIONS, 'precision', 'false-blk'];
|
|
39
|
+
const rows = Object.entries(groups).map(([key, t]) => [
|
|
40
|
+
key,
|
|
41
|
+
String(t.total),
|
|
42
|
+
...DISPOSITIONS.map((d) => `${t.counts[d]} (${pct(t.rates[d])})`),
|
|
43
|
+
pct(t.precision),
|
|
44
|
+
pct(t.falseBlocker),
|
|
45
|
+
]);
|
|
46
|
+
return alignRows([header, ...rows]).join('\n');
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** @param {string[][]} rows @returns {string[]} space-padded columns. */
|
|
50
|
+
function alignRows(rows) {
|
|
51
|
+
const widths = [];
|
|
52
|
+
for (const row of rows) {
|
|
53
|
+
row.forEach((cell, i) => {
|
|
54
|
+
widths[i] = Math.max(widths[i] ?? 0, cell.length);
|
|
55
|
+
});
|
|
56
|
+
}
|
|
57
|
+
return rows.map((row) =>
|
|
58
|
+
row
|
|
59
|
+
.map((cell, i) => cell.padEnd(widths[i]))
|
|
60
|
+
.join(' ')
|
|
61
|
+
.trimEnd(),
|
|
62
|
+
);
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* @param {string[]} [argv]
|
|
67
|
+
* @param {{
|
|
68
|
+
* resolveConfigImpl?: typeof resolveConfig,
|
|
69
|
+
* stdout?: { write: (s: string) => void },
|
|
70
|
+
* cwd?: string,
|
|
71
|
+
* }} [deps]
|
|
72
|
+
* @returns {Promise<object|null>} the summary, or null when nothing recorded.
|
|
73
|
+
*/
|
|
74
|
+
export async function runReviewDispositionsReport(
|
|
75
|
+
argv = process.argv.slice(2),
|
|
76
|
+
deps = {},
|
|
77
|
+
) {
|
|
78
|
+
const {
|
|
79
|
+
resolveConfigImpl = resolveConfig,
|
|
80
|
+
stdout = process.stdout,
|
|
81
|
+
cwd = process.cwd(),
|
|
82
|
+
} = deps;
|
|
83
|
+
const { values } = parseArgs({
|
|
84
|
+
args: argv,
|
|
85
|
+
options: { since: { type: 'string' }, json: { type: 'boolean' } },
|
|
86
|
+
});
|
|
87
|
+
if (values.since !== undefined && !DATE.test(values.since)) {
|
|
88
|
+
throw new Error(
|
|
89
|
+
`review-dispositions-report: --since must be YYYY-MM-DD (got "${values.since}").`,
|
|
90
|
+
);
|
|
91
|
+
}
|
|
92
|
+
const config = resolveConfigImpl({ cwd });
|
|
93
|
+
const records = await readDispositions({
|
|
94
|
+
config,
|
|
95
|
+
since: values.since ?? null,
|
|
96
|
+
});
|
|
97
|
+
if (records.length === 0) {
|
|
98
|
+
stdout.write('[review-dispositions-report] no dispositions recorded.\n');
|
|
99
|
+
return null;
|
|
100
|
+
}
|
|
101
|
+
const summary = summarizeDispositions(records);
|
|
102
|
+
if (values.json) {
|
|
103
|
+
stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
|
|
104
|
+
return summary;
|
|
105
|
+
}
|
|
106
|
+
stdout.write(
|
|
107
|
+
[
|
|
108
|
+
renderTable('provider', summary.byProvider),
|
|
109
|
+
'',
|
|
110
|
+
renderTable('severity', summary.bySeverity),
|
|
111
|
+
'',
|
|
112
|
+
renderTable('all', { all: summary.overall }),
|
|
113
|
+
'',
|
|
114
|
+
].join('\n'),
|
|
115
|
+
);
|
|
116
|
+
return summary;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
async function main() {
|
|
120
|
+
await runReviewDispositionsReport();
|
|
121
|
+
return 0;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
runAsCli(import.meta.url, main, {
|
|
125
|
+
source: 'review-dispositions-report',
|
|
126
|
+
propagateExitCode: true,
|
|
127
|
+
errorPrefix: '[review-dispositions-report] ❌ Fatal error',
|
|
128
|
+
usage: USAGE,
|
|
129
|
+
});
|
|
@@ -91,6 +91,55 @@ size, and there is no "review harder" knob a deterministic scorer can turn (its
|
|
|
91
91
|
module JSDoc documents this). When you (the host LLM) perform the Step 2 pillar
|
|
92
92
|
review yourself, honor the `depth` semantics above directly.
|
|
93
93
|
|
|
94
|
+
### Project review guidance and skip paths
|
|
95
|
+
|
|
96
|
+
A consumer tells the Story-scope reviewer what failure looks like in its own
|
|
97
|
+
codebase with a root `REVIEW.md`, or the file
|
|
98
|
+
`delivery.codeReview.guidanceFile` names. Keep it **short, project-specific
|
|
99
|
+
and evidence-required**: name the defect classes this codebase actually ships
|
|
100
|
+
(a retry loop without a bound, a query built without the tenant filter), each
|
|
101
|
+
with the file or pattern that shows it, and ask for proof rather than
|
|
102
|
+
suspicion. Generic advice the framework prompt already carries only dilutes it.
|
|
103
|
+
The review reads it once and renders it into every LLM provider's prompt
|
|
104
|
+
after the framework's severity and anti-gaming rules, under a fixed sentence:
|
|
105
|
+
guidance can add failure classes and paths worth skipping, but cannot lower a
|
|
106
|
+
severity rule, excuse a `shortcut:` comment, or change the output shape. Over
|
|
107
|
+
8,000 characters it is truncated and recorded as a degraded gate.
|
|
108
|
+
|
|
109
|
+
Prose cannot silence a finding. Only `delivery.codeReview.skipPaths`
|
|
110
|
+
(picomatch globs) drops findings, after grounding and verification and before
|
|
111
|
+
severity is counted; the report states how many were dropped.
|
|
112
|
+
|
|
113
|
+
### Bug classes, instances and repeats
|
|
114
|
+
|
|
115
|
+
Each LLM finding names its bug `class` and lists every `instances` location of
|
|
116
|
+
the same defect in the diff, rendered as one finding with an `Instances:`
|
|
117
|
+
list. Its stable id (class or category, first instance file, and for a
|
|
118
|
+
class-less finding its title; never a line number) rides a hidden
|
|
119
|
+
`<!-- finding:<id> -->` marker. A per-Story review history records every run;
|
|
120
|
+
a re-review renders a finding it already raised at an overlapping location
|
|
121
|
+
collapsed under **Previously raised**. A repeat still halts unless an operator
|
|
122
|
+
overrode that CRITICAL with `--override-review-block` earlier, in which case
|
|
123
|
+
it is downgraded to a suggestion.
|
|
124
|
+
|
|
125
|
+
### Review dispositions
|
|
126
|
+
|
|
127
|
+
When a Story lands, the post-land tail (before the temp purge reaps the
|
|
128
|
+
history) appends one record per finding id the Story's reviews raised to the
|
|
129
|
+
local, never-committed `<tempRoot>/review-dispositions.ndjson` (rotated at
|
|
130
|
+
1 MB, one `.1` generation kept). Precedence, with the last run as the final
|
|
131
|
+
review: `overridden` (an operator overrode it; the record carries the
|
|
132
|
+
redacted reason, clipped to 500 characters), `downgraded-ungrounded` and
|
|
133
|
+
`refuted-by-verifier` (flagged in the final run), `open-at-merge` (in the
|
|
134
|
+
final run otherwise), `fixed-on-branch` (raised earlier, absent from the
|
|
135
|
+
final run). A record holds ids, provider, severity, class and run count only,
|
|
136
|
+
never a title, body, path or excerpt; a Story already recorded appends
|
|
137
|
+
nothing. Summarize with
|
|
138
|
+
`node .agents/scripts/review-dispositions-report.js [--since <YYYY-MM-DD>] [--json]`:
|
|
139
|
+
per provider and severity, each disposition's count and rate, the precision
|
|
140
|
+
proxy (fixed-on-branch + open-at-merge over all) and the false-blocker proxy
|
|
141
|
+
(overridden + refuted + downgraded over all criticals).
|
|
142
|
+
|
|
94
143
|
## Step 0 — Resolve Context
|
|
95
144
|
|
|
96
145
|
1. Resolve `[TICKET_ID]` from `ticketId` (the Story for live `scope: story`).
|
|
@@ -350,6 +399,10 @@ Hard cutover per
|
|
|
350
399
|
[`rules/git-conventions.md`](../../rules/git-conventions.md) § Contract
|
|
351
400
|
Cutovers — no back-compat flag; `high` is opt-in to the old routing.
|
|
352
401
|
|
|
402
|
+
A finding with several `instances` is **one defect in several places**: it
|
|
403
|
+
counts as fixed only when every instance is fixed, so one fix round clears
|
|
404
|
+
the class.
|
|
405
|
+
|
|
353
406
|
### 🔴 / 🟠 findings — per-finding ceremony (unchanged)
|
|
354
407
|
|
|
355
408
|
For each 🔴 / 🟠 finding from Step 4, decide between two paths and keep the
|
package/docs/CHANGELOG.md
CHANGED
|
@@ -15,6 +15,28 @@ 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.108.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.107.0...mandrel-v2.108.0) (2026-10-27)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
### Added
|
|
22
|
+
|
|
23
|
+
* mark admitted suite spawns and export a self-admitting wrapper so hand-run consumer scripts cannot bypass or double-book suite admission ([#5929](https://github.com/dsj1984/mandrel/issues/5929)) ([#5930](https://github.com/dsj1984/mandrel/issues/5930)) ([ed43efc](https://github.com/dsj1984/mandrel/commit/ed43efcc573ac2171f1c59654b2c58bd8059761c))
|
|
24
|
+
|
|
25
|
+
## [2.107.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.106.0...mandrel-v2.107.0) (2026-10-27)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
### Added
|
|
29
|
+
|
|
30
|
+
* code review: consumer review guidance (REVIEW.md), bug-class findings with every instance, and no repeat findings ([#5920](https://github.com/dsj1984/mandrel/issues/5920)) ([#5925](https://github.com/dsj1984/mandrel/issues/5925)) ([120b8d3](https://github.com/dsj1984/mandrel/commit/120b8d3c88ba253550c7c5f1540643a6b51c10df))
|
|
31
|
+
* held review: an independent fresh-context verifier confirms each CRITICAL before it can halt ([#5919](https://github.com/dsj1984/mandrel/issues/5919)) ([#5923](https://github.com/dsj1984/mandrel/issues/5923)) ([d58f454](https://github.com/dsj1984/mandrel/commit/d58f454f1fd16906d1e13c5e41c9f91056279f40))
|
|
32
|
+
* review depth: let a consumer declare its own sensitive paths, merged over the shipped manifest ([#5917](https://github.com/dsj1984/mandrel/issues/5917)) ([#5922](https://github.com/dsj1984/mandrel/issues/5922)) ([ae22338](https://github.com/dsj1984/mandrel/commit/ae223384120ef4866716dec21bc08f5c8973974a))
|
|
33
|
+
* review dispositions: record what happened to every Story-scope finding, with per-provider and per-severity rates ([#5918](https://github.com/dsj1984/mandrel/issues/5918)) ([#5926](https://github.com/dsj1984/mandrel/issues/5926)) ([9afe0d6](https://github.com/dsj1984/mandrel/commit/9afe0d65d01b7dc6fb4fee8add6a743dde1524aa))
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
### Fixed
|
|
37
|
+
|
|
38
|
+
* held review: <callers> symbol extraction reads code only, never prose in strings, comments or docs ([#5927](https://github.com/dsj1984/mandrel/issues/5927)) ([#5928](https://github.com/dsj1984/mandrel/issues/5928)) ([70ef990](https://github.com/dsj1984/mandrel/commit/70ef990dc3ba408db95e47f2ad45d5362d86ad1c))
|
|
39
|
+
|
|
18
40
|
## [2.106.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.105.0...mandrel-v2.106.0) (2026-10-26)
|
|
19
41
|
|
|
20
42
|
|
package/package.json
CHANGED