mandrel 2.106.0 → 2.107.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.
Files changed (35) hide show
  1. package/.agents/docs/configuration.md +3 -0
  2. package/.agents/schemas/agentrc.schema.json +38 -0
  3. package/.agents/schemas/story-deliver-terminal.schema.json +4 -0
  4. package/.agents/scripts/lib/audit-suite/selector.js +13 -5
  5. package/.agents/scripts/lib/audit-suite/sensitive-paths.js +39 -0
  6. package/.agents/scripts/lib/config-settings-schema-quality.js +31 -0
  7. package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
  8. package/.agents/scripts/lib/observability/metrics-ledger.js +1 -1
  9. package/.agents/scripts/lib/observability/review-dispositions.js +208 -0
  10. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  11. package/.agents/scripts/lib/orchestration/code-review.js +77 -13
  12. package/.agents/scripts/lib/orchestration/review-deposit.js +2 -0
  13. package/.agents/scripts/lib/orchestration/review-depth.js +9 -3
  14. package/.agents/scripts/lib/orchestration/review-history.js +182 -0
  15. package/.agents/scripts/lib/orchestration/review-providers/callers-context.js +22 -2
  16. package/.agents/scripts/lib/orchestration/review-providers/claim-grounding.js +5 -4
  17. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +12 -0
  18. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +15 -8
  19. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +26 -5
  20. package/.agents/scripts/lib/orchestration/review-providers/codex.js +4 -2
  21. package/.agents/scripts/lib/orchestration/review-providers/critical-verifier.js +357 -0
  22. package/.agents/scripts/lib/orchestration/review-providers/finding-identity.js +53 -0
  23. package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js +85 -15
  24. package/.agents/scripts/lib/orchestration/review-providers/parse-findings.js +40 -1
  25. package/.agents/scripts/lib/orchestration/review-providers/review-guidance.js +68 -0
  26. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +25 -10
  27. package/.agents/scripts/lib/orchestration/review-providers/types.js +6 -0
  28. package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js +3 -0
  29. package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +14 -2
  30. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +1 -0
  31. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-override.js +24 -1
  32. package/.agents/scripts/review-dispositions-report.js +129 -0
  33. package/.agents/workflows/helpers/code-review.md +53 -0
  34. package/docs/CHANGELOG.md +15 -0
  35. package/package.json +1 -1
@@ -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,21 @@ 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.107.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.106.0...mandrel-v2.107.0) (2026-10-27)
19
+
20
+
21
+ ### Added
22
+
23
+ * 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))
24
+ * 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))
25
+ * 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))
26
+ * 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))
27
+
28
+
29
+ ### Fixed
30
+
31
+ * held review: &lt;callers&gt; 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))
32
+
18
33
  ## [2.106.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.105.0...mandrel-v2.106.0) (2026-10-26)
19
34
 
20
35
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.106.0",
3
+ "version": "2.107.0",
4
4
  "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
5
5
  "files": [
6
6
  ".agents/",