mandrel 2.96.0 → 2.97.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 (27) hide show
  1. package/.agents/audit-checklists/policies.md +23 -0
  2. package/.agents/docs/agentrc-reference.json +2 -5
  3. package/.agents/docs/configuration.md +8 -6
  4. package/.agents/docs/workflows.md +2 -1
  5. package/.agents/schemas/agentrc.schema.json +46 -29
  6. package/.agents/schemas/audit-rules.json +32 -0
  7. package/.agents/schemas/audit-rules.schema.json +2 -2
  8. package/.agents/scripts/lib/audit-suite/selector.js +119 -27
  9. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  10. package/.agents/scripts/lib/baselines/duplication-scanner.js +44 -3
  11. package/.agents/scripts/lib/baselines/refresh-service.js +54 -14
  12. package/.agents/scripts/lib/config/explain.js +1 -7
  13. package/.agents/scripts/lib/config/gates/duplication.schema.js +12 -5
  14. package/.agents/scripts/lib/config-settings-schema-quality.js +0 -27
  15. package/.agents/scripts/lib/config-settings-schema.js +30 -0
  16. package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
  17. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +2 -14
  18. package/.agents/scripts/lib/orchestration/review-providers/generated-diff.js +61 -0
  19. package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +19 -4
  20. package/.agents/scripts/lib/source-extensions.js +3 -2
  21. package/.agents/workflows/audit-documentation.md +5 -0
  22. package/.agents/workflows/audit-policies.md +221 -0
  23. package/docs/CHANGELOG.md +9 -0
  24. package/lib/migrations/index.js +2 -0
  25. package/lib/migrations/steps/2.91.0-retire-duplication-formats.js +65 -9
  26. package/lib/migrations/steps/2.97.0-retire-quality-navigability.js +80 -0
  27. package/package.json +1 -1
@@ -30,11 +30,11 @@ import { gitSpawn } from '../../git-utils.js';
30
30
  import { PROJECT_ROOT } from '../../project-root.js';
31
31
  import { buildCallersSection } from './callers-context.js';
32
32
  import {
33
- clip,
34
33
  FINDINGS_SCHEMA_JSON,
35
34
  readAuthStatus,
36
35
  resolveVerdict,
37
36
  } from './claude-verdict.js';
37
+ import { readDiff } from './generated-diff.js';
38
38
  import { renderDepthDirective } from './review-depth.js';
39
39
  import { probeClaudeCli } from './security-review.js';
40
40
 
@@ -211,18 +211,6 @@ async function reviewInTempDir(prompt, deps) {
211
211
  }
212
212
  }
213
213
 
214
- /**
215
- * @returns {{ reason: string } | { text: string }}
216
- */
217
- function readDiff(gitSpawnFn, { baseRef, headRef }) {
218
- const range = `${baseRef}...${headRef}`;
219
- const diff = gitSpawnFn(PROJECT_ROOT, 'diff', '--no-color', range);
220
- if (diff.status === 0) return { text: diff.stdout };
221
- return {
222
- reason: `git diff ${range} failed: ${clip(diff.stderr) || '<no output>'}`,
223
- };
224
- }
225
-
226
214
  function assertCliPresent(probeFn) {
227
215
  if (probeFn()) return;
228
216
  throw new Error(
@@ -269,7 +257,7 @@ export function createCodeReviewProviderForRegistry(deps = {}) {
269
257
  async runReview(input) {
270
258
  degradations = [];
271
259
  assertInput(input);
272
- const diff = readDiff(gitSpawnFn, input);
260
+ const diff = readDiff(gitSpawnFn, input, PROJECT_ROOT);
273
261
  if ('reason' in diff) return settle(diff);
274
262
  if (diff.text.trim().length === 0) return [];
275
263
  const truncation = truncationReason(diff.text);
@@ -0,0 +1,61 @@
1
+ // Generated files reach the reviewer as a stub; their own --check gates hold them.
2
+
3
+ import { clip } from './claude-verdict.js';
4
+
5
+ function sectionPath(section) {
6
+ return /^diff --git a\/.+? b\/(.+)$/m.exec(section)?.[1] ?? null;
7
+ }
8
+
9
+ function generatedPaths(paths, { cwd, gitSpawnFn }) {
10
+ const generated = new Set();
11
+ if (paths.length === 0) return generated;
12
+ const result = gitSpawnFn(
13
+ cwd,
14
+ 'check-attr',
15
+ '-z',
16
+ 'linguist-generated',
17
+ '--',
18
+ ...paths,
19
+ );
20
+ if (result?.status !== 0) return generated;
21
+ const fields = String(result.stdout ?? '').split('\0');
22
+ for (let i = 0; i + 2 < fields.length; i += 3) {
23
+ if (fields[i + 2] === 'true' || fields[i + 2] === 'set') {
24
+ generated.add(fields[i]);
25
+ }
26
+ }
27
+ return generated;
28
+ }
29
+
30
+ /** A failed attribute lookup leaves the diff whole. */
31
+ function omitGeneratedFiles(diff, deps) {
32
+ const sections = diff.split(/(?=^diff --git )/m);
33
+ const generated = generatedPaths(
34
+ sections.map(sectionPath).filter(Boolean),
35
+ deps,
36
+ );
37
+ if (generated.size === 0) return { text: diff, omitted: [] };
38
+ const omitted = [];
39
+ const text = sections
40
+ .map((section) => {
41
+ const file = sectionPath(section);
42
+ if (!file || !generated.has(file)) return section;
43
+ omitted.push(file);
44
+ return `diff --git a/${file} b/${file}\n[generated file: changed, content omitted from review]\n`;
45
+ })
46
+ .join('');
47
+ return { text, omitted };
48
+ }
49
+
50
+ /**
51
+ * @returns {{ reason: string } | { text: string }}
52
+ */
53
+ export function readDiff(gitSpawnFn, { baseRef, headRef }, cwd) {
54
+ const range = `${baseRef}...${headRef}`;
55
+ const diff = gitSpawnFn(cwd, 'diff', '--no-color', range);
56
+ if (diff.status === 0)
57
+ return omitGeneratedFiles(diff.stdout, { cwd, gitSpawnFn });
58
+ return {
59
+ reason: `git diff ${range} failed: ${clip(diff.stderr) || '<no output>'}`,
60
+ };
61
+ }
@@ -90,17 +90,24 @@ function resolveScopeBase({ workTree, git, baseBranch }) {
90
90
  * Guards plus the scoped file list. A dirty baseline file would otherwise be
91
91
  * swept into the commit.
92
92
  *
93
- * @param {{ workTree: string, baseBranch: string, storyBranch: string, git: Function, relPath: string }} ctx
93
+ * @param {{ workTree: string, baseBranch: string, storyBranch: string, git: Function, relPath: string, additionalFormats?: string[] }} ctx
94
94
  * @returns {{ reason: string } | { files: string[] }}
95
95
  */
96
- function resolveScope({ workTree, baseBranch, storyBranch, git, relPath }) {
96
+ function resolveScope({
97
+ workTree,
98
+ baseBranch,
99
+ storyBranch,
100
+ git,
101
+ relPath,
102
+ additionalFormats,
103
+ }) {
97
104
  if (currentBranch(workTree, git) !== storyBranch) {
98
105
  return { reason: 'wrong-branch' };
99
106
  }
100
107
  if (listDirtyPaths(workTree, git).includes(relPath)) {
101
108
  return { reason: 'dirty-tree' };
102
109
  }
103
- const isScorable = fileFilterFor(KIND);
110
+ const isScorable = fileFilterFor(KIND, { additionalFormats });
104
111
  const files = listChangedFiles({
105
112
  cwd: workTree,
106
113
  baseBranch: resolveScopeBase({ workTree, git, baseBranch }),
@@ -209,7 +216,15 @@ export async function runDuplicationCloseRescore({
209
216
  const relPath = gate.value.baselinePath ?? DEFAULT_BASELINE_REL_PATH;
210
217
  const writePath = path.resolve(workTree, relPath);
211
218
  const scope = await attempt(
212
- () => resolveScope({ workTree, baseBranch, storyBranch, git, relPath }),
219
+ () =>
220
+ resolveScope({
221
+ workTree,
222
+ baseBranch,
223
+ storyBranch,
224
+ git,
225
+ relPath,
226
+ additionalFormats: gate.value.additionalFormats,
227
+ }),
213
228
  'git-failed',
214
229
  );
215
230
  if (scope.reason) return skip(logger, scope.reason);
@@ -3,7 +3,8 @@
3
3
  * coverage-freshness check, the refresh scope predicates, the close-time
4
4
  * CRAP/MI projections, native review and the duplication scanner's jscpd
5
5
  * formats must all agree: a narrower selector makes a gate green while
6
- * measuring nothing. Not configurable, for the same reason.
6
+ * measuring nothing. Not configurable, for the same reason; only duplication's
7
+ * `additionalFormats` may scan more.
7
8
  *
8
9
  * MUST import only `node:` builtins — it runs on the pre-push path and must
9
10
  * not drag the scoring engines in.
@@ -51,7 +52,7 @@ export function isScorableSourceFile(filePath) {
51
52
 
52
53
  /**
53
54
  * The jscpd formats covering the scorable list. Derived, never declared: the
54
- * duplication gate scans exactly the files the other gates score.
55
+ * duplication gate always scans the files the other gates score.
55
56
  *
56
57
  * @returns {string[]}
57
58
  */
@@ -34,6 +34,11 @@ union of:
34
34
  escape hatch for everything outside 1–3; there is no dedicated config
35
35
  key for it.
36
36
 
37
+ **The published policy corpus is excluded.** Files matched by
38
+ `project.policies.corpusGlobs`, or the conventional policy files when it is
39
+ unset, are audited by [`/audit-policies`](audit-policies.md) — their fix is a
40
+ decision, not an edit — and never enter this lens's target set.
41
+
37
42
  **Generated docs are excluded from per-doc semantic review.** The output of
38
43
  `generate-config-docs.js` and `generate-workflows-doc.js`, and the synced
39
44
  `.claude/commands/` mirrors, are generator-owned: hand-editing them is never
@@ -0,0 +1,221 @@
1
+ ---
2
+ description: >-
3
+ Audit a project's published customer-facing policies (Terms, Privacy, Cookie,
4
+ refund and cancellation, consent and waiver text) against what the code
5
+ actually does, in both directions — promises the system does not keep and
6
+ practices no policy discloses. Never edits policy text; every finding names a
7
+ decision.
8
+ ---
9
+
10
+ # Policy Consistency Audit
11
+
12
+ You are a Policy Consistency Reviewer checking that a project's **published
13
+ customer-facing policies** describe the system that actually ships. Drift runs
14
+ both ways: the text promises or states something the system does not do, or
15
+ the system does something the text omits or contradicts. This lens is the
16
+ AI-driven backstop behind a project's deterministic policy guards.
17
+
18
+ The shared lens machinery lives in
19
+ [`helpers/audit-lens-core.md`](helpers/audit-lens-core.md). Write the report to
20
+ `{{auditResultsDir}}/audit-policies-results.md`. Dimension values:
21
+ `Contradiction | Unbacked Promise | Undisclosed Practice | Stale Reference |
22
+ Internal Inconsistency | Unverifiable`. Extra finding fields: **Policy:**,
23
+ **Implementation:**, **Backing:** and **Direction:** (see Report additions).
24
+ The report adds a mandatory **Claims Coverage** section.
25
+
26
+ ## The invariant: this lens never edits policy text
27
+
28
+ Policy text is published and legally binding, so its fix is a **decision**, not
29
+ an edit. The core's read-only constraint applies as usual, and on top of it:
30
+
31
+ - Every finding's **Recommendation & Rationale** names the decision to be made
32
+ — "change the code to honor the text, or change the text to describe the
33
+ code" — and never drafts replacement wording.
34
+ - When [`/audit-to-stories`](audit-to-stories.md) turns a finding from this
35
+ report into a Story, that Story's **first acceptance criterion is a recorded
36
+ operator decision** on the finding's Direction. Say so in the finding's
37
+ Acceptance signal.
38
+ - The report carries this fixed line in its Executive Summary: "This audit
39
+ checks consistency between published text and implementation, not legal
40
+ adequacy, and is not legal advice."
41
+
42
+ ## Target set (config-driven union)
43
+
44
+ The target set is the **policy corpus**, built as the union of:
45
+
46
+ 1. **`project.policies.corpusGlobs`** from `.agentrc.json`, when configured.
47
+ 2. **Conventional policy files**, when `corpusGlobs` is unset: text files
48
+ (`.md`, `.mdx`, `.html`, `.htm`, `.astro`, `.txt`) under a `policies/` or
49
+ `legal/` directory, or whose basename carries an explicit policy compound
50
+ (`privacy-policy`, `cookie-policy`, `cookie-notice`, `refund-policy`,
51
+ `cancellation-policy`, `terms-of-service`, `terms-of-use`,
52
+ `terms-and-conditions`). A bare `privacy.md` is not a policy.
53
+ 3. **An explicit `--paths` override** — files the operator names on
54
+ invocation are added to the union.
55
+
56
+ A project with no corpus never reaches this lens: the `policies` target's
57
+ `hasPolicyCorpus()` probe in
58
+ [`lib/audit-suite/selector.js`](../scripts/lib/audit-suite/selector.js) drops
59
+ it from the roster, failing open when the probe is indeterminate.
60
+
61
+ Three more optional `project.policies` keys shape the run:
62
+
63
+ - `impactMap` — a repo-relative path to a JSON object mapping code globs to
64
+ arrays of policy paths. It focuses a fenced run (below).
65
+ - `backingDocs` — runbook or SOP globs. A claim honored by a documented manual
66
+ procedure is **backed**, not a finding.
67
+ - `acceptedFindings` — a repo-relative path to a JSON array of
68
+ `{ policy, quote, reason, reviewBy }` entries, `reviewBy` as `YYYY-MM-DD`
69
+ (see Step 3).
70
+
71
+ ## Scope (deviant — intersect with the target set)
72
+
73
+ This lens deviates from the shared change-set fence: it intersects the fence
74
+ with the policy corpus above.
75
+
76
+ ```text
77
+ {{changedFiles}}
78
+ ```
79
+
80
+ - If the block contains a newline-delimited list of file paths, audit only:
81
+ every policy whose `impactMap` globs match a changed file; every changed
82
+ policy file; and every policy sentence that names a symbol, route,
83
+ provider, setting or value the change set touches.
84
+ - If the block renders as the literal string `{{changedFiles}}` (no
85
+ substitution supplied), sweep the whole corpus.
86
+
87
+ ## Execution strategy
88
+
89
+ Run this lens as one `subagent_type: auditor` dispatch per the core's
90
+ Execution strategy. Fan out per policy only when the operator's invocation
91
+ asks for it: a full sweep of a large corpus is expensive (the review that
92
+ motivated this lens spent about 500k tokens on 41 documents).
93
+
94
+ ## Step 1: Deterministic signals first
95
+
96
+ Before reading any claim closely, collect the signals a grep can settle:
97
+
98
+ 1. **Unresolved cross-references** — a policy that refers to another policy,
99
+ section or document that does not resolve inside the corpus.
100
+ 2. **Absent referenced documents** — a document a policy points readers to
101
+ (a protocol, a form, a schedule) that is not in the corpus or the site.
102
+ 3. **Contact drift** — email addresses, phone numbers or postal addresses
103
+ that differ across the corpus.
104
+ 4. **Money literals** — literal numbers beside refund, cancellation, fee or
105
+ deposit wording. List them once per policy; Step 2 verifies each value.
106
+
107
+ ## Step 2: Claims, both directions
108
+
109
+ **Text → code.** Extract each checkable claim per policy — data collected,
110
+ recipients and providers, cookies and tracking, access, retention and
111
+ erasure, money rules and values, deadlines, consent mechanics, and the
112
+ procedures a reader is told to follow. Verify each against the code with
113
+ `path:line` evidence, or against a `backingDocs` procedure. Record the
114
+ searches you ran when you find nothing.
115
+
116
+ **Code → text.** Inventory what the code does in those same categories —
117
+ providers reached, cookies and storage keys set, personal-data categories
118
+ stored, money rules enforced — and flag what no policy discloses.
119
+
120
+ ## Step 3: Evaluation dimensions
121
+
122
+ Every finding takes exactly one of these as its `Dimension`:
123
+
124
+ - **Contradiction** — the text says X; the code does Y.
125
+ - **Unbacked Promise** — a published commitment that no code and no
126
+ documented `backingDocs` procedure honors.
127
+ - **Undisclosed Practice** — the system does something (a provider reached, a
128
+ cookie set, a data category stored) that no policy discloses.
129
+ - **Stale Reference** — a renamed feature, a departed person or address, a
130
+ document readers cannot reach, or an expired accepted finding.
131
+ - **Internal Inconsistency** — two policies, or two sections of one policy,
132
+ disagree (a "one-time" fee here, an "annual" fee there).
133
+ - **Unverifiable** — a claim about a system outside the repository (a
134
+ partner-built app, a vendor's own retention). Info only.
135
+
136
+ ### Accepted findings
137
+
138
+ When a finding's Policy file and quoted sentence match an `acceptedFindings`
139
+ entry whose `reviewBy` date has not passed, do not report it; count it as
140
+ **accepted** in Claims Coverage. An entry whose `reviewBy` has passed is
141
+ reported as a Low `Stale Reference` naming the entry, and is this lens's
142
+ own — it is not `/audit-exceptions`' to grade.
143
+
144
+ ## Step 4: Severity anchors
145
+
146
+ - `High` — a published commitment about money, children's or health data,
147
+ deletion and retention, consent, or third-party sharing that the system
148
+ contradicts or does not honor.
149
+ - `Medium` — any other Contradiction, Unbacked Promise or Undisclosed
150
+ Practice.
151
+ - `Low` — Stale References and Internal Inconsistencies.
152
+ - `Info` — Unverifiable claims.
153
+
154
+ This lens does not grade Critical: a policy finding is a decision for the
155
+ operator, never a defect that should halt a delivery gate on its own.
156
+
157
+ ## Step 5: Boundaries with sibling lenses
158
+
159
+ - A code-side personal-data flow that involves **no policy sentence** stays
160
+ [`/audit-privacy`](audit-privacy.md)'s.
161
+ - [`/audit-documentation`](audit-documentation.md) excludes the policy corpus
162
+ from its own target set; published policy text is audited here only.
163
+ - Expired accepted findings are this lens's own, not
164
+ [`/audit-exceptions`](audit-exceptions.md)'.
165
+ - [`/audit-security`](audit-security.md) is unchanged.
166
+
167
+ ## Periodic full-scope sweep
168
+
169
+ Policies drift one merged change at a time, so a fenced run sees only the
170
+ day's slice. Pair it with a recurring full-scope run:
171
+
172
+ - **Scheduled invocation** — `/schedule` running `/audit-policies`
173
+ full-scope (no `--paths`, no change-set filter, so the `{{changedFiles}}`
174
+ block renders the literal token) on a weekly cron, and before any policy
175
+ rewrite ships. The nightly sweep-then-route recipe lives in
176
+ [`audit-to-stories.md` § Scheduling a nightly sweep](audit-to-stories.md#scheduling-a-nightly-sweep).
177
+
178
+ Route the resulting `audit-policies-results.md` through
179
+ [`/audit-to-stories`](audit-to-stories.md); each Story it files opens on the
180
+ recorded operator decision.
181
+
182
+ ## Report additions
183
+
184
+ Beyond the core's shared skeleton, this lens adds its title, the fixed
185
+ not-legal-advice line and a `Direction split` line in the Executive Summary,
186
+ the mandatory Claims Coverage section before the findings, and four finding
187
+ fields. Write `_No findings._` under a section rather than omitting it:
188
+
189
+ ```markdown
190
+ # Policy Consistency Audit Report
191
+
192
+ ## Executive Summary
193
+
194
+ [Headline read.]
195
+
196
+ This audit checks consistency between published text and implementation, not legal adequacy, and is not legal advice.
197
+
198
+ Self-cross-check: kept <k> / dropped <d>.
199
+ Severity tally: Critical 0 / High <n> / Medium <n> / Low <n>
200
+ Direction split: text <n> / code <n> / undecided <n>
201
+
202
+ ## Claims Coverage
203
+
204
+ | Policy | Claims extracted | Verified | Backed | Accepted | Findings |
205
+ | --- | --- | --- | --- | --- | --- |
206
+ | `path/to/policy.md` | <n> | <n> | <n> | <n> | <n> |
207
+
208
+ ## Detailed Findings
209
+
210
+ ### `path/to/policy.md` — [Short title of the issue]
211
+
212
+ - **Dimension:** [Contradiction | Unbacked Promise | Undisclosed Practice | Stale Reference | Internal Inconsistency | Unverifiable]
213
+ - **Severity:** [High | Medium | Low | Info]
214
+ - **Policy:** `path/to/policy.md` — "[the exact quoted sentence]"
215
+ - **Implementation:** [`path:line` evidence | none found — searches run: …]
216
+ - **Backing:** [a `backingDocs` procedure | none]
217
+ - **Direction:** [text | code | undecided — default undecided]
218
+ - [Location, Current State, Recommendation & Rationale, Acceptance signal —
219
+ per the core skeleton; the recommendation names the decision, never new
220
+ wording]
221
+ ```
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,15 @@ 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.97.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.96.0...mandrel-v2.97.0) (2026-10-22)
19
+
20
+
21
+ ### Added
22
+
23
+ * add /audit-policies: check published customer policies against the implementation in both directions, never editing policy text ([#5848](https://github.com/dsj1984/mandrel/issues/5848)) ([#5851](https://github.com/dsj1984/mandrel/issues/5851)) ([788728a](https://github.com/dsj1984/mandrel/commit/788728a720504722460abd007c90b4ab572dbff2))
24
+ * let the duplication gate scan extra jscpd languages (e.g. Python) on top of the scorable list ([#5849](https://github.com/dsj1984/mandrel/issues/5849)) ([#5853](https://github.com/dsj1984/mandrel/issues/5853)) ([32f8a17](https://github.com/dsj1984/mandrel/commit/32f8a17cfd15dd0f9e909290d69fc162597e20ac))
25
+ * re-survey the .agentrc surface: retire keys nobody sets and reset the leaf-key ceiling to the measured count ([#5850](https://github.com/dsj1984/mandrel/issues/5850)) ([#5854](https://github.com/dsj1984/mandrel/issues/5854)) ([9c3819b](https://github.com/dsj1984/mandrel/commit/9c3819ba5ed17cb9ff325f58368aa70fc62dfb85))
26
+
18
27
  ## [2.96.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.95.0...mandrel-v2.96.0) (2026-10-21)
19
28
 
20
29
 
@@ -23,6 +23,7 @@ import { hoistSystemPromptBlockStep } from './steps/2.84.0-hoist-system-prompt-b
23
23
  import { moveSharedCrapCaptureScript } from './steps/2.91.0-move-shared-crap-capture-script.js';
24
24
  import { retireDuplicationFormats } from './steps/2.91.0-retire-duplication-formats.js';
25
25
  import { unsetNullLintCommand } from './steps/2.91.0-unset-null-lint-command.js';
26
+ import { retireQualityNavigability } from './steps/2.97.0-retire-quality-navigability.js';
26
27
  import { stripRemovedAgentrcKeys } from './steps/strip-removed-agentrc-keys.js';
27
28
 
28
29
  /**
@@ -54,6 +55,7 @@ export const migrations = [
54
55
  moveSharedCrapCaptureScript,
55
56
  unsetNullLintCommand,
56
57
  retireDuplicationFormats,
58
+ retireQualityNavigability,
57
59
  ];
58
60
 
59
61
  export { compareVersions };
@@ -1,19 +1,34 @@
1
1
  // lib/migrations/steps/2.91.0-retire-duplication-formats.js
2
2
  /**
3
- * Strip `delivery.quality.gates.duplication.formats`: the jscpd formats are
4
- * now derived from the scorable-extension list every other gate scores, and
5
- * the gate block is `additionalProperties: false`. An emptied `duplication`
6
- * block is pruned; its parents keep their other gates.
3
+ * Retire `delivery.quality.gates.duplication.formats` (the scorable formats
4
+ * now derive from the scorable-extension list). Entries outside that list move
5
+ * into `additionalFormats` so the upgrade keeps measuring them; an emptied
6
+ * `duplication` block is pruned.
7
7
  */
8
8
 
9
- import { createRetireAgentrcKeyStep } from '../helpers/retire-agentrc-key.js';
9
+ import nodeFs from 'node:fs';
10
+ import {
11
+ AGENTRC_FILENAMES,
12
+ createRetireAgentrcKeyStep,
13
+ readAgentrcConfig,
14
+ resolveAgentrcPath,
15
+ } from '../helpers/retire-agentrc-key.js';
10
16
 
11
- export const retireDuplicationFormats = createRetireAgentrcKeyStep({
17
+ /** A 2.91.0 snapshot, not an import: migrations run builtins-only. */
18
+ const SCORABLE_FORMATS = Object.freeze([
19
+ 'javascript',
20
+ 'jsx',
21
+ 'typescript',
22
+ 'tsx',
23
+ ]);
24
+
25
+ const retireFormats = createRetireAgentrcKeyStep({
12
26
  version: '2.91.0',
13
27
  description:
14
- 'strip retired delivery.quality.gates.duplication.formats from ' +
15
- '.agentrc.json and .agentrc.local.json (the jscpd formats now derive ' +
16
- 'from the scorable-extension list — Story #5738)',
28
+ 'move non-scorable delivery.quality.gates.duplication.formats entries ' +
29
+ 'into additionalFormats, then strip the retired key from .agentrc.json ' +
30
+ 'and .agentrc.local.json (the scorable jscpd formats now derive from ' +
31
+ 'the scorable-extension list — Stories #5738, #5849)',
17
32
  keys: [
18
33
  {
19
34
  path: ['delivery', 'quality', 'gates', 'duplication', 'formats'],
@@ -21,3 +36,44 @@ export const retireDuplicationFormats = createRetireAgentrcKeyStep({
21
36
  },
22
37
  ],
23
38
  });
39
+
40
+ /**
41
+ * @param {object | null} config
42
+ * @returns {{ duplication: object, extra: string[] } | null}
43
+ */
44
+ function nonScorableFormats(config) {
45
+ const duplication = config?.delivery?.quality?.gates?.duplication;
46
+ if (!Array.isArray(duplication?.formats)) return null;
47
+ const extra = duplication.formats.filter(
48
+ (name) => typeof name === 'string' && !SCORABLE_FORMATS.includes(name),
49
+ );
50
+ return extra.length > 0 ? { duplication, extra } : null;
51
+ }
52
+
53
+ /** Leaves `formats` itself for the retire step to strip. */
54
+ function carryNonScorableFormats(ctx) {
55
+ const fsImpl = ctx?.fs ?? nodeFs;
56
+ for (const filename of AGENTRC_FILENAMES) {
57
+ const config = readAgentrcConfig(ctx, filename, fsImpl);
58
+ const found = nonScorableFormats(config);
59
+ if (!found) continue;
60
+ const prior = Array.isArray(found.duplication.additionalFormats)
61
+ ? found.duplication.additionalFormats
62
+ : [];
63
+ found.duplication.additionalFormats = [
64
+ ...new Set([...prior, ...found.extra]),
65
+ ];
66
+ fsImpl.writeFileSync(
67
+ resolveAgentrcPath(ctx, filename),
68
+ `${JSON.stringify(config, null, 2)}\n`,
69
+ );
70
+ }
71
+ }
72
+
73
+ export const retireDuplicationFormats = {
74
+ ...retireFormats,
75
+ apply(ctx) {
76
+ carryNonScorableFormats(ctx);
77
+ retireFormats.apply(ctx);
78
+ },
79
+ };
@@ -0,0 +1,80 @@
1
+ // lib/migrations/steps/2.97.0-retire-quality-navigability.js
2
+ /**
3
+ * Retire the `delivery.quality.navigability` block. The route
4
+ * tree and nav registry have one home, `planning.navigation`, which the plan
5
+ * reachability gate, the navigability lens and the audit selector all read;
6
+ * `journeySuite` and this block's `navRegistry` had no reader. Values are not
7
+ * moved — that would switch on the plan-time reachability gate — so a value
8
+ * `planning.navigation` does not already carry is reported as a behaviour
9
+ * change instead.
10
+ */
11
+
12
+ import nodeFs from 'node:fs';
13
+ import {
14
+ AGENTRC_FILENAMES,
15
+ createRetireAgentrcKeyStep,
16
+ readAgentrcConfig,
17
+ } from '../helpers/retire-agentrc-key.js';
18
+
19
+ const BLOCK = ['delivery', 'quality', 'navigability'];
20
+
21
+ /** The planning.navigation sibling that now owns each key; null = no reader. */
22
+ const SUCCESSORS = Object.freeze({
23
+ routeGlobs: 'routeGlobs',
24
+ navRegistry: 'navRegistry',
25
+ journeySuite: null,
26
+ });
27
+
28
+ const retireBlock = createRetireAgentrcKeyStep({
29
+ version: '2.97.0',
30
+ description:
31
+ 'strip delivery.quality.navigability from .agentrc.json and ' +
32
+ '.agentrc.local.json — route globs and the nav registry live under ' +
33
+ 'planning.navigation, and journeySuite had no reader (Story #5850)',
34
+ keys: Object.keys(SUCCESSORS).map((key) => ({
35
+ path: [...BLOCK, key],
36
+ pruneDepth: 1,
37
+ })),
38
+ });
39
+
40
+ /**
41
+ * @param {string} filename
42
+ * @param {object} config
43
+ * @returns {string[]}
44
+ */
45
+ function reportLines(filename, config) {
46
+ const block = config?.delivery?.quality?.navigability;
47
+ if (!block || typeof block !== 'object') return [];
48
+ const planning = config?.planning?.navigation ?? {};
49
+ const lines = [];
50
+ for (const [key, successor] of Object.entries(SUCCESSORS)) {
51
+ if (!Object.hasOwn(block, key)) continue;
52
+ const dotted = `${BLOCK.join('.')}.${key}`;
53
+ const value = JSON.stringify(block[key]);
54
+ if (successor === null) {
55
+ lines.push(` removed ${filename} ${dotted}; it had no reader`);
56
+ } else if (JSON.stringify(planning[successor]) === value) {
57
+ lines.push(
58
+ ` removed ${filename} ${dotted}; planning.navigation.${successor} already carries it`,
59
+ );
60
+ } else {
61
+ lines.push(
62
+ ` behaviour change: ${filename} set ${dotted} = ${value}; set planning.navigation.${successor} to keep it`,
63
+ );
64
+ }
65
+ }
66
+ return lines;
67
+ }
68
+
69
+ export const retireQualityNavigability = {
70
+ ...retireBlock,
71
+ apply(ctx) {
72
+ const fsImpl = ctx?.fs ?? nodeFs;
73
+ const log = ctx?.log ?? console.log;
74
+ for (const filename of AGENTRC_FILENAMES) {
75
+ const config = readAgentrcConfig(ctx, filename, fsImpl);
76
+ for (const line of reportLines(filename, config)) log(line);
77
+ }
78
+ retireBlock.apply(ctx);
79
+ },
80
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.96.0",
3
+ "version": "2.97.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/",