Skip to content

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.

feat(loop-sync): detect gate.yaml <-> docs/safety.md policy drift (#599)

THRISHAL DOMAcc20ebe73794
diff --git a/docs/safety.md b/docs/safety.md
index 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 f
exits `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.md
index 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
- Inconsistencies
diff --git a/tools/loop-sync/dist/policy-drift.d.ts b/tools/loop-sync/dist/policy-drift.d.ts
new file mode 100644
index 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.js
new file mode 100644
index 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.js
index 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 information
const 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.json
index 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.json
index 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.ts
new file mode 100644
index 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.ts
index 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 information
const 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.mjs
new file mode 100644
index 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');
+ });
+});