@ketecode/loom 0.0.0-stage → 0.2.0

package/hooks/format-on-edit/hook.js

@@ -0,0 +1,89 @@
+'use strict';
+
+// After the agent edits files, formats each one with the formatter the project already uses.
+// Never formats with a tool the project hasn't chosen, never touches files outside the project,
+// never fails the edit. check({ files: [{ path }], cwd }) -> {}
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const TIMEOUT_MS = 15000;
+const WEB = /\.(?:[cm]?[jt]sx?|json|jsonc|css|scss|less|html|vue|svelte|astro|md|mdx|ya?ml|graphql)$/;
+
+const exists = (p) => fs.existsSync(p);
+const read = (p) => {
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch {
+    return '';
+  }
+};
+
+function onPath(bin) {
+  const exts = process.platform === 'win32' ? (process.env.PATHEXT || '.EXE;.CMD').split(';') : [''];
+  for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+    for (const ext of exts) if (dir && exists(path.join(dir, bin + ext))) return path.join(dir, bin + ext);
+  }
+  return null;
+}
+
+// Nearest folder at or above `from` (but not above `root`) that contains `marker`.
+function nearest(from, root, marker) {
+  for (let dir = from; ; dir = path.dirname(dir)) {
+    if (exists(path.join(dir, marker))) return dir;
+    if (dir === root || dir === path.dirname(dir)) return null;
+  }
+}
+
+function localBin(from, root, name) {
+  const dir = nearest(from, root, path.join('node_modules', '.bin', name));
+  return dir && path.join(dir, 'node_modules', '.bin', name);
+}
+
+// Returns [program, args] for the project's formatter for this file, or null.
+function formatterFor(file, root) {
+  const dir = path.dirname(file);
+  if (WEB.test(file)) {
+    const biomeDir = nearest(dir, root, 'biome.json') || nearest(dir, root, 'biome.jsonc');
+    const biome = biomeDir && localBin(dir, root, 'biome');
+    if (biome) return [biome, ['format', '--write', file]];
+    const prettier = localBin(dir, root, 'prettier');
+    if (prettier) return [prettier, ['--write', '--log-level', 'warn', file]];
+    return null;
+  }
+  if (file.endsWith('.py')) {
+    const pyproject = read(path.join(nearest(dir, root, 'pyproject.toml') || '', 'pyproject.toml'));
+    const ruffConfig = /\[tool\.ruff/.test(pyproject) || nearest(dir, root, 'ruff.toml') || nearest(dir, root, '.ruff.toml');
+    if (ruffConfig && onPath('ruff')) return [onPath('ruff'), ['format', file]];
+    if (/\[tool\.black/.test(pyproject) && onPath('black')) return [onPath('black'), ['-q', file]];
+    return null;
+  }
+  if (file.endsWith('.go') && onPath('gofmt')) return [onPath('gofmt'), ['-w', file]];
+  if (file.endsWith('.rs') && onPath('rustfmt')) {
+    const cargo = nearest(dir, root, 'Cargo.toml');
+    const edition = (/^\s*edition\s*=\s*"(\d{4})"/m.exec(read(path.join(cargo || '', 'Cargo.toml'))) || [])[1];
+    return [onPath('rustfmt'), [...(edition ? ['--edition', edition] : []), file]];
+  }
+  return null;
+}
+
+function check(event) {
+  const root = path.resolve(event.cwd || process.cwd());
+  for (const f of event.files || []) {
+    if (!f || typeof f.path !== 'string') continue;
+    const file = path.resolve(root, f.path);
+    const rel = path.relative(root, file);
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel) || !exists(file)) continue;
+    const fmt = formatterFor(file, root);
+    if (!fmt) continue;
+    try {
+      execFileSync(fmt[0], fmt[1], { cwd: root, stdio: 'ignore', timeout: TIMEOUT_MS });
+    } catch {
+      // A formatter error (syntax error mid-edit, missing plugin) must never fail the edit.
+    }
+  }
+  return {};
+}
+
+module.exports = { check, formatterFor };

package/hooks/guard-secrets/HOOK.md

@@ -0,0 +1,19 @@
+---
+name: guard-secrets
+description: Stops the agent from writing API keys, tokens, passwords, connection strings or private keys into files, using the same rules as the security-review secret scanner.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: security
+  kete-loom/risk: read-only
+  kete-loom/event: "pre-edit"
+  kete-loom/owner: "Kete-org"
+---
+
+# Guard secrets
+
+Runs before every file write or edit and checks the new text for secrets: AWS, GitHub, Anthropic, OpenAI, Paystack, Stripe, Slack and Google keys, private key blocks, JWTs, connection strings with passwords, and hard-coded `password`/`api_key`/`token` assignments. If it finds one, the edit is refused and the agent is told to read the value from an environment variable or secret store.
+
+Placeholders such as `<your-api-key>`, `${API_KEY}`, `process.env...`, `changeme` or `your_key_here` are allowed. The reason message masks the value, so the secret isn't echoed back.
+
+It uses the same rules as `skills/security-review/scripts/scan-secrets.js`, which a test keeps in sync. Not available in Cursor, which has no documented hook before an edit.

package/hooks/guard-secrets/cases.json

@@ -0,0 +1,110 @@
+{
+  "should_block": [
+    {
+      "files": [
+        {
+          "path": "src/pay.ts",
+          "content": "const key = 'sk_live_{{repeat:a:40}}';"
+        }
+      ]
+    },
+    {
+      "files": [
+        {
+          "path": "config.py",
+          "content": "AWS_KEY = 'AKIA{{repeat:Q:16}}'"
+        }
+      ]
+    },
+    {
+      "files": [
+        {
+          "path": "app.js",
+          "content": "const k = process.env.KEY || 'sk_live_{{repeat:b:40}}'"
+        }
+      ]
+    },
+    {
+      "files": [
+        {
+          "path": "ci.yml",
+          "content": "token: ghp_{{repeat:a:36}}"
+        }
+      ]
+    },
+    {
+      "files": [
+        {
+          "path": "db.ts",
+          "content": "const url = 'postgres://admin:hunter2pass@db.internal:5432/app'"
+        }
+      ]
+    },
+    {
+      "files": [
+        {
+          "path": "keys/deploy",
+          "content": "{{repeat:-:5}}BEGIN OPENSSH PRIVATE KEY{{repeat:-:5}}\nabc"
+        }
+      ]
+    },
+    {
+      "files": [
+        {
+          "path": "settings.json",
+          "content": "{ \"api_key\": \"q8Zr1xWm3Lp9TbV2\" }"
+        }
+      ]
+    }
+  ],
+  "should_allow": [
+    {
+      "files": [
+        {
+          "path": "src/pay.ts",
+          "content": "const key = process.env.PAYSTACK_SECRET_KEY"
+        }
+      ]
+    },
+    {
+      "files": [
+        {
+          "path": ".env.example",
+          "content": "PAYSTACK_SECRET_KEY=sk_test_your_key_here"
+        }
+      ]
+    },
+    {
+      "files": [
+        {
+          "path": "docs/setup.md",
+          "content": "Set api_key: \"<your-api-key>\" in config"
+        }
+      ]
+    },
+    {
+      "files": [
+        {
+          "path": "db.ts",
+          "content": "const url = `postgres://${user}:${pass}@${host}/app`"
+        }
+      ]
+    },
+    {
+      "files": [
+        {
+          "path": "README.md",
+          "content": "Get a key from the dashboard and export it."
+        }
+      ]
+    },
+    {
+      "files": [
+        {
+          "path": "test/fixtures.ts",
+          "content": "const password = 'changeme-in-tests'"
+        }
+      ]
+    }
+  ]
+}

package/hooks/guard-secrets/hook.js

@@ -0,0 +1,44 @@
+'use strict';
+
+// Blocks agent edits that would write a secret (API key, token, private key, password) into a file.
+// check({ files: [{ path, content }], cwd }) -> verdict. Content is the new text being written.
+
+// Same rules as skills/security-review/scripts/scan-secrets.js; tests/hooks.test.js keeps them in sync.
+const RULES = [
+  ['AWS access key', /\b(AKIA|ASIA)[0-9A-Z]{16}\b/],
+  ['GitHub token', /\b(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b|\bgithub_pat_[A-Za-z0-9_]{60,}\b/],
+  ['Anthropic API key', /\bsk-ant-[A-Za-z0-9_-]{20,}\b/],
+  ['OpenAI API key', /\bsk-(proj-)?[A-Za-z0-9_-]{32,}\b/],
+  ['Paystack secret key', /\bsk_(live|test)_[a-f0-9]{40}\b/],
+  ['Stripe live key', /\b(sk|rk)_live_[A-Za-z0-9]{20,}\b/],
+  ['Slack token', /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/],
+  ['Google API key', /\bAIza[0-9A-Za-z_-]{35}\b/],
+  ['Private key block', /-----BEGIN (RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/],
+  ['JWT', /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/],
+  ['Connection string with password', /\b(postgres(ql)?|mysql|mongodb(\+srv)?|redis|amqp):\/\/[^\s:@/]+:[^\s@/]{3,}@/i],
+  ['Hard-coded secret assignment', /\b(password|passwd|secret|api[_-]?key|access[_-]?token|auth[_-]?token)\b["']?\s*[:=]\s*["'][^"'\s]{8,}["']/i],
+];
+
+const PLACEHOLDER = /(example|placeholder|changeme|your[_-]|xxxx|dummy|fake|<[^>]+>|\$\{|process\.env|os\.environ)/i;
+
+const mask = (s) => (s.length <= 8 ? '****' : `${s.slice(0, 4)}…${s.slice(-2)} (${s.length} chars)`);
+
+function check(event) {
+  for (const file of event.files || []) {
+    if (!file || typeof file.content !== 'string') continue;
+    const lines = file.content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      for (const [label, re] of RULES) {
+        const m = re.exec(lines[i]);
+        if (!m || PLACEHOLDER.test(m[0])) continue;
+        return {
+          block: true,
+          reason: `Blocked by kete-loom (guard-secrets): this edit writes a ${label} (${mask(m[0])}) into ${file.path || 'a file'}. Read it from an environment variable or secret store instead, and if it is real, tell the user to rotate it.`,
+        };
+      }
+    }
+  }
+  return { block: false };
+}
+
+module.exports = { check, RULES };

package/hooks/load-session-context/HOOK.md

@@ -0,0 +1,20 @@
+---
+name: load-session-context
+description: At the start of each session, tells the agent the current branch, how many uncommitted changes there are, and the latest session handoff note, so it picks up where the last session stopped.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: meta
+  kete-loom/risk: runs-commands
+  kete-loom/event: "session-start"
+  kete-loom/owner: "Kete-org"
+---
+
+# Load session context
+
+Runs when a session starts, in a git repository only. It adds a short note to the agent's context:
+
+- the current branch and the number of uncommitted changes (from `git status`);
+- the session handoff note written by the `session-handoff` skill, if there is one: `.handoff/<branch>.md`, then `HANDOFF.md`, then the newest note in `.handoff/` or `docs/handoff/`. At most 60 lines are included, and the agent is told to check it against the repository before acting on it.
+
+It only reads; it never changes files. Not available in OpenCode, which has no way for a hook to add context at session start.

package/hooks/load-session-context/hook.js

@@ -0,0 +1,56 @@
+'use strict';
+
+// At session start, tells the agent where things stand: the branch, uncommitted work, and the
+// latest session handoff note (written by the session-handoff skill). check({ cwd }) -> { context }
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const MAX_NOTE_LINES = 60;
+const MAX_NOTE_CHARS = 3000;
+
+function git(cwd, args) {
+  try {
+    return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000 }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function newest(dir) {
+  try {
+    return fs.readdirSync(dir).filter((f) => f.endsWith('.md'))
+      .map((f) => path.join(dir, f))
+      .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs)[0] || null;
+  } catch {
+    return null;
+  }
+}
+
+// The note for this branch first, then HANDOFF.md, then the newest note in the usual folders.
+function findNote(root, branch) {
+  const candidates = [];
+  if (branch) for (const name of [branch, branch.replace(/\//g, '-')]) candidates.push(path.join(root, '.handoff', `${name}.md`));
+  candidates.push(path.join(root, 'HANDOFF.md'));
+  const direct = candidates.find((p) => fs.existsSync(p));
+  return direct || newest(path.join(root, '.handoff')) || newest(path.join(root, 'docs', 'handoff'));
+}
+
+function check(event) {
+  const cwd = event.cwd || process.cwd();
+  const root = git(cwd, ['rev-parse', '--show-toplevel']);
+  if (!root) return {};
+  const branch = git(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  const changes = (git(root, ['status', '--porcelain']) || '').split('\n').filter(Boolean).length;
+  const lines = [`Session context from kete-loom (load-session-context):`, `- Branch: ${branch || 'unknown'}, ${changes} uncommitted change(s).`];
+  const note = findNote(root, branch);
+  if (note) {
+    let text = fs.readFileSync(note, 'utf8').split('\n').slice(0, MAX_NOTE_LINES).join('\n');
+    if (text.length > MAX_NOTE_CHARS) text = `${text.slice(0, MAX_NOTE_CHARS)}\n…`;
+    lines.push(`- Handoff note ${path.relative(root, note)} (check it against the repository before acting on it):`, '', text);
+  }
+  return { context: lines.join('\n') };
+}
+
+module.exports = { check };

package/hooks/notify-on-stop/HOOK.md

@@ -0,0 +1,25 @@
+---
+name: notify-on-stop
+description: Shows a desktop notification when the agent finishes its turn, so you can switch away during long tasks and come back when it is your move.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: meta
+  kete-loom/risk: runs-commands
+  kete-loom/event: "stop"
+  kete-loom/opt-in: "true"
+  kete-loom/owner: "Kete-org"
+---
+
+# Notify on stop
+
+Runs when the agent ends its turn and shows a notification naming the project folder:
+
+- on macOS through `osascript`;
+- on Linux through `notify-send`, when it is installed.
+
+On Windows and on machines with neither, it does nothing. It never blocks, never changes files and never uses the network.
+
+Available in Claude Code, Codex, Gemini CLI, Kete Code, Cursor and GitHub Copilot.
+
+Opt-in: `--hooks` leaves it out; install it by name with `--hook`.

package/hooks/notify-on-stop/hook.js

@@ -0,0 +1,27 @@
+'use strict';
+
+// Desktop notification when the agent finishes its turn. Never blocks. check({ cwd }) -> {}
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+function notifier(platform = process.platform, env = process.env) {
+  if (platform === 'darwin') return (title, body) => ['osascript', ['-e', `display notification ${JSON.stringify(body)} with title ${JSON.stringify(title)}`]];
+  if (platform === 'linux' && (env.PATH || '').split(path.delimiter).some((d) => d && fs.existsSync(path.join(d, 'notify-send')))) return (title, body) => ['notify-send', [title, body]];
+  return null; // shortcut: no Windows toast (it needs a PowerShell module); add one if Windows users ask
+}
+
+function check(event) {
+  const make = notifier();
+  if (!make) return {};
+  const [program, args] = make('Agent finished', `${path.basename(path.resolve(event.cwd || process.cwd()))}: your turn`);
+  try {
+    execFileSync(program, args, { stdio: 'ignore', timeout: 3000 });
+  } catch {
+    // a notification that can't be shown is not worth failing over
+  }
+  return {};
+}
+
+module.exports = { check, notifier };

package/hooks/protect-files/HOOK.md

@@ -0,0 +1,24 @@
+---
+name: protect-files
+description: Stops the agent from editing files that should never be hand-edited, such as .env files with secrets, package lockfiles, anything inside .git, and private keys.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: security
+  kete-loom/risk: read-only
+  kete-loom/event: "pre-edit"
+  kete-loom/owner: "Kete-org"
+---
+
+# Protect files
+
+Runs before every file write or edit. Blocks:
+
+| Files | Why | What the agent should do instead |
+|---|---|---|
+| `.env`, `.env.local`, `.env.production`… (not `.env.example`/`.sample`/`.template`) | They hold real secrets | Edit `.env.example` and tell you which values to set |
+| Lockfiles (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lock`, `Cargo.lock`, `poetry.lock`, `uv.lock`, `go.sum`, `Gemfile.lock`, `composer.lock` and others) | Hand edits break dependency resolution | Run the package manager, which rewrites the lockfile |
+| Anything under `.git/` | Editing git's internals can corrupt the repository | Use git commands |
+| Private keys and keystores (`id_rsa`, `id_ed25519`, `*.pem`, `*.key`, `*.p12`…; `.pub` files are fine) | Keys don't belong in the repository | Generate and store keys outside it |
+
+Not available in Cursor, which has no documented hook before an edit.

package/hooks/protect-files/cases.json

@@ -0,0 +1,27 @@
+{
+  "should_block": [
+    { "files": [{ "path": ".env", "content": "DB_URL=postgres://x" }] },
+    { "files": [{ "path": "apps/api/.env.local", "content": "X=1" }] },
+    { "files": [{ "path": ".env.production", "content": "X=1" }] },
+    { "files": [{ "path": "package-lock.json", "content": "{}" }] },
+    { "files": [{ "path": "web/pnpm-lock.yaml", "content": "" }] },
+    { "files": [{ "path": "Cargo.lock", "content": "" }] },
+    { "files": [{ "path": "go.sum", "content": "" }] },
+    { "files": [{ "path": ".git/config", "content": "[core]" }] },
+    { "files": [{ "path": ".git/hooks/pre-commit", "content": "exit 0" }] },
+    { "files": [{ "path": "certs/server.key", "content": "x" }] },
+    { "files": [{ "path": "deploy/id_ed25519", "content": "x" }] },
+    { "files": [{ "path": "src/ok.ts", "content": "x" }, { "path": "yarn.lock", "content": "" }] }
+  ],
+  "should_allow": [
+    { "files": [{ "path": ".env.example", "content": "DB_URL=" }] },
+    { "files": [{ "path": "config/.env.template", "content": "X=" }] },
+    { "files": [{ "path": "src/env.ts", "content": "export const env = process.env" }] },
+    { "files": [{ "path": "package.json", "content": "{}" }] },
+    { "files": [{ "path": "docs/lockfiles.md", "content": "about package-lock.json" }] },
+    { "files": [{ "path": ".github/workflows/ci.yml", "content": "on: push" }] },
+    { "files": [{ "path": "deploy/id_ed25519.pub", "content": "ssh-ed25519 AAAA" }] },
+    { "files": [{ "path": "src/keyboard.ts", "content": "x" }] },
+    { "files": [{ "path": ".gitignore", "content": "node_modules" }] }
+  ]
+}

package/hooks/protect-files/hook.js

@@ -0,0 +1,39 @@
+'use strict';
+
+// Blocks agent edits to files that should never be hand-edited: secrets (.env), lockfiles,
+// git internals and private keys. check({ files: [{ path, content }], cwd }) -> verdict.
+
+const path = require('path');
+
+const RULES = [
+  {
+    test: (rel, base) => /^\.env(?:\..+)?$/.test(base) && !/\.(?:example|sample|template|dist|defaults)$/.test(base),
+    reason: 'is an environment file that holds secrets. Edit .env.example and tell the user which values to set.',
+  },
+  {
+    test: (rel, base) => /^(?:package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|Cargo\.lock|poetry\.lock|uv\.lock|Pipfile\.lock|Gemfile\.lock|composer\.lock|go\.sum|pubspec\.lock|Podfile\.lock|mix\.lock|packages\.lock\.json|gradle\.lockfile|flake\.lock)$/.test(base),
+    reason: "is a lockfile. Change the dependency with the package manager (it rewrites the lockfile) instead of editing it.",
+  },
+  {
+    test: (rel) => /(?:^|\/)\.git\//.test(rel) || rel === '.git',
+    reason: "is inside .git. Use git commands; editing git's internals can corrupt the repository.",
+  },
+  {
+    test: (rel, base) => /^(?:id_(?:rsa|dsa|ecdsa|ed25519)|.*\.(?:pem|key|p12|pfx|jks|keystore))$/.test(base) && !/\.pub$/.test(base),
+    reason: 'looks like a private key or keystore. Keys are generated and stored outside the repository.',
+  },
+];
+
+function check(event) {
+  const cwd = event.cwd || process.cwd();
+  for (const file of event.files || []) {
+    if (!file || typeof file.path !== 'string') continue;
+    const rel = path.relative(cwd, path.resolve(cwd, file.path)).split(path.sep).join('/');
+    const base = path.basename(file.path);
+    const rule = RULES.find((r) => r.test(rel, base));
+    if (rule) return { block: true, reason: `Blocked by kete-loom (protect-files): \`${rel}\` ${rule.reason}` };
+  }
+  return { block: false };
+}
+
+module.exports = { check };

package/hooks/protect-lint-config/HOOK.md

@@ -0,0 +1,29 @@
+---
+name: protect-lint-config
+description: Stops the agent from editing existing linter, formatter and type-checker configs, so it fixes the code that breaks a rule instead of weakening or switching off the rule.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: read-only
+  kete-loom/event: "pre-edit"
+  kete-loom/opt-in: "true"
+  kete-loom/owner: "Kete-org"
+---
+
+# Protect lint config
+
+Runs before every file write or edit. It blocks changes to existing quality-gate configs:
+
+| Tool | Files |
+|---|---|
+| ESLint | `.eslintrc*`, `eslint.config.*` |
+| Biome, Prettier, Stylelint | `biome.json(c)`, `.prettierrc*`, `prettier.config.*`, `.stylelintrc*`, `stylelint.config.*` |
+| Python | `ruff.toml`, `.ruff.toml`, `.flake8`, `.pylintrc`, `mypy.ini`, `.mypy.ini` |
+| Go, Rust, Ruby, PHP | `.golangci.yml/.yaml/.toml`, `clippy.toml`, `.clippy.toml`, `rustfmt.toml`, `.rubocop.yml`, `phpstan.neon(.dist)` |
+
+The agent is told to fix the code that breaks the rule instead. If you asked for the config change yourself, the agent says so, and you make the edit or turn this hook off.
+
+Creating a config that doesn't exist yet is allowed, so setting up a new project still works. Settings inside `pyproject.toml` or `package.json` are not covered, because those files hold much more than lint settings.
+
+Opt-in: `--hooks` leaves it out; install it by name with `--hook` or with `--profile strict`. Not available in Cursor, which has no documented hook before an edit.

package/hooks/protect-lint-config/cases.json

@@ -0,0 +1,18 @@
+{
+  "should_block": [
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": ".eslintrc.json", "content": "{\"rules\":{}}" }] },
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": "eslint.config.mjs", "content": "export default []" }] },
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": "biome.json", "content": "{}" }] },
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": ".prettierrc", "content": "{}" }] },
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": "ruff.toml", "content": "ignore = [\"E501\"]" }] },
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": ".golangci.yml", "content": "linters: {}" }] },
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": "src/a.ts", "content": "x" }, { "path": ".rubocop.yml", "content": "" }] }
+  ],
+  "should_allow": [
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": "src/app.ts", "content": "x" }] },
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": "tsconfig.json", "content": "{}" }] },
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": ".stylelintrc.json", "content": "{}" }] },
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": "docs/eslint-rules.md", "content": "x" }] },
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": "pyproject.toml", "content": "[tool.ruff]" }] }
+  ]
+}

package/hooks/protect-lint-config/fixtures/.eslintrc.json

@@ -0,0 +1 @@
+{}

package/hooks/protect-lint-config/fixtures/.golangci.yml

@@ -0,0 +1 @@
+{}

package/hooks/protect-lint-config/fixtures/.prettierrc

@@ -0,0 +1 @@
+{}

package/hooks/protect-lint-config/fixtures/.rubocop.yml

@@ -0,0 +1 @@
+{}

package/hooks/protect-lint-config/fixtures/biome.json

@@ -0,0 +1 @@
+{}

package/hooks/protect-lint-config/fixtures/eslint.config.mjs

@@ -0,0 +1 @@
+{}

package/hooks/protect-lint-config/fixtures/ruff.toml

@@ -0,0 +1 @@
+{}

package/hooks/protect-lint-config/hook.js

@@ -0,0 +1,25 @@
+'use strict';
+
+// Blocks edits to existing linter, formatter and type-checker configs, so the agent fixes the code
+// instead of weakening the rule. New configs are allowed. check({ files: [{ path }], cwd }) -> verdict.
+
+const fs = require('fs');
+const path = require('path');
+
+const CONFIG = /^(?:\.eslintrc(?:\.[a-z]+)?|eslint\.config\.[cm]?[jt]s|biome\.jsonc?|\.prettierrc(?:\.[a-z]+)?|prettier\.config\.[cm]?[jt]s|\.stylelintrc(?:\.[a-z]+)?|stylelint\.config\.[cm]?js|\.?ruff\.toml|\.flake8|\.pylintrc|\.?mypy\.ini|\.golangci\.(?:ya?ml|toml|json)|\.?clippy\.toml|\.?rustfmt\.toml|\.rubocop\.yml|phpstan\.neon(?:\.dist)?)$/;
+
+function check(event) {
+  const cwd = event.cwd || process.cwd();
+  for (const f of event.files || []) {
+    if (!f || typeof f.path !== 'string') continue;
+    const base = path.basename(f.path);
+    if (!CONFIG.test(base) || !fs.existsSync(path.resolve(cwd, f.path))) continue;
+    return {
+      block: true,
+      reason: `Blocked by kete-loom (protect-lint-config): \`${f.path}\` configures a linter or formatter. Fix the code that breaks the rule instead of changing the rule. If the user asked for this config change, tell them this hook blocks it so they can make the edit themselves.`,
+    };
+  }
+  return { block: false };
+}
+
+module.exports = { check };

package/hooks/read-before-edit/HOOK.md

@@ -0,0 +1,26 @@
+---
+name: read-before-edit
+description: Stops the first edit of each existing file in a session and tells the agent to read the file and search for its callers first, so changes are grounded in the real code rather than a guess.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/event: "pre-edit"
+  kete-loom/opt-in: "true"
+  kete-loom/owner: "Kete-org"
+---
+
+# Read before edit
+
+Runs before every file write or edit. The first time in a session the agent tries to change a file that already exists, the edit is refused with this instruction:
+
+1. Read the whole file.
+2. Search the codebase for everything that imports, calls or configures it.
+3. Then make the same edit again.
+
+The retry goes through, and so does every later edit of that file in the session. New files are never blocked.
+
+It remembers which files it has seen in `~/.kete-loom/state/read-before-edit.json` (set `KETE_LOOM_STATE_DIR` to move it). It keeps them per session when the host sends a session id, otherwise per project per day. Entries older than two days are dropped. It reads no file contents and never uses the network.
+
+Expect one extra round trip per file. Opt-in: `--hooks` leaves it out; install it by name with `--hook` or with `--profile strict`. Not available in Cursor, which has no documented hook before an edit.

package/hooks/read-before-edit/cases.json

@@ -0,0 +1,15 @@
+{
+  "should_block": [
+    { "files": [{ "path": "package.json", "content": "{}" }] },
+    { "files": [{ "path": "README.md", "content": "x" }] },
+    { "files": [{ "path": "bin/kete-loom.js", "content": "x" }] },
+    { "files": [{ "path": "scripts/lib/lint.js", "content": "x" }] },
+    { "files": [{ "path": "brand-new-file.ts", "content": "x" }, { "path": "AGENTS.md", "content": "x" }] }
+  ],
+  "should_allow": [
+    { "files": [{ "path": "src/does-not-exist-yet.ts", "content": "x" }] },
+    { "files": [{ "path": "notes/new-plan.md", "content": "x" }] },
+    { "files": [{ "path": "package.json", "content": "{}" }] },
+    { "files": [{ "path": "README.md", "content": "y" }] }
+  ]
+}