Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.
TypeScript agentic-aiai-agentsai-codinganthropicautomationclaudeclaude-codecodexcoding-agentsdevops-automationdevtoolsgithub-actionsgrokllmloop-engineeringmcpprompt-engineering
feat(loop-sync): detect gate.yaml <-> docs/safety.md policy drift (#599)
THRISHAL DOMAcc20ebe73794
diff --git a/docs/safety.md b/docs/safety.mdindex c8cb2dd..af2ff58 100644--- a/docs/safety.md+++ b/docs/safety.md@@ -31,6 +31,14 @@ loop to have read this file: `loop-gate check --action <type> --paths <changed fexits `2` to escalate, `0` to proceed — same convention `loop-context --check`already uses, so control scripts chain both.+`gate.yaml` also sets `maxFiles: 10` — a change touching more than 10 files+escalates regardless of which paths it touches, on the assumption that a loop+proposing a large diff has lost the plot.++`loop-sync` checks this section against `gate.yaml` on every run and reports any+divergence, so the prose above and the enforced policy cannot drift apart+silently. It never rewrites either file: which side is correct is a human call.+## Auto-Merge Policy**Default: no auto-merge.**diff --git a/tools/loop-sync/README.md b/tools/loop-sync/README.mdindex d0f924f..3f87dd6 100644--- a/tools/loop-sync/README.md+++ b/tools/loop-sync/README.md@@ -68,11 +68,25 @@ loop-sync ./my-project --auto-fix- State file references- Pattern consistency-3. **Skills directory**+3. **`gate.yaml` ↔ `docs/safety.md` policy parity**+ - Denylist paths documented in `docs/safety.md` but **not enforced** by `gate.yaml` (error —+ readers trust the doc while `loop-gate` silently allows the path)+ - Denylist paths enforced by `gate.yaml` but **undocumented** in `docs/safety.md` (warning)+ - `gate.yaml` limits such as `maxFiles` that the prose policy never states (info)++ `gate.yaml` calls itself "the machine-readable twin of `docs/safety.md`" and asks you to keep+ the two in sync by hand. This check makes that invariant mechanical. It is **read-only even+ under `--auto-fix`**: which side is correct is a human decision, so loop-sync reports the+ divergence rather than silently rewriting a safety policy.++ Skipped when either file is absent — a project with no `docs/safety.md` has no prose policy+ to drift from.++4. **Skills directory**- Existence of `.claude/skills/`- Version information in SKILL.md files-4. **Configuration drift**+5. **Configuration drift**- Missing references- Orphaned files- Inconsistenciesdiff --git a/tools/loop-sync/dist/policy-drift.d.ts b/tools/loop-sync/dist/policy-drift.d.tsnew file mode 100644index 0000000..0d436ef--- /dev/null+++ b/tools/loop-sync/dist/policy-drift.d.ts@@ -0,0 +1,53 @@+/**+ * gate.yaml <-> docs/safety.md policy drift detection.+ *+ * docs/safety.md's "Path Denylist" fenced block is the prose policy; gate.yaml+ * is its machine-readable twin that loop-gate actually enforces. gate.yaml says+ * "Keep in sync with docs/safety.md when either changes" -- but nothing checked+ * it, so the two could silently diverge and leave loop-gate approving paths the+ * documented policy forbids. This module makes that invariant mechanical.+ *+ * Deliberately read-only: a divergence is a human decision (which side is+ * right?), so we never auto-fix a safety policy.+ */+/** Where a denylist was read from, for message text. */+export interface DenylistSource {+ patterns: string[];+ /** Entries the parser saw but could not use, e.g. non-string YAML nodes. */+ malformed: string[];+}+export interface PolicyDrift {+ /** In docs/safety.md but absent from gate.yaml -- enforcement is weaker than the doc. */+ missingInGate: string[];+ /** In gate.yaml but absent from docs/safety.md -- enforcement is undocumented. */+ missingInDoc: string[];+ /** gate.yaml limits that the prose policy never states. */+ undocumentedLimits: string[];+}+/**+ * Pull the denylist globs out of docs/safety.md.+ *+ * Takes the first fenced block after the "Path Denylist" heading. Strips inline+ * `#` comments (safety.md annotates entries, e.g.+ * `**\/migrations/** # unless explicit migration loop`).+ *+ * Returns null when the heading or its code block is absent, so callers can+ * tell "no policy documented" apart from "policy documented as empty".+ */+export declare function extractSafetyDenylist(markdown: string): DenylistSource | null;+/**+ * Pull denylist + limits out of gate.yaml. Returns null when the file is not+ * valid YAML or has no denylist -- loop-gate reports those itself, and we do+ * not want to double-report a broken gate file as a drift error.+ */+export declare function extractGateDenylist(yamlText: string): DenylistSource | null;+/** gate.yaml numeric limits that should also appear in the prose policy. */+export declare function findUndocumentedLimits(yamlText: string, markdown: string): string[];+/**+ * Compare the two policies. Comparison is exact string equality on the trimmed+ * glob: two globs can be semantically equivalent while differing textually+ * (`**\/auth/**` vs `**\/auth/*`), and for a safety policy we want the doc and+ * the enforced file to read identically, not merely overlap.+ */+export declare function comparePolicies(safety: DenylistSource, gate: DenylistSource, undocumentedLimits?: string[]): PolicyDrift;+export declare function hasDrift(drift: PolicyDrift): boolean;diff --git a/tools/loop-sync/dist/policy-drift.js b/tools/loop-sync/dist/policy-drift.jsnew file mode 100644index 0000000..e0d3d31--- /dev/null+++ b/tools/loop-sync/dist/policy-drift.js@@ -0,0 +1,138 @@+/**+ * gate.yaml <-> docs/safety.md policy drift detection.+ *+ * docs/safety.md's "Path Denylist" fenced block is the prose policy; gate.yaml+ * is its machine-readable twin that loop-gate actually enforces. gate.yaml says+ * "Keep in sync with docs/safety.md when either changes" -- but nothing checked+ * it, so the two could silently diverge and leave loop-gate approving paths the+ * documented policy forbids. This module makes that invariant mechanical.+ *+ * Deliberately read-only: a divergence is a human decision (which side is+ * right?), so we never auto-fix a safety policy.+ */+import { parse } from 'yaml';+const DENYLIST_HEADING = /^#{1,6}\s+Path Denylist\s*$/im;+const FENCE = /^\s*```/;+/**+ * Pull the denylist globs out of docs/safety.md.+ *+ * Takes the first fenced block after the "Path Denylist" heading. Strips inline+ * `#` comments (safety.md annotates entries, e.g.+ * `**\/migrations/** # unless explicit migration loop`).+ *+ * Returns null when the heading or its code block is absent, so callers can+ * tell "no policy documented" apart from "policy documented as empty".+ */+export function extractSafetyDenylist(markdown) {+ const heading = DENYLIST_HEADING.exec(markdown);+ if (!heading)+ return null;+ const after = markdown.slice(heading.index + heading[0].length);+ const lines = after.split(/\r?\n/);+ let start = -1;+ for (let i = 0; i < lines.length; i++) {+ if (FENCE.test(lines[i])) {+ start = i + 1;+ break;+ }+ // A following heading before any fence means the section has no code block.+ if (/^#{1,6}\s/.test(lines[i]))+ return null;+ }+ if (start === -1)+ return null;+ const patterns = [];+ for (let i = start; i < lines.length; i++) {+ if (FENCE.test(lines[i])) {+ return { patterns, malformed: [] };+ }+ const entry = stripComment(lines[i]);+ if (entry)+ patterns.push(entry);+ }+ // Unterminated fence -- treat as unparseable rather than guessing.+ return null;+}+function stripComment(line) {+ const hash = line.indexOf('#');+ // A leading '#' is a whole-line comment; '**/#foo' is not a glob we expect.+ const withoutComment = hash === -1 ? line : line.slice(0, hash);+ return withoutComment.trim();+}+/**+ * Pull denylist + limits out of gate.yaml. Returns null when the file is not+ * valid YAML or has no denylist -- loop-gate reports those itself, and we do+ * not want to double-report a broken gate file as a drift error.+ */+export function extractGateDenylist(yamlText) {+ let parsed;+ try {+ parsed = parse(yamlText);+ }+ catch {+ return null;+ }+ if (!parsed || typeof parsed !== 'object')+ return null;+ const denylist = parsed.denylist;+ if (!Array.isArray(denylist))+ return null;+ const patterns = [];+ const malformed = [];+ for (const entry of denylist) {+ if (typeof entry === 'string' && entry.trim()) {+ patterns.push(entry.trim());+ }+ else {+ malformed.push(String(entry));+ }+ }+ return { patterns, malformed };+}+/** gate.yaml numeric limits that should also appear in the prose policy. */+export function findUndocumentedLimits(yamlText, markdown) {+ let parsed;+ try {+ parsed = parse(yamlText);+ }+ catch {+ return [];+ }+ if (!parsed || typeof parsed !== 'object')+ return [];+ const limits = [];+ const maxFiles = parsed.maxFiles;+ if (typeof maxFiles === 'number' && !mentionsMaxFiles(markdown, maxFiles)) {+ limits.push(`maxFiles: ${maxFiles}`);+ }+ return limits;+}+function mentionsMaxFiles(markdown, value) {+ if (/maxFiles/i.test(markdown))+ return true;+ // Accept prose phrasings like "more than 10 files" / "10 changed files".+ // String.raw so the escapes reach RegExp intact -- a plain template literal+ // would turn \b into a backspace character.+ const prose = String.raw `\b${value}\b[^.\n]{0,24}\bfiles?\b`;+ return new RegExp(prose, 'i').test(markdown);+}+/**+ * Compare the two policies. Comparison is exact string equality on the trimmed+ * glob: two globs can be semantically equivalent while differing textually+ * (`**\/auth/**` vs `**\/auth/*`), and for a safety policy we want the doc and+ * the enforced file to read identically, not merely overlap.+ */+export function comparePolicies(safety, gate, undocumentedLimits = []) {+ const gateSet = new Set(gate.patterns);+ const safetySet = new Set(safety.patterns);+ return {+ missingInGate: safety.patterns.filter((p) => !gateSet.has(p)),+ missingInDoc: gate.patterns.filter((p) => !safetySet.has(p)),+ undocumentedLimits,+ };+}+export function hasDrift(drift) {+ return (drift.missingInGate.length > 0 ||+ drift.missingInDoc.length > 0 ||+ drift.undocumentedLimits.length > 0);+}diff --git a/tools/loop-sync/dist/sync.js b/tools/loop-sync/dist/sync.jsindex 304255f..e3f3892 100644--- a/tools/loop-sync/dist/sync.js+++ b/tools/loop-sync/dist/sync.js@@ -10,6 +10,7 @@import { readFile, writeFile, access, mkdir } from 'node:fs/promises';import { readdir, stat } from 'node:fs/promises';import path from 'node:path';+import { comparePolicies, extractGateDenylist, extractSafetyDenylist, findUndocumentedLimits, hasDrift, } from './policy-drift.js';/*** Check if a file exists*/@@ -379,6 +380,10 @@ export async function runSync(options) {}}}+ // Check gate.yaml ↔ docs/safety.md policy parity. gate.yaml is the+ // machine-readable twin of safety.md's Path Denylist; if they drift,+ // loop-gate enforces something other than the documented policy.+ await checkPolicyDrift(targetDir, issues);// Scan skills for version informationconst skillsVersions = await scanSkillsDirectory(targetDir);const hasSkillsDir = await fileExists(path.join(targetDir, 'skills'))@@ -474,3 +479,76 @@ export function formatReport(report) {}return lines.join('\n');}+/**+ * Compare docs/safety.md's Path Denylist against gate.yaml and record any+ * divergence. Read-only by design: which side is correct is a human call, so+ * this is never auto-fixed even under --auto-fix.+ */+async function checkPolicyDrift(targetDir, issues) {+ const gatePath = path.join(targetDir, 'gate.yaml');+ const safetyPath = path.join(targetDir, 'docs', 'safety.md');+ const gateRaw = await readFileContent(gatePath);+ const safetyRaw = await readFileContent(safetyPath);+ // Missing gate.yaml is already reported by the required-files check, and a+ // project with no docs/safety.md has no prose policy to drift from.+ if (!gateRaw || !safetyRaw)+ return;+ const gate = extractGateDenylist(gateRaw);+ const safety = extractSafetyDenylist(safetyRaw);+ if (!gate) {+ // loop-gate reports malformed gate files in detail; just point at it.+ issues.push({+ type: 'inconsistent',+ file: 'gate.yaml',+ message: 'gate.yaml has no readable denylist — cannot verify it matches docs/safety.md',+ severity: 'warning',+ suggestion: "Run 'npx @cobusgreyling/loop-gate check --action commit --paths .' to see the parse error",+ });+ return;+ }+ if (!safety) {+ issues.push({+ type: 'inconsistent',+ file: 'docs/safety.md',+ message: 'docs/safety.md has no "Path Denylist" code block to compare against gate.yaml',+ severity: 'info',+ suggestion: 'Document the denylist in docs/safety.md so the enforced policy has a prose twin',+ });+ return;+ }+ const drift = comparePolicies(safety, gate, findUndocumentedLimits(gateRaw, safetyRaw));+ if (!hasDrift(drift))+ return;+ // Documented-but-unenforced is the dangerous direction: readers trust+ // safety.md while loop-gate silently allows the path.+ if (drift.missingInGate.length > 0) {+ issues.push({+ type: 'inconsistent',+ file: 'gate.yaml ↔ docs/safety.md',+ message: `${drift.missingInGate.length} denylist ${plural(drift.missingInGate.length, 'path')} documented in docs/safety.md but not enforced by gate.yaml: ${drift.missingInGate.join(', ')}`,+ severity: 'error',+ suggestion: 'Add these entries to gate.yaml\'s denylist, or remove them from docs/safety.md if intentional',+ });+ }+ if (drift.missingInDoc.length > 0) {+ issues.push({+ type: 'inconsistent',+ file: 'gate.yaml ↔ docs/safety.md',+ message: `${drift.missingInDoc.length} denylist ${plural(drift.missingInDoc.length, 'path')} enforced by gate.yaml but undocumented in docs/safety.md: ${drift.missingInDoc.join(', ')}`,+ severity: 'warning',+ suggestion: 'Add these entries to the Path Denylist block in docs/safety.md so humans see what is blocked',+ });+ }+ if (drift.undocumentedLimits.length > 0) {+ issues.push({+ type: 'inconsistent',+ file: 'gate.yaml ↔ docs/safety.md',+ message: `gate.yaml sets ${drift.undocumentedLimits.join(', ')} but docs/safety.md never states this limit`,+ severity: 'info',+ suggestion: 'Document the limit in docs/safety.md so the escalation threshold is discoverable',+ });+ }+}+function plural(n, word) {+ return n === 1 ? word : `${word}s`;+}diff --git a/tools/loop-sync/package-lock.json b/tools/loop-sync/package-lock.jsonindex d08609a..565af4b 100644--- a/tools/loop-sync/package-lock.json+++ b/tools/loop-sync/package-lock.json@@ -8,6 +8,9 @@"name": "@cobusgreyling/loop-sync","version": "1.0.0","license": "MIT",+ "dependencies": {+ "yaml": "^2.8.0"+ },"bin": {"loop-sync": "dist/cli.js"},@@ -49,6 +52,21 @@"integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==","dev": true,"license": "MIT"+ },+ "node_modules/yaml": {+ "version": "2.9.0",+ "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",+ "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==",+ "license": "ISC",+ "bin": {+ "yaml": "bin.mjs"+ },+ "engines": {+ "node": ">= 14.6"+ },+ "funding": {+ "url": "https://github.com/sponsors/eemeli"+ }}}}diff --git a/tools/loop-sync/package.json b/tools/loop-sync/package.jsonindex 8cb4316..f494986 100644--- a/tools/loop-sync/package.json+++ b/tools/loop-sync/package.json@@ -1,7 +1,7 @@{"name": "@cobusgreyling/loop-sync","version": "1.0.0",- "description": "Detect and sync drift between Loop configuration files (STATE.md ↔ LOOP.md, Skills versions)",+ "description": "Detect and sync drift between Loop configuration files (STATE.md ↔ LOOP.md, gate.yaml ↔ docs/safety.md, Skills versions)","type": "module","main": "dist/cli.js","bin": {@@ -13,14 +13,16 @@],"scripts": {"build": "tsc",- "test": "npm run build && node --test test/sync.test.mjs",+ "test": "npm run build && node --test test/*.test.mjs","prepublishOnly": "npm test"},"keywords": ["loop-engineering","sync","drift-detection",- "configuration"+ "configuration",+ "safety",+ "policy"],"author": "Cobus Greyling","license": "MIT",@@ -39,5 +41,8 @@"devDependencies": {"@types/node": "^22.0.0","typescript": "^5.9.3"+ },+ "dependencies": {+ "yaml": "^2.8.0"}-}\ No newline at end of file+}diff --git a/tools/loop-sync/src/policy-drift.ts b/tools/loop-sync/src/policy-drift.tsnew file mode 100644index 0000000..6e5b95d--- /dev/null+++ b/tools/loop-sync/src/policy-drift.ts@@ -0,0 +1,164 @@+/**+ * gate.yaml <-> docs/safety.md policy drift detection.+ *+ * docs/safety.md's "Path Denylist" fenced block is the prose policy; gate.yaml+ * is its machine-readable twin that loop-gate actually enforces. gate.yaml says+ * "Keep in sync with docs/safety.md when either changes" -- but nothing checked+ * it, so the two could silently diverge and leave loop-gate approving paths the+ * documented policy forbids. This module makes that invariant mechanical.+ *+ * Deliberately read-only: a divergence is a human decision (which side is+ * right?), so we never auto-fix a safety policy.+ */++import { parse } from 'yaml';++/** Where a denylist was read from, for message text. */+export interface DenylistSource {+ patterns: string[];+ /** Entries the parser saw but could not use, e.g. non-string YAML nodes. */+ malformed: string[];+}++export interface PolicyDrift {+ /** In docs/safety.md but absent from gate.yaml -- enforcement is weaker than the doc. */+ missingInGate: string[];+ /** In gate.yaml but absent from docs/safety.md -- enforcement is undocumented. */+ missingInDoc: string[];+ /** gate.yaml limits that the prose policy never states. */+ undocumentedLimits: string[];+}++const DENYLIST_HEADING = /^#{1,6}\s+Path Denylist\s*$/im;+const FENCE = /^\s*```/;++/**+ * Pull the denylist globs out of docs/safety.md.+ *+ * Takes the first fenced block after the "Path Denylist" heading. Strips inline+ * `#` comments (safety.md annotates entries, e.g.+ * `**\/migrations/** # unless explicit migration loop`).+ *+ * Returns null when the heading or its code block is absent, so callers can+ * tell "no policy documented" apart from "policy documented as empty".+ */+export function extractSafetyDenylist(markdown: string): DenylistSource | null {+ const heading = DENYLIST_HEADING.exec(markdown);+ if (!heading) return null;++ const after = markdown.slice(heading.index + heading[0].length);+ const lines = after.split(/\r?\n/);++ let start = -1;+ for (let i = 0; i < lines.length; i++) {+ if (FENCE.test(lines[i])) {+ start = i + 1;+ break;+ }+ // A following heading before any fence means the section has no code block.+ if (/^#{1,6}\s/.test(lines[i])) return null;+ }+ if (start === -1) return null;++ const patterns: string[] = [];+ for (let i = start; i < lines.length; i++) {+ if (FENCE.test(lines[i])) {+ return { patterns, malformed: [] };+ }+ const entry = stripComment(lines[i]);+ if (entry) patterns.push(entry);+ }+ // Unterminated fence -- treat as unparseable rather than guessing.+ return null;+}++function stripComment(line: string): string {+ const hash = line.indexOf('#');+ // A leading '#' is a whole-line comment; '**/#foo' is not a glob we expect.+ const withoutComment = hash === -1 ? line : line.slice(0, hash);+ return withoutComment.trim();+}++/**+ * Pull denylist + limits out of gate.yaml. Returns null when the file is not+ * valid YAML or has no denylist -- loop-gate reports those itself, and we do+ * not want to double-report a broken gate file as a drift error.+ */+export function extractGateDenylist(yamlText: string): DenylistSource | null {+ let parsed: unknown;+ try {+ parsed = parse(yamlText);+ } catch {+ return null;+ }+ if (!parsed || typeof parsed !== 'object') return null;++ const denylist = (parsed as { denylist?: unknown }).denylist;+ if (!Array.isArray(denylist)) return null;++ const patterns: string[] = [];+ const malformed: string[] = [];+ for (const entry of denylist) {+ if (typeof entry === 'string' && entry.trim()) {+ patterns.push(entry.trim());+ } else {+ malformed.push(String(entry));+ }+ }+ return { patterns, malformed };+}++/** gate.yaml numeric limits that should also appear in the prose policy. */+export function findUndocumentedLimits(yamlText: string, markdown: string): string[] {+ let parsed: unknown;+ try {+ parsed = parse(yamlText);+ } catch {+ return [];+ }+ if (!parsed || typeof parsed !== 'object') return [];++ const limits: string[] = [];+ const maxFiles = (parsed as { maxFiles?: unknown }).maxFiles;+ if (typeof maxFiles === 'number' && !mentionsMaxFiles(markdown, maxFiles)) {+ limits.push(`maxFiles: ${maxFiles}`);+ }+ return limits;+}++function mentionsMaxFiles(markdown: string, value: number): boolean {+ if (/maxFiles/i.test(markdown)) return true;+ // Accept prose phrasings like "more than 10 files" / "10 changed files".+ // String.raw so the escapes reach RegExp intact -- a plain template literal+ // would turn \b into a backspace character.+ const prose = String.raw`\b${value}\b[^.\n]{0,24}\bfiles?\b`;+ return new RegExp(prose, 'i').test(markdown);+}++/**+ * Compare the two policies. Comparison is exact string equality on the trimmed+ * glob: two globs can be semantically equivalent while differing textually+ * (`**\/auth/**` vs `**\/auth/*`), and for a safety policy we want the doc and+ * the enforced file to read identically, not merely overlap.+ */+export function comparePolicies(+ safety: DenylistSource,+ gate: DenylistSource,+ undocumentedLimits: string[] = [],+): PolicyDrift {+ const gateSet = new Set(gate.patterns);+ const safetySet = new Set(safety.patterns);+ return {+ missingInGate: safety.patterns.filter((p) => !gateSet.has(p)),+ missingInDoc: gate.patterns.filter((p) => !safetySet.has(p)),+ undocumentedLimits,+ };+}++export function hasDrift(drift: PolicyDrift): boolean {+ return (+ drift.missingInGate.length > 0 ||+ drift.missingInDoc.length > 0 ||+ drift.undocumentedLimits.length > 0+ );+}diff --git a/tools/loop-sync/src/sync.ts b/tools/loop-sync/src/sync.tsindex 12238e5..5a5d52a 100644--- a/tools/loop-sync/src/sync.ts+++ b/tools/loop-sync/src/sync.ts@@ -11,6 +11,13 @@import { readFile, writeFile, access, mkdir } from 'node:fs/promises';import { readdir, stat } from 'node:fs/promises';import path from 'node:path';+import {+ comparePolicies,+ extractGateDenylist,+ extractSafetyDenylist,+ findUndocumentedLimits,+ hasDrift,+} from './policy-drift.js';export interface DriftReport {score: number; // 0-100 consistency score@@ -442,6 +449,11 @@ export async function runSync(options: SyncOptions): Promise<DriftReport> {}}+ // Check gate.yaml ↔ docs/safety.md policy parity. gate.yaml is the+ // machine-readable twin of safety.md's Path Denylist; if they drift,+ // loop-gate enforces something other than the documented policy.+ await checkPolicyDrift(targetDir, issues);+// Scan skills for version informationconst skillsVersions = await scanSkillsDirectory(targetDir);@@ -548,4 +560,85 @@ export function formatReport(report: DriftReport): string {}return lines.join('\n');-}\ No newline at end of file+}+/**+ * Compare docs/safety.md's Path Denylist against gate.yaml and record any+ * divergence. Read-only by design: which side is correct is a human call, so+ * this is never auto-fixed even under --auto-fix.+ */+async function checkPolicyDrift(targetDir: string, issues: DriftIssue[]): Promise<void> {+ const gatePath = path.join(targetDir, 'gate.yaml');+ const safetyPath = path.join(targetDir, 'docs', 'safety.md');++ const gateRaw = await readFileContent(gatePath);+ const safetyRaw = await readFileContent(safetyPath);++ // Missing gate.yaml is already reported by the required-files check, and a+ // project with no docs/safety.md has no prose policy to drift from.+ if (!gateRaw || !safetyRaw) return;++ const gate = extractGateDenylist(gateRaw);+ const safety = extractSafetyDenylist(safetyRaw);++ if (!gate) {+ // loop-gate reports malformed gate files in detail; just point at it.+ issues.push({+ type: 'inconsistent',+ file: 'gate.yaml',+ message: 'gate.yaml has no readable denylist — cannot verify it matches docs/safety.md',+ severity: 'warning',+ suggestion: "Run 'npx @cobusgreyling/loop-gate check --action commit --paths .' to see the parse error",+ });+ return;+ }++ if (!safety) {+ issues.push({+ type: 'inconsistent',+ file: 'docs/safety.md',+ message: 'docs/safety.md has no "Path Denylist" code block to compare against gate.yaml',+ severity: 'info',+ suggestion: 'Document the denylist in docs/safety.md so the enforced policy has a prose twin',+ });+ return;+ }++ const drift = comparePolicies(safety, gate, findUndocumentedLimits(gateRaw, safetyRaw));+ if (!hasDrift(drift)) return;++ // Documented-but-unenforced is the dangerous direction: readers trust+ // safety.md while loop-gate silently allows the path.+ if (drift.missingInGate.length > 0) {+ issues.push({+ type: 'inconsistent',+ file: 'gate.yaml ↔ docs/safety.md',+ message: `${drift.missingInGate.length} denylist ${plural(drift.missingInGate.length, 'path')} documented in docs/safety.md but not enforced by gate.yaml: ${drift.missingInGate.join(', ')}`,+ severity: 'error',+ suggestion: 'Add these entries to gate.yaml\'s denylist, or remove them from docs/safety.md if intentional',+ });+ }++ if (drift.missingInDoc.length > 0) {+ issues.push({+ type: 'inconsistent',+ file: 'gate.yaml ↔ docs/safety.md',+ message: `${drift.missingInDoc.length} denylist ${plural(drift.missingInDoc.length, 'path')} enforced by gate.yaml but undocumented in docs/safety.md: ${drift.missingInDoc.join(', ')}`,+ severity: 'warning',+ suggestion: 'Add these entries to the Path Denylist block in docs/safety.md so humans see what is blocked',+ });+ }++ if (drift.undocumentedLimits.length > 0) {+ issues.push({+ type: 'inconsistent',+ file: 'gate.yaml ↔ docs/safety.md',+ message: `gate.yaml sets ${drift.undocumentedLimits.join(', ')} but docs/safety.md never states this limit`,+ severity: 'info',+ suggestion: 'Document the limit in docs/safety.md so the escalation threshold is discoverable',+ });+ }+}++function plural(n: number, word: string): string {+ return n === 1 ? word : `${word}s`;+}diff --git a/tools/loop-sync/test/policy-drift.test.mjs b/tools/loop-sync/test/policy-drift.test.mjsnew file mode 100644index 0000000..0014679--- /dev/null+++ b/tools/loop-sync/test/policy-drift.test.mjs@@ -0,0 +1,200 @@+import { test, describe } from 'node:test';+import assert from 'node:assert/strict';+import path from 'node:path';+import { mkdir, writeFile, rm, readFile } from 'node:fs/promises';+import {+ extractSafetyDenylist,+ extractGateDenylist,+ comparePolicies,+ findUndocumentedLimits,+ hasDrift,+} from '../dist/policy-drift.js';+import { runSync } from '../dist/sync.js';++const REPO_ROOT = path.resolve(import.meta.dirname, '../../..');+const FENCE = '```';++const SAFETY_MD = [+ '# Safety & Guardrails',+ '',+ '## Path Denylist',+ '',+ 'The loop must **never** auto-edit these without human approval:',+ '',+ FENCE,+ '**/.env',+ '**/secrets/**',+ '**/migrations/** # unless explicit migration loop',+ FENCE,+ '',+ '## Auto-Merge Policy',+ '',+].join('\n');++const GATE_YAML = [+ 'version: 1',+ '',+ 'denylist:',+ ' - "**/.env"',+ ' - "**/secrets/**"',+ ' - "**/migrations/**"',+ '',+ 'maxFiles: 10',+ '',+].join('\n');++describe('extractSafetyDenylist', () => {+ test('pulls globs from the Path Denylist fenced block', () => {+ const result = extractSafetyDenylist(SAFETY_MD);+ assert.deepEqual(result.patterns, ['**/.env', '**/secrets/**', '**/migrations/**']);+ });++ test('strips inline comments so annotated entries still compare equal', () => {+ const result = extractSafetyDenylist(SAFETY_MD);+ assert.ok(!result.patterns.some((p) => p.includes('#')));+ assert.ok(result.patterns.includes('**/migrations/**'));+ });++ test('returns null when there is no Path Denylist heading', () => {+ assert.equal(extractSafetyDenylist('# Safety\n\n## Other\n\ntext\n'), null);+ });++ test('returns null when the heading has no code block before the next heading', () => {+ assert.equal(extractSafetyDenylist('## Path Denylist\n\nprose only\n\n## Next\n'), null);+ });++ test('returns null on an unterminated fence rather than guessing', () => {+ assert.equal(extractSafetyDenylist(`## Path Denylist\n\n${FENCE}\n**/.env\n`), null);+ });++ test('parses CRLF markdown', () => {+ const result = extractSafetyDenylist(SAFETY_MD.replace(/\n/g, '\r\n'));+ assert.deepEqual(result.patterns, ['**/.env', '**/secrets/**', '**/migrations/**']);+ });+});++describe('extractGateDenylist', () => {+ test('reads the denylist array', () => {+ const result = extractGateDenylist(GATE_YAML);+ assert.deepEqual(result.patterns, ['**/.env', '**/secrets/**', '**/migrations/**']);+ });++ test('returns null on invalid YAML instead of throwing', () => {+ assert.equal(extractGateDenylist('denylist: [unclosed'), null);+ });++ test('returns null when denylist is absent', () => {+ assert.equal(extractGateDenylist('version: 1\n'), null);+ });++ test('collects non-string entries as malformed rather than dropping them silently', () => {+ const result = extractGateDenylist('denylist:\n - "**/.env"\n - 42\n');+ assert.deepEqual(result.patterns, ['**/.env']);+ assert.deepEqual(result.malformed, ['42']);+ });+});++describe('comparePolicies', () => {+ test('reports no drift when the two agree', () => {+ const drift = comparePolicies(extractSafetyDenylist(SAFETY_MD), extractGateDenylist(GATE_YAML));+ assert.equal(hasDrift(drift), false);+ });++ test('flags a path documented in safety.md but not enforced by gate.yaml', () => {+ const gate = extractGateDenylist(GATE_YAML.replace(' - "**/secrets/**"\n', ''));+ const drift = comparePolicies(extractSafetyDenylist(SAFETY_MD), gate);+ assert.deepEqual(drift.missingInGate, ['**/secrets/**']);+ assert.equal(drift.missingInDoc.length, 0);+ assert.equal(hasDrift(drift), true);+ });++ test('flags a path enforced by gate.yaml but undocumented in safety.md', () => {+ const gate = extractGateDenylist(GATE_YAML.replace('\nmaxFiles', ' - "**/ssh/**"\n\nmaxFiles'));+ const drift = comparePolicies(extractSafetyDenylist(SAFETY_MD), gate);+ assert.deepEqual(drift.missingInDoc, ['**/ssh/**']);+ assert.equal(drift.missingInGate.length, 0);+ });+});++describe('findUndocumentedLimits', () => {+ test('flags maxFiles when the prose never states it', () => {+ assert.deepEqual(findUndocumentedLimits(GATE_YAML, SAFETY_MD), ['maxFiles: 10']);+ });++ test('accepts prose phrasing like "more than 10 files"', () => {+ const doc = `${SAFETY_MD}\nEscalate on more than 10 files changed.\n`;+ assert.deepEqual(findUndocumentedLimits(GATE_YAML, doc), []);+ });++ test('accepts a literal maxFiles mention', () => {+ const doc = `${SAFETY_MD}\ngate.yaml sets maxFiles.\n`;+ assert.deepEqual(findUndocumentedLimits(GATE_YAML, doc), []);+ });+});++describe('runSync policy drift integration', () => {+ const dir = path.join(process.cwd(), '.test-policy-tmp');+ const opts = { autoFix: false, dryRun: false, verbose: false };+ const policyIssues = (r) =>+ r.issues.filter((i) => i.file.includes('gate.yaml') || i.file.includes('safety.md'));++ async function seed(gate, safety) {+ await rm(dir, { recursive: true, force: true });+ await mkdir(path.join(dir, 'docs'), { recursive: true });+ for (const f of ['STATE.md', 'LOOP.md', 'AGENTS.md', 'loop-budget.md', 'loop-run-log.md']) {+ await writeFile(path.join(dir, f), '# stub\n');+ }+ if (gate !== null) await writeFile(path.join(dir, 'gate.yaml'), gate);+ if (safety !== null) await writeFile(path.join(dir, 'docs', 'safety.md'), safety);+ }++ test('is silent when gate.yaml and safety.md agree', async () => {+ await seed(GATE_YAML.replace('\nmaxFiles: 10\n', '\n'), SAFETY_MD);+ const report = await runSync({ targetDir: dir, ...opts });+ assert.deepEqual(policyIssues(report), []);+ await rm(dir, { recursive: true, force: true });+ });++ test('raises an error-severity issue for documented-but-unenforced paths', async () => {+ await seed(GATE_YAML.replace(' - "**/secrets/**"\n', ''), SAFETY_MD);+ const report = await runSync({ targetDir: dir, ...opts });+ const issue = report.issues.find(+ (i) => i.severity === 'error' && i.message.includes('not enforced'),+ );+ assert.ok(issue, 'expected an error issue for the unenforced path');+ assert.match(issue.message, /secrets/);+ await rm(dir, { recursive: true, force: true });+ });++ test('does not auto-fix a safety policy even with --auto-fix', async () => {+ const weakened = GATE_YAML.replace(' - "**/secrets/**"\n', '');+ await seed(weakened, SAFETY_MD);+ await runSync({ targetDir: dir, autoFix: true, dryRun: false, verbose: false });+ assert.equal(await readFile(path.join(dir, 'gate.yaml'), 'utf8'), weakened);+ await rm(dir, { recursive: true, force: true });+ });++ test('stays quiet when the project has no docs/safety.md', async () => {+ await seed(GATE_YAML, null);+ const report = await runSync({ targetDir: dir, ...opts });+ assert.deepEqual(+ policyIssues(report).filter((i) => i.type === 'inconsistent'),+ [],+ );+ await rm(dir, { recursive: true, force: true });+ });+});++describe('this repository', () => {+ test('gate.yaml denylist matches docs/safety.md (dogfood)', async () => {+ const gate = extractGateDenylist(await readFile(path.join(REPO_ROOT, 'gate.yaml'), 'utf8'));+ const safety = extractSafetyDenylist(+ await readFile(path.join(REPO_ROOT, 'docs/safety.md'), 'utf8'),+ );+ assert.ok(gate, 'repo gate.yaml should parse');+ assert.ok(safety, 'repo docs/safety.md should have a Path Denylist block');+ const drift = comparePolicies(safety, gate);+ assert.deepEqual(drift.missingInGate, [], 'safety.md documents paths gate.yaml does not enforce');+ assert.deepEqual(drift.missingInDoc, [], 'gate.yaml enforces paths safety.md does not document');+ });+});