@euanmsm/preflight 0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# @euanmsm/preflight
+
+A Claude Code hook that blocks an edit until the agent has read the conventions
+governing the file it is about to change.
+
+The problem it solves: an agent that has not opened your conventions writes code
+from memory of how code is usually written, not how _your_ code is written. You
+then spend the review asking for the same changes you asked for last week. This
+turns the conventions from something an agent might read into something it must.
+
+## Installing
+
+```sh
+npm i -D @euanmsm/preflight
+mkdir -p .devkit
+cp node_modules/@euanmsm/preflight/preflight.example.json .devkit/preflight.json
+```
+
+Then register it as a `PreToolUse` hook in `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [{ "type": "command", "command": "npx preflight" }]
+      }
+    ]
+  }
+}
+```
+
+## The map
+
+`.devkit/preflight.json` says which skills each path needs. Patterns are regular
+expressions tested against the path relative to the repository root.
+
+```json
+{
+  "exclude": ["node_modules/", "\\.d\\.ts$"],
+  "primary": [
+    { "pattern": "^src/api/", "skills": ["api-routes"] },
+    { "pattern": "^src/", "skills": ["readability"] }
+  ],
+  "universal": [{ "pattern": "\\.(tsx?|mjs)$", "skills": ["comments"] }]
+}
+```
+
+`exclude` wins over everything. `primary` is **first match wins**, so list the
+most specific pattern first — `^src/api/` above `^src/`, never the other way
+round. `universal` rules always add on top of whichever primary rule matched.
+
+A path no rule names requires nothing, so the gate is opt-in per directory.
+
+## When it does not block
+
+The gate fails open. A missing map, an unreadable transcript, a file outside the
+repository or a malformed payload all allow the edit rather than halting work on
+a tool that cannot do its job. `PREFLIGHT=off` disables it for one command.
+
+Deliberate: a gate that breaks your session when its own config has a typo is a
+gate you will remove within the week.

package/bin/preflight.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { main } from '../src/gate.mjs';
+
+// A missing config, an unreadable transcript or a malformed payload allows the edit.
+try {
+  main();
+} catch (error) {
+  process.stderr.write(
+    `preflight: edit allowed unchecked — ${error.message}\n`,
+  );
+  process.exit(0);
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@euanmsm/preflight",
+  "version": "0.1.0",
+  "description": "Claude Code PreToolUse hook that blocks an edit until the file's governing convention skill has been loaded",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/euanmsm/devkit.git",
+    "directory": "packages/preflight"
+  },
+  "bin": {
+    "preflight": "bin/preflight.mjs"
+  },
+  "exports": {
+    ".": "./src/gate.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "preflight.example.json"
+  ],
+  "engines": {
+    "node": ">=22.11"
+  },
+  "dependencies": {
+    "@euanmsm/devkit-core": "0.1.0"
+  }
+}

package/preflight.example.json

@@ -0,0 +1,23 @@
+{
+  "_readme": "Path-to-skill map. Patterns are JS regexes tested against the repo-relative path. `primary` is first-match-wins, so order matters — most specific first. `universal` rules always add on top.",
+
+  "exclude": [
+    "node_modules/",
+    "^tmp/",
+    "\\.tmp\\.",
+    "\\.min\\.[cm]?js$",
+    "\\.d\\.ts$"
+  ],
+
+  "primary": [
+    { "pattern": "^_CONVENTIONS/", "skills": ["conventions"] },
+    { "pattern": "(^|/)README\\.md$", "skills": ["readmes"] }
+  ],
+
+  "universal": [
+    {
+      "pattern": "\\.(tsx?|mjs|cjs|js)$",
+      "skills": ["comments", "readability"]
+    }
+  ]
+}

package/src/gate.mjs

@@ -0,0 +1,138 @@
+// ============================================================================
+// Skill Gate
+// ============================================================================
+//
+// PreToolUse hook on Edit and Write. Blocks the edit until the file's required
+// convention skills have been loaded this session. Fails open on any error.
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, relative } from 'node:path';
+
+import { compile, loadConfig, repoRoot } from '@euanmsm/devkit-core';
+
+const CONFIG_NAME = 'preflight.json';
+
+/** Anything other than an explicit deny lets the tool call through. */
+function allow() {
+  process.exit(0);
+}
+
+/** Blocks the tool call, showing the agent which skills to load. */
+function deny(reason) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: reason,
+      },
+    }),
+  );
+  process.exit(0);
+}
+
+/**
+ * Locates the session transcript the hook payload belongs to.
+ *
+ * @param input - The hook payload
+ * @returns Path to the transcript, or null when it cannot be found
+ */
+export function findTranscript(input) {
+  if (input.transcript_path && existsSync(input.transcript_path))
+    return input.transcript_path;
+
+  const projects = join(homedir(), '.claude', 'projects');
+  if (!input.session_id || !existsSync(projects)) return null;
+
+  for (const dir of readdirSync(projects)) {
+    const candidate = join(projects, dir, `${input.session_id}.jsonl`);
+    if (existsSync(candidate)) return candidate;
+  }
+
+  return null;
+}
+
+/**
+ * Reads every skill loaded in a transcript.
+ *
+ * @param transcriptPath - Path to the session's JSONL transcript
+ * @returns Skill names, one per Skill tool call
+ */
+export function loadedSkills(transcriptPath) {
+  const raw = readFileSync(transcriptPath, 'utf8');
+  const skills = new Set();
+
+  for (const match of raw.matchAll(
+    /"name":"Skill","input":\{"skill":"([^"]+)"/g,
+  )) {
+    skills.add(match[1]);
+  }
+
+  return skills;
+}
+
+/**
+ * Names the skills a path requires.
+ *
+ * @param rel - Repo-relative path of the edited file
+ * @param map - Parsed skill map
+ * @returns Required skill names, empty when the path is ungoverned
+ */
+export function requiredFor(rel, map) {
+  if (compile(map.exclude).some((p) => p.test(rel))) return [];
+
+  const required = new Set();
+
+  // First match wins, so the map lists the most specific pattern first.
+  const hit = (map.primary ?? []).find((rule) => matches(rule.pattern, rel));
+  if (hit) hit.skills.forEach((s) => required.add(s));
+
+  for (const rule of map.universal ?? []) {
+    if (matches(rule.pattern, rel)) rule.skills.forEach((s) => required.add(s));
+  }
+
+  return [...required];
+}
+
+/** True when a pattern compiles and matches, false when it does neither. */
+function matches(pattern, rel) {
+  return compile([pattern]).some((p) => p.test(rel));
+}
+
+/** Reads the hook payload and denies when a required skill is missing. */
+export function main() {
+  if (process.env.PREFLIGHT === 'off') allow();
+
+  const input = JSON.parse(readFileSync(0, 'utf8'));
+  const filePath = input?.tool_input?.file_path;
+  if (!filePath) allow();
+
+  const root = repoRoot();
+  const rel = relative(root, filePath);
+
+  // A file in another checkout is not this repo's to govern.
+  if (rel.startsWith('..')) allow();
+
+  const map = loadConfig(CONFIG_NAME, null, root);
+  if (!map) allow();
+
+  const required = requiredFor(rel, map);
+  if (required.length === 0) allow();
+
+  const transcript = findTranscript(input);
+  if (!transcript) allow();
+
+  const loaded = loadedSkills(transcript);
+  const missing = required.filter((s) => !loaded.has(s));
+  if (missing.length === 0) allow();
+
+  const calls = missing.map((s) => `  Skill(skill: "${s}")`).join('\n');
+
+  deny(
+    `BLOCKED — ${rel} is governed by convention skills you have not loaded this session.\n\n` +
+      `Load them, then make this edit again:\n${calls}\n\n` +
+      `These skills hold the conventions this file must follow. Do not work around this by ` +
+      `writing from memory. The mapping lives in .devkit/${CONFIG_NAME}.`,
+  );
+}