@damiangilgonzalez/harness 1.3.7

package/targets/commands.js

@@ -0,0 +1,211 @@
+import { existsSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { agentByName, allAgentNames } from './agents.js';
+
+const COMMAND_TARGETS = Object.freeze({
+  claude: { dir: '.claude/commands', ext: '.md', format: 'claude', skillsAreCommands: true },
+  cursor: { dir: '.cursor/commands', ext: '.md', format: 'plain' },
+  gemini: { dir: '.gemini/commands', ext: '.toml', format: 'gemini' },
+  opencode: { dir: '.opencode/commands', ext: '.md', format: 'opencode' },
+  copilot: { dir: '.github/prompts', ext: '.prompt.md', format: 'copilot' },
+  windsurf: { dir: '.windsurf/workflows', ext: '.md', format: 'windsurf' },
+  cline: { dir: '.clinerules/workflows', ext: '.md', format: 'plain', invocationSuffix: '.md' },
+  roo: { dir: '.roo/commands', ext: '.md', format: 'roo' },
+});
+
+export const COMMAND_TARGET_IDS = Object.freeze(Object.keys(COMMAND_TARGETS));
+export const targetHasCommands = (target) => Boolean(COMMAND_TARGETS[target]);
+
+const delegate = (kind, backing) => `Delegate this request to the ${backing} ${kind}. Pass the invocation arguments unchanged: {{ARGS}}\nDo not reproduce that ${kind}'s method here; load it and follow its own stopping and verification rules.`;
+
+const skillCommand = (name, backing = name) => ({
+  name,
+  kind: 'skill',
+  backing,
+  description: `Run the ${backing} skill through a short, non-duplicating entry point.`,
+  body: delegate('skill', backing),
+});
+
+const FIXED_COMMANDS = Object.freeze([
+  {
+    name: 'build-fix', kind: 'resolver-selector', backing: 'build-resolver',
+    description: 'Route a build failure to the installed stack resolver without guessing.',
+    body: `Use an installed build-resolver for this failure: {{ARGS}}\nChoose from diagnostic text and affected paths. If more than one remains plausible, list the candidates and ask the user; never dispatch at random.`,
+  },
+  skillCommand('refactor-clean', 'simplify-code'),
+  {
+    name: 'test-coverage', kind: 'testing-skill', backing: 'testing-*',
+    description: 'Delegate coverage work to the installed stack testing skill.',
+    body: delegate('skill', 'testing-*'),
+  },
+  skillCommand('update-docs', 'knowledge-ops'),
+  {
+    name: 'checkpoint', kind: 'capability', backing: 'sello',
+    description: 'Freeze the current candidate for review and seal it only after the required lenses approve.',
+    body: `Use the sello backing for this checkpoint: {{ARGS}}\nRun \`npx @damiangilgonzalez/harness sello freeze\`, complete the required review, then run \`sello approve\` only with the observed lenses. Do not treat freeze as approval.`,
+  },
+  skillCommand('harness-audit', 'harness'),
+  skillCommand('security-scan', 'security-scan'),
+  {
+    name: 'learn', kind: 'memory', backing: 'memory:learn',
+    description: 'Propose one local lesson; saving still requires individual explicit approval.',
+    body: `Invoke memory:learn for exactly one proposed lesson: {{ARGS}}\nAfter individual explicit approval, run \`npx @damiangilgonzalez/harness memory learn\` with its text, evidence, scope, confidence and \`--approve\`. Without that approval, write nothing.`,
+  },
+  {
+    name: 'save-session', kind: 'memory', backing: 'memory:save',
+    description: 'Force a local deterministic session checkpoint.',
+    body: `Invoke memory:save with the current local session identifiers: {{ARGS}}\nRun \`npx @damiangilgonzalez/harness memory save --session <id>\`. Persist only allowed git and SDD ledger metadata; never include conversation or file content.`,
+  },
+  {
+    name: 'resume-session', kind: 'memory', backing: 'memory:resume',
+    description: 'Read the bounded local continuation record for this branch and worktree.',
+    body: `Invoke memory:resume for the current branch and worktree: {{ARGS}}\nRun \`npx @damiangilgonzalez/harness memory resume\`. Label a nearby branch result as nearby; never merge it silently into the exact continuation.`,
+  },
+]);
+
+export const fixedCommands = () => FIXED_COMMANDS.map((command) => ({ ...command }));
+export const fixedCommandNames = () => FIXED_COMMANDS.map((command) => command.name);
+
+function withBacking(command, backing, body) {
+  return { ...command, backing, body: body || command.body.replace(command.backing, backing) };
+}
+
+function fixedFor({ target, skills, agents, memoryMode }) {
+  const spec = COMMAND_TARGETS[target];
+  if (!spec) return [];
+  const skillSet = new Set(skills);
+  const resolverIds = agents.filter((id) => agentByName(id)?.role === 'build-resolver');
+  const testing = skills.filter((id) => id.startsWith('testing-')).sort();
+  const out = [];
+  for (const command of FIXED_COMMANDS) {
+    if (command.kind === 'skill') {
+      if (!skillSet.has(command.backing) || spec.skillsAreCommands) continue;
+      out.push({ ...command });
+    } else if (command.kind === 'testing-skill') {
+      if (!testing.length || spec.skillsAreCommands) continue;
+      out.push(withBacking(command, testing[0]));
+    } else if (command.kind === 'resolver-selector') {
+      if (!resolverIds.length) continue;
+      const backing = resolverIds.length === 1 ? resolverIds[0] : 'build-resolver';
+      const candidates = resolverIds.join(', ');
+      out.push(withBacking(command, backing,
+        `Choose the matching installed build-resolver from: ${candidates}. Pass the failure and invocation arguments unchanged: {{ARGS}}\nUse diagnostics and affected paths. If the choice is ambiguous, list candidates and ask; never dispatch at random.`));
+    } else if (command.kind === 'memory') {
+      if (!['full', 'assisted'].includes(memoryMode)) continue;
+      out.push({ ...command });
+    } else {
+      out.push({ ...command });
+    }
+  }
+  return out;
+}
+
+function stackAliases({ skills, agents }) {
+  const skillSet = new Set(skills);
+  const out = [];
+  for (const id of agents) {
+    const agent = agentByName(id);
+    if (!agent || !['reviewer', 'build-resolver'].includes(agent.role) || !agent.skills?.length) continue;
+    const installedAliases = agent.skills.filter((skill) => skillSet.has(skill));
+    const aliases = installedAliases.length ? installedAliases : [agent.skills[0]];
+    const suffix = agent.role === 'reviewer' ? 'review' : 'build';
+    for (const skill of aliases) {
+      out.push({
+        name: `${skill}-${suffix}`,
+        kind: 'agent',
+        backing: id,
+        description: `Delegate ${skill} ${suffix} work to the installed ${id} agent.`,
+        body: delegate('agent', id),
+      });
+    }
+  }
+  return out;
+}
+
+export function resolveCommands({ target, skills = [], agents = [], memoryMode = 'unsupported' }) {
+  if (!targetHasCommands(target)) return [];
+  const byName = new Map();
+  for (const command of [...fixedFor({ target, skills, agents, memoryMode }), ...stackAliases({ skills, agents })]) {
+    byName.set(command.name, command);
+  }
+  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function validateCommandCatalog(definitions = FIXED_COMMANDS) {
+  const errors = [];
+  const seen = new Set();
+  for (const command of definitions) {
+    const prefix = command?.name || '<unnamed>';
+    if (!command?.name || seen.has(command.name)) errors.push(`${prefix}: unique name required`);
+    seen.add(command?.name);
+    if (!command?.backing || !command?.body?.includes(command.backing)) errors.push(`${prefix}: body must name its exact backing`);
+    if ((command?.body || '').split('\n').length > 40) errors.push(`${prefix}: body exceeds 40 lines`);
+    if (/everything[- ]claude|affaan|worldflow/iu.test(`${command?.description || ''}\n${command?.body || ''}`)) errors.push(`${prefix}: foreign project vocabulary`);
+  }
+  return errors;
+}
+
+export function commandPath(target, cwd, name) {
+  const spec = COMMAND_TARGETS[target];
+  return spec ? join(cwd, ...spec.dir.split('/'), `${name}${spec.ext}`) : null;
+}
+
+function renderArgs(target, body) {
+  const placeholder = target === 'claude' || target === 'opencode' ? '$ARGUMENTS'
+    : target === 'gemini' ? '{{args}}'
+      : 'any text following the slash command';
+  return body.replaceAll('{{ARGS}}', placeholder);
+}
+
+function markdown(command, target) {
+  const body = renderArgs(target, command.body);
+  if (target === 'cursor' || target === 'cline') return `# /${command.name}\n\n${command.description}\n\n${body}\n`;
+  if (target === 'windsurf') return `# /${command.name}\n\n${command.description}\n\n1. ${body.replaceAll('\n', '\n2. ')}\n`;
+  const fm = ['---', `description: "${command.description.replaceAll('"', '\\"')}"`, 'argument-hint: "[arguments]"'];
+  if (target === 'copilot') fm.push('mode: agent');
+  if (target === 'opencode' && command.kind === 'agent') fm.push(`agent: ${command.backing}`);
+  fm.push('---', '');
+  return `${fm.join('\n')}${body}\n`;
+}
+
+function render(command, target) {
+  if (target !== 'gemini') return markdown(command, target);
+  const body = renderArgs(target, command.body);
+  return `description = ${JSON.stringify(command.description)}\nprompt = ${JSON.stringify(body)}\n`;
+}
+
+export function reconcileCommands(target, cwd, previousNames = [], desiredCommands = []) {
+  if (!targetHasCommands(target)) return { written: [], removed: [], collisions: [], names: [] };
+  const previous = new Set(previousNames);
+  const desiredNames = new Set(desiredCommands.map((command) => command.name));
+  const removed = [];
+  for (const name of previous) {
+    if (desiredNames.has(name)) continue;
+    const path = commandPath(target, cwd, name);
+    if (path && existsSync(path)) { rmSync(path, { force: true }); removed.push(path); }
+  }
+  const written = [];
+  const collisions = [];
+  const names = [];
+  for (const command of desiredCommands) {
+    const path = commandPath(target, cwd, command.name);
+    if (existsSync(path) && !previous.has(command.name)) {
+      collisions.push(path);
+      continue;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, render(command, target));
+    written.push(path);
+    names.push(command.name);
+  }
+  return { written, removed, collisions, names };
+}
+
+export function allPotentialCommandNames() {
+  const names = new Set(fixedCommandNames());
+  // Every stack alias follows directly from catalog metadata; no second mapping.
+  const agents = allAgentNames();
+  const skills = [...new Set(agents.flatMap((id) => agentByName(id)?.skills || []))];
+  for (const command of stackAliases({ skills, agents })) names.add(command.name);
+  return [...names];
+}

package/targets/cursor.js

@@ -0,0 +1,30 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export function writeSkill(id, fromDir, toPath) {
+  const body = readFileSync(join(fromDir, 'SKILL.md'), 'utf8');
+  mkdirSync(dirname(toPath), { recursive: true });
+  writeFileSync(toPath, `---\ndescription: rsc skill ${id}\nalwaysApply: false\n---\n${stripFrontmatter(body)}`);
+  return [toPath];
+}
+
+export function wireHook(paths, sourceMd, policy = {}) {
+  const full = stripFrontmatter(readFileSync(sourceMd, 'utf8'));
+  const body = policy.codeHooks === false
+    ? `# rsc-suggest — always-on operations layer\n\nRead \`docs/wiki/harness/user-profile.md\` before acting. Use \`orient\` and offer missing skills through \`suggest\` only when needed.\n`
+    : full;
+  mkdirSync(dirname(paths.hookTarget), { recursive: true });
+  writeFileSync(paths.hookTarget, `---\ndescription: rsc auto-suggest\nalwaysApply: true\n---\n${body}`);
+  return [paths.hookTarget];
+}
+
+// Inverse of wireHook: the cursor detector is its own file, so just remove it.
+export function unwireHook(paths) {
+  if (!existsSync(paths.hookTarget)) return [];
+  rmSync(paths.hookTarget, { force: true });
+  return [paths.hookTarget];
+}
+
+function stripFrontmatter(md) {
+  return md.replace(/^---\n[\s\S]*?\n---\n?/, '');
+}

package/targets/danger-guard.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+// rsc Danger guard (claude). Wired by targets/claude.js onto PreToolUse (matcher Bash)
+// as `node ...` so it runs on every platform including Windows.
+//   argv[2] = absolute project root   stdin = PreToolUse hook JSON
+//
+// For a NON-TECHNICAL user (per docs/wiki/harness/user-profile.md → technical_level),
+// it DENIES irreversible, foot-gun Bash commands and tells the agent to find a safer,
+// scoped alternative. A fully `technical` user is never guarded. Default-safe: if there
+// is no profile yet, the harness convention is "assume non-technical", so the guard is ON.
+//
+// Disable per project with .rsc/.no-danger-guard — but only when the USER explicitly asks
+// for it (the deny message says so). Fail-open on any internal error (never brick a shell).
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const root = process.argv[2] || process.cwd();
+
+function allow() { process.exit(0); }
+function deny(why) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason:
+        `BLOCKED for a non-technical user — this command ${why}. ` +
+        `Do NOT run it: explain the risk in plain language and propose a safer, scoped alternative ` +
+        `(name exact paths, add a WHERE clause, back up first, etc.). ` +
+        `Only if the USER explicitly insists on allowing dangerous commands here, create .rsc/.no-danger-guard to disable this guard.`,
+    },
+  }));
+  process.exit(0);
+}
+
+if (existsSync(join(root, '.rsc', '.no-danger-guard'))) allow();
+
+// technical_level === 'technical' → not guarded. non-technical / mixed / missing → guarded.
+function technicalLevel() {
+  try {
+    const txt = readFileSync(join(root, 'docs', 'wiki', 'harness', 'user-profile.md'), 'utf8');
+    const m = txt.match(/technical_level:\s*([a-z-]+)/i);
+    return m ? m[1].toLowerCase() : null;
+  } catch { return null; }
+}
+if (technicalLevel() === 'technical') allow();
+
+// Only Bash commands can be dangerous here.
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8') || '{}'); } catch { allow(); }
+if ((input.tool_name || input.toolName) !== 'Bash') allow();
+const cmd = input.tool_input?.command || input.toolInput?.command || '';
+if (typeof cmd !== 'string' || !cmd) allow();
+
+// --- the dangerous-command list ---------------------------------------------
+// High-signal, low-false-positive. Each rule: what it catches and the plain why.
+const noWhere = (verbRe) => verbRe.test(cmd) && !/\bwhere\b/i.test(cmd);
+
+// A flag is a whitespace-separated token that BEGINS with a dash. That sounds obvious, and the
+// first version of this rule got it wrong in a way that cost real trust: it tested
+// /-[a-z]*r[a-z]*\b/ and /-[a-z]*f[a-z]*\b/ against the ENTIRE command string, so any hyphenated
+// path segment carrying an "r" and an "f" read as the flags -r and -f. The segment `-fixture` alone
+// satisfies both (f-i-x-t-u-r-e), so `rm skills/zz-case-fixture/SKILL.md` and `rm my-draft.md` were
+// DENIED with the reason "rm with -r and -f" — a claim that was false about the command in front of
+// it. It also denied commands that merely QUOTED a dangerous one, which is the same mistake the
+// gitmoji guard had to fix: blocking the conversation about a command, not the command.
+//
+// That is worse than a nuisance. The deny message ends by telling the user how to switch this guard
+// OFF, so crying wolf on a single-file delete is an active instruction to disable the thing that
+// stops a real recursive wipe. Friction has to stay proportional to risk or the protection gets
+// turned off (P7), and a denial's stated reason has to be true (P6).
+//
+// Flags are also scoped to the segment that actually runs rm: `rm notes.md && ls -lrtF` carries an
+// r and an F, but they belong to ls.
+function rmFlagsIn(segment) {
+  return segment.split(/\s+/).filter((t) => /^--?[A-Za-z]/.test(t));
+}
+
+// Wrappers that stand in front of the real command without being it. A shell with -c is included
+// deliberately: `bash -c "rm -rf /"` DOES run the delete, and dropping it would have been the hole
+// this rewrite opened while fixing the over-fire.
+const WRAPPERS = /^(sudo|doas|env|command|time|nohup|xargs)$/i;
+const SHELLS = /^(bash|sh|zsh|dash|ksh)$/i;
+
+// `rm` has to be the command being EXECUTED, not a word inside someone else's argument. Without
+// this, `echo "never run rm -rf /"` was denied — the guard blocking the conversation about a
+// command instead of the command, exactly the defect the gitmoji guard had to fix with its own
+// RUNS_GIT check. A guard that argues with you about a sentence is a guard you turn off.
+function runsRm(segment) {
+  const tokens = segment.trim().split(/\s+/).filter(Boolean);
+  let i = 0;
+  while (i < tokens.length) {
+    const bare = tokens[i].replace(/^['"]/, '');
+    if (WRAPPERS.test(bare)) { i += 1; continue; }
+    if (SHELLS.test(bare)) {
+      i += 1;
+      while (i < tokens.length && /^-/.test(tokens[i])) i += 1; // skip -c and friends
+      continue;
+    }
+    return bare === 'rm' || bare.endsWith('/rm');
+  }
+  return false;
+}
+
+function isRmRecursiveForce() {
+  if (!/\brm\b/.test(cmd)) return false;
+  for (const segment of cmd.split(/\|\||&&|[|;&]/)) {
+    if (!runsRm(segment)) continue;
+    const flags = rmFlagsIn(segment);
+    const hasR = flags.some((f) => /^--recursive$/i.test(f) || /^-[A-Za-z]*r/i.test(f));
+    const hasF = flags.some((f) => /^--force$/i.test(f) || /^-[A-Za-z]*f/i.test(f));
+    if (hasR && hasF) return true; // -rf / -fr / -Rf / -r -f / --recursive --force
+  }
+  return false;
+}
+
+const RULES = [
+  { id: 'rm-rf', why: 'deletes whole files/folders irreversibly (rm with -r and -f)', match: isRmRecursiveForce },
+  { id: 'find-delete', why: 'mass-deletes matched files (find … -delete / -exec rm)', match: () => /\bfind\b[^|;&]*(-delete\b|-exec\s+rm\b)/i.test(cmd) },
+  { id: 'dd-disk', why: 'overwrites a raw disk device and can destroy the whole drive (dd of=/dev/…)', match: () => /\bdd\b[^|;&]*\bof=\/dev\//i.test(cmd) },
+  { id: 'mkfs', why: 'formats a filesystem, erasing everything on it (mkfs)', match: () => /\bmkfs(\.\w+)?\b/i.test(cmd) },
+  { id: 'curl-pipe-shell', why: 'pipes a downloaded script straight into a shell (curl|bash) — runs untrusted code', match: () => /\b(curl|wget)\b[^|]*\|\s*(sudo\s+)?(sh|bash|zsh)\b/i.test(cmd) },
+
+  { id: 'git-push-force', why: 'force-pushes and can overwrite shared history for everyone (git push --force)', match: () => /\bgit\s+push\b[^|;&]*(--force(?!-with-lease)\b|\s-f\b)/i.test(cmd) },
+  { id: 'git-reset-hard', why: 'throws away all uncommitted work with no undo (git reset --hard)', match: () => /\bgit\s+reset\b[^|;&]*--hard\b/i.test(cmd) },
+  { id: 'git-clean', why: 'permanently deletes untracked files (git clean -f)', match: () => /\bgit\s+clean\b[^|;&]*-[a-z]*f/i.test(cmd) },
+  { id: 'git-branch-D', why: 'force-deletes a branch even if its work was never merged (git branch -D)', match: () => /\bgit\s+branch\b[^|;&]*\s-D\b/.test(cmd) },
+
+  { id: 'sql-drop', why: 'drops an entire database/schema/table (DROP …)', match: () => /\bdrop\s+(database|schema|table)\b/i.test(cmd) },
+  { id: 'sql-truncate', why: 'empties an entire table (TRUNCATE)', match: () => /\btruncate\s+(table\s+)?\S/i.test(cmd) },
+  { id: 'sql-delete-no-where', why: 'deletes EVERY row — a DELETE with no WHERE clause', match: () => noWhere(/\bdelete\s+from\s+\S/i) },
+  { id: 'sql-update-no-where', why: 'rewrites EVERY row — an UPDATE with no WHERE clause', match: () => noWhere(/\bupdate\s+\S+\s+set\b/i) },
+  { id: 'mongo-wipe', why: 'drops a collection/database or deletes all documents (drop()/dropDatabase/deleteMany({}))', match: () => /\.drop\(\s*\)|dropdatabase\s*\(|deletemany\(\s*\{\s*\}\s*\)|\.remove\(\s*\{\s*\}\s*\)/i.test(cmd) },
+];
+
+for (const rule of RULES) {
+  try { if (rule.match()) deny(rule.why); } catch { /* a rule erroring must never block */ }
+}
+
+allow();

package/targets/gitmoji-guard.mjs

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+// rsc Gitmoji guard (claude). Wired by targets/claude.js onto PreToolUse (matcher Bash)
+// as `node ...` so it runs on every platform including Windows.
+//   argv[2] = absolute project root   stdin = PreToolUse hook JSON
+//
+// Enforces one convention at the only deterministic moment it can be enforced: the
+// commit is being written. Every commit message this harness produces carries a
+// gitmoji (https://gitmoji.dev) — the intention of the change, visible in one glyph
+// in `git log --oneline`, on top of the Conventional Commits grammar that already
+// drives the semver bump. Prose in a skill asks; this hook decides.
+//
+// Accepted shapes (both are gitmoji-valid; the first is what `git-workflow` prescribes):
+//   ✨ feat(api): add cursor paging
+//   feat(api): ✨ add cursor paging
+//
+// Design (constitution P1/P2/P6/P7): deterministic, local-only, precise — it fires only
+// on a `git commit` that carries its message inline, where the message can actually be
+// read. Anything it cannot read with certainty (editor commit, -F file, --amend
+// --no-edit, an unparseable command) is ALLOWED: a guard that guesses is a guard that
+// gets turned off. Every deny names its recovery. Opt out with .rsc/.no-gitmoji.
+import { pathToFileURL } from 'node:url';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// The official gitmoji set (gitmoji.dev/api/gitmojis), as data: [emoji, code, semver, meaning].
+// A table, not a chain of ifs — so a test can iterate it and the reference doc can be
+// checked against it instead of drifting apart in prose.
+export const GITMOJIS = [
+  ['🎨', ':art:', null, "Improve structure / format of the code."],
+  ['⚡️', ':zap:', 'patch', "Improve performance."],
+  ['🔥', ':fire:', null, "Remove code or files."],
+  ['🐛', ':bug:', 'patch', "Fix a bug."],
+  ['🚑️', ':ambulance:', 'patch', "Critical hotfix."],
+  ['✨', ':sparkles:', 'minor', "Introduce new features."],
+  ['📝', ':memo:', null, "Add or update documentation."],
+  ['🚀', ':rocket:', null, "Deploy stuff."],
+  ['💄', ':lipstick:', 'patch', "Add or update the UI and style files."],
+  ['🎉', ':tada:', null, "Begin a project."],
+  ['✅', ':white_check_mark:', null, "Add, update, or pass tests."],
+  ['🔒️', ':lock:', 'patch', "Fix security or privacy issues."],
+  ['🔐', ':closed_lock_with_key:', null, "Add or update secrets."],
+  ['🔖', ':bookmark:', null, "Release / Version tags."],
+  ['🚨', ':rotating_light:', null, "Fix compiler / linter warnings."],
+  ['🚧', ':construction:', null, "Work in progress."],
+  ['💚', ':green_heart:', null, "Fix CI Build."],
+  ['⬇️', ':arrow_down:', 'patch', "Downgrade dependencies."],
+  ['⬆️', ':arrow_up:', 'patch', "Upgrade dependencies."],
+  ['📌', ':pushpin:', 'patch', "Pin dependencies to specific versions."],
+  ['👷', ':construction_worker:', null, "Add or update CI build system."],
+  ['📈', ':chart_with_upwards_trend:', 'patch', "Add or update analytics or track code."],
+  ['♻️', ':recycle:', null, "Refactor code."],
+  ['➕', ':heavy_plus_sign:', 'patch', "Add a dependency."],
+  ['➖', ':heavy_minus_sign:', 'patch', "Remove a dependency."],
+  ['🔧', ':wrench:', 'patch', "Add or update configuration files."],
+  ['🔨', ':hammer:', null, "Add or update development scripts."],
+  ['🌐', ':globe_with_meridians:', 'patch', "Internationalization and localization."],
+  ['✏️', ':pencil2:', 'patch', "Fix typos."],
+  ['💩', ':poop:', null, "Write bad code that needs to be improved."],
+  ['⏪️', ':rewind:', 'patch', "Revert changes."],
+  ['🔀', ':twisted_rightwards_arrows:', null, "Merge branches."],
+  ['📦️', ':package:', 'patch', "Add or update compiled files or packages."],
+  ['👽️', ':alien:', 'patch', "Update code due to external API changes."],
+  ['🚚', ':truck:', null, "Move or rename resources (e.g.: files, paths, routes)."],
+  ['📄', ':page_facing_up:', null, "Add or update license."],
+  ['💥', ':boom:', 'major', "Introduce breaking changes."],
+  ['🍱', ':bento:', 'patch', "Add or update assets."],
+  ['♿️', ':wheelchair:', 'patch', "Improve accessibility."],
+  ['💡', ':bulb:', null, "Add or update comments in source code."],
+  ['🍻', ':beers:', null, "Write code drunkenly."],
+  ['💬', ':speech_balloon:', 'patch', "Add or update text and literals."],
+  ['🗃️', ':card_file_box:', 'patch', "Perform database related changes."],
+  ['🔊', ':loud_sound:', null, "Add or update logs."],
+  ['🔇', ':mute:', null, "Remove logs."],
+  ['👥', ':busts_in_silhouette:', null, "Add or update contributor(s)."],
+  ['🚸', ':children_crossing:', 'patch', "Improve user experience / usability."],
+  ['🏗️', ':building_construction:', null, "Make architectural changes."],
+  ['📱', ':iphone:', 'patch', "Work on responsive design."],
+  ['🤡', ':clown_face:', null, "Mock things."],
+  ['🥚', ':egg:', 'patch', "Add or update an easter egg."],
+  ['🙈', ':see_no_evil:', null, "Add or update a .gitignore file."],
+  ['📸', ':camera_flash:', null, "Add or update snapshots."],
+  ['⚗️', ':alembic:', 'patch', "Perform experiments."],
+  ['🔍️', ':mag:', 'patch', "Improve SEO."],
+  ['🏷️', ':label:', 'patch', "Add or update types."],
+  ['🌱', ':seedling:', null, "Add or update seed files."],
+  ['🚩', ':triangular_flag_on_post:', 'patch', "Add, update, or remove feature flags."],
+  ['🥅', ':goal_net:', 'patch', "Catch errors."],
+  ['💫', ':dizzy:', 'patch', "Add or update animations and transitions."],
+  ['🗑️', ':wastebasket:', 'patch', "Deprecate code that needs to be cleaned up."],
+  ['🛂', ':passport_control:', 'patch', "Work on code related to authorization, roles and permissions."],
+  ['🩹', ':adhesive_bandage:', 'patch', "Simple fix for a non-critical issue."],
+  ['🧐', ':monocle_face:', null, "Data exploration/inspection."],
+  ['⚰️', ':coffin:', null, "Remove dead code."],
+  ['🧪', ':test_tube:', null, "Add a failing test."],
+  ['👔', ':necktie:', 'patch', "Add or update business logic."],
+  ['🩺', ':stethoscope:', null, "Add or update healthcheck."],
+  ['🧱', ':bricks:', null, "Infrastructure related changes."],
+  ['🧑‍💻', ':technologist:', null, "Improve developer experience."],
+  ['💸', ':money_with_wings:', null, "Add sponsorships or money related infrastructure."],
+  ['🧵', ':thread:', null, "Add or update code related to multithreading or concurrency."],
+  ['🦺', ':safety_vest:', null, "Add or update code related to validation."],
+  ['✈️', ':airplane:', null, "Improve offline support."],
+  ['🦖', ':t-rex:', null, "Code that adds backwards compatibility."],];
+
+// Some official gitmojis carry U+FE0F (⚡️, 🔒️, 🗑️ …). A human typing the bare
+// code point means the same emoji, so compare with the variation selector stripped —
+// otherwise the guard would reject a correct commit over an invisible byte.
+const bare = (s) => s.replace(/️/g, '');
+export const EMOJI_SET = new Set(GITMOJIS.map(([e]) => bare(e)));
+export const CODE_SET = new Set(GITMOJIS.map(([, c]) => c));
+
+// git's own functional prefixes: these messages are consumed by `rebase --autosquash`,
+// not read by humans, and the final message is the target commit's. Nothing to enforce.
+const GIT_MAGIC = /^(fixup|squash|amend)!/;
+// A Conventional Commits header, optionally present before the emoji.
+const CONVENTIONAL = /^[a-zA-Z]+(\([^)\n]*\))?!?:\s*/;
+
+// Does this subject line open with a gitmoji — either before the conventional prefix
+// or immediately after it? An emoji buried mid-sentence is not an intention marker.
+export function hasGitmoji(message) {
+  const subject = String(message ?? '').split(/\r?\n/, 1)[0].trim();
+  if (!subject) return false;
+  if (GIT_MAGIC.test(subject)) return true;
+  const candidates = [subject, subject.replace(CONVENTIONAL, '')];
+  for (const c of candidates) {
+    const head = bare(c);
+    for (const e of EMOJI_SET) if (head.startsWith(e)) return true;
+    const code = head.match(/^:[a-z0-9_+-]+:/);
+    if (code && CODE_SET.has(code[0])) return true;
+  }
+  return false;
+}
+
+// ---- reading the message out of a shell command --------------------------------
+// Shell is not parseable in a regex and we do not pretend otherwise: this recognizes
+// the forms an agent or a human actually types, and returns null ("cannot tell") for
+// everything else so the caller allows it.
+
+const COMMIT = /\bgit\b(?:\s+-{1,2}\S+(?:\s+\S+)?)*\s+commit\b/;
+const NO_MESSAGE_TO_READ = /(?:^|\s)(?:-F|--file|--template|-C\s+\S*HEAD|--reuse-message|--reedit-message)\b/;
+const AMEND_NO_EDIT = /--no-edit\b/;
+const HAS_INLINE_M = /(?:^|\s)(?:-[a-zA-Z]*m|--message)(?:=|\s|$)/;
+// `git` must be the command being RUN, not text inside someone else's argument —
+// otherwise `echo "git commit -m x"` or `grep "git commit -m"` gets denied, and a guard
+// that blocks the discussion of commits is exactly the kind that gets switched off.
+const RUNS_GIT = /^\s*(?:sudo\s+)?(?:[A-Za-z_][A-Za-z0-9_]*=\S*\s+)*git\b/;
+
+const SEPARATORS = /&&|\|\||[;\n]/;
+
+// Is this segment a `git commit` that carries its message inline and readably?
+function readableCommit(segment) {
+  return RUNS_GIT.test(segment)
+    && COMMIT.test(segment)
+    && HAS_INLINE_M.test(segment)
+    && !NO_MESSAGE_TO_READ.test(segment)
+    && !AMEND_NO_EDIT.test(segment);
+}
+
+// `-m "$(cat <<'EOF' … EOF)"` — the multi-line form. The heredoc body IS the message,
+// and it may contain && or ; so it must be lifted out before any splitting.
+function heredocBody(command) {
+  const m = command.match(/<<-?\s*['"]?([A-Za-z_][A-Za-z0-9_]*)['"]?\r?\n([\s\S]*?)\r?\n[ \t]*\1\b/);
+  return m ? m[2] : null;
+}
+
+// -m/--message value, quoted or bare.
+function inlineMessage(segment) {
+  const m = segment.match(/(?:^|\s)(?:-[a-zA-Z]*m|--message)(?:=|\s+)("([^"]*)"|'([^']*)'|([^\s'"][^\s]*))/);
+  if (!m) return null;
+  return m[2] ?? m[3] ?? m[4] ?? null;
+}
+
+// Every commit message this command would write, or null when nothing is checkable.
+export function commitMessages(command) {
+  const cmd = String(command ?? '');
+  if (!COMMIT.test(cmd)) return [];
+
+  // The heredoc form must be handled before any splitting: its body is the message and
+  // may legitimately contain && or ;. The command that owns it is whatever runs just
+  // before the `<<`.
+  const hIdx = cmd.search(/<<-?\s*['"]?[A-Za-z_]/);
+  if (hIdx !== -1) {
+    const owner = cmd.slice(0, hIdx).split(SEPARATORS).pop() || '';
+    if (!readableCommit(owner)) return [];
+    const body = heredocBody(cmd);
+    if (body === null) return [];
+    const first = body.split(/\r?\n/).find((l) => l.trim() !== '');
+    return first === undefined ? [] : [first];
+  }
+
+  const out = [];
+  for (const segment of cmd.split(SEPARATORS)) {
+    if (!readableCommit(segment)) continue;
+    const msg = inlineMessage(segment);
+    if (msg === null) continue;                       // editor commit — cannot read it here
+    if (/^\$/.test(msg.trim())) continue;             // a variable/substitution, not a literal
+    out.push(msg);
+  }
+  return out;
+}
+
+// ---- the deny message (P6: the recovery lives inside the refusal) ---------------
+
+export const SUGGESTIONS = [
+  ['feat', '✨'], ['fix', '🐛'], ['docs', '📝'], ['refactor', '♻️'], ['test', '✅'],
+  ['perf', '⚡️'], ['chore', '🔧'], ['ci', '👷'], ['style', '🎨'], ['revert', '⏪️'],
+];
+
+export function denyMessage(message) {
+  const subject = String(message ?? '').split(/\r?\n/, 1)[0].trim();
+  const type = subject.match(/^([a-zA-Z]+)(\([^)\n]*\))?!?:/)?.[1]?.toLowerCase();
+  const hit = SUGGESTIONS.find(([t]) => t === type);
+  const rewrite = hit
+    ? `${hit[1]} ${subject}`
+    : `${SUGGESTIONS.find(([t]) => t === 'chore')[1]} ${subject || '<type>(<scope>): <subject>'}`;
+  return [
+    `This commit message has no gitmoji: "${subject}".`,
+    'Every commit in this project opens with a gitmoji (gitmoji.dev) before the Conventional Commits header — the intention of the change, readable in one glyph in `git log --oneline`.',
+    `Recover: re-run the commit with the emoji in front — \`${rewrite}\` — picking the gitmoji that matches the intention (✨ feature · 🐛 fix · 📝 docs · ♻️ refactor · ✅ tests · ⚡️ perf · 🔧 config · 👷 CI · 💥 breaking · 🔖 release). The full table is in the \`git-workflow\` skill (references/gitmoji.md). To turn this guard off for this project, create .rsc/.no-gitmoji.`,
+  ].join('\n');
+}
+
+// ---- hook entrypoint -----------------------------------------------------------
+// Skipped when imported by a test (P2: the mechanism is testable without a subprocess).
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const root = process.argv[2] || process.cwd();
+  const allow = () => process.exit(0);
+
+  if (existsSync(join(root, '.rsc', '.no-gitmoji'))) allow();
+
+  let input = {};
+  try { input = JSON.parse(readFileSync(0, 'utf8') || '{}'); } catch { allow(); }
+  if ((input.tool_name || input.toolName) !== 'Bash') allow();
+  const command = input.tool_input?.command || input.toolInput?.command || '';
+  if (typeof command !== 'string' || !command) allow();
+
+  let offender = null;
+  try {
+    offender = commitMessages(command).find((m) => !hasGitmoji(m)) ?? null;
+  } catch { allow(); } // any parsing surprise → allow (fail open, by design)
+  if (offender === null) allow();
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: denyMessage(offender),
+    },
+  }));
+  process.exit(0);
+}