@codedology/code-forge 0.5.1 → 0.6.1

package/src/session/facts.mjs

@@ -117,11 +117,93 @@ const COMMAND_IN_SPAN = /^([a-z][a-z0-9-]*) ([a-z][a-z0-9-]*)(?![\w.\/-])/;
 const trimTail = (token) => token.replace(/[.,:;]+$/, '');
 
 /**
- * Every claim token of `text`, deduplicated by (kind, token), in order of first appearance.
+ * @typedef {object} ExtractOpts
+ * @property {ReadonlyArray<string>} [projectBins] - the project's own CLI names (its package.json
+ *   `bin` keys, {@link readProjectBins}); none ⇒ command claims are kept as written.
+ * @property {string} [briefText] - the brief alone (no sources): only IT can name the project CLI
+ *   that a command claim gets prefixed with (default: the whole text).
+ */
+
+/**
+ * `word` as a whole CLI word: not inside another word (`a-word`, `word2`), a path (`./word`,
+ * `dir/word`) or a file name (`.word.yml`, `word.config`); a sentence's full stop after it is fine.
+ * @param {string} word @returns {RegExp}
+ */
+export const cliWordRe = (word) => new RegExp(`(?<![\\w./-])${word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w/-]|\\.\\w)`);
+
+/**
+ * Does the brief use `word` as a CLI of its own in a code span — the span is `word` alone, or `word`
+ * followed by an option or a path (`` `gh` ``, `` `gh --repo x` ``, `` `jq ./a.json` ``)? A
+ * `` `word verb` `` span is the claim shape itself and does not count.
+ * @param {string} word @param {string} brief
+ * @returns {boolean}
+ */
+function namedAsCli(word, brief) {
+  return [...brief.matchAll(/`([^`\n]+)`/g)].some((m) => {
+    const span = m[1].trim();
+    return span === word || (span.startsWith(`${word} `) && /^[-./~]/.test(span.slice(word.length + 1).trimStart()));
+  });
+}
+
+/** CLIs that are never a verb of the project's own CLI: a claim starting with one is never prefixed. */
+const WELL_KNOWN_CLIS = new Set(['git', 'gh', 'npm', 'npx', 'node', 'pnpm', 'yarn', 'bun', 'deno', 'ls', 'cat', 'grep', 'which', 'find', 'test', 'make', 'docker', 'curl', 'claude', 'codex', 'python', 'python3', 'pip', 'go', 'cargo', 'op']);
+
+/**
+ * B50: a `<cli> <verb>` claim written without the project's CLI (`run reload` in a brief about
+ * `code-forge`) gets it — deterministically, from the brief and package.json only (never PATH):
+ * the BRIEF (`opts.briefText`, never a source) names a project bin as a whole word
+ * ({@link cliWordRe}), the claim's first word is not itself a project bin nor a well-known CLI
+ * ({@link WELL_KNOWN_CLIS}), and the brief never uses that first word as a CLI of its own
+ * ({@link namedAsCli}). Then the token becomes `<bin> <token>`; anything else stays as written.
+ * @param {string} token @param {string} text @param {ExtractOpts} opts
+ * @returns {string}
+ */
+function withProjectCli(token, text, opts) {
+  const bins = (opts.projectBins ?? []).filter((b) => BARE_CLI.test(b));
+  const first = token.split(' ')[0];
+  const brief = opts.briefText ?? text;
+  if (bins.length === 0 || bins.includes(first) || WELL_KNOWN_CLIS.has(first) || namedAsCli(first, brief)) return token;
+  const named = bins.find((b) => cliWordRe(b).test(brief));
+  return named === undefined ? token : `${named} ${token}`;
+}
+
+/**
+ * The CLI names a project ships: the keys of its package.json `bin` (a string `bin` names the
+ * package, without its scope). No package.json, or no `bin` ⇒ none.
+ * @param {string} projectDir
+ * @returns {string[]}
+ * @throws {FactsError} `usage` when package.json exists but cannot be read or is not JSON (the
+ *   message names the file only, never its content).
+ */
+export function readProjectBins(projectDir) {
+  let text;
+  try {
+    text = readFileSync(path.join(projectDir, 'package.json'), 'utf8');
+  } catch (err) {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') return []; // the project ships no CLI
+    throw new FactsError('usage', `package.json at the project root cannot be read (${/** @type {NodeJS.ErrnoException} */ (err).code ?? 'error'})`);
+  }
+  let pkg;
+  try {
+    pkg = JSON.parse(text);
+  } catch {
+    throw new FactsError('usage', 'package.json at the project root is not valid JSON');
+  }
+  if (typeof pkg?.bin === 'string' && typeof pkg.name === 'string') return [pkg.name.replace(/^@[^/]+\//, '')];
+  if (pkg?.bin !== null && typeof pkg?.bin === 'object' && !Array.isArray(pkg.bin)) return Object.keys(pkg.bin);
+  return [];
+}
+
+
+/**
+ * Every claim token of `text`, deduplicated by (kind, token), in order of first appearance. With
+ * `opts.projectBins`, a command claim written without its CLI gets the project's (B50,
+ * {@link withProjectCli}).
  * @param {string} text
+ * @param {ExtractOpts} [opts]
  * @returns {Claim[]}
  */
-export function extractClaims(text) {
+export function extractClaims(text, opts = {}) {
   let masked = String(text);
   /** @type {Array<{index: number, token: string, kind: ClaimKind}>} */
   const found = [];
@@ -145,7 +227,7 @@ export function extractClaims(text) {
     const cmd = COMMAND_IN_SPAN.exec(m[1]);
     if (!cmd) continue;
     const start = /** @type {number} */ (m.index) + 1;
-    found.push({ index: start, token: `${cmd[1]} ${cmd[2]}`, kind: 'command' });
+    found.push({ index: start, token: withProjectCli(`${cmd[1]} ${cmd[2]}`, String(text), opts), kind: 'command' });
     mask(start, cmd[0].length);
   }
   for (const entry of PATTERNS.slice(3)) scan(...entry);
@@ -322,11 +404,13 @@ function pathViolation(word) {
 }
 
 /** Commands that read and print, allowed with any in-cwd arguments (after the secret-path check). */
-const PLAIN_READERS = new Set(['ls', 'cat', 'head', 'tail', 'wc', 'grep', 'rg', 'stat', 'file', 'uname', 'sw_vers', 'jq', 'which']);
+// B50: `rg` is not one — it searches recursively by default, so any pattern could sweep the tree
+const PLAIN_READERS = new Set(['ls', 'cat', 'head', 'tail', 'wc', 'grep', 'stat', 'file', 'uname', 'sw_vers', 'jq', 'which']);
 
-const GIT_READS = new Set(['log', 'show', 'status', 'rev-parse', 'ls-files', 'cat-file', '--version']);
-const NPM_READS = new Set(['view', 'ls', '--version']);
-const HELP_FORMS = new Set(['--help', '-h', '--version']);
+// B50: no `--help`, `-h` or `--version` form anywhere (a program may read it as an operand: BSD
+// `rm foo --help` deletes); a version claim is checked with `npm view`, `which` or `ls`
+const GIT_READS = new Set(['log', 'show', 'status', 'rev-parse', 'ls-files', 'cat-file']);
+const NPM_READS = new Set(['view', 'ls']);
 /**
  * find: an ALLOWED predicate list (B9b.1). Any other word starting with `-` (`-exec`, `-execdir`,
  * `-ok`, `-okdir`, `-delete`, `-fls`, `-fprint*`, …) is refused by omission; `!` and bare words are
@@ -356,7 +440,7 @@ function findViolation(rest) {
   }
   return null;
 }
-/** Build/task runners: their `help`/default targets run user recipes, so the `<cli> --help` case never admits them. */
+/** Build/task runners: their targets run user recipes; named in the refusal so the delegate sees why. */
 const BUILD_RUNNERS = new Set(['make', 'gmake', 'just', 'task', 'rake', 'gradle', 'gradlew', 'mvn', 'mvnw', 'ant', 'ninja', 'cmake', 'bazel', 'bazelisk', 'tox', 'nox', 'invoke', 'inv', 'doit', 'earthly', 'mage', 'npx', 'pnpx', 'bunx']);
 /** curl: the long options allowed; the short ones are any cluster of `s S I L f`; `--max-time <N>` is handled apart. */
 const CURL_LONG = new Set(['--head', '--silent', '--show-error', '--location', '--fail']);
@@ -404,8 +488,7 @@ function segmentViolation(argv) {
     if (why) return why;
   }
   if (PLAIN_READERS.has(verb)) {
-    if (verb === 'rg' && rest.some((t) => t.startsWith('--pre'))) return 'rg --pre runs a command';
-    if (verb === 'grep' && rest.some((t) => /^-[a-zA-Z]*[rR]/.test(t) || t === '--recursive' || t === '--dereference-recursive')) return 'grep: -r, -R and --recursive are not allowed';
+    if (verb === 'grep') return grepViolation(rest);
     return null;
   }
   switch (verb) {
@@ -414,84 +497,178 @@ function segmentViolation(argv) {
     case 'find':
       return findViolation(rest);
     case 'git':
-      if (rest.length === 0 || !GIT_READS.has(rest[0])) return 'git: only log, show, status, rev-parse, ls-files, cat-file or --version, with no global option';
+      if (rest.length === 0 || !GIT_READS.has(rest[0])) return 'git: only log, show, status, rev-parse, ls-files or cat-file, with no global option';
       return rest.some((t) => /^--(output|ext-diff|textconv)/.test(t)) ? 'git: --output, --ext-diff and --textconv are not allowed' : null;
     case 'npm':
-      return rest.length > 0 && NPM_READS.has(rest[0]) ? null : 'npm: only view, ls or --version';
-    case 'node':
-      return rest.length === 1 && (rest[0] === '--version' || rest[0] === '-v') ? null : 'node: only --version';
+      return rest.length > 0 && NPM_READS.has(rest[0]) ? null : 'npm: only view or ls';
     case 'test':
       return rest.length === 2 && ['-e', '-f', '-d', '-n'].includes(rest[0]) ? null : 'test: only -e, -f, -d or -n with one operand';
     case 'curl':
       return curlViolation(rest);
     default:
-      // `<cli> --help|-h|--version` — exactly two tokens, a bare CLI name (never a path), never a build runner
+      // B50: no `<cli> --help|-h|--version` form — any other program is refused
       if (BUILD_RUNNERS.has(verb)) return `${verb}: build and task runners are not allowed`;
-      return rest.length === 1 && HELP_FORMS.has(rest[0]) && /^[a-z0-9][a-z0-9._-]*$/.test(verb) ? null : `not an allowed read-only form: "${verb}"`;
+      return `not an allowed read-only form: "${verb}"`;
   }
 }
 
-/** A bare CLI name (never a path) for the `<cli> … --help` forms. */
+/** A bare CLI name (never a path). */
 const BARE_CLI = /^[a-z0-9][a-z0-9._-]*$/;
-/** A subcommand word of the `<cli> <subcommand> --help | grep -c -- <flag>` form. */
-const SUBCOMMAND_WORD = /^[a-z][a-z0-9-]*$/;
-/** The flag a help page is searched for (`grep -c -- <flag>`). */
-const HELP_FLAG = /^--?[A-Za-z0-9][A-Za-z0-9-]*$/;
+/** The pattern of the recursive source grep: a long flag with at least 3 characters after `--`. */
+const SOURCE_GREP_FLAG = /^--[a-z][a-z0-9-]{2,}$/;
 
 /**
- * Never a `<cli>` of the subcommand-help form, even when the brief names it: interpreters and shells
- * run a project file (`node scripts --help`), and BSD file tools take `--help` as an operand after
- * one (`rm foo --help`). git keeps its own read list.
+ * B50: the ONLY option words grep may carry before `--` (an exact allow-list — no digits, no long
+ * option, no other cluster: `-2r`, `--recur`, `--dir=recurse`, `-d`, `-R`, `-l`, `-L`, `-e`, `-f` are
+ * all refused). `-rn`/`-nr` is the recursive source grep and needs its exact form ({@link sourceGrep}).
  */
-export const SUBCOMMAND_HELP_DENY = Object.freeze([
-  'node', 'deno', 'bun', 'sh', 'bash', 'zsh', 'fish', 'dash', 'python', 'python3', 'ruby', 'perl', 'php',
-  'rm', 'mv', 'cp', 'kill', 'pkill', 'chmod', 'chown', 'ln', 'dd', 'tee', 'git',
-  // launchers that run their subcommand as a program
-  'npx', 'pnpx', 'bunx', 'uvx', 'pipx', 'npm', 'pnpm', 'yarn', 'env', 'sudo', 'doas', 'xargs', 'exec', 'nice', 'nohup', 'timeout', 'time', 'watch', 'command', 'builtin', 'eval', 'source',
-]);
-const SUBCOMMAND_HELP_DENIED = new Set(SUBCOMMAND_HELP_DENY);
+const GREP_OPTIONS = new Set(['-n', '-c', '-i', '-w', '-F', '-rn', '-nr']);
+const GREP_RECURSIVE = new Set(['-rn', '-nr']);
+const GREP_MESSAGE = 'grep: options only -n -c -i -w -F before --, or the source grep grep -rn -- <flag> <path>';
+const SOURCE_GREP_MESSAGE = 'grep -rn: only grep -rn -- <--long-flag> <path> (one relative subdirectory or file, never . or the root)';
+
+/** @param {string[]} rest - the words after `grep`. @returns {string[]} every dash word before `--` (GNU grep permutes, so an option may follow an operand). */
+function grepOptionWords(rest) {
+  const end = rest.indexOf('--');
+  return (end < 0 ? rest : rest.slice(0, end)).filter((t) => t.startsWith('-'));
+}
+
+/** @param {string[]} rest @returns {boolean} the grep asks for recursion (`-rn`/`-nr` before `--`). */
+function grepRecurses(rest) {
+  return grepOptionWords(rest).some((t) => GREP_RECURSIVE.has(t));
+}
 
 /**
- * The CLIs the subcommand-help form may name: the first word of every `command` claim of the brief.
- * @param {ReadonlyArray<Claim>} claims
- * @returns {Set<string>}
+ * Why a grep segment is not allowed, or null: every option word before `--` is in
+ * {@link GREP_OPTIONS}; a recursive one is exactly the source grep ({@link sourceGrep}).
+ * @param {string[]} rest - the words after `grep`.
+ * @returns {string | null}
+ */
+function grepViolation(rest) {
+  if (!grepOptionWords(rest).every((t) => GREP_OPTIONS.has(t))) return GREP_MESSAGE;
+  if (grepRecurses(rest)) return sourceGrep(rest) === null ? SOURCE_GREP_MESSAGE : null;
+  return null;
+}
+
+/**
+ * Is `where` a relative subdirectory or file of the cwd — never the cwd itself (`.`, `./`, `src/..`),
+ * the root, `~`, an absolute path, a `..` segment or a secret-looking path? The facts snapshot
+ * already drops every secret-looking file at any depth (`sealTree` and `copyNoFollow` test the full
+ * relative path against {@link SECRET_PATH}, so `config/.env` goes too); a named subdirectory is a
+ * second fence, so a grep never sweeps the whole tree.
+ * @param {string} where
+ * @returns {boolean}
+ */
+function isSubPath(where) {
+  if (where.length === 0 || where.startsWith('/') || where.startsWith('~') || where.startsWith('-')) return false;
+  if (pathViolation(where) !== null || SECRET_PATH.some((re) => re.test(where))) return false;
+  const norm = path.posix.normalize(where);
+  return norm !== '.' && norm !== './' && !norm.startsWith('..') && !norm.split('/').some((seg) => SECRET_PATH.some((re) => re.test(seg)));
+}
+
+/**
+ * B50: the one recursive `grep` form — a flag claim checked in the project's SOURCE TEXT, inside the
+ * read-only snapshot, alone (never in a pipe), EXACTLY `grep -rn -- <flag> <path>` (or `-nr`): five
+ * words, the pattern a long flag of 3+ characters ({@link SOURCE_GREP_FLAG}, so `-a`, `-e` or `-1`
+ * cannot match every line), one relative subdirectory or file ({@link isSubPath}). Claude runs grep
+ * as a read-only command, so the delegate needs no permission rule for it.
+ * @param {string[]} rest - the words after `grep`.
+ * @returns {{pattern: string, path: string} | null} null when `rest` is not exactly that form.
+ */
+function sourceGrep(rest) {
+  if (rest.length !== 4 || !GREP_RECURSIVE.has(rest[0]) || rest[1] !== '--') return null;
+  const [, , pattern, where] = rest;
+  return SOURCE_GREP_FLAG.test(pattern) && isSubPath(where) ? { pattern, path: where } : null;
+}
+
+/**
+ * The pattern and path of a command that is exactly one source-grep segment ({@link sourceGrep}), or null.
+ * @param {string} command
+ * @returns {{pattern: string, path: string} | null}
  */
-export function claimClis(claims) {
-  return new Set(claims.filter((c) => c.kind === 'command').map((c) => c.token.split(' ')[0]));
+function sourceGrepOf(command) {
+  const { segments, separators, refused } = splitCommand(command);
+  if (refused || segments.length !== 1 || separators.length !== 0 || segments[0][0] !== 'grep') return null;
+  return sourceGrep(segments[0].slice(1));
 }
 
+/** Folders whose text is about the code, not the code: a hit there could be the claim quoting itself. */
+const NON_SOURCE_DIRS = new Set(['docs', 'plans', 'test', 'tests', 'fixtures', 'node_modules']);
+/** Top-level folders a NOT-FOUND never searches as "the source": text, tests, vendored or built output. */
+const NON_SOURCE_FOLDERS = new Set([...NON_SOURCE_DIRS, 'dist', 'build', 'coverage', 'out']);
+/** Text files never prove a flag (the brief and every note are one). */
+const NON_SOURCE_FILE = /\.(md|markdown|txt)$/i;
+
+/** @param {string} p @returns {string} `p` as a normalised POSIX path without a leading `./` or a trailing `/`. */
+const relPosix = (p) => path.posix.normalize(p).replace(/^(\.\/)+/, '').replace(/\/+$/, '');
+
 /**
- * Is `segments` (split at `separators`) exactly `<cli> <subcommand> --help | grep -c -- <flag>`?
- * One pipe and nothing else; `<cli>` a bare name that a `command` claim of the brief starts with
- * (`clis`), never a build runner nor one of {@link SUBCOMMAND_HELP_DENY}; a plain lowercase
- * subcommand word; a flag-shaped pattern. The two-token `<cli> --help` form stays a segment of its
- * own ({@link segmentViolation}).
- * @param {string[][]} segments @param {string[]} separators @param {ReadonlySet<string>} clis
+ * Is `file` (relative to the delegate's cwd) a SOURCE file — not a `.md`, `.markdown` or `.txt`
+ * file, under no `docs/ plans/ test/ tests/ fixtures/ node_modules/` folder (at any depth), and
+ * not the brief itself?
+ * @param {string} file @param {string | undefined} briefRel
  * @returns {boolean}
  */
-function isSubcommandHelpGrep(segments, separators, clis) {
-  if (segments.length !== 2 || separators.length !== 1 || separators[0] !== '|') return false;
-  const [help, grep] = segments;
-  const cli = help[0];
-  if (help.length !== 3 || help[2] !== '--help' || !BARE_CLI.test(cli) || !clis.has(cli) || BUILD_RUNNERS.has(cli) || SUBCOMMAND_HELP_DENIED.has(cli) || !SUBCOMMAND_WORD.test(help[1])) return false;
-  return grep.length === 4 && grep[0] === 'grep' && grep[1] === '-c' && grep[2] === '--' && HELP_FLAG.test(grep[3]);
+function isSourceFile(file, briefRel) {
+  const rel = relPosix(file);
+  if ((briefRel !== undefined && rel === relPosix(briefRel)) || NON_SOURCE_FILE.test(rel)) return false;
+  return !rel.split('/').slice(0, -1).some((seg) => NON_SOURCE_DIRS.has(seg));
 }
 
+/**
+ * Does the excerpt hold at least one `file:line:text` hit whose file sits under the grep's `under`
+ * path, is a source file ({@link isSourceFile}) and whose text holds `flag` as a whole token
+ * ({@link holdsFlag})? A hit line without the `file:line:` prefix never counts.
+ * @param {string} excerpt @param {string} flag @param {string} under - the grep's path.
+ * @param {string | undefined} briefRel
+ * @returns {boolean}
+ */
+function sourceHit(excerpt, flag, under, briefRel) {
+  const scope = relPosix(under);
+  return excerpt.split(/\r?\n/).some((line) => {
+    const hit = /^([^:\n]+):(\d+):(.*)$/.exec(line.trim());
+    if (hit === null) return false;
+    const file = relPosix(hit[1]);
+    return (file === scope || file.startsWith(`${scope}/`)) && isSourceFile(file, briefRel) && holdsFlag(hit[3], flag);
+  });
+}
+
+/**
+ * Is `where` a source FOLDER of the delegate's cwd (the snapshot): an existing directory, no segment
+ * hidden (`.x`) or one of {@link NON_SOURCE_FOLDERS}, and — with `topLevel` — one single name (a
+ * NOT-FOUND proves absence only over a whole top-level folder). A file (`package.json`,
+ * `src/a.mjs`) never counts; with no known cwd nothing can be checked, so nothing counts.
+ * @param {string} where @param {string | undefined} cwd @param {boolean} topLevel
+ * @returns {boolean}
+ */
+function isSourceFolder(where, cwd, topLevel) {
+  const rel = relPosix(where);
+  const segs = rel.split('/');
+  if (cwd === undefined || rel.length === 0 || rel === '.' || (topLevel && segs.length !== 1)) return false;
+  if (segs.some((seg) => seg.startsWith('.') || NON_SOURCE_FOLDERS.has(seg))) return false;
+  try {
+    return statSync(path.join(cwd, rel)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+const ONE_COMMAND_MESSAGE = 'one command per row: no pipe or list (| ; && || & or a newline)';
+
 /**
  * Why a delegate's `command` is not an allowed read-only command, or null when it is. An
- * ALLOW-LIST (fail closed): every segment between `;`, `&&`, `||`, `|`, `&`, newline or CR must
- * be one of the forms in {@link segmentViolation}, or the whole command is exactly
- * `<cli> <subcommand> --help | grep -c -- <flag>` for a `<cli>` in `opts.clis`
- * ({@link isSubcommandHelpGrep}); `$`, backticks and redirections are refused.
+ * ALLOW-LIST (fail closed): exactly ONE command (B50: any `;`, `&&`, `||`, `|`, `&`, newline or CR
+ * is refused, as the packet says), and it is one of the forms in {@link segmentViolation}; `$`,
+ * backticks and redirections are refused.
  * @param {string} command
- * @param {{clis?: ReadonlySet<string>}} [opts] - `clis`: {@link claimClis} of the brief (none ⇒ the subcommand form is never admitted).
  * @returns {string | null}
  */
-export function readOnlyViolation(command, opts = {}) {
+export function readOnlyViolation(command) {
   const { segments, separators, refused } = splitCommand(command);
   if (refused) return refused;
   if (segments.length === 0) return 'empty command';
-  if (isSubcommandHelpGrep(segments, separators, opts.clis ?? new Set()) && !segments.flat().some((t) => SECRET_PATH.some((re) => re.test(t)))) return null;
+  // B50: one command per row, as the packet says — no pipe and no list
+  if (separators.length > 0) return ONE_COMMAND_MESSAGE;
   for (const argv of segments) {
     const why = segmentViolation(argv);
     if (why) return why;
@@ -552,22 +729,48 @@ export function isSilentCommand(command) {
 
 /** @typedef {{fact_id: string, reason: string}} Downgrade */
 
+const SOURCE_GREP_CLAIM_MESSAGE = 'a source grep counts only for a flag claim, with that flag as its pattern; not counted';
+const SOURCE_GREP_HIT_MESSAGE = 'VERIFIED source grep without a file:line: hit in a source file naming the claimed flag (docs, plans, tests, fixtures, text files and the brief do not count); not counted';
+const SOURCE_GREP_SCOPE_MESSAGE = 'NOT-FOUND source grep must search one whole top-level source folder (not docs, plans, test, tests, fixtures or node_modules); not counted';
+const FLAG_PROOF_MESSAGE = 'a flag claim is proved only by grep -rn -- <flag> <source folder>; not counted';
+
+/**
+ * Does a grep hit line hold `flag` as a whole token — not preceded by a word character or `-`, not
+ * followed by `[A-Za-z0-9_-]` (`--force-push` does not hold `--force`)? A `-l` file-name line never does.
+ * @param {string} excerpt @param {string} flag
+ * @returns {boolean}
+ */
+function holdsFlag(excerpt, flag) {
+  return new RegExp(`(?<![\\w-])${flag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![A-Za-z0-9_-])`).test(excerpt);
+}
+
 /**
  * Which check rule a counted row (VERIFIED or NOT-FOUND) breaks, or null. A row the delegate
  * already tagged UNVERIFIABLE is never counted, so it keeps its own `why`.
- * @param {Fact} row @param {Claim} claim @param {ReadonlySet<string>} clis - {@link claimClis}.
+ * @param {Fact} row @param {Claim} claim
+ * @param {{briefRel?: string, cwd?: string}} ctx - the brief relative to the delegate's cwd, and that cwd (the snapshot).
  * @returns {string | null}
  */
-function ruleBroken(row, claim, clis) {
+function ruleBroken(row, claim, ctx) {
   if (row.tag === 'UNVERIFIABLE') return null;
   if (row.command.trim().length === 0) return `${row.tag} without a check command; not counted`;
   if (claim.kind === 'env') {
     const env = ENV_CHECK.exec(row.command);
     if (!env || env[1] !== claim.token) return `an env claim may only be checked with printenv ${claim.token} >/dev/null; not counted`;
   } else {
-    const why = readOnlyViolation(row.command, { clis });
+    const why = readOnlyViolation(row.command);
     if (why) return `check command not allowed: ${why}; not counted`;
     if (row.tag === 'VERIFIED' && isSilentCommand(row.command)) return 'silent command; excerpt cannot be its output; not counted';
+    // B50: a flag claim is proved (VERIFIED or NOT-FOUND) ONLY by `grep -rn -- <flag> <dir>`, its
+    // pattern the claimed flag, over an existing source directory of the snapshot; a source grep
+    // proves nothing else. A VERIFIED one needs a `file:line:` hit in a source file under that
+    // directory holding the flag as a whole token (never the brief, a doc or a test: the claim would
+    // prove itself); a NOT-FOUND one needs one whole top-level source folder
+    const grep = sourceGrepOf(row.command);
+    if (grep !== null && (claim.kind !== 'flag' || grep.pattern !== claim.token)) return SOURCE_GREP_CLAIM_MESSAGE;
+    if (claim.kind === 'flag' && (grep === null || !isSourceFolder(grep.path, ctx.cwd, false))) return FLAG_PROOF_MESSAGE;
+    if (grep !== null && row.tag === 'VERIFIED' && !sourceHit(row.output_excerpt, grep.pattern, grep.path, ctx.briefRel)) return SOURCE_GREP_HIT_MESSAGE;
+    if (grep !== null && row.tag === 'NOT-FOUND' && !isSourceFolder(grep.path, ctx.cwd, true)) return SOURCE_GREP_SCOPE_MESSAGE;
   }
   if (row.tag === 'VERIFIED' && row.output_excerpt.trim().length === 0) return 'VERIFIED with an empty output excerpt; not counted';
   return null;
@@ -584,10 +787,13 @@ function ruleBroken(row, claim, clis) {
  * empty excerpt or from a silent `test`) becomes UNVERIFIABLE with `why` = the rule and is listed
  * in `downgraded`. Every row shows the CANONICAL claim token and kind.
  * @param {unknown} answer @param {ReadonlyArray<Claim>} claims
+ * @param {{briefRel?: string, cwd?: string}} [opts] - `briefRel`: the brief's path relative to the
+ *   delegate's cwd (a source-grep hit in it never counts); `cwd`: that cwd (the project snapshot),
+ *   where a NOT-FOUND source grep's folder must exist as a directory (none ⇒ no NOT-FOUND grep counts).
  * @returns {{facts: Fact[], downgraded: Downgrade[]}} the rows in claim order, and the downgrades.
  * @throws {FactsError} `refused` when the answer does not match the schema.
  */
-export function validateFacts(answer, claims) {
+export function validateFacts(answer, claims, opts = {}) {
   if (!validateFile(answer)) {
     const where = (validateFile.errors ?? []).map((e) => `${e.instancePath || '/'} ${e.message}`).slice(0, 5);
     throw new FactsError('refused', `facts answer does not match facts.schema.json: ${where.join('; ')}`);
@@ -597,7 +803,6 @@ export function validateFacts(answer, claims) {
   const facts = [];
   /** @type {Downgrade[]} */
   const downgraded = [];
-  const clis = claimClis(claims);
   // each row answers at most ONE claim: pass 1 anchors rows by fact_id (with the kind, else with the
   // echoed claim); pass 2 gives the rows left over to claims still open, by kind + echoed claim
   /** @type {Set<Fact>} */
@@ -623,7 +828,7 @@ export function validateFacts(answer, claims) {
       return;
     }
     const base = { fact_id: id, claim: redact(claim.token), kind: claim.kind, command: redact(row.command), output_excerpt: claim.kind === 'env' ? '' : redact(row.output_excerpt) };
-    const broken = ruleBroken(row, claim, clis);
+    const broken = ruleBroken(row, claim, opts);
     if (broken) {
       const reason = redact(broken);
       downgraded.push({ fact_id: id, reason });
@@ -718,20 +923,22 @@ export function checkSheetFresh(sheetText, briefPath) {
 const RULE = [
   '# Facts delegate',
   '',
-  'For each claim below, run the cheapest READ-ONLY check (`<cli> --help | grep -c -- <flag>`,',
-  '`<cli> <subcommand> --help | grep -c -- <flag>`, `which <cli>`, `ls <path>`, `<cli> --version`,',
-  '`npm view <name> version`). Quote the exact command and the output line it printed (at most 200',
+  'For each claim below, run the cheapest READ-ONLY check (`grep -rn -- <flag> <path>`, `which <cli>`,',
+  '`ls <path>`, `npm view <name> version`). Quote the exact command and the output line it printed (at most 200',
   'characters). Tag each claim VERIFIED (the output shows it), NOT-FOUND (the check ran and it is absent) or',
   'UNVERIFIABLE (no read-only check can decide it — say why in `why`). Never infer, never guess: the excerpt is the',
   "command's literal output, never your reading of it. For a path use `ls <path>` (it prints the path); `test` prints",
-  'nothing, so a `test` check can never be VERIFIED. Only these forms are accepted, joined by `|` if needed: which,',
-  'command -v, ls, cat, head, tail, wc, grep (no -r), rg,',
+  'nothing, so a `test` check can never be VERIFIED. A flag is checked in the source text of the project, never by',
+  'running a program: `grep -rn -- <flag> <path>` (`<path>` a top-level source folder such as `src`, never `.`,',
+  'the root, docs, plans or tests) — VERIFIED only with a hit line (`file:line:text`) from a source file (not',
+  'Markdown or text, not docs, plans, tests or fixtures) that contains the flag, as the excerpt. Never run a program with `--help`, `-h` or `--version`: a version is checked with `npm view <name>',
+  'version`, `which` or `ls`. Run one command at a time, never a pipe. Only these forms are accepted: which,',
+  'command -v, ls, cat, head, tail, wc, grep (options only -n -c -i -w -F; recursive only as',
+  '`grep -rn -- <flag> <path>`),',
   'find (only -name -iname -path -ipath -type -maxdepth -mindepth -print -print0 -newer -size -empty -mtime -mmin',
-  '-not ! -a -o -and -or, plus paths), stat, file, uname, sw_vers, jq, `<cli> --help|-h|--version` (a bare CLI name, no path, no build runner), git',
-  'log|show|status|rev-parse|ls-files|cat-file, npm view|ls, node --version, test -e|-f|-d|-n, `curl -sI <one URL>`;',
-  'and, as a whole command only, `<cli> <subcommand> --help | grep -c -- <flag>` (`<cli>` the first word of a',
-  'command claim below, never an interpreter, shell or file tool; a lowercase subcommand word; no other pipe or',
-  'argument). A check that breaks these rules is not counted.',
+  '-not ! -a -o -and -or, plus paths), stat, file, uname, sw_vers, jq, git',
+  'log|show|status|rev-parse|ls-files|cat-file, npm view|ls, test -e|-f|-d|-n, `curl -sI <one URL>`.',
+  'A check that breaks these rules is not counted.',
   'No `$`, no backticks, no redirection, no unquoted glob, no `~`, no absolute path outside /usr, /opt/homebrew or',
   '/bin, no secret files.',
   'An env claim is checked ONLY with `printenv NAME >/dev/null` (quote its exit status; the value is never shown).',
@@ -966,7 +1173,15 @@ export async function buildSnapshot(projectDir, sources, snapDir, workDir, run =
  */
 export async function buildFacts(opts, deps = {}) {
   const brief = readBriefOnce(opts.briefPath);
-  const claims = extractClaims([brief.bytes.toString('utf8'), ...readSourcesText(opts.sources ?? [])].join('\n'));
+  // B50: a command claim written without its CLI gets the project's own (package.json `bin`)
+  const briefText = brief.bytes.toString('utf8');
+  // prefix; a broken package.json only drops that optional prefix, never the whole sheet.
+  let projectBins = [];
+  if (opts.projectDir !== undefined) {
+    try { projectBins = readProjectBins(opts.projectDir); } catch { projectBins = []; }
+  }
+  const extractOpts = opts.projectDir === undefined ? {} : { projectBins, briefText };
+  const claims = extractClaims([briefText, ...readSourcesText(opts.sources ?? [])].join('\n'), extractOpts);
   const root = opts.runRoot ?? currentRunRoot();
   // B9b.1: a run root inside a git work tree (`tmp.root` configured in the project) cannot hold
   // the snapshot — git and the harness would walk up into the live repo — so the facts area moves
@@ -996,7 +1211,10 @@ export async function buildFacts(opts, deps = {}) {
       deps,
     );
     if (result.status !== 'ok') return { status: result.status, reason: result.reason ?? null, claims };
-    const { facts, downgraded } = validateFacts(result.answer, claims);
+    // the delegate's cwd is the project (snapshot): the brief, seen from there
+    const briefRel = opts.projectDir === undefined ? undefined : path.relative(realOrResolved(opts.projectDir), realOrResolved(opts.briefPath)).split(path.sep).join('/');
+    // validated while the snapshot still exists (it is removed in `finally`)
+    const { facts, downgraded } = validateFacts(result.answer, claims, { briefRel, ...(cwd === undefined ? {} : { cwd }) });
     const now = (opts.now ?? (() => new Date()))();
     const rel = path.relative(path.dirname(opts.outPath), opts.briefPath).split(path.sep).join('/');
     const text = renderSheet({

package/src/session/plan-check.mjs

@@ -5,9 +5,11 @@
  * `acceptance` columns; the wave is the nearest heading that says `Wave <n>`) and checks:
  *  - a facts sheet is present (pasted in the plan's §0 or given as `--facts`) and was built from
  *    the brief as it is now; a separate sheet's `brief_sha256` line must also appear in the plan;
- *  - every acceptance clause (the cell split on `;`) whose claim tokens the sheet does not mark
- *    VERIFIED is listed in the "… the facts sheet cannot back" section by a line that names the
- *    token, the block, and a tolerance — else `unbackable clause without tolerance: <block> <clause>`;
+ *  - every acceptance clause (the cell split on `;` and on ` · (n) ` clause markers, B50) whose
+ *    claim tokens the sheet does not mark VERIFIED is listed in the "… the facts sheet cannot
+ *    back" section by a line that names the token, the block, and a tolerance (a list item saying
+ *    `tolerance`, or a row of an older-template table with a non-empty tolerance column) — else
+ *    `unbackable clause without tolerance: <block> <clause>`;
  *  - a caller map section exists and names every block (C9);
  *  - the required sections are found by their exact headings (`plan-sections.mjs`); a near miss at
  *    the expected position is accepted with a WARN naming the exact heading (B36);
@@ -190,6 +192,65 @@ const listItems = (body) =>
     .filter((l) => /^\s*(?:[-*]|\d+\.)\s+/.test(l))
     .map((l) => l.trim());
 
+/**
+ * The tolerance lines of the unbackable-clauses section (B50): every list item that says
+ * `tolerance` (the form `templates/plan.md` shows), plus — so plans written from the older table
+ * template keep passing — every data row of a table in the section whose HEADER (its first row,
+ * never a later one) has a `tolerance` cell, when that row's tolerance cell is filled: empty and
+ * the placeholders in {@link EMPTY_CELLS} do not count.
+ * @param {string} body @returns {string[]}
+ */
+export function toleranceLines(body) {
+  const out = listItems(body).filter((l) => /\btolerance\b/i.test(l));
+  /** @type {number | null} null: not in a table; -1: in a table without a tolerance column. */
+  let col = null;
+  for (const raw of body.split('\n')) {
+    const line = raw.trim();
+    if (!line.startsWith('|')) {
+      col = null;
+      continue;
+    }
+    const row = cells(line);
+    if (col === null) {
+      col = row.findIndex((c) => /\btolerance\b/i.test(plain(c)));
+      continue;
+    }
+    if (col < 0 || row.every((c) => /^:?-+:?$/.test(c))) continue; // no tolerance column, or the separator row
+    if (!EMPTY_CELLS.has(plain(row[col] ?? '').toLowerCase())) out.push(line);
+  }
+  return out;
+}
+
+/** Tolerance cells that say nothing (compared lower-cased, after trimming). */
+const EMPTY_CELLS = new Set(['', '—', '–', '-', '--', '…', '...', 'n/a']);
+
+/**
+ * Is a clause's claim backed by a VERIFIED fact? Its token is, or (B50) a command claim written
+ * without its CLI (`run reload`) matches the sheet's token that `forge facts` prefixed with the
+ * project's CLI (`code-forge run reload`: exactly one more leading word, and that word one of the
+ * project's own CLIs — `projectBins`).
+ * @param {{token: string, kind: string}} claim @param {ReadonlySet<string>} verified
+ * @param {() => ReadonlyArray<string>} projectBins - called only when a command claim needs it.
+ * @returns {boolean}
+ */
+function isVerified(claim, verified, projectBins) {
+  if (verified.has(claim.token)) return true;
+  if (claim.kind !== 'command') return false;
+  return projectBins().some((bin) => verified.has(`${bin} ${claim.token}`));
+}
+
+/**
+ * The clauses of an acceptance cell (B50): split on `;` and on a ` · (n) ` clause marker (the
+ * template numbers clauses `(1) … · (2) …`); a `·` not followed by `(n)` stays inside its clause.
+ * @param {string} acceptance @returns {string[]}
+ */
+export function splitClauses(acceptance) {
+  return acceptance
+    .split(/;|\s·\s+(?=\(\d+\))/)
+    .map((c) => plain(c))
+    .filter((c) => c.length > 0);
+}
+
 /** Where a lane may come from: Jev's `lane` answer, or the deterministic fallback rule (`--rules`). */
 export const LANE_SOURCES = Object.freeze(['jev', 'rules']);
 
@@ -233,6 +294,10 @@ export function recordedLanes(rows, planName) {
  * @property {string} [planPath] - where the plan lives (resolves the sheet's brief reference).
  * @property {string} [factsText] @property {string} [factsPath] - a separate sheet (else the plan's own §0).
  * @property {Record<string, any>} [cfg] - `caps.coders`, `budget.block_cases`, `budget.block_lines`.
+ * @property {ReadonlyArray<string> | (() => ReadonlyArray<string>)} [projectBins] - B50: the
+ *   project's own CLI names (`readProjectBins` of the project root), or a function giving them —
+ *   called at most once, and only when a command claim is not VERIFIED as written; a clause's
+ *   `run reload` is then backed by a VERIFIED `<bin> run reload`.
  * @property {Array<Record<string, any>>} [decisions] - the project's ledger rows (the recorded lanes);
  *   none given ⇒ no block has a recorded lane.
  */
@@ -282,10 +347,14 @@ export function checkPlan(text, opts = {}) {
   // unbackable clauses
   const unbackable = required(REQUIRED_SECTIONS.unbackable);
   if (!unbackable) errors.push('unbackable-clauses section missing (write "none" when there is none)');
-  const tolerances = unbackable ? listItems(unbackable.body).filter((l) => /\btolerance\b/i.test(l)) : [];
+  const tolerances = unbackable ? toleranceLines(unbackable.body) : [];
+  /** @type {ReadonlyArray<string> | undefined} */
+  let binsCache;
+  const given = opts.projectBins;
+  const projectBins = () => (binsCache ??= typeof given === 'function' ? given() : given ?? []);
   for (const b of blocks) {
-    for (const clause of b.acceptance.split(';').map((c) => plain(c)).filter((c) => c.length > 0)) {
-      const unbacked = extractClaims(clause).filter((c) => !verified.has(c.token));
+    for (const clause of splitClauses(b.acceptance)) {
+      const unbacked = extractClaims(clause).filter((c) => !isVerified(c, verified, projectBins));
       if (unbacked.every((c) => tolerances.some((t) => t.includes(c.token) && idRe(b.id).test(t)))) continue;
       errors.push(`unbackable clause without tolerance: ${b.id} ${clause}`);
     }