@kontourai/flow-agents 3.2.0 → 3.4.0

package/scripts/hooks/lib/kit-catalog.js

@@ -0,0 +1,235 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const KIT_ID_RE = /^[a-z][a-z0-9-]*$/;
+const WORKFLOW_TRIGGER_IDENTIFIER_RE = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+const MAX_STEERING_VALUE_LENGTH = 240;
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function containedPath(root, rel) {
+  if (typeof rel !== 'string' || path.isAbsolute(rel)) return null;
+  const resolved = path.resolve(root, rel);
+  const absRoot = path.resolve(root);
+  if (resolved === absRoot || resolved.startsWith(`${absRoot}${path.sep}`)) return resolved;
+  return null;
+}
+
+function loadKitManifest(kitRoot, sourceKind, warnings) {
+  const manifestPath = path.join(kitRoot, 'kit.json');
+  try {
+    if (!fs.existsSync(manifestPath)) return null;
+    const manifest = readJson(manifestPath);
+    const kitId = typeof manifest.id === 'string' ? manifest.id : '';
+    if (!KIT_ID_RE.test(kitId)) {
+      warnings.push(`${manifestPath}: kit id must be a kebab-case id (^[a-z][a-z0-9-]*$); skipping kit`);
+      return null;
+    }
+    return { kit_id: kitId, source_kind: sourceKind, manifest };
+  } catch (error) {
+    warnings.push(`${manifestPath}: ${String(error && error.message ? error.message : error)}`);
+    return null;
+  }
+}
+
+function readKitManifests(root) {
+  const warnings = [];
+  const kits = [];
+  const catalogPath = path.join(root, 'kits', 'catalog.json');
+  if (fs.existsSync(catalogPath)) {
+    try {
+      const catalog = readJson(catalogPath);
+      if (Array.isArray(catalog.kits)) {
+        for (const entry of catalog.kits) {
+          const rel = entry && typeof entry === 'object' ? entry.path : undefined;
+          const kitRoot = containedPath(root, rel);
+          if (!kitRoot || !fs.existsSync(kitRoot)) continue;
+          const loaded = loadKitManifest(kitRoot, 'builtin', warnings);
+          if (loaded) kits.push(loaded);
+        }
+      }
+    } catch (error) {
+      warnings.push(String(error && error.message ? error.message : error));
+    }
+  }
+
+  const registryPath = path.join(root, 'kits', 'local', 'installed-kits.json');
+  if (fs.existsSync(registryPath)) {
+    try {
+      const registry = readJson(registryPath);
+      if (Array.isArray(registry.kits)) {
+        for (const entry of registry.kits) {
+          const id = entry && typeof entry === 'object' ? entry.id : undefined;
+          if (typeof id !== 'string') continue;
+          const kitRoot = path.join(root, 'kits', 'local', 'repositories', id);
+          if (!fs.existsSync(kitRoot)) continue;
+          const loaded = loadKitManifest(kitRoot, 'local', warnings);
+          if (loaded) kits.push(loaded);
+        }
+      }
+    } catch (error) {
+      warnings.push(String(error && error.message ? error.message : error));
+    }
+  }
+  return { kits, warnings };
+}
+
+function isWorkflowTriggerIdentifier(value) {
+  return typeof value === 'string' && WORKFLOW_TRIGGER_IDENTIFIER_RE.test(value);
+}
+
+function optionalWorkflowTriggerIdentifier(value) {
+  return value === undefined || isWorkflowTriggerIdentifier(value);
+}
+
+function optionalWorkflowTriggerIdentifierList(value) {
+  return value === undefined ||
+    (Array.isArray(value) && value.length > 0 && value.every(isWorkflowTriggerIdentifier));
+}
+
+function optionalConditionalSkills(value) {
+  return value === undefined ||
+    (Array.isArray(value) && value.every(item =>
+      item && typeof item === 'object' &&
+      isWorkflowTriggerIdentifier(item.when) &&
+      isWorkflowTriggerIdentifier(item.skill)
+    ));
+}
+
+function renderKitSteering(trigger) {
+  const kitId = isWorkflowTriggerIdentifier(trigger.kit_id) ? trigger.kit_id : '';
+  const category = isWorkflowTriggerIdentifier(trigger.when) ? trigger.when : 'matching';
+  const targetFlowId = isWorkflowTriggerIdentifier(trigger.target_flow_id) ? trigger.target_flow_id : '';
+  const defaultSkill = isWorkflowTriggerIdentifier(trigger.default_skill) ? trigger.default_skill : '';
+  const conditionalSkills = Array.isArray(trigger.conditional_skills) ? trigger.conditional_skills
+    .map(item => ({
+      when: isWorkflowTriggerIdentifier(item && item.when) ? item.when : '',
+      skill: isWorkflowTriggerIdentifier(item && item.skill) ? item.skill : '',
+    }))
+    .filter(item => item.when && item.skill) : [];
+  const requiredSequence = Array.isArray(trigger.required_sequence)
+    ? trigger.required_sequence.filter(isWorkflowTriggerIdentifier)
+    : [];
+  const postVerifyTargets = Array.isArray(trigger.post_verify_targets)
+    ? trigger.post_verify_targets.filter(isWorkflowTriggerIdentifier)
+    : [];
+
+  const lines = [
+    `KIT WORKFLOW ROUTE: this user prompt matches ${category}.`,
+  ];
+  if (kitId && targetFlowId) {
+    lines.push(`Before source edits or implementation commands, use the \`${kitId}\` kit's \`${targetFlowId}\` workflow.`);
+  } else if (kitId) {
+    lines.push(`Before source edits or implementation commands, use the \`${kitId}\` kit workflow.`);
+  } else {
+    lines.push('Before source edits or implementation commands, use the matching kit workflow.');
+  }
+  if (conditionalSkills.length || defaultSkill) {
+    const conditionalText = conditionalSkills
+      .map(item => `If ${item.when}, activate \`${item.skill}\``)
+      .join('; ');
+    if (conditionalText && defaultSkill) lines.push(`${conditionalText}; otherwise activate \`${defaultSkill}\`.`);
+    else if (conditionalText) lines.push(`${conditionalText}.`);
+    else lines.push(`Activate \`${defaultSkill}\`.`);
+  }
+  if (targetFlowId) {
+    lines.push(`Keep the session on \`${targetFlowId}\` and use \`npm run workflow:sidecar -- ensure-session --flow-id ${targetFlowId} ...\` when the repo provides the sidecar writer.`);
+  }
+  if (requiredSequence.length) {
+    lines.push(`Do not bypass ${requiredSequence.join(' -> ')} for matching work.`);
+  }
+  if (postVerifyTargets.length) {
+    lines.push(`After local verification, continue to ${postVerifyTargets.join(' and ')}; do not treat local verification as terminal delivery.`);
+  }
+  return lines.join(' ');
+}
+
+function workflowTriggerValidationErrors(manifest, manifestPath) {
+  const errors = [];
+  const raw = manifest.workflow_triggers;
+  if (raw === undefined) return errors;
+  if (!Array.isArray(raw)) {
+    errors.push(`${manifestPath}: .workflow_triggers must be a list`);
+    return errors;
+  }
+  const seenIds = new Set();
+  raw.forEach((trigger, index) => {
+    if (!trigger || typeof trigger !== 'object') {
+      errors.push(`${manifestPath}: workflow_triggers[${index}] must be an object`);
+      return;
+    }
+    if (!isWorkflowTriggerIdentifier(trigger.id)) {
+      errors.push(`${manifestPath}: workflow_triggers[${index}].id must match ^[a-z0-9]+(?:[.-][a-z0-9]+)*$`);
+      return;
+    }
+    if (seenIds.has(trigger.id)) errors.push(`${manifestPath}: workflow_triggers[${index}].id duplicates '${trigger.id}'`);
+    seenIds.add(trigger.id);
+    if (!isWorkflowTriggerIdentifier(trigger.when)) {
+      errors.push(`${manifestPath}: workflow_triggers[${index}].when must match ^[a-z0-9]+(?:[.-][a-z0-9]+)*$`);
+      return;
+    }
+    if (trigger.hint !== undefined) {
+      errors.push(`${manifestPath}: workflow_triggers[${index}].hint is retired; use structured steering fields`);
+      return;
+    }
+    if (trigger.display_name !== undefined) {
+      errors.push(`${manifestPath}: workflow_triggers[${index}].display_name is not supported in workflow_triggers; use catalog/listing metadata for human-readable names`);
+      return;
+    }
+    if (!optionalWorkflowTriggerIdentifier(trigger.target_flow_id)) {
+      errors.push(`${manifestPath}: workflow_triggers[${index}].target_flow_id must match ^[a-z0-9]+(?:[.-][a-z0-9]+)*$ when present`);
+      return;
+    }
+    if (!optionalWorkflowTriggerIdentifier(trigger.default_skill)) {
+      errors.push(`${manifestPath}: workflow_triggers[${index}].default_skill must match ^[a-z0-9]+(?:[.-][a-z0-9]+)*$ when present`);
+      return;
+    }
+    if (!optionalConditionalSkills(trigger.conditional_skills)) {
+      errors.push(`${manifestPath}: workflow_triggers[${index}].conditional_skills must be a list of { when, skill } identifiers matching ^[a-z0-9]+(?:[.-][a-z0-9]+)*$ when present`);
+      return;
+    }
+    if (!optionalWorkflowTriggerIdentifierList(trigger.required_sequence)) {
+      errors.push(`${manifestPath}: workflow_triggers[${index}].required_sequence must be a non-empty identifier list matching ^[a-z0-9]+(?:[.-][a-z0-9]+)*$ when present`);
+      return;
+    }
+    if (!optionalWorkflowTriggerIdentifierList(trigger.post_verify_targets)) {
+      errors.push(`${manifestPath}: workflow_triggers[${index}].post_verify_targets must be a non-empty identifier list matching ^[a-z0-9]+(?:[.-][a-z0-9]+)*$ when present`);
+    }
+  });
+  return errors;
+}
+
+function workflowTriggersFor(root, when) {
+  const result = [];
+  const inventory = readKitManifests(root);
+  for (const kit of inventory.kits) {
+    const triggers = kit.manifest.workflow_triggers;
+    if (!Array.isArray(triggers)) continue;
+    const manifestPath = path.join(root, kit.source_kind === 'local' ? 'kits/local/repositories' : 'kits', kit.kit_id, 'kit.json');
+    const parseErrors = workflowTriggerValidationErrors(kit.manifest, manifestPath);
+    if (parseErrors.length) {
+      const warning = `${kit.kit_id}: invalid workflow_triggers metadata; skipping workflow_triggers: ${parseErrors.join('; ')}`;
+      inventory.warnings.push(warning);
+      process.stderr.write(`[flow-agents] ${warning}\n`);
+      continue;
+    }
+    for (const trigger of triggers) {
+      if (trigger.when !== when) continue;
+      const steering = renderKitSteering({ ...trigger, kit_id: kit.kit_id });
+      if (!steering) continue;
+      result.push({ kit_id: kit.kit_id, id: trigger.id, when, steering });
+    }
+  }
+  return result;
+}
+
+module.exports = {
+  MAX_STEERING_VALUE_LENGTH,
+  renderKitSteering,
+  readKitManifests,
+  workflowTriggersFor,
+};

package/scripts/hooks/lib/liveness-write.js

@@ -19,6 +19,32 @@
 
 const fs = require('fs');
 const path = require('path');
+const { spawn } = require('child_process');
+
+/**
+ * OPTIONAL console liveness relay (#295, ADR 0021 §4/§7). Best-effort, FULLY detached mirror of a
+ * liveness event to the hosted Console via `scripts/liveness/relay.sh`. Local-first is sacred: this
+ * runs AFTER the durable local append and can never block, throw, or affect it — gated on
+ * `FLOW_AGENTS_CONSOLE_LIVENESS_RELAY`, the whole thing wrapped so any failure (missing script,
+ * spawn error) is swallowed. No flag ⇒ a single cheap env read and return (true no-op).
+ *
+ * @param {object} evt  The liveness event just written locally.
+ * @returns {void}
+ */
+function relayLivenessEvent(evt) {
+  try {
+    const flag = String(process.env.FLOW_AGENTS_CONSOLE_LIVENESS_RELAY || '').toLowerCase();
+    if (flag !== '1' && flag !== 'true' && flag !== 'yes' && flag !== 'on') return;
+    // scripts/hooks/lib/ -> scripts/liveness/relay.sh (same relative layout in dist/* bundles).
+    const relay = path.join(__dirname, '..', '..', 'liveness', 'relay.sh');
+    if (!fs.existsSync(relay)) return;
+    const child = spawn('bash', [relay, JSON.stringify(evt)], { detached: true, stdio: 'ignore' });
+    child.on('error', () => {}); // never surface a spawn failure
+    child.unref(); // fully detach — the parent never waits on the relay
+  } catch {
+    // Best-effort only: the durable local write already succeeded above.
+  }
+}
 
 /**
  * Resolve the path to the shared liveness event stream for a given artifact root.
@@ -40,7 +66,8 @@ function livenessStreamFile(root) {
 function appendLivenessEvent(root, evt) {
   const file = livenessStreamFile(root);
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.appendFileSync(file, `${JSON.stringify(evt)}\n`);
+  fs.appendFileSync(file, `${JSON.stringify(evt)}\n`); // local-first: the durable write happens first
+  relayLivenessEvent(evt); // then optionally mirror to the Console — best-effort, detached, off by default
 }
 
 module.exports = { livenessStreamFile, appendLivenessEvent };

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