@cobusgreyling/loop-gate 1.0.0

package/README.md

@@ -0,0 +1,72 @@
+# loop-gate
+
+Mechanical enforcement of static safety policy — the code behind `docs/safety.md`'s Path Denylist and Auto-Merge Policy, and `LOOP.md`'s *"No auto-merge on main except trivial dependency patches"* / *"Denylist... without human review"* rules. Nothing evaluated a proposed change against that prose before; `loop-gate` does.
+
+Deliberately has **no knowledge of run history**. Stagnation, repeated failures, and token/daily budgets already belong to [`loop-context`](../loop-context)'s circuit breaker — `loop-gate` only looks at *what* is being proposed (which paths, what action type), not *how the run has behaved so far*. Chain the two:
+
+```bash
+loop-context --check --ledger run.json ...            || exit 2   # run-history based
+loop-gate check --action auto-merge --paths a.ts,b.ts  || exit 2   # policy based
+do-the-merge
+```
+
+## Install & Run
+
+```bash
+npx @cobusgreyling/loop-gate check --action auto-merge --paths docs/guide.md
+```
+
+**From this repo:**
+
+```bash
+cd tools/loop-gate
+npm install
+npm test
+```
+
+## Usage
+
+```bash
+loop-gate check --action <commit|merge|auto-merge> --paths <f1,f2,...> [--gate-file gate.yaml] [--json]
+```
+
+| Flag | Default | Meaning |
+|------|---------|---------|
+| `--action <commit\|merge\|auto-merge>` | required | What the loop is about to do |
+| `--paths <f1,f2,...>` | required | Comma-separated changed file paths |
+| `--gate-file <path>` | `gate.yaml` (cwd) | Policy file to evaluate against |
+| `--json` | off | Machine-readable decision output |
+
+Exit codes: `0` allowed · `2` escalate · `1` error (bad flags, missing/invalid config).
+
+## Policy file
+
+`gate.yaml` is the machine-readable twin of `docs/safety.md` — see [`templates/gate.yaml.template`](../../templates/gate.yaml.template) to scaffold your own, or this repo's own dogfood [`gate.yaml`](../../gate.yaml):
+
+```yaml
+version: 1
+denylist:
+  - ".env"
+  - "**/secrets/**"
+  - "auth/**"
+maxFiles: 10
+autoMergeAllowlist:
+  - "docs/**"
+  - "**/*.md"
+```
+
+Checked in order (first match wins, same "most specific trigger first" convention `loop-context`'s circuit breaker uses):
+
+1. **`denylist`** — any changed path matching a glob here escalates, regardless of `--action`.
+2. **`maxFiles`** — more changed paths than this escalates (matches `docs/safety.md`'s "Changes touching >N files" human gate).
+3. **`autoMergeAllowlist`** — only checked when `--action auto-merge`; every changed path must match one of these globs, or it escalates.
+
+Glob matching is via [`minimatch`](https://www.npmjs.com/package/minimatch) (the same semantics `.gitignore`-style globs use — `**` matches across path segments).
+
+## What this does not do
+
+- Does not read a run ledger, and never will — that keeps it decoupled from `loop-context` at the source level, the same way `loop-worktree` and `loop-context` stay independent while still being paired by convention in a control script.
+- Does not produce its own escalation summary format — fold its JSON decision into whatever your control script already assembles from `loop-context --inject` when escalating to a human.
+- Does not enforce anything by itself — like `loop-worktree`'s locks, this is advisory: a control script that skips calling `loop-gate` is not physically blocked. The mechanism is only as good as the scripts that call it.
+
+See [docs/safety.md](../../docs/safety.md) for the policy this codifies, and [docs/primitives.md](../../docs/primitives.md) for where safety gates fit in the Five Building Blocks + Memory model.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import { checkGate, loadGateConfig, assertValidAction, } from './gate.js';
+function parseFlags(argv) {
+    const flags = { help: false, gateFile: 'gate.yaml', json: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--help' || a === '-h')
+            flags.help = true;
+        else if (a === '--action')
+            flags.action = argv[++i];
+        else if (a === '--paths')
+            flags.paths = argv[++i];
+        else if (a === '--gate-file')
+            flags.gateFile = argv[++i];
+        else if (a === '--json')
+            flags.json = true;
+    }
+    return flags;
+}
+const HELP = `loop-gate — mechanical enforcement of static safety policy
+
+Evaluates a proposed change (action type + changed paths) against
+gate.yaml's denylist, max-files, and auto-merge allowlist. No knowledge of
+run history — pair with loop-context --check for stagnation/budget triggers.
+
+Usage:
+  loop-gate check --action <commit|merge|auto-merge> --paths <f1,f2,...> [options]
+
+Options:
+  --action <commit|merge|auto-merge>   What the loop is about to do
+  --paths <f1,f2,...>                  Comma-separated changed file paths
+  --gate-file <path>                   Policy file (default: gate.yaml)
+  --json                               Machine-readable output
+  -h, --help                           This help
+
+Exit codes: 0 allowed · 2 escalate · 1 error
+
+Example:
+  loop-gate check --action auto-merge --paths $(git diff --name-only | tr '\\n' ',')
+`;
+async function main() {
+    const argv = process.argv.slice(2);
+    const command = argv[0];
+    if (!command || command === '--help' || command === '-h') {
+        console.log(HELP);
+        return command ? 0 : 1;
+    }
+    if (command !== 'check') {
+        console.error(`Unknown command "${command}".\n\n${HELP}`);
+        return 1;
+    }
+    const flags = parseFlags(argv.slice(1));
+    if (flags.help) {
+        console.log(HELP);
+        return 0;
+    }
+    if (!flags.action || !flags.paths) {
+        throw new Error('check requires --action and --paths.');
+    }
+    assertValidAction(flags.action);
+    const config = await loadGateConfig(flags.gateFile);
+    const paths = flags.paths.split(',').map((p) => p.trim()).filter(Boolean);
+    if (paths.length === 0) {
+        throw new Error('--paths must contain at least one non-empty path.');
+    }
+    const decision = checkGate({ config, action: flags.action, paths });
+    if (flags.json) {
+        console.log(JSON.stringify(decision, null, 2));
+    }
+    else {
+        console.log(`${decision.allowed ? 'ALLOWED' : 'ESCALATE'} [${decision.trigger}] — ${decision.reason}`);
+    }
+    return decision.allowed ? 0 : 2;
+}
+main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/gate.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Mechanical enforcement of static policy (path denylist, auto-merge
+ * allowlist, max changed files) — the machine-readable twin of
+ * docs/safety.md's prose. Deliberately has no knowledge of run history
+ * (stagnation, repeat failures): that already belongs to loop-context's
+ * circuit breaker and must not be duplicated here.
+ */
+export type Action = 'commit' | 'merge' | 'auto-merge';
+export declare const VALID_ACTIONS: Action[];
+export declare function assertValidAction(action: string): asserts action is Action;
+export interface GateConfig {
+    version: 1;
+    /** Glob patterns that must never be touched without human approval. */
+    denylist: string[];
+    /** Escalate when more than this many paths are in the proposed change. */
+    maxFiles?: number;
+    /** For --action auto-merge: every path must match one of these globs. */
+    autoMergeAllowlist?: string[];
+}
+export declare function loadGateConfig(file: string): Promise<GateConfig>;
+export type GateTrigger = 'ok' | 'denylist' | 'file-count' | 'not-allowlisted';
+export interface GateDecision {
+    allowed: boolean;
+    trigger: GateTrigger;
+    reason: string;
+    /** Paths responsible for the trigger (empty when trigger is 'ok'). */
+    matchedPaths: string[];
+}
+export interface CheckInput {
+    config: GateConfig;
+    action: Action;
+    paths: string[];
+}
+/**
+ * Evaluate a proposed change against static policy. Checks the cheapest and
+ * most severe condition first (denylist), then file-count, then the
+ * auto-merge allowlist — mirroring loop-context's checkCircuitBreaker
+ * "most specific trigger first" ordering.
+ *
+ * All glob matching uses minimatch's `dot: true` — without it, `*` never
+ * matches a path segment starting with `.`, so denylist entries like
+ * `**\/secrets/**` or `**\/*_key*` would silently miss `.secrets/prod.json`
+ * or `.aws_key`, exactly the paths a denylist most needs to catch.
+ */
+export declare function checkGate(input: CheckInput): GateDecision;

package/dist/gate.js

@@ -0,0 +1,99 @@
+/**
+ * Mechanical enforcement of static policy (path denylist, auto-merge
+ * allowlist, max changed files) — the machine-readable twin of
+ * docs/safety.md's prose. Deliberately has no knowledge of run history
+ * (stagnation, repeat failures): that already belongs to loop-context's
+ * circuit breaker and must not be duplicated here.
+ */
+import { readFile } from 'node:fs/promises';
+import { parse } from 'yaml';
+import { minimatch } from 'minimatch';
+export const VALID_ACTIONS = ['commit', 'merge', 'auto-merge'];
+export function assertValidAction(action) {
+    if (!VALID_ACTIONS.includes(action)) {
+        throw new Error(`Invalid --action: ${action}. Use one of: ${VALID_ACTIONS.join(', ')}.`);
+    }
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((v) => typeof v === 'string');
+}
+export async function loadGateConfig(file) {
+    let raw;
+    try {
+        raw = await readFile(file, 'utf8');
+    }
+    catch {
+        throw new Error(`Gate config not found: ${file}. Create one (see templates/gate.yaml.template) or pass --gate-file <path>.`);
+    }
+    let parsed;
+    try {
+        parsed = parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Invalid YAML in ${file}: ${err.message}`);
+    }
+    const config = parsed;
+    const invalid = (detail) => new Error(`Invalid gate config at ${file}: ${detail}`);
+    if (!config || config.version !== 1) {
+        throw invalid('expected { version: 1, denylist: string[], ... }.');
+    }
+    if (!isStringArray(config.denylist)) {
+        throw invalid('"denylist" must be an array of strings.');
+    }
+    if (config.maxFiles !== undefined && (typeof config.maxFiles !== 'number' || !Number.isFinite(config.maxFiles))) {
+        throw invalid('"maxFiles" must be a number.');
+    }
+    if (config.autoMergeAllowlist !== undefined && !isStringArray(config.autoMergeAllowlist)) {
+        throw invalid('"autoMergeAllowlist" must be an array of strings.');
+    }
+    return config;
+}
+/**
+ * Evaluate a proposed change against static policy. Checks the cheapest and
+ * most severe condition first (denylist), then file-count, then the
+ * auto-merge allowlist — mirroring loop-context's checkCircuitBreaker
+ * "most specific trigger first" ordering.
+ *
+ * All glob matching uses minimatch's `dot: true` — without it, `*` never
+ * matches a path segment starting with `.`, so denylist entries like
+ * `**\/secrets/**` or `**\/*_key*` would silently miss `.secrets/prod.json`
+ * or `.aws_key`, exactly the paths a denylist most needs to catch.
+ */
+export function checkGate(input) {
+    const { config, action, paths } = input;
+    const denylistHits = paths.filter((p) => config.denylist.some((glob) => minimatch(p, glob, { dot: true })));
+    if (denylistHits.length > 0) {
+        return {
+            allowed: false,
+            trigger: 'denylist',
+            reason: `${denylistHits.length} path(s) match the denylist: ${denylistHits.join(', ')}. Escalating for human review.`,
+            matchedPaths: denylistHits,
+        };
+    }
+    if (config.maxFiles !== undefined && paths.length > config.maxFiles) {
+        return {
+            allowed: false,
+            trigger: 'file-count',
+            reason: `${paths.length} changed file(s) exceeds the max-files threshold (${config.maxFiles}). Escalating for human review.`,
+            matchedPaths: paths,
+        };
+    }
+    if (action === 'auto-merge') {
+        const allowlist = config.autoMergeAllowlist ?? [];
+        const notAllowlisted = paths.filter((p) => !allowlist.some((glob) => minimatch(p, glob, { dot: true })));
+        if (notAllowlisted.length > 0) {
+            return {
+                allowed: false,
+                trigger: 'not-allowlisted',
+                reason: `${notAllowlisted.length} path(s) are not on the auto-merge allowlist: ${notAllowlisted.join(', ')}. Escalating for human review.`,
+                matchedPaths: notAllowlisted,
+            };
+        }
+    }
+    return {
+        allowed: true,
+        trigger: 'ok',
+        reason: 'Within policy — cleared to proceed.',
+        matchedPaths: [],
+    };
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@cobusgreyling/loop-gate",
+  "version": "1.0.0",
+  "description": "Mechanical enforcement of LOOP.md/docs/safety.md's path denylist and auto-merge allowlist — evaluate a proposed change against static policy and block or allow it.",
+  "type": "module",
+  "main": "dist/gate.js",
+  "exports": {
+    ".": "./dist/gate.js"
+  },
+  "bin": {
+    "loop-gate": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepublishOnly": "npm test",
+    "start": "node dist/cli.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "loop-engineering",
+    "ai-agents",
+    "coding-agents",
+    "safety",
+    "policy",
+    "auto-merge",
+    "claude-code",
+    "grok",
+    "devtools"
+  ],
+  "author": "Cobus Greyling",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cobusgreyling/loop-engineering.git",
+    "directory": "tools/loop-gate"
+  },
+  "homepage": "https://cobusgreyling.github.io/loop-engineering/",
+  "bugs": {
+    "url": "https://github.com/cobusgreyling/loop-engineering/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "minimatch": "^10.0.0",
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}