@kontourai/flow-agents 3.3.0 → 3.4.0

package/scripts/hooks/lib/local-artifact-paths.js

@@ -2,14 +2,105 @@
 
 const fs = require('fs');
 const path = require('path');
+const { execFileSync } = require('child_process');
 
 const KONTOURAI_DIR = '.kontourai';
 const FLOW_AGENTS_RUNTIME_SUBDIR = 'flow-agents';
 const FLOW_AGENTS_RUNTIME_DIR = `${KONTOURAI_DIR}/${FLOW_AGENTS_RUNTIME_SUBDIR}`;
 const DURABLE_FLOW_AGENTS_DIR = '.flow-agents';
 
+/**
+ * #357: resolve the SHARED, git-common-dir-anchored repo root for `cwd`. CJS twin of
+ * src/lib/local-artifact-root.ts's resolveSharedRepoRoot — see that file's doc comment for
+ * the full rationale (git-common-dir resolves to the SAME primary-checkout .git directory
+ * from any linked worktree, so path.dirname() of its absolute form is the one shared repo
+ * root every worktree of a repo should read/write .kontourai/flow-agents under). Returns
+ * null (never throws) when git is unavailable, cwd is not inside a git working tree, or the
+ * command fails — callers MUST fail open to the existing cwd-based behavior in that case.
+ *
+ * #413 iteration-2 Fix 3: strips the ambient GIT_DIR/GIT_COMMON_DIR/GIT_WORK_TREE/
+ * GIT_CEILING_DIRECTORIES env vars before shelling out — see the TS twin's doc comment for
+ * the full rationale (an ambient GIT_DIR etc. could otherwise silently redirect resolution to
+ * a different repo than the one cwd is actually inside).
+ */
+function resolveSharedRepoRoot(cwd) {
+  try {
+    const env = { ...process.env };
+    delete env.GIT_DIR;
+    delete env.GIT_COMMON_DIR;
+    delete env.GIT_WORK_TREE;
+    delete env.GIT_CEILING_DIRECTORIES;
+    const out = execFileSync('git', ['rev-parse', '--git-common-dir'], {
+      cwd,
+      env,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    if (!out) return null;
+    const absoluteCommonDir = path.resolve(cwd, out);
+    return path.dirname(absoluteCommonDir);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * #413 iteration-2 Fix 1: cheap discriminator for the loud-vs-silent fail-open decision below.
+ * CJS twin of the TS lib's isInsideGitWorkingTree — see that file's doc comment for the full
+ * rationale. Walks up from `cwd` looking for a `.git` entry (file or directory) without
+ * shelling out to git, so it stays meaningful even when git itself is broken/absent.
+ */
+function isInsideGitWorkingTree(cwd) {
+  try {
+    let dir = path.resolve(cwd);
+    const root = path.parse(dir).root;
+    for (let depth = 0; depth < 40; depth++) {
+      if (fs.existsSync(path.join(dir, '.git'))) return true;
+      if (dir === root) break;
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * #413 iteration-2 Fix 1 (HIGH, security): emit a LOUD stderr warning before falling open, but
+ * ONLY when `cwd` is genuinely inside a git working tree AND resolveSharedRepoRoot still
+ * returned null. See the TS twin's doc comment for the full rationale — the benign case (no
+ * git repo at all) must stay perfectly silent; the loud case is #357's exact silent-fail-open
+ * bug (an isolated, invisible cwd-local store), and a warning (not a hard refuse, since this
+ * sits on read paths too) gives an operator the signal to pass --artifact-root explicitly.
+ */
+function warnIfFailingOpenInsideGitTree(cwd, fallbackPath) {
+  if (!isInsideGitWorkingTree(cwd)) return;
+  process.stderr.write(
+    `[artifact-root] WARNING: inside a git working tree but could not resolve the shared repo root ` +
+      `(git rev-parse --git-common-dir failed or returned nothing from ${cwd}); falling back to a ` +
+      `cwd-local store at ${fallbackPath} — coordination claims may be invisible to other ` +
+      `worktrees/actors. Pass --artifact-root explicitly to fix.\n`
+  );
+}
+
+/**
+ * #413 iteration-2 Fix 2 (documentation only, no behavior change): CJS twin of the TS lib's own
+ * doc comment on flowAgentsArtifactRoot — see that file for the full rationale. A SUBDIRECTORY
+ * cwd of a plain checkout intentionally resolves to the shared <repo-root>/.kontourai/flow-agents
+ * store (via the git-common-dir walk-up), not a subdir-anchored path.resolve(cwd, ...) — the
+ * correct one-store-per-repo semantics, not a regression.
+ */
 function flowAgentsArtifactRoot(cwd = process.cwd()) {
-  return path.resolve(cwd, FLOW_AGENTS_RUNTIME_DIR);
+  const sharedRepoRoot = resolveSharedRepoRoot(cwd);
+  if (sharedRepoRoot) return path.resolve(sharedRepoRoot, FLOW_AGENTS_RUNTIME_DIR);
+  // Fail-open: not a git repo, git unavailable, or command failed — reproduce today's plain
+  // cwd-based behavior unchanged (AC6 backward-compat guarantee). #413 iteration-2 Fix 1: loud,
+  // not silent, when cwd IS inside a git working tree (see warnIfFailingOpenInsideGitTree).
+  const fallback = path.resolve(cwd, FLOW_AGENTS_RUNTIME_DIR);
+  warnIfFailingOpenInsideGitTree(cwd, fallback);
+  return fallback;
 }
 
 function durableFlowAgentsRoot(cwd = process.cwd()) {
@@ -35,4 +126,9 @@ module.exports = {
   flowAgentsArtifactRoot,
   flowAgentsArtifactRootsForRead,
   defaultArtifactRootForRead,
+  resolveSharedRepoRoot,
+  // #413 iteration-2 Fix 1: exported so findRepoRoot in stop-goal-fit.js/workflow-steering.js
+  // can apply the SAME loud-when-in-git-tree warning this lib's own flowAgentsArtifactRoot
+  // uses, rather than a second, independently-drifting copy of the discriminator.
+  warnIfFailingOpenInsideGitTree,
 };

package/scripts/hooks/lib/runnable-command.js

@@ -0,0 +1,177 @@
+'use strict';
+/**
+ * runnable-command.js — shared pure-CJS runnable-command-text heuristic (#412)
+ *
+ * Zero external dependencies (only string ops). Consumed by:
+ *   - scripts/hooks/stop-goal-fit.js     (CJS, direct require)
+ *   - build/src/cli/workflow-sidecar.js  (ESM compiled, via createRequire)
+ *
+ * Extracted verbatim (no logic change) from stop-goal-fit.js's former inline
+ * `isRunnableCommandText`, so the heuristic has exactly one source of truth
+ * instead of drifting between the hook (Stop-time backstop) and the sidecar
+ * (record-time rejection).
+ *
+ * Exports:
+ *   isRunnableCommandText(text) → boolean
+ *   isAmbiguousAbsenceCommand(text) → boolean
+ */
+
+// WS8 (AC10b): a kind:"command" evidence ref's excerpt/command must be a literally runnable
+// shell command, not a prose description of a manual verification step. This heuristic
+// rejects prose so the goal-fit backstop never spawns `bash -lc "<a sentence>"` and
+// misreports the resulting shell error as a caught false-completion. Pairs with the rule
+// stated in context/contracts/planning-contract.md (AC11).
+//
+// #362 (Wave 3 coherence fix): a leading `!` negation (optionally followed by whitespace) is
+// stripped before evaluation, mirroring isAmbiguousAbsenceCommand's own negation handling
+// (runnable-command.js's OTHER export, above/below) -- a negated runnable command (e.g.
+// `! grep -r foo src/`, the exact self-asserting rewrite this module's ambiguous-absence
+// guidance recommends) is itself still a literally runnable shell command, not prose. Without
+// this, the ambiguous-absence advisory's own suggested remediation would be rejected by this
+// function's fatal runnability guard -- a self-defeating loop. Only a BARE leading `!` is
+// stripped (a single strip, not recursive); the remainder is evaluated by the existing checks
+// unchanged, so a genuinely non-command sentence that happens to start with `!` (e.g.
+// `! a prose sentence. It fails.`) still fails the sentence-like-prose check below and is
+// rejected, fail-closed exactly as before.
+function isRunnableCommandText(text) {
+  const s = typeof text === 'string' ? text.trim() : '';
+  if (!s) return false;
+  const unnegated = s.replace(/^!\s*/, '');
+  if (!unnegated) return false;
+
+  const prosePunctuation = /[.!?]\s+\S|[;:]\s+[A-Za-z]/;
+  const startsLikeSentence = /^[A-Z][A-Za-z]+(?:\s+[A-Z][A-Za-z]+|\s+[a-z]{2,})/.test(unnegated);
+  if (prosePunctuation.test(unnegated) && startsLikeSentence) return false;
+
+  const assignment = /^[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S*)/;
+  let rest = unnegated;
+  let sawAssignment = false;
+  // Strip leading KEY=value prefixes before evaluating the actual command token.
+  // A line containing only assignments is still a valid shell command.
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const m = rest.match(assignment);
+    if (!m) break;
+    sawAssignment = true;
+    rest = rest.slice(m[0].length).trimStart();
+    if (!rest) return true;
+  }
+
+  const first = rest.split(/\s+/)[0] || '';
+  if (!first) return sawAssignment;
+  // WS8 (AC10b, iteration 2): the first-token allowlist is broadened to the common
+  // real-world verify binaries a project's runnable evidence names (git, tsc, eslint,
+  // python/python3, docker, curl, jq, diff, grep, test) so honest command evidence is not
+  // misclassified as prose. Still fail-closed for genuinely non-command prose: a bare
+  // sentence whose first token is none of these (and carries no path prefix or shell
+  // metacharacter) is rejected rather than executed.
+  const knownBinary = /^(npm|npx|pnpm|yarn|node|bash|sh|zsh|make|just|task|cargo|go|pytest|tox|deno|bun|ruby|rake|mvn|gradle|dotnet|swift|flutter|dart|git|tsc|eslint|python|python3|docker|curl|jq|diff|grep|test|exit|cd|false|true|set|unset|export|echo|\[|return|:|source|\.)$/.test(first)
+    || first.startsWith('./') || first.startsWith('/') || first.includes('/');
+  if (knownBinary) {
+    const remainder = rest.slice(first.length).trim();
+    if (!remainder) return true;
+    if (isCommandShapedRemainder(remainder)) return true;
+    return !isPlainEnglishRemainder(remainder);
+  }
+
+  // Shell operators are only a command signal when the first token itself looks like a
+  // command word. Incidental punctuation in prose ("External CI (green)", "done: shipped")
+  // must not make the text runnable.
+  const commandLikeToken = /^[a-z_][a-z0-9._+-]*$/i.test(first) && first === first.toLowerCase();
+  const hasCommandPositionOperator = /(?:^|\s)(?:&&|\|\||[|;])(?:\s|$)|[$`]/.test(rest);
+  if (commandLikeToken && hasCommandPositionOperator && !/[;:]\s+[A-Za-z]{2,}/.test(rest)) return true;
+
+  return false;
+}
+
+function isCommandShapedRemainder(remainder) {
+  const tokens = remainder.split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) return true;
+  if (/['"`|&;<>()${}]/.test(remainder)) return true;
+  return tokens.some((token) => {
+    return /^--?[A-Za-z0-9][A-Za-z0-9_-]*(?:=.*)?$/.test(token)
+      || /^[A-Za-z_][A-Za-z0-9_]*=/.test(token)
+      || token.startsWith('./')
+      || token.includes('/')
+      || /\.[A-Za-z0-9]{1,12}(?::\d+)?$/.test(token);
+  });
+}
+
+function isPlainEnglishRemainder(remainder) {
+  const tokens = remainder.split(/\s+/).filter(Boolean);
+  if (tokens.length < 3) return false;
+  return tokens.every((token) => /^[A-Za-z]+[,.]?$/.test(token));
+}
+
+// #362: a BARE (non-negated, non-self-asserting) `grep`/`diff` invocation is exit-code
+// AMBIGUOUS for its two most common uses — a "the thing is absent" check (author intends
+// exit 1 = PASS) and a "the thing is present" check (author intends exit 1 = FAIL) look
+// byte-identical to any downstream consumer that only sees the exit code. This heuristic
+// recognizes that SHAPE (narrowly: grep/diff only, per the plan's explicit two-binary
+// carve-out — see plan body "#362 root cause") so callers can classify a bare exit-1
+// result as ambiguous/NOT_VERIFIED instead of guessing pass or fail.
+//
+// A command is NOT ambiguous (i.e. already self-asserting, exit code already encodes the
+// author's intent) when ANY of:
+//   - it is negated with a leading `!` (`! grep ...` — negation flips 0/1 into the
+//     intended fail/pass, so exit 0 unambiguously means "pattern is present/absent" per
+//     the author's own assertion)
+//   - it is part of a `||`/`&&` boolean chain (`grep ... || true`, `grep ... && echo ok`)
+//     — the chain itself already asserts what a given branch outcome means
+//   - it is piped into a count-assertion (`grep -c ... | grep -qx 0`, `grep ... | wc -l`
+//     style) — the author is asserting on a MATCH COUNT, not on grep's own raw exit code
+//   - its first real command token (after stripping `bash -lc '...'` wrapping and any
+//     leading `KEY=value` env assignments) is not exactly `grep` or `diff`
+//
+// FROZEN, narrowly-scoped by design (plan item 4): exactly two binaries, one ambiguous
+// exit code each (1). Do NOT grow this into a general per-binary exit-code table — that
+// is explicitly rejected in the plan (unreliable for pipelines/subshells/compound
+// commands). This function classifies EXIT-CODE ambiguity only; it has no opinion on
+// (and does not touch) the recorded command's regex dialect/flags (BRE vs ERE, -E/-P/-G,
+// etc.) — that is a SEPARATE invariant, enforced at replay time by
+// `resolveTrustedCommand`/`runBackstop` (scripts/hooks/stop-goal-fit.js, search
+// "DIALECT-PRESERVATION INVARIANT"): the recorded command string is replayed verbatim on
+// every backstop re-run path so a `grep -E '(foo|bar)'`-style ERE construct is never
+// silently reinterpreted as BRE.
+function isAmbiguousAbsenceCommand(text) {
+  const s = typeof text === 'string' ? text.trim() : '';
+  if (!s) return false;
+
+  // Unwrap a `bash -lc '<command>'` / `sh -c "<command>"` style wrapper so the real
+  // command is inspected, not the shell launcher. Only a single level of unwrapping is
+  // attempted — this stays a narrow heuristic, not a shell parser.
+  let inner = s;
+  const wrapped = inner.match(/^(?:bash|sh|zsh)\s+-\S*c\s+(['"])([\s\S]*)\1\s*$/);
+  if (wrapped) inner = wrapped[2].trim();
+
+  if (!inner) return false;
+
+  // Negation anywhere at the start of the (unwrapped) command already asserts intent.
+  if (/^!\s*/.test(inner)) return false;
+
+  // A `||`/`&&` boolean chain already asserts what a given exit code means for the
+  // overall command (e.g. `grep ... || true`, `grep ... && echo found`).
+  if (/\|\|/.test(inner) || /&&/.test(inner)) return false;
+
+  // Strip leading `KEY=value` environment assignments (e.g. `FOO=bar grep ...`) to find
+  // the first REAL command token.
+  let rest = inner;
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const m = rest.match(/^[A-Za-z_][A-Za-z0-9_]*=\S*\s+(\S[\s\S]*)$/);
+    if (!m) break;
+    rest = m[1].trim();
+  }
+
+  // A pipe (any `|`, since `||` was already excluded above) into a count-assertion
+  // (`grep -c ... | grep -qx 0`, `... | wc -l`) already asserts intent on the MATCH
+  // COUNT, not on grep/diff's own raw exit code — so ANY pipe makes this "not a bare
+  // invocation" for this narrow heuristic: a bare absence-style grep/diff is by
+  // definition not piped anywhere.
+  if (rest.includes('|')) return false;
+
+  const first = rest.trim().split(/\s+/)[0] || '';
+  return first === 'grep' || first === 'diff';
+}
+
+module.exports = { isRunnableCommandText, isAmbiguousAbsenceCommand };

package/scripts/hooks/lib/skill-drift.js

@@ -0,0 +1,350 @@
+'use strict';
+/**
+ * skill-drift.js — shared pure-CJS manifest/drift-comparison library for installed Claude Code
+ * skill files (kontourai/flow-agents#439, slice 1).
+ *
+ * Zero external dependencies (only Node core: fs, path, crypto, os). Consumed by:
+ *   - src/cli/init.ts               (compiled ESM, via createRequire — writes the manifest at
+ *                                     `init --global` sync time, Wave 2)
+ *   - src/cli/skill-drift-check.ts  (compiled ESM, via createRequire — standalone read-only
+ *                                     CLI check, Wave 2)
+ *   - scripts/hooks/workflow-steering.js (CJS, direct require — SessionStart advisory, Wave 2)
+ *
+ * Purpose (issue #439): this is the SINGLE choke point for classifying installed-skill drift so
+ * the manifest writer, the CLI check, and the SessionStart advisory can never disagree with one
+ * another about what "in sync" / "stale" / "user-modified" means for a given file. Every consumer
+ * calls `compareSkillDrift()` instead of hand-rolling its own comparison, mirroring the same
+ * "one shared CJS module, multiple TS/hook consumers" convention already established by
+ * `current-pointer.js` (#291) and `actor-identity.js` for this repo's TS/CJS boundary.
+ *
+ * Hashing convention: `hashFile()` returns `"sha256:<hex>"` — the SAME string prefix convention
+ * `src/cli/kit.ts`'s `contentHash`/`kitContentHash` already established for Flow Kit installs.
+ * This module does not invent a second hash format (ADR 0008/0010 consume-never-fork).
+ *
+ * File-walk convention: `walkFilesSorted()`/`relPathPosix()` re-implement the SAME
+ * sorted-recursive-`readdirSync` traversal and POSIX-joined relative-path normalization as
+ * `src/lib/fs.ts`'s `walkFiles`/`relPath` — byte-identical relative-path strings for the same
+ * directory tree. This file cannot `import` that TS module directly (it must stay pure CJS so
+ * `workflow-steering.js` can `require()` it directly without a compiled-ESM detour), so it is an
+ * intentional, minimal, SAME-SHAPE re-implementation across the CJS boundary, not a fork of
+ * behavior — this must not diverge from `walkFiles`/`relPath` at review time.
+ *
+ * Exports:
+ *   hashFile(absPath)                                  → "sha256:<hex>" string
+ *   buildManifest({ skillsSourceDir, runtime })         → manifest object (see below)
+ *   loadManifest(manifestPath)                          → parsed manifest object, or null if
+ *                                                          absent/unreadable (never throws)
+ *   writeManifestAtomic(manifestPath, manifest)          → void (tmp-write-then-rename, same
+ *                                                          idiom `src/cli/init.ts` uses for
+ *                                                          `install.json`)
+ *   compareSkillDrift({ installedDir, kitSourceDir, manifest }) → drift report (see below)
+ *   resolveClaudeGlobalSkillsDir(env = process.env)      → string (the global claude-code dest
+ *                                                          dir, e.g. `~/.claude`, honoring
+ *                                                          FLOW_AGENTS_USER_CLAUDE_SETTINGS for
+ *                                                          test isolation — same resolution
+ *                                                          `src/cli/init.ts`'s `globalDest`
+ *                                                          already implements for "claude-code")
+ *
+ * Manifest shape:
+ *   {
+ *     schema_version: "1.0",
+ *     runtime: string,
+ *     generatedAt: string (ISO 8601),
+ *     sourceDir: string,
+ *     files: { "<skill>/<relpath>": "sha256:<hex>", ... }
+ *   }
+ *
+ * Drift report shape (from compareSkillDrift):
+ *   {
+ *     checkedAt: string (ISO 8601),
+ *     installedDir: string,
+ *     kitSourceDir: string,
+ *     manifestFound: boolean,
+ *     files: [{ path, state, installedHash, kitHash, manifestHash }],
+ *     summary: { total, inSync, kitUpdated, userModified, unbaselined, missingInstall, kitRemoved },
+ *     hasDrift: boolean
+ *   }
+ *
+ * Classification states (one of exactly six per file; names must stay identical across every
+ * consumer — the manifest writer, the CLI check, and the hook advisory never hand-roll their own
+ * classification strings):
+ *   - "in_sync"        installedHash === kitHash (installed bytes already match current kit
+ *                       source, regardless of manifest).
+ *   - "kit_updated"     installedHash !== kitHash but installedHash === manifestHash (installed
+ *                       copy matches the last recorded baseline; kit source has since changed).
+ *   - "user_modified"   installedHash !== manifestHash (and not in_sync) — installed bytes were
+ *                       changed locally since the last recorded install. This ALWAYS wins over
+ *                       "kit_updated" when both installedHash !== kitHash and
+ *                       installedHash !== manifestHash are true (never silently reclassified as
+ *                       a kit update).
+ *   - "unbaselined"     no manifest entry exists for this path (manifest missing entirely, or
+ *                       present but lacking this path's key) and installedHash !== kitHash —
+ *                       reported distinctly, never conflated with user_modified/kit_updated.
+ *   - "missing_install" a kit-source file has no installed counterpart at all (skill never
+ *                       synced locally yet) — reported distinctly, though also resolved by the
+ *                       same refresh command as the other non-in_sync states.
+ *   - "kit_removed"     kitHash === null (the path no longer exists anywhere in the current kit
+ *                       source) but the installed file still matches the last recorded baseline
+ *                       exactly (installedHash === manifestHash). Distinct from "kit_updated":
+ *                       the additive `copyDirMerge`-based refresh can only add/update files, it
+ *                       can never delete, so it cannot "fix" this state — reported with guidance
+ *                       to review/remove the installed file manually. Sub-case precedence:
+ *                       kitHash === null AND installedHash !== manifestHash still classifies as
+ *                       "user_modified" (installed bytes differ from the recorded baseline wins
+ *                       over "kit_removed", same precedence rule as the kit_updated case above).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const os = require('os');
+
+/**
+ * Sorted recursive file walk — mirrors `src/lib/fs.ts`'s `walkFiles` exactly (sorted
+ * `fs.readdirSync`, depth-first, files only). Returns absolute paths.
+ *
+ * Uses `readdirSync(dir, { withFileTypes: true })` Dirent type checks — NOT `fs.statSync`, which
+ * follows symlinks — so a symlink under the tree (e.g. pointing outside it, or dangling/looped)
+ * is neither followed nor hashed, and never throws (ELOOP / ENOENT on a dangling symlink). This
+ * is the exact same semantics `copyDirMerge` already uses for install copying
+ * (`src/cli/init.ts`): recurse into `entry.isDirectory()`, include `entry.isFile()`, silently
+ * skip everything else (symlinks, sockets, etc). Manifest/drift walking and install copying must
+ * never disagree about which files exist.
+ *
+ * @param {string} root
+ * @returns {string[]}
+ */
+function walkFilesSorted(root) {
+  const out = [];
+  if (!fs.existsSync(root)) return out;
+  const entries = fs.readdirSync(root, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  for (const entry of entries) {
+    const file = path.join(root, entry.name);
+    if (entry.isDirectory()) out.push(...walkFilesSorted(file));
+    else if (entry.isFile()) out.push(file);
+    // else: symlink, socket, fifo, etc — skip (see doc comment above).
+  }
+  return out;
+}
+
+/**
+ * POSIX-joined relative path — mirrors `src/lib/fs.ts`'s `relPath` exactly.
+ *
+ * @param {string} root
+ * @param {string} file
+ * @returns {string}
+ */
+function relPathPosix(root, file) {
+  const rel = path.relative(root, file);
+  return rel && !rel.startsWith('..') && !path.isAbsolute(rel)
+    ? rel.split(path.sep).join('/')
+    : file.split(path.sep).join('/');
+}
+
+/**
+ * `sha256:<hex>` content hash of a single file — same prefix convention as
+ * `src/cli/kit.ts`'s `contentHash`/`kitContentHash`.
+ *
+ * @param {string} absPath
+ * @returns {string}
+ */
+function hashFile(absPath) {
+  const hash = crypto.createHash('sha256');
+  hash.update(fs.readFileSync(absPath));
+  return `sha256:${hash.digest('hex')}`;
+}
+
+/**
+ * Builds a per-skill-file content-hash manifest by walking `skillsSourceDir` (e.g. a built
+ * `dist/claude-code/.claude/skills` bundle directory). Keys are POSIX relative paths under
+ * `skillsSourceDir` (e.g. `pull-work/SKILL.md`).
+ *
+ * @param {{ skillsSourceDir: string, runtime: string }} params
+ * @returns {object} manifest (see module doc comment for shape)
+ */
+function buildManifest({ skillsSourceDir, runtime }) {
+  const files = {};
+  for (const file of walkFilesSorted(skillsSourceDir)) {
+    const rel = relPathPosix(skillsSourceDir, file);
+    files[rel] = hashFile(file);
+  }
+  return {
+    schema_version: '1.0',
+    runtime,
+    generatedAt: new Date().toISOString(),
+    sourceDir: skillsSourceDir,
+    files,
+  };
+}
+
+/**
+ * Best-effort tolerant manifest read: missing file or corrupt/unparseable content are BOTH
+ * treated as "absent" (returns null), never thrown — mirrors the `readCurrentPointer`-style
+ * tolerance already established for advisory reads in this repo.
+ *
+ * @param {string} manifestPath
+ * @returns {object|null}
+ */
+function loadManifest(manifestPath) {
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Atomic write: tmp-write-then-rename, the SAME idiom `src/cli/init.ts` already uses for
+ * `install.json` (`${path}.tmp.${pid}` then `fs.renameSync`).
+ *
+ * @param {string} manifestPath
+ * @param {object} manifest
+ * @returns {void}
+ */
+function writeManifestAtomic(manifestPath, manifest) {
+  fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+  const tmp = `${manifestPath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+  fs.renameSync(tmp, manifestPath);
+}
+
+/**
+ * Hashes a single relative path under `dir`, if it exists there as a file. Returns null if
+ * absent (covers both "not installed yet" and "not present in this kit source snapshot").
+ *
+ * @param {string} dir
+ * @param {string} rel
+ * @returns {string|null}
+ */
+function hashRelIfPresent(dir, rel) {
+  const abs = path.join(dir, rel);
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) return null;
+  try {
+    return hashFile(abs);
+  } catch {
+    // Race between the existsSync/statSync check above and this read (file deleted or made
+    // unreadable in between — ENOENT/EACCES) — treat as "hash unavailable" (null), same as "not
+    // present", rather than throwing and crashing the whole drift check over one flaky file.
+    return null;
+  }
+}
+
+/**
+ * Compares installed skill files, the current kit/bundle source, and the last-recorded manifest
+ * baseline, classifying every relative path into exactly one of six states. See the module doc
+ * comment for the full state semantics and precedence rules.
+ *
+ * @param {{ installedDir: string, kitSourceDir: string, manifest: object|null }} params
+ * @returns {object} drift report (see module doc comment for shape)
+ */
+function compareSkillDrift({ installedDir, kitSourceDir, manifest }) {
+  const manifestFiles = manifest && manifest.files && typeof manifest.files === 'object' ? manifest.files : null;
+
+  const relPaths = new Set();
+  for (const file of walkFilesSorted(kitSourceDir)) relPaths.add(relPathPosix(kitSourceDir, file));
+  for (const file of walkFilesSorted(installedDir)) relPaths.add(relPathPosix(installedDir, file));
+  if (manifestFiles) {
+    for (const rel of Object.keys(manifestFiles)) {
+      // Defense-in-depth: our own writer (`buildManifest`) only ever produces POSIX-relative
+      // keys derived from `walkFilesSorted` + `relPathPosix`, so a key that is absolute, contains
+      // a backslash, or has any '..' path segment can only come from a malformed or hostile
+      // manifest — skip it entirely (never join it onto installedDir/kitSourceDir, never report
+      // it) rather than trusting untrusted manifest content into a path.join.
+      if (path.isAbsolute(rel) || rel.includes('\\') || rel.split('/').includes('..')) continue;
+      relPaths.add(rel);
+    }
+  }
+
+  const summary = { total: 0, inSync: 0, kitUpdated: 0, userModified: 0, unbaselined: 0, missingInstall: 0, kitRemoved: 0 };
+  const files = [];
+
+  for (const rel of Array.from(relPaths).sort()) {
+    const installedHash = hashRelIfPresent(installedDir, rel);
+    const kitHash = hashRelIfPresent(kitSourceDir, rel);
+    const manifestHash = manifestFiles && Object.prototype.hasOwnProperty.call(manifestFiles, rel) ? manifestFiles[rel] : null;
+
+    // A path recorded only in a stale manifest, with no counterpart in the kit source NOR the
+    // installed dir any more, is nothing currently installable or driftable — skip it rather
+    // than inventing a seventh state for it.
+    if (installedHash === null && kitHash === null) continue;
+
+    // An installed-only path with no kit-source counterpart AND no manifest entry is outside the
+    // kit's jurisdiction entirely — e.g. another tool's skill directory living alongside
+    // kit-installed skills under the same shared `~/.claude/skills` dest. `copyDirMerge`'s doc
+    // contract (`src/cli/init.ts`) is explicit that the dest may hold unrelated content it must
+    // never touch; the drift classifier honors the same boundary by staying silent about paths it
+    // never owned, rather than reporting them "unbaselined". `unbaselined` stays reserved for
+    // kit-owned paths (kitHash !== null) that simply predate the manifest baseline; `kit_removed`
+    // is unaffected — a manifest entry there proves prior kit ownership, so it never reaches this
+    // skip (manifestHash === null is required here).
+    if (kitHash === null && manifestHash === null) continue;
+
+    let state;
+    if (kitHash !== null && installedHash === null) {
+      state = 'missing_install';
+    } else if (installedHash !== null && kitHash !== null && installedHash === kitHash) {
+      state = 'in_sync';
+    } else if (manifestHash === null) {
+      state = 'unbaselined';
+    } else if (installedHash !== manifestHash) {
+      // user_modified always wins over kit_updated/kit_removed when installed bytes differ from
+      // the recorded baseline — see module doc comment. This precedence also covers the
+      // kitHash === null sub-case (file removed from kit source AND locally modified): still
+      // reported as user_modified, never kit_removed.
+      state = 'user_modified';
+    } else if (kitHash === null) {
+      // Installed file matches the last recorded baseline exactly, but no longer exists anywhere
+      // in the current kit source (removed upstream). Distinct from kit_updated: the additive
+      // copyDirMerge-based refresh cannot delete, so it cannot "fix" this state.
+      state = 'kit_removed';
+    } else {
+      state = 'kit_updated';
+    }
+
+    files.push({ path: rel, state, installedHash, kitHash, manifestHash });
+    summary.total += 1;
+    if (state === 'in_sync') summary.inSync += 1;
+    else if (state === 'kit_updated') summary.kitUpdated += 1;
+    else if (state === 'user_modified') summary.userModified += 1;
+    else if (state === 'unbaselined') summary.unbaselined += 1;
+    else if (state === 'missing_install') summary.missingInstall += 1;
+    else if (state === 'kit_removed') summary.kitRemoved += 1;
+  }
+
+  return {
+    checkedAt: new Date().toISOString(),
+    installedDir,
+    kitSourceDir,
+    manifestFound: manifest !== null,
+    files,
+    summary,
+    hasDrift: files.some((entry) => entry.state !== 'in_sync'),
+  };
+}
+
+/**
+ * Resolves the global claude-code destination directory (e.g. `~/.claude`), honoring
+ * `FLOW_AGENTS_USER_CLAUDE_SETTINGS` for test isolation — the SAME resolution
+ * `src/cli/init.ts`'s `globalDest("claude-code")` already implements, re-implemented here in
+ * pure CJS so `workflow-steering.js` can call it directly without a `createRequire`-of-a-
+ * differently-shaped-compiled-path detour. `src/cli/skill-drift-check.ts` instead calls the
+ * real exported `globalDest` from `init.ts` directly (already TS-to-TS, no duplication needed
+ * there).
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string}
+ */
+function resolveClaudeGlobalSkillsDir(env = process.env) {
+  const override = env['FLOW_AGENTS_USER_CLAUDE_SETTINGS'];
+  if (override) return path.dirname(override);
+  return path.join(os.homedir(), '.claude');
+}
+
+module.exports = {
+  hashFile,
+  buildManifest,
+  loadManifest,
+  writeManifestAtomic,
+  compareSkillDrift,
+  resolveClaudeGlobalSkillsDir,
+};