@mmerterden/multi-agent-pipeline 20.33.0 → 20.35.0

package/pipeline/scripts/_guard_rules.py

@@ -32,6 +32,8 @@ import re
 import shlex
 import time
 
+RUN_STATE = "agent-state.json"
+
 MAX_FILE_BYTES = 256 * 1024
 CONFIRM_TTL_SECONDS = 600
 
@@ -47,6 +49,16 @@ AI_GENERATED = re.compile(
 )
 JIRA_TRANSITION = re.compile(r"/rest/api/(?:\d+|latest)/issue/[^/\s'\"]+/transitions\b", re.IGNORECASE)
 POST_METHOD = re.compile(r"(?:^|\s)(?:-X|--request)\s*=?\s*['\"]?post\b", re.IGNORECASE)
+WRITE_METHOD = re.compile(r"(?:^|\s)(?:-X|--request)\s*=?\s*['\"]?(?:post|put|patch)\b", re.IGNORECASE)
+PUT_METHOD = re.compile(r"(?:^|\s)(?:-X|--request)\s*=?\s*['\"]?put\b", re.IGNORECASE)
+SHARED_WRITE = re.compile(
+    r"/rest/api/(?:\d+|latest)/issue/[^/\s'\"]+/comment\b|/rest/api/content\b|hooks\.slack\.com/services/",
+    re.IGNORECASE,
+)
+PR_UPDATE = re.compile(
+    r"/rest/api/(?:[\d.]+|latest)/projects/[^/\s'\"]+/repos/[^/\s'\"]+/pull-requests/\d+(?=[\s'\"?]|$)"
+)
+DATA_FLAGS = {"-d", "--data", "--data-binary", "--data-raw", "--data-ascii"}
 BODY_FLAG = re.compile(r"(?:^|\s)(?:-d|--data[\w-]*|--json|-F|--form)(?:\s|=|$)")
 HEREDOC_OPEN = re.compile(r"<<(-?)\s*(['\"]?)([A-Za-z_][A-Za-z0-9_]*)\2")
 ASSIGN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=")
@@ -446,6 +458,7 @@ def _gh_ask(argv, cwd):
     if group == "pr" and sub in ("create", "edit"):
         bodies = _flag_values(cleaned, {"--body"}, "-b")
         bodies += [read_bounded(p, cwd) for p in _flag_values(cleaned, {"--body-file"}, "-F")]
+        bodies += _flag_values(cleaned, {"--title"}, "-t")
         if any(CLOSING.search(b or "") for b in bodies):
             return (
                 f"gh pr {sub} with a closing keyword (Closes/Fixes/Resolves #N) closes the issue on merge; "
@@ -468,10 +481,445 @@ def _jira_ask(argv, seg):
     return None
 
 
+def _shared_ask(argv, seg):
+    """A comment, page or message posted to a system other people read."""
+    if not argv or os.path.basename(argv[0]) not in HTTP_CLIENTS:
+        return None
+    if not SHARED_WRITE.search(seg):
+        return None
+    if WRITE_METHOD.search(seg) or BODY_FLAG.search(seg):
+        return "this posts to a shared system (Jira comment, Confluence page or Slack); the user confirms each post"
+    return None
+
+
+def _payload(argv, cwd):
+    """The request body a curl-like command sends, read from @file when given."""
+    for i, a in enumerate(argv):
+        val = None
+        if a in DATA_FLAGS and i + 1 < len(argv):
+            val = argv[i + 1]
+        else:
+            for f in DATA_FLAGS:
+                if a.startswith(f + "="):
+                    val = a.split("=", 1)[1]
+        if val is not None:
+            return read_bounded(val[1:], cwd) if val.startswith("@") else val
+    return None
+
+
+def pr_update_reason(toks, seg, cwd=None):
+    """A Bitbucket pull request PUT replaces the whole record: a body without
+    reviewers, fromRef or toRef wipes them."""
+    _, argv = command_word(toks)
+    if not argv or os.path.basename(argv[0]) not in HTTP_CLIENTS:
+        return None
+    if not PR_UPDATE.search(seg) or not PUT_METHOD.search(seg):
+        return None
+    body = _payload(argv, cwd)
+    try:
+        doc = json.loads(body) if body else None
+    except ValueError:
+        doc = None
+    if not isinstance(doc, dict):
+        return "this pull request update sends no readable JSON body; send the full record with reviewers, fromRef and toRef"
+    missing = [k for k in ("fromRef", "toRef") if not doc.get(k)]
+    if not doc.get("reviewers"):
+        missing.insert(0, "reviewers")
+    if missing:
+        return (
+            "a pull request PUT replaces the record, and this body has no "
+            + ", ".join(missing)
+            + "; read the current pull request and send its reviewers, fromRef, toRef and draft back"
+        )
+    return None
+
+
+AGENT_NAME = re.compile(r"^[A-Za-z0-9._:-]{1,80}$")
+GH_WRITE_SUBS = {
+    ("pr", "create"), ("pr", "edit"), ("pr", "comment"), ("pr", "review"), ("pr", "merge"),
+    ("pr", "close"), ("pr", "ready"), ("issue", "create"), ("issue", "edit"),
+    ("issue", "comment"), ("issue", "close"), ("issue", "reopen"), ("release", "create"),
+}
+
+
+def read_only_agent(agent_type, env=None):
+    """True when the subagent's definition denies it the Write tool: it reviews,
+    reads or reports, and anything it does outside its answer is a side effect."""
+    if not isinstance(agent_type, str) or not AGENT_NAME.match(agent_type):
+        return False
+    env = os.environ if env is None else env
+    home = env.get("HOME") or os.path.expanduser("~")
+    name = agent_type.split(":")[-1]
+    for root in (os.path.join(home, ".claude", "agents"), os.path.join(os.getcwd(), ".claude", "agents")):
+        text = read_bounded(os.path.join(root, name + ".md"), None)
+        if not text.startswith("---"):
+            continue
+        head = text.split("---", 2)[1] if text.count("---") >= 2 else ""
+        m = re.search(r"^disallowedTools:\s*(.+)$", head, re.MULTILINE)
+        return bool(m and re.search(r"\bWrite\b", m.group(1)))
+    return False
+
+
+def subagent_side_effect(cmd):
+    """What in this command reaches past a read-only subagent's answer, or None."""
+    stripped, _ = strip_heredoc_bodies(cmd)
+    if re.search(r"write-state\.mjs", stripped):
+        return "it writes run state (write-state.mjs)"
+    for seg in split_simple(stripped):
+        toks = tokens(seg)
+        split = _git_split(toks)
+        if split and split[2] in WRITE_SUBS:
+            return f"it runs git {split[2]}"
+        _, argv = command_word(toks)
+        if not argv:
+            continue
+        base = os.path.basename(argv[0])
+        if base in HTTP_CLIENTS and (WRITE_METHOD.search(seg) or BODY_FLAG.search(seg)):
+            return f"it sends a write request with {base}"
+        if base == "gh":
+            plains = [a for a in argv[1:] if not a.startswith("-")]
+            if len(plains) >= 2 and (GH_ALIASES.get(plains[0], plains[0]), plains[1]) in GH_WRITE_SUBS:
+                return f"it runs gh {plains[0]} {plains[1]}"
+            if plains[:1] == ["api"] and (
+                re.search(r"(?:^|\s)(?:-X|--method)\s*=?\s*(?:post|put|patch|delete)\b", seg, re.I)
+                or re.search(r"(?:^|\s)(?:-f|-F|--field|--raw-field|--input)(?:\s|=)", seg)
+            ):
+                return "it writes through gh api"
+    return None
+
+
+CLEANUP_SCRIPTS = {"purge.sh": None, "prune-logs.sh": "--yes", "run-kill.mjs": "apply"}
+
+
+def _cleanup_ask(argv):
+    """purge, prune-logs --yes and run-kill apply delete run history for good."""
+    if not argv:
+        return None
+    rest = argv
+    if os.path.basename(argv[0]) in ("bash", "sh", "zsh", "node"):
+        rest = argv[1:]
+    if not rest:
+        return None
+    name = os.path.basename(rest[0])
+    if name not in CLEANUP_SCRIPTS:
+        return None
+    needs = CLEANUP_SCRIPTS[name]
+    if needs and needs not in rest[1:]:
+        return None
+    return f"{name} deletes run logs or worktrees for good; the user confirms each clean-up"
+
+
 def ask_reason(toks, seg, cwd=None):
     """Why a person should confirm this segment, or None."""
     _, argv = command_word(toks)
-    return _gh_ask(argv, cwd) or _jira_ask(argv, seg)
+    return _gh_ask(argv, cwd) or _jira_ask(argv, seg) or _shared_ask(argv, seg) or _cleanup_ask(argv)
+
+
+GH_TEXT_SUBS = {
+    ("pr", "create"), ("pr", "edit"), ("pr", "comment"), ("pr", "review"),
+    ("issue", "create"), ("issue", "edit"), ("issue", "comment"),
+}
+
+
+def gh_text(toks, cwd=None):
+    """The title and body text a gh pull request or issue write publishes."""
+    _, argv = command_word(toks)
+    if not argv or os.path.basename(argv[0]) != "gh":
+        return ""
+    args = [a for a in argv[1:]]
+    plains = [a for a in args if not a.startswith("-")]
+    if len(plains) < 2:
+        return ""
+    if (GH_ALIASES.get(plains[0], plains[0]), plains[1]) not in GH_TEXT_SUBS:
+        return ""
+    parts = _flag_values(args, {"--body", "--title"}, "-b") + _flag_values(args, {"--title"}, "-t")
+    parts += [read_bounded(p, cwd) for p in _flag_values(args, {"--body-file"}, "-F")]
+    return "\n".join(p for p in parts if p)
+
+
+def vercel_token_reason(toks):
+    """A --token on the vercel command line lands in the transcript."""
+    _, argv = command_word(toks)
+    if not argv:
+        return None
+    words = [os.path.basename(argv[0])] + argv[1:3]
+    if "vercel" not in words:
+        return None
+    if any(a in ("--token", "-t") or a.startswith("--token=") for a in argv[1:]):
+        return (
+            "vercel with --token puts the token on the command line; run it through the "
+            "vercel wrapper, which reads the token from the credential store"
+        )
+    return None
+
+
+SECRET_READ = re.compile(
+    r"credential-store\.sh['\"]?\s+get\b|\bsecurity\s+find-(?:generic|internet)-password\b[^;&|\n]*\s-w\b"
+)
+
+
+def secret_echo_reason(cmd):
+    """A stored secret read with nothing capturing or consuming its output prints
+    it into the transcript."""
+    stripped, _ = strip_heredoc_bodies(cmd)
+    for m in SECRET_READ.finditer(stripped):
+        before = stripped[: m.start()]
+        if before.count("$(") > before.count(")") or before.count("`") % 2:
+            continue
+        tail = re.split(r";|&&|\|\||\n", stripped[m.end():], maxsplit=1)[0]
+        if re.search(r"(?<!\|)\|(?!\|)|>", tail):
+            continue
+        return (
+            "this prints a stored secret into the transcript; capture it in a variable "
+            "(VAR=\"$(...)\"), pipe it into the consumer, or send it to /dev/null"
+        )
+    return None
+
+
+# --- the run this session drives ----------------------------------------------
+
+
+def _logs_root(env=None):
+    env = os.environ if env is None else env
+    return env.get("LOGS_ROOT") or os.path.join(os.path.expanduser("~"), ".claude", "logs", "multi-agent")
+
+
+LIVE_STATUSES = ("in_progress", "awaiting_input")
+_DRIVING = {}
+
+
+def driving_run(session_id, env=None):
+    """The live run whose hostSessionId is this session, or None: status
+    in_progress or awaiting_input (the statuses _active-run.mjs treats as
+    live), the most recently written one when several match. Read once per
+    hook process.
+
+    Runs live at <root>/<project>/<task>/agent-state.json or <root>/<task>/; both
+    depths are read. A missing session id matches nothing."""
+    if not isinstance(session_id, str) or not session_id:
+        return None
+    root = _logs_root(env)
+    key = (root, session_id)
+    if key not in _DRIVING:
+        _DRIVING[key] = _scan_driving(root, session_id)
+    return _DRIVING[key]
+
+
+def _scan_driving(root, session_id):
+    candidates = []
+    try:
+        for a in os.listdir(root):
+            pa = os.path.join(root, a)
+            if not os.path.isdir(pa):
+                continue
+            candidates.append(os.path.join(pa, RUN_STATE))
+            try:
+                for b in os.listdir(pa):
+                    candidates.append(os.path.join(pa, b, RUN_STATE))
+            except OSError:
+                continue
+    except OSError:
+        return None
+    best, best_t = None, -1.0
+    for path in candidates:
+        try:
+            st = os.stat(path)
+            if st.st_size > 4 * 1024 * 1024:
+                continue
+            with open(path, encoding="utf-8") as fh:
+                doc = json.load(fh)
+        except (OSError, ValueError):
+            continue
+        if not isinstance(doc, dict) or doc.get("hostSessionId") != session_id:
+            continue
+        if doc.get("status") in LIVE_STATUSES and st.st_mtime > best_t:
+            best, best_t = doc, st.st_mtime
+    return best
+
+
+def run_commit_reason(doc):
+    """Why a commit in the attended run this session drives needs the user's
+    yes (rules.md, "No auto-commit"), or None for no run or an unattended one."""
+    if not isinstance(doc, dict):
+        return None
+    launch = doc.get("launchRequest") if isinstance(doc.get("launchRequest"), dict) else {}
+    if doc.get("autopilot") is True or launch.get("mode") in ("autopilot", "background"):
+        return None
+    return (
+        "this commits inside the pipeline run this session is driving (" + str(doc.get("taskId") or "?")
+        + "); a commit waits for the user's explicit yes"
+    )
+
+
+# --- output format inside a run --------------------------------------------------
+
+# A repo profile may put the ticket first in any of its styles: [KEY-1], (KEY-1),
+# KEY-1:, #1 (repo-profile-derive.mjs PREFIX_RE). The type and scope follow the
+# same reader's CONV_RE: a lowercase word, any parenthesised scope.
+TICKET_PREFIX = r"(\s*[\[(]?\s*(?:[A-Z][A-Z0-9]+-\d+|#\d+)\s*[\])]?:?\s+)?"
+COMMIT_SUBJECT = re.compile(r"^" + TICKET_PREFIX + r"[a-z]+(\([^)]+\))?!?:\s+\S")
+SUBJECT_MAX = 72
+SKIPPED_SUBJECTS = re.compile(r"^(Merge |Revert \"|fixup! |squash! |amend! )|^\s*wip\b", re.I)
+ENTITY = re.compile(r"&(amp|lt|gt|quot|#39|#x27);")
+FENCE = re.compile(r"```.*?(```|$)", re.S)
+INLINE = re.compile(r"`[^`\n]*`")
+JIRA_CODE = re.compile(r"\{(code|noformat)[^}]*\}.*?(\{\1\}|$)", re.S)
+# A literal backslash-n meant as a line break sits between two pieces of
+# text: glued to the word before it and followed by more text
+# ("Summary\nThe change", "Changes:\n- a"), or after a space before a
+# capital ("Summary \nNext"). One ending a token (printf hello\n), quoted or
+# bracketed is a mention of the escape; \r\n and drive paths (C:\Users\name)
+# are removed before the search.
+LOST_BREAK = re.compile(r"(?<=[^\s\\'\"`(\[])\\n(?=[^\s'\"`)\]])|(?<=\s)\\n(?=[A-Z])")
+CRLF = re.compile(r"\\r\\n")
+DRIVE_PATH = re.compile(r"\b[A-Za-z]:\\\S*")
+
+
+def _subject(message):
+    """The first line of a commit message that carries text. A heredoc message
+    (`-m "$(cat <<EOF ...)"`) reaches the hook with the opening quote on its
+    own line, ahead of the body."""
+    for line in (message or "").split("\n"):
+        if re.search(r"[A-Za-z0-9]", line):
+            return line.strip()
+    return ""
+
+
+def profile_conventional(cwd):
+    """False when the repo's stored profile says its subjects are not
+    conventional, else True (no profile, unreadable, or conventional)."""
+    script = os.path.join(os.path.dirname(os.path.abspath(__file__)), "repo-profile.mjs")
+    if not os.path.isfile(script):
+        return True
+    try:
+        import subprocess
+
+        r = subprocess.run(
+            ["node", script, "resolve", "commit.format", "--repo", cwd or os.getcwd()],
+            capture_output=True, text=True, timeout=3,
+        )
+        doc = json.loads(r.stdout) if r.returncode == 0 and r.stdout.strip() else {}
+    except (OSError, ValueError, Exception):
+        return True
+    value = doc.get("value") if isinstance(doc, dict) and doc.get("use") else None
+    return not (isinstance(value, dict) and value.get("conventional") is False)
+
+
+def commit_subject_reason(message, cwd=None):
+    """Why a commit subject breaks the commit convention (rules.md), or None.
+
+    Not judged: a subject the hook cannot read for certain (a shell expansion
+    in it), git's merge, revert, fixup and squash subjects, checkpoint commits
+    (wip ...), and the type check in a repo whose profile is not conventional."""
+    subject = _subject(message)
+    if not subject or "$" in subject or "`" in subject or SKIPPED_SUBJECTS.search(subject):
+        return None
+    if len(subject) > SUBJECT_MAX:
+        return "the commit subject is " + str(len(subject)) + " characters; the convention caps it at " + str(SUBJECT_MAX)
+    if not COMMIT_SUBJECT.match(subject) and profile_conventional(cwd):
+        return (
+            "the commit subject does not start with a conventional type, as in type(scope): description "
+            "(after a repo profile's ticket prefix if any)"
+        )
+    return None
+
+
+def body_text_reason(text, entities=False):
+    """Why text published as a PR, issue or Jira body will render wrong, or
+    None: a literal backslash-n where a line break was meant, outside Markdown
+    and Jira code. With entities, an HTML entity too: a Jira payload renders
+    it verbatim, while Markdown on GitHub decodes it (and needs &lt; for a
+    literal angle bracket)."""
+    prose = DRIVE_PATH.sub(" ", CRLF.sub(" ", INLINE.sub("", FENCE.sub("", JIRA_CODE.sub("", text or "")))))
+    if LOST_BREAK.search(prose):
+        return "the body carries a literal \\n; write real line breaks (a heredoc or a body file)"
+    m = ENTITY.search(prose) if entities else None
+    if m:
+        return "the body carries the HTML entity " + m.group(0) + "; write the character itself"
+    return None
+
+
+def _json_strings(value, out):
+    """The prose strings of a JSON body, leaving out ADF code blocks and text
+    marked as code."""
+    if isinstance(value, str):
+        out.append(value)
+    elif isinstance(value, dict):
+        if value.get("type") == "codeBlock":
+            return out
+        marks = value.get("marks")
+        if isinstance(marks, list) and any(isinstance(m, dict) and m.get("type") == "code" for m in marks):
+            return out
+        for v in value.values():
+            _json_strings(v, out)
+    elif isinstance(value, list):
+        for v in value:
+            _json_strings(v, out)
+    return out
+
+
+def payload_files(argv):
+    """Files a request sends as its body: curl -d/--data/--data-binary/--json
+    @file and --data-urlencode [name]@file, and gh api --input file and
+    -F/--field name=@file. "@-" (stdin) is the caller's to resolve."""
+    if argv and os.path.basename(argv[0]) == "gh" and len(argv) > 1 and argv[1] == "api":
+        out, i = [], 2
+        while i < len(argv):
+            a = argv[i]
+            if a == "--input" and i + 1 < len(argv):
+                out.append(argv[i + 1])
+                i += 1
+            elif a in ("-F", "--field") and i + 1 < len(argv):
+                v = argv[i + 1]
+                if "=@" in v and not v.endswith("=@-"):
+                    out.append(v.split("=@", 1)[1])
+                i += 1
+            i += 1
+        return out
+    if not argv or os.path.basename(argv[0]) not in HTTP_CLIENTS:
+        return []
+    out, i = [], 1
+    while i < len(argv):
+        a = argv[i]
+        val = None
+        if a in ("-d", "--data", "--data-binary", "--data-ascii", "--json") and i + 1 < len(argv):
+            val = argv[i + 1]
+            i += 1
+        elif a.startswith(("--data=", "--data-binary=", "--data-ascii=", "--json=")):
+            val = a.split("=", 1)[1]
+        elif a == "--data-urlencode" and i + 1 < len(argv):
+            m = re.match(r"^[A-Za-z0-9_.-]*@(.+)$", argv[i + 1])
+            i += 1
+            val = "@" + m.group(1) if m else None
+        if val and val.startswith("@") and len(val) > 1 and val != "@-":
+            out.append(val[1:])
+        i += 1
+    return out
+
+
+def stdin_payload(argv):
+    """True when the request reads its body from stdin (-d @-, --data-binary @-, --input -)."""
+    return "@-" in argv or (len(argv) > 2 and argv[1] == "api" and "--input" in argv and "-" in argv)
+
+
+# Jira issue and comment endpoints only: Bitbucket Server (/rest/api/1.0/)
+# takes Markdown and Confluence storage format needs entities.
+JIRA_API = re.compile(r"/rest/api/(?:2|3|latest)/(?:issue|comment)\b", re.I)
+
+
+def payload_reason(path, cwd, entities=True, raw=None):
+    """body_text_reason over a request body file (or raw text). A JSON body is
+    judged on its decoded string values, where an escaped newline is a real
+    line break. Entities are judged only for a Jira target, which renders
+    them verbatim; GitHub and Bitbucket Markdown decode them."""
+    raw = read_bounded(path, cwd) if raw is None else raw
+    if not raw:
+        return None
+    try:
+        text = "\n".join(_json_strings(json.loads(raw), []))
+    except ValueError:
+        text = raw
+    return body_text_reason(text, entities=entities)
 
 
 # --- confirmations ---------------------------------------------------------------

package/pipeline/scripts/_memory-policy.mjs

@@ -0,0 +1,165 @@
+/**
+ * @file _memory-policy.mjs  -  what the per-repo memory stores may keep, and
+ * how much weight an entry has earned.
+ *
+ *   ledgerRowId(row)       the stable id of a learnings-ledger row, the one
+ *                          feedback is recorded against
+ *   checkedSlug(slug)      the slug as one folder name; a separator, NUL, `.`
+ *                          or `..`, anything that could leave
+ *                          ~/.claude/memory/multi-agent/, throws
+ *   memoryExcluded(slug)   prefs.global.memory.excludeProjects lists repo slugs
+ *                          whose memory is never written; every store asks
+ *                          before it writes
+ *   standing(feedback)     what the outcomes recorded against one ledger entry
+ *                          say about it: suppressed (marked corrected, or
+ *                          judged a dead end more often than useful, twice or
+ *                          more), corroborated (useful at least twice) and a
+ *                          strength that decays with age (ACT-R base level,
+ *                          ln of the sum of age^-0.5 over the useful dates)
+ *   nearDuplicate(a, b)    two statements that say the same thing in other
+ *                          words: TF-IDF cosine at or above the threshold, the
+ *                          same numbers, the same negations and mostly the
+ *                          same word order ("A over B" is not "B over A")
+ *
+ * Zero dependencies.
+ *
+ * @module pipeline/scripts/_memory-policy
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { shortId, tokens } from "./_retrieval.mjs";
+
+const CORROBORATION = 2;
+const NEAR_DUP = 0.9;
+const ORDER_OVERLAP = 0.5;
+const NEGATIONS = /\b(not|never|no|none|without|except|only|avoid|don't|do not)\b/gi;
+
+function prefs(env) {
+  const p =
+    env.MULTI_AGENT_PREFS || join(env.HOME || homedir(), ".claude", "multi-agent-preferences.json");
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+/** Stable id of a ledger row: its kind and its whitespace-folded statement. */
+export function ledgerRowId(row) {
+  const statement = String(row?.statement || "")
+    .toLowerCase()
+    .replace(/\s+/g, " ")
+    .trim();
+  return shortId("L", row?.kind, statement);
+}
+
+/**
+ * The slug, when it names one folder; throws on anything that could leave the
+ * memory folder (a separator, NUL, `.` or `..`). Spaces and non-ASCII letters
+ * are fine: a repository folder may carry them.
+ */
+export function checkedSlug(slug) {
+  const s = String(slug ?? "");
+  if (!s || s.length > 255 || /[/\\\0]/.test(s) || s === "." || s === "..") {
+    throw new Error(`not a repository slug: ${JSON.stringify(s.slice(0, 80))}`);
+  }
+  return s.normalize("NFC");
+}
+
+/** True when the repo's memory must not be written. */
+export function memoryExcluded(slug, env = process.env) {
+  const list = prefs(env)?.global?.memory?.excludeProjects;
+  const want = String(slug ?? "").normalize("NFC");
+  return Array.isArray(list) && list.some((p) => String(p).normalize("NFC") === want);
+}
+
+/**
+ * @param {Array<{ts: string, outcome: string}>} feedback  rows for one entry
+ * @returns {{useful: number, deadEnd: number, corrected: number, suppressed: boolean, corroborated: boolean, strength: number}}
+ */
+export function standing(feedback, now = Date.now()) {
+  const useful = feedback.filter((f) => f.outcome === "useful");
+  const deadEnd = feedback.filter((f) => f.outcome === "dead_end").length;
+  const corrected = feedback.filter((f) => f.outcome === "corrected").length;
+  const sum = useful.reduce((s, f) => {
+    const t = Date.parse(f.ts);
+    const days = Number.isNaN(t) ? 365 : Math.max(0, (now - t) / 86400000);
+    return s + Math.pow(days + 1, -0.5);
+  }, 0);
+  return {
+    useful: useful.length,
+    deadEnd,
+    corrected,
+    suppressed: corrected > 0 || (deadEnd >= CORROBORATION && deadEnd > useful.length),
+    corroborated: useful.length >= CORROBORATION,
+    strength: sum > 0 ? Math.log(sum) + 10 : 0,
+  };
+}
+
+const numbersIn = (s) => (String(s).match(/\d+(?:\.\d+)?/g) || []).sort().join(",");
+const negationsIn = (s) =>
+  (String(s).toLowerCase().match(NEGATIONS) || [])
+    .map((w) => w.replace(/\s+/g, " "))
+    .sort()
+    .join(",");
+
+/** Inverse document frequencies over a corpus of token lists. */
+function idf(corpus) {
+  const df = new Map();
+  for (const doc of corpus) for (const t of new Set(doc)) df.set(t, (df.get(t) || 0) + 1);
+  const n = corpus.length;
+  return (t) => Math.log(1 + n / (df.get(t) || 1));
+}
+
+function tfidf(doc, weight) {
+  const tf = new Map();
+  for (const t of doc) tf.set(t, (tf.get(t) || 0) + 1);
+  const v = new Map();
+  for (const [t, c] of tf) v.set(t, c * weight(t));
+  return v;
+}
+
+function cosine(va, vb) {
+  let dot = 0;
+  for (const [t, w] of va) dot += w * (vb.get(t) || 0);
+  const norm = (v) => Math.sqrt([...v.values()].reduce((s, w) => s + w * w, 0));
+  const d = norm(va) * norm(vb);
+  return d ? dot / d : 0;
+}
+
+/** Jaccard overlap of adjacent token pairs: low when the same words come in another order. */
+function orderOverlap(a, b) {
+  const pairs = (doc) => new Set(doc.slice(1).map((t, i) => `${doc[i]} ${t}`));
+  const pa = pairs(a);
+  const pb = pairs(b);
+  if (!pa.size || !pb.size) return 0;
+  let shared = 0;
+  for (const p of pa) if (pb.has(p)) shared++;
+  return shared / (pa.size + pb.size - shared);
+}
+
+/**
+ * The existing statement `candidate` repeats in other words, or null.
+ *
+ * @param {string} candidate
+ * @param {string[]} existing  statements of the same kind
+ */
+export function nearDuplicate(candidate, existing) {
+  const c = tokens(candidate);
+  if (c.length < 3) return null;
+  const docs = existing.map((s) => tokens(s));
+  const weight = idf([...docs, c]);
+  const vc = tfidf(c, weight);
+  const nums = numbersIn(candidate);
+  const negs = negationsIn(candidate);
+  for (let i = 0; i < existing.length; i++) {
+    if (numbersIn(existing[i]) !== nums) continue;
+    if (negationsIn(existing[i]) !== negs) continue;
+    if (orderOverlap(c, docs[i]) < ORDER_OVERLAP) continue;
+    if (cosine(vc, tfidf(docs[i], weight)) >= NEAR_DUP) return existing[i];
+  }
+  return null;
+}