mandrel 2.96.0 → 2.98.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/policies.md +23 -0
- package/.agents/docs/agentrc-reference.json +2 -5
- package/.agents/docs/configuration.md +8 -6
- package/.agents/docs/workflows.md +2 -1
- package/.agents/schemas/agentrc.schema.json +46 -29
- package/.agents/schemas/audit-rules.json +32 -0
- package/.agents/schemas/audit-rules.schema.json +2 -2
- package/.agents/scripts/lib/audit-suite/selector.js +119 -27
- package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
- package/.agents/scripts/lib/baselines/duplication-scanner.js +44 -3
- package/.agents/scripts/lib/baselines/refresh-service.js +54 -14
- package/.agents/scripts/lib/config/explain.js +1 -7
- package/.agents/scripts/lib/config/gates/duplication.schema.js +12 -5
- package/.agents/scripts/lib/config-settings-schema-quality.js +0 -27
- package/.agents/scripts/lib/config-settings-schema.js +30 -0
- package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
- package/.agents/scripts/lib/orchestration/review-providers/code-review.js +2 -14
- package/.agents/scripts/lib/orchestration/review-providers/generated-diff.js +61 -0
- package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-gate-steps.js +3 -1
- package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +1 -1
- package/.agents/scripts/lib/orchestration/story-close/commit-body.js +100 -0
- package/.agents/scripts/lib/orchestration/story-close/context-budget-writeback.js +1 -1
- package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +20 -5
- package/.agents/scripts/lib/orchestration/story-close/ratchet-shrink-writeback.js +1 -1
- package/.agents/scripts/lib/source-extensions.js +3 -2
- package/.agents/workflows/audit-documentation.md +5 -0
- package/.agents/workflows/audit-policies.md +221 -0
- package/docs/CHANGELOG.md +16 -0
- package/lib/migrations/index.js +2 -0
- package/lib/migrations/steps/2.91.0-retire-duplication-formats.js +65 -9
- package/lib/migrations/steps/2.97.0-retire-quality-navigability.js +80 -0
- 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
|
+
}
|
|
@@ -10,6 +10,7 @@
|
|
|
10
10
|
|
|
11
11
|
import { Logger } from '../../../Logger.js';
|
|
12
12
|
import { runBaselineUpwardWriteback as defaultRunBaselineUpwardWriteback } from '../../story-close/baseline-upward-writeback.js';
|
|
13
|
+
import { refusalMark } from '../../story-close/commit-body.js';
|
|
13
14
|
import { runContextBudgetWriteback as defaultRunContextBudgetWriteback } from '../../story-close/context-budget-writeback.js';
|
|
14
15
|
import { runDuplicationCloseRescore as defaultRunDuplicationCloseRescore } from '../../story-close/duplication-close-rescore.js';
|
|
15
16
|
import { runScopedFormatAutofix as defaultRunScopedFormatAutofix } from '../../story-close/format-autofix.js';
|
|
@@ -74,7 +75,7 @@ async function writebackStep(
|
|
|
74
75
|
tag,
|
|
75
76
|
writeback?.committed
|
|
76
77
|
? `✅ ${describe(writeback)} as ${writeback.sha} on ${storyBranch}.`
|
|
77
|
-
:
|
|
78
|
+
: `${refusalMark(tag, writeback?.reason)} No ${noun} (${writeback?.reason ?? 'nothing to write'}).`,
|
|
78
79
|
);
|
|
79
80
|
}
|
|
80
81
|
|
|
@@ -88,6 +89,7 @@ async function bestEffort({ tag, label, progress, run }) {
|
|
|
88
89
|
try {
|
|
89
90
|
await run();
|
|
90
91
|
} catch (err) {
|
|
92
|
+
refusalMark(tag, err?.message);
|
|
91
93
|
progress(
|
|
92
94
|
tag,
|
|
93
95
|
`⚠️ ${label} failed (close continues; the gate chain is authoritative): ${err?.message ?? err}`,
|
|
@@ -28,10 +28,10 @@ import {
|
|
|
28
28
|
resolveDefaultScorer,
|
|
29
29
|
} from '../../baselines/refresh-service.js';
|
|
30
30
|
import { getQuality } from '../../config-resolver.js';
|
|
31
|
-
import { gitSync as defaultGitSync } from '../../git-utils.js';
|
|
32
31
|
import { Logger as DefaultLogger } from '../../Logger.js';
|
|
33
32
|
import { isScorableSourceFile } from '../../source-extensions.js';
|
|
34
33
|
import { toPosix } from '../../util/paths.js';
|
|
34
|
+
import { closeGitSync as defaultGitSync } from './commit-body.js';
|
|
35
35
|
import {
|
|
36
36
|
currentBranch,
|
|
37
37
|
listChangedFiles,
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* commit-body.js — the git close-time baseline write-backs commit with: each
|
|
3
|
+
* body line bounded to commitlint's `body-max-line-length` (100), never by
|
|
4
|
+
* bypassing the consumer's hook; a refusal names the rule and warns.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { gitSync } from '../../git-utils.js';
|
|
8
|
+
import { Logger } from '../../Logger.js';
|
|
9
|
+
|
|
10
|
+
const BODY_LINE_MAX = 100;
|
|
11
|
+
|
|
12
|
+
/** Survives each writer's own `<label>: <message>` skip reason. */
|
|
13
|
+
const COMMIT_REFUSED = 'commit-refused:';
|
|
14
|
+
|
|
15
|
+
const ROW_PREFIX = '- ';
|
|
16
|
+
const CONTINUATION = ' ';
|
|
17
|
+
const LEFT_ELLIPSIS = '…/';
|
|
18
|
+
|
|
19
|
+
/** Keep the path's tail, cut at a segment boundary. */
|
|
20
|
+
function truncatePathLeft(rowPath, max) {
|
|
21
|
+
if (rowPath.length <= max) return rowPath;
|
|
22
|
+
const tail = rowPath.slice(rowPath.length - (max - LEFT_ELLIPSIS.length));
|
|
23
|
+
const cut = tail.indexOf('/');
|
|
24
|
+
const kept = cut >= 0 && cut < tail.length - 1 ? tail.slice(cut + 1) : tail;
|
|
25
|
+
return `${LEFT_ELLIPSIS}${kept}`;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
function truncateRight(text, max) {
|
|
29
|
+
return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** `- <path>: <detail>`, or the path then an indented detail line. */
|
|
33
|
+
function formatBodyRow(rowPath, detail) {
|
|
34
|
+
const oneLine = `${ROW_PREFIX}${rowPath}: ${detail}`;
|
|
35
|
+
if (oneLine.length <= BODY_LINE_MAX) return [oneLine];
|
|
36
|
+
return [
|
|
37
|
+
`${ROW_PREFIX}${truncatePathLeft(rowPath, BODY_LINE_MAX - ROW_PREFIX.length)}`,
|
|
38
|
+
`${CONTINUATION}${truncateRight(detail, BODY_LINE_MAX - CONTINUATION.length)}`,
|
|
39
|
+
];
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** Re-flow over-long rows (split at the last `: `); cut other long lines. */
|
|
43
|
+
function boundBody(body) {
|
|
44
|
+
return body
|
|
45
|
+
.split('\n')
|
|
46
|
+
.flatMap((line) => {
|
|
47
|
+
if (line.length <= BODY_LINE_MAX) return [line];
|
|
48
|
+
const split = line.lastIndexOf(': ');
|
|
49
|
+
if (!line.startsWith(ROW_PREFIX) || split < 0) {
|
|
50
|
+
return [truncateRight(line, BODY_LINE_MAX)];
|
|
51
|
+
}
|
|
52
|
+
return formatBodyRow(
|
|
53
|
+
line.slice(ROW_PREFIX.length, split),
|
|
54
|
+
line.slice(split + 2),
|
|
55
|
+
);
|
|
56
|
+
})
|
|
57
|
+
.join('\n');
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** The commitlint rule(s) from hook stderr — not the message, which echoes argv. */
|
|
61
|
+
function describeCommitRefusal(err) {
|
|
62
|
+
const text = String(err?.stderr || err?.message || err || '');
|
|
63
|
+
const rules = [
|
|
64
|
+
...new Set([...text.matchAll(/\[([a-z][a-z0-9-]*)\]/g)].map((m) => m[1])),
|
|
65
|
+
];
|
|
66
|
+
if (rules.length > 0)
|
|
67
|
+
return `commit-msg hook refused it [${rules.join(', ')}]`;
|
|
68
|
+
const lines = text.split('\n').map((l) => l.trim());
|
|
69
|
+
return truncateRight(lines.filter(Boolean).at(-1) ?? 'unknown', 200);
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/** `git commit` itself failed (a hook refused it), not a write or `git add`. */
|
|
73
|
+
class CommitRefusedError extends Error {
|
|
74
|
+
constructor(cause) {
|
|
75
|
+
super(`${COMMIT_REFUSED} ${describeCommitRefusal(cause)}`, { cause });
|
|
76
|
+
this.name = 'CommitRefusedError';
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** Drop-in `gitSync`: a `git commit` gets bounded `-m` paragraphs. */
|
|
81
|
+
export function closeGitSync(cwd, ...args) {
|
|
82
|
+
if (args[0] !== 'commit') return gitSync(cwd, ...args);
|
|
83
|
+
const bounded = args.map((arg, i) =>
|
|
84
|
+
args[i - 1] === '-m' ? boundBody(arg) : arg,
|
|
85
|
+
);
|
|
86
|
+
try {
|
|
87
|
+
return gitSync(cwd, ...bounded);
|
|
88
|
+
} catch (err) {
|
|
89
|
+
throw new CommitRefusedError(err);
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/** `⚠️` plus a warn-level log for a refused commit, else `⏭`. */
|
|
94
|
+
export function refusalMark(tag, reason) {
|
|
95
|
+
if (!String(reason ?? '').includes(COMMIT_REFUSED)) return '⏭';
|
|
96
|
+
Logger.warn(
|
|
97
|
+
`[${tag}] baseline commit refused; its rows stay stale: ${reason}`,
|
|
98
|
+
);
|
|
99
|
+
return '⚠️';
|
|
100
|
+
}
|
|
@@ -22,8 +22,8 @@ import {
|
|
|
22
22
|
loadBaseline as defaultLoadBaseline,
|
|
23
23
|
} from '../../../check-context-budget.js';
|
|
24
24
|
import { resolveDocTiers as defaultResolveDocTiers } from '../../doc-tiers.js';
|
|
25
|
-
import { gitSync as defaultGitSync } from '../../git-utils.js';
|
|
26
25
|
import { Logger as DefaultLogger } from '../../Logger.js';
|
|
26
|
+
import { closeGitSync as defaultGitSync } from './commit-body.js';
|
|
27
27
|
|
|
28
28
|
const TAG = '[context-budget-writeback]';
|
|
29
29
|
|
|
@@ -19,8 +19,8 @@ import {
|
|
|
19
19
|
} from '../../baselines/refresh-service.js';
|
|
20
20
|
import { getBaselineEpsilon } from '../../config/quality.js';
|
|
21
21
|
import { getQuality } from '../../config-resolver.js';
|
|
22
|
-
import { gitSync as defaultGitSync } from '../../git-utils.js';
|
|
23
22
|
import { Logger as DefaultLogger } from '../../Logger.js';
|
|
23
|
+
import { closeGitSync as defaultGitSync } from './commit-body.js';
|
|
24
24
|
import {
|
|
25
25
|
currentBranch,
|
|
26
26
|
listChangedFiles,
|
|
@@ -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({
|
|
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
|
-
() =>
|
|
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);
|
|
@@ -28,9 +28,9 @@ import {
|
|
|
28
28
|
extractRowsFromKnip,
|
|
29
29
|
} from '../../dead-exports-knip.js';
|
|
30
30
|
import { resolveDeadExportsMode } from '../../dead-exports-mode.js';
|
|
31
|
-
import { gitSync as defaultGitSync } from '../../git-utils.js';
|
|
32
31
|
import { Logger as DefaultLogger } from '../../Logger.js';
|
|
33
32
|
import { toPosix } from '../../util/paths.js';
|
|
33
|
+
import { closeGitSync as defaultGitSync } from './commit-body.js';
|
|
34
34
|
import { currentBranch, listDirtyPaths } from './format-autofix.js';
|
|
35
35
|
|
|
36
36
|
const TAG = '[ratchet-shrink]';
|
|
@@ -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
|
|
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,22 @@ 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.98.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.97.0...mandrel-v2.98.0) (2026-10-22)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
### Fixed
|
|
22
|
+
|
|
23
|
+
* close-time baseline commits stay under commitlint's 100-char body line limit, so a deep file path no longer silently drops the re-score ([#5859](https://github.com/dsj1984/mandrel/issues/5859)) ([#5860](https://github.com/dsj1984/mandrel/issues/5860)) ([3f85ed8](https://github.com/dsj1984/mandrel/commit/3f85ed88a0f6a0f8eafbb3d328f0353e1f4f00ed))
|
|
24
|
+
|
|
25
|
+
## [2.97.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.96.0...mandrel-v2.97.0) (2026-10-22)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
### Added
|
|
29
|
+
|
|
30
|
+
* 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))
|
|
31
|
+
* 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))
|
|
32
|
+
* 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))
|
|
33
|
+
|
|
18
34
|
## [2.96.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.95.0...mandrel-v2.96.0) (2026-10-21)
|
|
19
35
|
|
|
20
36
|
|
package/lib/migrations/index.js
CHANGED
|
@@ -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 };
|