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.
Files changed (33) hide show
  1. package/.agents/audit-checklists/policies.md +23 -0
  2. package/.agents/audit-checklists/red-team.md +20 -0
  3. package/.agents/docs/agentrc-reference.json +2 -5
  4. package/.agents/docs/configuration.md +8 -6
  5. package/.agents/docs/workflows.md +4 -1
  6. package/.agents/schemas/agentrc.schema.json +46 -29
  7. package/.agents/schemas/audit-rules.json +48 -0
  8. package/.agents/schemas/audit-rules.schema.json +2 -2
  9. package/.agents/scripts/lib/audit-suite/selector.js +119 -27
  10. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +2 -0
  11. package/.agents/scripts/lib/baselines/duplication-scanner.js +44 -3
  12. package/.agents/scripts/lib/baselines/refresh-service.js +54 -14
  13. package/.agents/scripts/lib/config/explain.js +1 -7
  14. package/.agents/scripts/lib/config/gates/duplication.schema.js +12 -5
  15. package/.agents/scripts/lib/config-settings-schema-quality.js +0 -27
  16. package/.agents/scripts/lib/config-settings-schema.js +30 -0
  17. package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
  18. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +2 -14
  19. package/.agents/scripts/lib/orchestration/review-providers/generated-diff.js +61 -0
  20. package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +19 -4
  21. package/.agents/scripts/lib/source-extensions.js +3 -2
  22. package/.agents/scripts/lint-issue-body.js +65 -10
  23. package/.agents/workflows/audit-documentation.md +5 -0
  24. package/.agents/workflows/audit-policies.md +221 -0
  25. package/.agents/workflows/audit-red-team.md +191 -0
  26. package/.agents/workflows/audit-security.md +4 -1
  27. package/.agents/workflows/mandrel-leverage.md +199 -0
  28. package/.agents/workflows/mandrel-plan.md +3 -1
  29. package/docs/CHANGELOG.md +23 -0
  30. package/lib/migrations/index.js +2 -0
  31. package/lib/migrations/steps/2.91.0-retire-duplication-formats.js +65 -9
  32. package/lib/migrations/steps/2.97.0-retire-quality-navigability.js +80 -0
  33. 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
  */
@@ -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
- '<details><summary>Parser warnings (non-blocking)</summary>',
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 comment = renderConformanceComment(verdict);
215
- ghFn(['issue', 'comment', String(issue), ...repoArgs, '--body', comment]);
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
+ ```