@ketecode/loom 0.0.0-stage → 0.1.0

package/hooks/block-dangerous-commands/hook.js

@@ -0,0 +1,75 @@
+'use strict';
+
+// Blocks shell commands that destroy data or systems before they run.
+// check({ command, cwd }) -> { block: true, reason } | { block: false }
+// Pure and dependency-free: the kete-loom hook runner calls it for every host.
+
+// shortcut: regex over shell segments, not a shell parser; quoting tricks can evade it. It is a
+// seatbelt against agent mistakes, not a security boundary.
+const SEGMENT_SPLIT = /\s*(?:&&|\|\||;|\n)\s*/;
+const SUDO = /^(?:sudo|doas)\s+(?:-\S+\s+)*/;
+
+const ROOTISH = String.raw`(?:/|/\*|~|~/|~/\*|\$HOME|\$\{HOME\}|\$HOME/\*|\.\.?/?|\*)`;
+const PROTECTED = new Set(['main', 'master', 'trunk', 'production', 'prod', 'release']);
+
+// `git push -f origin feature/main-fix` is fine; `git push -f origin main` or `+main` or `HEAD:main` is not.
+function forcePushesProtected(s) {
+  const args = s.split(/\s+/).slice(2);
+  const force = args.some((a) => a === '-f' || a === '--force' || /^-[a-zA-Z]*f[a-zA-Z]*$/.test(a)) && !args.some((a) => a.startsWith('--force-with-lease'));
+  const refs = args.filter((a) => !a.startsWith('-')).slice(1); // first non-flag is the remote
+  return refs.some((r) => {
+    const dst = r.replace(/^\+/, '').split(':').pop().replace(/^refs\/heads\//, '');
+    return PROTECTED.has(dst) && (force || r.startsWith('+'));
+  });
+}
+
+const RULES = [
+  {
+    // rm with both recursive and force flags, aimed at /, ~, $HOME, . or ..
+    test: (s) => /^rm\s/.test(s) && /\s-(?:[a-zA-Z]*r[a-zA-Z]*f|[a-zA-Z]*f[a-zA-Z]*r)\b|\s--recursive\b.*\s--force\b|\s--force\b.*\s--recursive\b|\s-r\b.*\s-f\b|\s-f\b.*\s-r\b/.test(s)
+      && new RegExp(String.raw`\s["']?${ROOTISH}["']?(?:\s|$)`).test(s) || /^rm\s.*--no-preserve-root/.test(s),
+    reason: 'deletes everything under /, your home folder or the whole working tree. Delete the specific paths you mean instead.',
+  },
+  {
+    test: (s) => /^git\s+push\b/.test(s) && forcePushesProtected(s),
+    reason: 'force-pushes a protected branch (main, master, release...). Push a new branch, or use --force-with-lease on your own branch.',
+  },
+  {
+    test: (s) => /^(?:mkfs(?:\.\w+)?|wipefs|fdisk|sfdisk|parted)\b/.test(s) || /^dd\b.*\bof=\/dev\/(?!null\b|zero\b|stdout\b|stderr\b)/.test(s) || /(?:^|\s)>\s*\/dev\/(?:sd|nvme|disk|hd|vd)\w*/.test(s),
+    reason: 'writes directly to a disk device, which destroys its data.',
+  },
+  {
+    test: (s) => /^(?:chmod|chown|chgrp)\s+(?:-\S*R\S*|--recursive)\b/.test(s) && new RegExp(String.raw`\s["']?(?:/|~|\$HOME|\$\{HOME\})["']?(?:\s|$)`).test(s),
+    reason: 'recursively changes permissions or ownership of / or your home folder.',
+  },
+  {
+    test: (s) => /^(?:curl|wget)\b/.test(s) && /\|\s*(?:sudo\s+)?(?:ba|z|da|k)?sh\b/.test(s),
+    reason: 'pipes a script from the internet straight into a shell. Download it, read it, then run it.',
+  },
+  {
+    test: (s) => /\bdrop\s+(?:database|schema)\b/i.test(s) && /^(?:psql|mysql|mariadb|sqlite3|sqlcmd|mongosh|clickhouse(?:-client)?|cockroach)\b/.test(s),
+    reason: 'drops a whole database or schema.',
+  },
+  {
+    test: (s) => /^(?:terraform|tofu)\s+(?:destroy\b|apply\b.*\s-destroy\b)/.test(s) && /\s-auto-approve\b/.test(s),
+    reason: 'destroys infrastructure without a review step. Run the plan and let a person approve it.',
+  },
+];
+
+function check(event) {
+  const command = typeof event.command === 'string' ? event.command : '';
+  // Checked on the whole command: a fork bomb contains `;`, which the segment split would cut.
+  if (/:\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;?\s*:/.test(command)) {
+    return { block: true, reason: 'Blocked by kete-loom (block-dangerous-commands): this command is a fork bomb.' };
+  }
+  // Pipes stay inside a segment so `curl ... | sh` is seen whole.
+  for (const raw of command.split(SEGMENT_SPLIT)) {
+    const segment = raw.trim().replace(SUDO, '');
+    if (!segment) continue;
+    const rule = RULES.find((r) => r.test(segment));
+    if (rule) return { block: true, reason: `Blocked by kete-loom (block-dangerous-commands): \`${segment.slice(0, 120)}\` ${rule.reason}` };
+  }
+  return { block: false };
+}
+
+module.exports = { check };

package/hooks/block-no-verify/HOOK.md

@@ -0,0 +1,25 @@
+---
+name: block-no-verify
+description: Stops the agent from skipping the project's git hooks with git commit --no-verify, -n, HUSKY=0, SKIP= or a swapped core.hooksPath, so pre-commit checks keep running.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: security
+  kete-loom/risk: read-only
+  kete-loom/event: "pre-shell"
+  kete-loom/owner: "Kete-org"
+---
+
+# Block --no-verify
+
+Agents that hit a failing pre-commit or pre-push hook often retry with `--no-verify`. This hook refuses that, so the agent fixes what the hook reported instead.
+
+| Blocks | Example |
+|---|---|
+| `--no-verify` on commit, push, merge, rebase, am, cherry-pick, revert | `git commit --no-verify -m wip` |
+| `-n` on `git commit` (short for `--no-verify`) | `git commit -nm wip` |
+| Turning Husky off | `HUSKY=0 git commit` |
+| Skipping pre-commit hooks | `SKIP=eslint git commit` |
+| Pointing git at another hooks folder | `git -c core.hooksPath=/dev/null commit` |
+
+Commit messages that mention `--no-verify` are fine. If you really need to skip hooks, run the command yourself.

package/hooks/block-no-verify/cases.json

@@ -0,0 +1,30 @@
+{
+  "should_block": [
+    "git commit --no-verify -m 'wip'",
+    "git commit -m 'wip' --no-verify",
+    "git commit -n -m 'skip'",
+    "git commit -nm 'skip'",
+    "git commit -am 'x' -n",
+    "git push --no-verify origin feature/x",
+    "git -C app commit --no-verify -m x",
+    "HUSKY=0 git commit -m 'x'",
+    "HUSKY_SKIP_HOOKS=1 git push",
+    "git -c core.hooksPath=/dev/null commit -m x",
+    "git config core.hooksPath /tmp/empty",
+    "SKIP=eslint,prettier git commit -m 'x'",
+    "npm test && git commit --no-verify -m x",
+    "git -c user.name=bot commit --no-verify -m x"
+  ],
+  "should_allow": [
+    "git commit -m 'fix: handle empty input'",
+    "git commit -am 'feat: add retry' ",
+    "git push origin feature/x",
+    "git log --no-merges -n 5",
+    "git config --get core.hooksPath",
+    "git commit -m 'docs: explain --no-verify policy'",
+    "npx husky init",
+    "git merge --no-ff feature/x",
+    "git commit -m \"skip -n flag docs\"",
+    "git -C app log -n 3"
+  ]
+}

package/hooks/block-no-verify/hook.js

@@ -0,0 +1,43 @@
+'use strict';
+
+// Blocks shell commands that skip the project's git hooks (pre-commit, commit-msg, pre-push).
+
+const SEGMENT_SPLIT = /\s*(?:&&|\|\||;|\n)\s*/;
+// git's global options, including the ones that take a value (`-C dir`, `-c key=value`).
+const GIT = String.raw`^git\s+(?:(?:-C|-c)\s+\S+\s+|--?[\w-]+(?:=\S+)?\s+)*`;
+// Quoted text (commit messages) can mention --no-verify without using it.
+const unquote = (s) => s.replace(/'[^']*'|"(?:[^"\\]|\\.)*"/g, "''");
+
+const RULES = [
+  {
+    // --no-verify on any git subcommand that runs hooks; `-n` means --no-verify only for commit.
+    test: (s) => new RegExp(GIT + String.raw`(?:commit|push|merge|rebase|am|cherry-pick|revert)\b.*\s--no-verify\b`).test(s)
+      || new RegExp(GIT + String.raw`commit\b(?:\s+\S+)*\s-(?!-)[a-zA-Z]*n[a-zA-Z]*(?:\s|$)`).test(s),
+    reason: 'skips the git hooks with --no-verify. Fix what the hook reports instead.',
+  },
+  {
+    test: (s) => /^(?:\w+=\S*\s+)*(?:HUSKY|HUSKY_SKIP_HOOKS)=(?:0|false|1|true)\s+(?:\w+=\S*\s+)*git\b/.test(s)
+      && /(?:^|\s)HUSKY=0\b|HUSKY_SKIP_HOOKS=(?:1|true)\b|HUSKY=false\b/.test(s),
+    reason: 'turns off Husky git hooks for this command. Fix what the hook reports instead.',
+  },
+  {
+    test: (s) => /^git\s+.*-c\s+core\.hooksPath=/.test(s) || /^git\s+config\b.*\bcore\.hooksPath\b/.test(s) && !/--get\b|--unset\b/.test(s) && /core\.hooksPath\s+\S+/.test(s),
+    reason: "points git at a different hooks folder, which bypasses the project's hooks.",
+  },
+  {
+    test: (s) => /^(?:\w+=\S*\s+)*SKIP=\S+\s+(?:\w+=\S*\s+)*git\b/.test(s) || /^PRE_COMMIT_ALLOW_NO_CONFIG=1\s/.test(s),
+    reason: 'skips pre-commit hooks for this command. Fix what the hook reports instead.',
+  },
+];
+
+function check(event) {
+  const command = typeof event.command === 'string' ? event.command : '';
+  for (const raw of command.split(SEGMENT_SPLIT)) {
+    const segment = raw.trim().replace(/^(?:sudo|doas)\s+/, '');
+    const rule = segment && RULES.find((r) => r.test(unquote(segment)));
+    if (rule) return { block: true, reason: `Blocked by kete-loom (block-no-verify): \`${segment.slice(0, 120)}\` ${rule.reason}` };
+  }
+  return { block: false };
+}
+
+module.exports = { check };

package/hooks/format-on-edit/HOOK.md

@@ -0,0 +1,24 @@
+---
+name: format-on-edit
+description: After the agent edits a file, formats it with the formatter the project already uses (Biome or Prettier, Ruff or Black, gofmt, rustfmt), so agent changes match the project's style.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/event: "post-edit"
+  kete-loom/owner: "Kete-org"
+---
+
+# Format on edit
+
+Runs after each file write or edit and formats the changed file, only with a formatter the project has chosen:
+
+| Files | Formatter | Used when |
+|---|---|---|
+| JS, TS, JSON, CSS, HTML, Markdown, YAML, Vue, Svelte… | Biome, else Prettier | the project has `biome.json` and a local Biome, or a local Prettier in `node_modules` |
+| Python | Ruff, else Black | `[tool.ruff]`, `ruff.toml` or `[tool.black]` is configured and the tool is on your PATH |
+| Go | `gofmt -w` | `gofmt` is on your PATH |
+| Rust | `rustfmt`, with the edition from `Cargo.toml` | `rustfmt` is on your PATH |
+
+It never installs anything, never formats files outside the project, never uses the network, and never fails an edit: if the formatter errors (for example on a half-finished edit), the file is left as the agent wrote it. Each run is limited to 15 seconds per file.

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/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 };