mandrel 2.95.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.
- package/.agents/audit-checklists/policies.md +23 -0
- package/.agents/audit-checklists/red-team.md +20 -0
- package/.agents/docs/agentrc-reference.json +2 -5
- package/.agents/docs/configuration.md +8 -6
- package/.agents/docs/workflows.md +4 -1
- package/.agents/schemas/agentrc.schema.json +46 -29
- package/.agents/schemas/audit-rules.json +48 -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 +2 -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/story-close/duplication-close-rescore.js +19 -4
- package/.agents/scripts/lib/source-extensions.js +3 -2
- package/.agents/scripts/lint-issue-body.js +65 -10
- package/.agents/workflows/audit-documentation.md +5 -0
- package/.agents/workflows/audit-policies.md +221 -0
- package/.agents/workflows/audit-red-team.md +191 -0
- package/.agents/workflows/audit-security.md +4 -1
- package/.agents/workflows/mandrel-leverage.md +199 -0
- package/.agents/workflows/mandrel-plan.md +3 -1
- package/docs/CHANGELOG.md +23 -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
|
+
}
|
|
@@ -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);
|
|
@@ -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
|
*/
|
|
@@ -21,6 +21,30 @@ const REQUIRED_SECTIONS = [
|
|
|
21
21
|
{ field: 'verify', label: 'Verify' },
|
|
22
22
|
];
|
|
23
23
|
|
|
24
|
+
/** The closed set of section names a comment may print. */
|
|
25
|
+
const SECTION_LABELS = new Map([
|
|
26
|
+
['goal', 'Goal'],
|
|
27
|
+
['acceptance', 'Acceptance'],
|
|
28
|
+
['verify', 'Verify'],
|
|
29
|
+
['changes', 'Changes'],
|
|
30
|
+
['references', 'References'],
|
|
31
|
+
['spec', 'Spec'],
|
|
32
|
+
['context', 'Context'],
|
|
33
|
+
['slicing', 'Slicing'],
|
|
34
|
+
['non_goals', 'Non-Goals'],
|
|
35
|
+
]);
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* Fixed-vocabulary problem line for a parse failure. `err.message` and
|
|
39
|
+
* `err.raw` echo issue text, so they go to the run log, never the comment.
|
|
40
|
+
*/
|
|
41
|
+
function parseFailureProblem(err) {
|
|
42
|
+
const label = SECTION_LABELS.get(err.field);
|
|
43
|
+
return label
|
|
44
|
+
? `The \`## ${label}\` section could not be parsed into the canonical schema.`
|
|
45
|
+
: 'An unrecognised section could not be parsed into the canonical schema.';
|
|
46
|
+
}
|
|
47
|
+
|
|
24
48
|
/**
|
|
25
49
|
* Issue Forms render a skipped field as `_No response_`; treat it as absent.
|
|
26
50
|
* @param {string} body
|
|
@@ -39,6 +63,7 @@ function stripNoResponseSentinel(body) {
|
|
|
39
63
|
* @property {string[]} problems
|
|
40
64
|
* @property {string[]} warnings
|
|
41
65
|
* @property {boolean} parseFailed
|
|
66
|
+
* @property {string|null} parseError - Full parser message; run log only.
|
|
42
67
|
*/
|
|
43
68
|
|
|
44
69
|
/**
|
|
@@ -54,6 +79,7 @@ export function evaluateIssueBody(body) {
|
|
|
54
79
|
problems: ['The issue body is empty.'],
|
|
55
80
|
warnings: [],
|
|
56
81
|
parseFailed: true,
|
|
82
|
+
parseError: null,
|
|
57
83
|
};
|
|
58
84
|
}
|
|
59
85
|
|
|
@@ -66,11 +92,10 @@ export function evaluateIssueBody(body) {
|
|
|
66
92
|
if (err instanceof StoryBodyParseError) {
|
|
67
93
|
return {
|
|
68
94
|
conformant: false,
|
|
69
|
-
problems: [
|
|
70
|
-
`The body could not be parsed into the canonical schema: ${err.message}`,
|
|
71
|
-
],
|
|
95
|
+
problems: [parseFailureProblem(err)],
|
|
72
96
|
warnings: [],
|
|
73
97
|
parseFailed: true,
|
|
98
|
+
parseError: err.message,
|
|
74
99
|
};
|
|
75
100
|
}
|
|
76
101
|
throw err;
|
|
@@ -103,10 +128,13 @@ export function evaluateIssueBody(body) {
|
|
|
103
128
|
problems,
|
|
104
129
|
warnings: result.warnings,
|
|
105
130
|
parseFailed: false,
|
|
131
|
+
parseError: null,
|
|
106
132
|
};
|
|
107
133
|
}
|
|
108
134
|
|
|
109
135
|
/**
|
|
136
|
+
* Built only from fixed strings and the fixed-vocabulary `problems`; warning
|
|
137
|
+
* text echoes issue content, so only the count is shown.
|
|
110
138
|
* @param {ConformanceVerdict} verdict
|
|
111
139
|
* @returns {string}
|
|
112
140
|
*/
|
|
@@ -127,11 +155,8 @@ export function renderConformanceComment(verdict) {
|
|
|
127
155
|
if (verdict.warnings.length > 0) {
|
|
128
156
|
lines.push(
|
|
129
157
|
'',
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
...verdict.warnings.map((w) => `- ${w}`),
|
|
133
|
-
'',
|
|
134
|
-
'</details>',
|
|
158
|
+
`The parser also raised ${verdict.warnings.length} non-blocking ` +
|
|
159
|
+
'warning(s); see the workflow run log for the details.',
|
|
135
160
|
);
|
|
136
161
|
}
|
|
137
162
|
return lines.join('\n');
|
|
@@ -159,6 +184,34 @@ export function isStoryTicket(labelNames) {
|
|
|
159
184
|
return Array.isArray(labelNames) && labelNames.includes('type::story');
|
|
160
185
|
}
|
|
161
186
|
|
|
187
|
+
/**
|
|
188
|
+
* The bot-authored marker comment to update, or `null`. A human-authored
|
|
189
|
+
* marker is ignored so an issue author cannot hijack or suppress the lint.
|
|
190
|
+
*/
|
|
191
|
+
function findMarkerCommentId(ghFn, repoPath, issue) {
|
|
192
|
+
const out = ghFn([
|
|
193
|
+
'api',
|
|
194
|
+
`repos/${repoPath}/issues/${issue}/comments`,
|
|
195
|
+
'--paginate',
|
|
196
|
+
'--jq',
|
|
197
|
+
'.[] | {id, login: .user.login, body}',
|
|
198
|
+
]);
|
|
199
|
+
const comments = out.split('\n').filter((line) => line.trim() !== '');
|
|
200
|
+
return comments.map((line) => JSON.parse(line)).find(isBotMarker)?.id ?? null;
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
const isBotMarker = (c) =>
|
|
204
|
+
c.body?.startsWith(LINT_COMMENT_MARKER) && c.login?.endsWith('[bot]');
|
|
205
|
+
|
|
206
|
+
function upsertArgs(id, issue, repo, comment) {
|
|
207
|
+
if (id === null) {
|
|
208
|
+
const repoArgs = repo ? ['--repo', repo] : [];
|
|
209
|
+
return ['issue', 'comment', String(issue), ...repoArgs, '--body', comment];
|
|
210
|
+
}
|
|
211
|
+
const path = `repos/${repo ?? '{owner}/{repo}'}/issues/comments/${id}`;
|
|
212
|
+
return ['api', '-X', 'PATCH', path, '-f', `body=${comment}`];
|
|
213
|
+
}
|
|
214
|
+
|
|
162
215
|
/**
|
|
163
216
|
* @param {{
|
|
164
217
|
* issue: string|number,
|
|
@@ -201,6 +254,8 @@ export function runLintIssueBody({
|
|
|
201
254
|
issue: Number(issue),
|
|
202
255
|
conformant: verdict.conformant,
|
|
203
256
|
problems: verdict.problems,
|
|
257
|
+
warnings: verdict.warnings,
|
|
258
|
+
parseError: verdict.parseError,
|
|
204
259
|
})}\n`,
|
|
205
260
|
);
|
|
206
261
|
|
|
@@ -211,8 +266,8 @@ export function runLintIssueBody({
|
|
|
211
266
|
};
|
|
212
267
|
}
|
|
213
268
|
|
|
214
|
-
const
|
|
215
|
-
ghFn(
|
|
269
|
+
const id = findMarkerCommentId(ghFn, repo ?? '{owner}/{repo}', issue);
|
|
270
|
+
ghFn(upsertArgs(id, issue, repo, renderConformanceComment(verdict)));
|
|
216
271
|
return { conformant: false, problems: verdict.problems };
|
|
217
272
|
}
|
|
218
273
|
|
|
@@ -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
|
+
```
|