@mmerterden/multi-agent-pipeline 20.8.0 → 20.8.2

package/pipeline/lib/redact.mjs

@@ -7,6 +7,13 @@
  * `[redacted:<rule>]`; the text around it is kept, because a log line is read
  * to debug a failure and the message is what makes it useful.
  *
+ * The rules run on the folded copy of the text (normalize-text.mjs), so a token
+ * carrying an invisible character or a look-alike letter is found, and the
+ * span of the ORIGINAL text it came from is the one replaced. Everything
+ * outside a match is written back as it was: a Persian zero-width non-joiner,
+ * a direction mark, an emoji joined by U+200D and a soft hyphen all survive,
+ * and a text with no match is returned unchanged.
+ *
  * As a CLI it reads stdin and writes the redacted text to stdout. It never
  * fails its caller: on an internal error it writes the input unchanged.
  *
@@ -15,26 +22,93 @@
 
 import { RULES } from "./outbound-gate.mjs";
 import { invokedDirectly } from "./invoked-directly.mjs";
-import { stripInvisible } from "./normalize-text.mjs";
+import { foldWithIndex, normalizeForMatch } from "./normalize-text.mjs";
 
 const CERTAIN = RULES.filter((r) => r.certain);
 
+const globalCopy = (re) =>
+  new RegExp(re.source, re.flags.includes("g") ? re.flags : `${re.flags}g`);
+const marker = (name) =>
+  name === "url-with-credentials" ? `[redacted:${name}]@` : `[redacted:${name}]`;
+
+// Where two rules match overlapping text, the one with the longer literal
+// prefix names the span: `sk-ant-...` is an Anthropic key even though the
+// shorter `sk-` OpenAI rule matches it too. Equal prefixes keep rule order.
+const literalPrefix = (re) => (re.source.replace(/^\\b/, "").match(/^[A-Za-z0-9_-]*/) || [""])[0];
+const RANK = new Map(
+  CERTAIN.map((r, i) => [r.name, { specificity: literalPrefix(r.re).length, order: i }]),
+);
+const moreSpecific = (a, b) => {
+  const x = RANK.get(a);
+  const y = RANK.get(b);
+  return x.specificity > y.specificity || (x.specificity === y.specificity && x.order < y.order);
+};
+
+/**
+ * Spans of `text` a certain rule matches, as [from, to, rule], merged and in
+ * order. The rules run on the raw text and on the folded copy: a letter that
+ * folds to a word character (the Turkish dotless i, a ligature, a
+ * mathematical letter) right before a token removes the word boundary the
+ * rule needs in the folded copy only, and a look-alike inside a token hides it
+ * from the raw text only. Raw spans are already in original indices; folded
+ * ones are mapped back through the fold's index.
+ */
+function findSpans(text) {
+  const spans = [];
+  for (const rule of CERTAIN) {
+    for (const m of text.matchAll(globalCopy(rule.re))) {
+      if (m[0]) spans.push([m.index, m.index + m[0].length, rule.name]);
+    }
+  }
+  const { folded, start, end } = foldWithIndex(text);
+  if (folded !== text) {
+    for (const rule of CERTAIN) {
+      for (const m of folded.matchAll(globalCopy(rule.re))) {
+        if (!m[0]) continue;
+        spans.push([start[m.index], end[m.index + m[0].length - 1], rule.name]);
+      }
+    }
+  }
+  spans.sort((x, y) => x[0] - y[0] || y[1] - x[1]);
+  const merged = [];
+  for (const s of spans) {
+    const last = merged.at(-1);
+    if (last && s[0] < last[1]) {
+      if (s[1] > last[1]) last[1] = s[1];
+      if (moreSpecific(s[2], last[2])) last[2] = s[2];
+    } else {
+      merged.push([...s]);
+    }
+  }
+  return merged;
+}
+
+function stillMatches(text) {
+  const folded = normalizeForMatch(text);
+  return CERTAIN.find((r) => globalCopy(r.re).test(text) || globalCopy(r.re).test(folded));
+}
+
 /** @param {string} text */
 export function redact(text) {
   if (typeof text !== "string" || !text) return text;
-  // Invisible characters are removed first: they change nothing a reader sees,
-  // and a token split by one would otherwise slip past every rule.
-  let out = stripInvisible(text);
-  for (const rule of CERTAIN) {
-    const re = new RegExp(
-      rule.re.source,
-      rule.re.flags.includes("g") ? rule.re.flags : `${rule.re.flags}g`,
-    );
-    out = out.replace(re, () =>
-      rule.name === "url-with-credentials" ? `[redacted:${rule.name}]@` : `[redacted:${rule.name}]`,
-    );
+  const spans = findSpans(text);
+  let out = text;
+  for (let k = spans.length - 1; k >= 0; k--) {
+    const [from, to, name] = spans[k];
+    out = out.slice(0, from) + marker(name) + out.slice(to);
   }
-  return out;
+  // The per-code-point fold that locates spans can differ from the whole-text
+  // fold the gate uses where NFKC composes across characters. A line the gate
+  // would still flag after both the raw and the folded spans are replaced is
+  // replaced whole rather than written with a credential.
+  if (!stillMatches(out)) return out;
+  return out
+    .split("\n")
+    .map((line) => {
+      const rule = stillMatches(line);
+      return rule ? marker(rule.name) : line;
+    })
+    .join("\n");
 }
 
 if (invokedDirectly(import.meta.url)) {

package/pipeline/multi-agent-refs/analysis/evidence.md

@@ -107,7 +107,7 @@ the bucket patterns use (`docs/adr/0010-own-code-graph.md`).
 | domainEntities | `Domain/Entities/*.swift` | `domain/entities/*.kt` / `entities/*.py` |
 | routes | Public `enum *Route` matching `DomainRoute` | `*Route` sealed / NavRoute / `routes.*` modules |
 | coordinators | `*Coordinator.swift` + `CoordinatorProtocol`/`DomainRouter` | Navigator / NavController helpers |
-| diConfigurators | `*DependencyConfigurator.swift`, `Module.kt` (Hilt) | DI container registrations |
+| diConfigurators | `*DependencyRegistrar.swift`, `*Assembly.swift`, `Module.kt` (Hilt) | DI container registrations |
 | uiComponents | `Common/UIComponents/.../Components/**/*.swift` triplet (Configuration + View + +Modifiers) | Compose @Composable functions / React components |
 | tokens | `*Token` enums under `UIAssetTokens/Generated/` | `Theme.kt` / `tokens.ts` / `tailwind.config.*` |
 | localizationKeys | `LocalizationStringKeys.swift` public enum + cases | `strings.xml` keys / `i18n/*.json` keys |

package/pipeline/multi-agent-refs/analysis/synthesis.md

@@ -49,7 +49,7 @@ Convention preview - Pass B will render with:
 | Test naming | @Test func scenario_expected() ^[C4 medium: 4 examples] | fun scenario_expectedBehavior() ^[C4 high] |
 | Identifier | userProfile.continueButton ^[C5 high] | userProfileContinueButton ^[C5 medium] |
 | Localization key | UserProfile.ContinueButton ^[C6 high] | user_profile_continue_button ^[C6 high] |
-| DI | UserProfileDependencyConfigurator ^[C7 high] | UserProfileModule (Hilt) ^[C7 fallback: defaults] |
+| DI | UserProfileDependencyRegistrar ^[C7 high] | UserProfileModule (Hilt) ^[C7 fallback: defaults] |
 
 Confidence summary:
   iOS:     5/5 high, 0 medium, 0 low, 0 fallback

package/pipeline/multi-agent-refs/component-dispatch.md

@@ -47,7 +47,7 @@ run produced entities and a mapper but left the screen half-wired.
 
 | `state.componentScope` | Meaning | iOS skill | Android skill |
 |---|---|---|---|
-| `screen` (default when the frame is a full screen, or the task names a screen) | Full clean-architecture vertical: Entity → Repository → Mapper → UseCase → LocalizedText → AnalyticsTracking → CoordinatorEvent → ViewModel → Scene → Preview, then verify | `ai-ios-toolkit:create-screen` | `ai-android-toolkit:create-screen` |
+| `screen` (default when the frame is a full screen, or the task names a screen) | Full clean-architecture vertical: Entity → Repository → Mapper → UseCase → Copy → AnalyticsTracking → CoordinatorEvent → ViewModel → Scene → Preview, then verify | `ai-ios-toolkit:create-screen` | `ai-android-toolkit:create-screen` |
 | `component` | One reusable UI component (Configuration / View / +Modifiers / Code Connect) | `ai-ios-toolkit:create-component` (fallback `create-ui-component`) | `ai-android-toolkit:create-component` (fallback `create-ui-component`) |
 | `evolve` | Change an existing component | `evolve-component` (fallback `evolve-ui-component`) | same |
 

package/pipeline/multi-agent-refs/conventions-defaults.md

@@ -160,7 +160,7 @@ Detection: scan up to 10 SwiftUI view files in the candidate set; majority pick
 
 | Platform | Default | Example | Rationale |
 |---|---|---|---|
-| iOS | Manual configurator | `<Domain>DependencyConfigurator.register<Feature>()` | Avoids framework lock-in; testable |
+| iOS | Manual configurator | `<Domain>DependencyRegistrar.register<Feature>()` | Avoids framework lock-in; testable |
 | Android | Hilt module | `@Module @InstallIn(SingletonComponent::class) class <Feature>Module` | Standard Android DI |
 | Backend FastAPI | `Depends(get_<feature>_service)` | `service: OrderSummaryService = Depends(get_order_summary_service)` | Native FastAPI pattern |
 | Web | hook factory | `useOrderSummaryApi()` returns a memoized client | No framework DI needed |

package/pipeline/multi-agent-refs/features/unattended-security.md

@@ -287,8 +287,8 @@ Before every launch - the dev run, a research pass, a resume - the runner:
   settings, read the way `install/claude.mjs` writes it: a matcher is a regex
   over the tool name (the legacy `Bash(git push:*)` covers nothing, and the web
   entry has to cover `agent_run_steps` and both `open_url` tools), the hook
-  command is exactly the installer's `bash $HOME/.claude/scripts/agent-guard.sh`
-  (or the same path with `$HOME` expanded) and that script exists. The
+  command is exactly the installer's `bash "$HOME/.claude/scripts/agent-guard.sh"`
+  (quoted or not, or the same path with `$HOME` expanded) and that script exists. The
   checkout's `.claude/` settings never count toward the registration - the repo
   under work is not where the guard may come from - but `disableAllHooks` in
   any of these files, the checkout's included, turns every hook off. It also

package/pipeline/scripts/agent-guard.py

@@ -51,12 +51,24 @@ ATTRIBUTION = re.compile(
 )
 
 
+def _strip_set(ranges):
+    out = set()
+    for spec in ranges:
+        first, _, last = str(spec).partition("-")
+        try:
+            lo, hi = int(first, 16), int(last or first, 16)
+        except ValueError:
+            continue
+        out.update(chr(cp) for cp in range(lo, hi + 1))
+    return out
+
+
 def _load_confusables():
     here = os.path.dirname(os.path.abspath(__file__))
     try:
         with open(os.path.join(here, "..", "lib", "confusables.json"), encoding="utf-8") as fh:
             table = json.load(fh)
-        return set(table.get("strip", [])), dict(table.get("map", {}))
+        return _strip_set(table.get("stripRanges", [])), dict(table.get("map", {}))
     except (OSError, ValueError):
         return set(), {}
 
@@ -65,12 +77,14 @@ _STRIP, _MAP = _load_confusables()
 
 
 def normalize_for_match(text: str) -> str:
-    """NFKC, invisible characters removed, look-alike letters mapped to ASCII.
+    """NFKC, Default_Ignorable_Code_Point removed, look-alikes mapped to ASCII.
 
     The same fold lib/normalize-text.mjs applies, from the same table. Rules
     that match text content run on the raw command and on this copy, so a
     trailer written with a zero-width space or a Cyrillic letter still matches.
-    Without the table only NFKC applies.
+    The table's map also carries the compatibility letters newer than this
+    Python's unicodedata, which NFKC here would leave alone. Without the table
+    only NFKC applies.
     """
     return "".join(
         _MAP.get(ch, ch) for ch in unicodedata.normalize("NFKC", text) if ch not in _STRIP
@@ -130,10 +144,23 @@ GIT_FLAG_OPTIONS = {
 SEPARATORS = re.compile(r"&&|\|\||;|\||\n")
 
 
+# shlex grows each token one character at a time, which is quadratic in the
+# token's length: a megabyte argument takes longer than the deadline. A segment
+# longer than this is split on whitespace with its quotes and backslashes
+# removed instead, which keeps every word the segment names in order.
+SHLEX_MAX_CHARS = 16384
+
+
+def coarse_tokens(cmd: str) -> list:
+    return [re.sub(r"[\"'\\]", "", t) for t in cmd.split()]
+
+
 def tokenize(cmd: str) -> list:
     """shlex tokens, or whitespace tokens when shlex cannot parse (an unbalanced
-    quote). Never returns None: a guard has to reason about a segment it cannot
-    parse cleanly, not skip it."""
+    quote) or the segment is too long for it. Never returns None: a guard has to
+    reason about a segment it cannot parse cleanly, not skip it."""
+    if len(cmd) > SHLEX_MAX_CHARS:
+        return coarse_tokens(cmd)
     try:
         return shlex.split(cmd)
     except Exception:
@@ -401,11 +428,12 @@ def _decide_push(cmd: str, toks=None, cwd=None) -> str:
     force_flag = bool(FORCE.search(cmd))
     if not force_flag and not FORCED_REFSPEC.search(cmd) and not PUSH_GATE.search(cmd):
         return "OK"
-    try:
-        shlex.split(cmd)
-    except Exception:
-        # A force-push we can't tokenize -> can't prove it's safe -> block.
-        return "BLOCK_FORCE"
+    if len(cmd) <= SHLEX_MAX_CHARS:
+        try:
+            shlex.split(cmd)
+        except Exception:
+            # A force-push we can't tokenize -> can't prove it's safe -> block.
+            return "BLOCK_FORCE"
     git_dir, opts, positionals = _parse_push(toks)
     keys = {k for k, _ in opts}
     force_flag = any(
@@ -451,17 +479,97 @@ def _decide_push(cmd: str, toks=None, cwd=None) -> str:
     return "OK"
 
 
+FALLBACK_SPLIT = re.compile(r"&&|\|\||[;|\n()`]|\\n")
+FALLBACK_FORCE_WORDS = {"-d", "--force", "--force-with-lease", "--force-if-includes", "--mirror", "--delete", "--prune"}
+FALLBACK_TARGET_WORDS = {"head", "@", "--all", "--mirror", "--branches"}
+
+
+def _fallback_forced(tok: str) -> bool:
+    key = tok.split("=", 1)[0]
+    if key in FALLBACK_FORCE_WORDS or tok.startswith("+") or ":+" in tok or tok.startswith(":"):
+        return True
+    return tok.startswith("-") and not tok.startswith("--") and tok[1:].isalpha() and "f" in tok
+
+
+def _fallback_protected(tok: str) -> bool:
+    name = tok.rsplit(":", 1)[-1].lstrip("+")
+    if name.startswith("refs/heads/"):
+        name = name[len("refs/heads/"):]
+    return name in PROTECTED or tok in FALLBACK_TARGET_WORDS
+
+
+def fallback_verdict(text: str) -> str:
+    """The always-on rules as a linear scan, for input the tokenizer could not
+    finish in time. Each piece between shell separators is split on whitespace
+    with its quotes and backslashes removed, and no regex that can backtrack
+    runs over it. A push piece with a force indicator is blocked when it names a
+    protected branch, HEAD / @ or every ref, or when the checkout's own branch
+    is protected or unknown; a line with a git commit is blocked when the
+    attribution pattern matches the raw or the folded text. Stricter than
+    decide() by design: it only runs when decide() could not."""
+    try:
+        folded = normalize_for_match(text)
+    except Exception:
+        folded = text
+    current = os.environ.get("CUR_BRANCH", "")
+    commits = False
+    for t in (text, folded):
+        for piece in FALLBACK_SPLIT.split(t.lower()):
+            toks = coarse_tokens(piece)
+            if not any(os.path.basename(x) == "git" for x in toks):
+                continue
+            words = set(toks)
+            if "commit" in words:
+                commits = True
+            if "push" not in words or not any(_fallback_forced(x) for x in toks):
+                continue
+            if any(_fallback_protected(x) for x in toks) or current in PROTECTED or current in ("", "HEAD"):
+                return "BLOCK_FORCE"
+    if commits and (ATTRIBUTION.search(text) or ATTRIBUTION.search(folded)):
+        return "BLOCK_ATTRIB"
+    return "OK"
+
+
 def unattended() -> bool:
     """MULTI_AGENT_UNATTENDED=1 in the hook's own environment - the launcher's,
     never anything the run wrote (lib/unattended.sh ma_unattended)."""
     return os.environ.get("MULTI_AGENT_UNATTENDED", "") == "1"
 
 
+def _arm_deadline(on_deadline) -> None:
+    """Run on_deadline (which must end the process) once deadline_seconds()
+    have passed. Where SIGALRM is unavailable the call simply runs to the end."""
+
+    def _fire(_signum, _frame):
+        try:
+            signal.setitimer(signal.ITIMER_REAL, 0)
+        except (ValueError, AttributeError, OSError):
+            pass
+        on_deadline()
+
+    try:
+        signal.signal(signal.SIGALRM, _fire)
+        signal.setitimer(signal.ITIMER_REAL, deadline_seconds())
+    except (ValueError, AttributeError, OSError):
+        pass
+
+
+def _exit_with(line: str) -> None:
+    # os._exit skips the stdio flush, so the line is flushed first or the
+    # caller reads nothing.
+    if line:
+        print(line, flush=True)
+    os._exit(0)
+
+
 def git_subcommand_mode() -> None:
     """`agent-guard.py --git-subcommand`: read a Bash payload (or a raw command
     on argv) and print each git subcommand it runs, one per line, using the same
     tokenizer the guard uses. pre-commit-check.sh reads this to detect a commit
-    without a regex. Never executes anything."""
+    without a regex. Never executes anything. At the deadline it prints
+    `commit`, so the caller scans rather than skipping a commit it could not
+    rule out."""
+    _arm_deadline(lambda: _exit_with("commit"))
     if len(sys.argv) > 2:
         cmd = sys.argv[2]
     else:
@@ -490,8 +598,9 @@ def commit_dir_mode() -> None:
     """`agent-guard.py --commit-dir`: read a Bash payload and print the
     directory the first commit-writing git command on the line runs in, after
     any `cd` / `git -C`, resolved from the payload's cwd. Prints nothing when
-    there is no commit or the directory cannot be read literally, so the caller
-    keeps its own cwd. Never executes anything."""
+    there is no commit, the directory cannot be read literally, or the deadline
+    passes, so the caller keeps its own cwd. Never executes anything."""
+    _arm_deadline(lambda: _exit_with(""))
     try:
         data = json.load(sys.stdin)
         cmd = (data.get("tool_input") or {}).get("command", "")
@@ -519,21 +628,37 @@ def main() -> None:
         commit_dir_mode()
         return
     strict = unattended()
-
-    def _deadline(_signum, _frame):
-        # os._exit skips the stdio flush, so the verdict is flushed first or
-        # the wrapper reads nothing.
-        print("BLOCK_UNATTENDED\tthe guard hit its internal deadline" if strict else "OK", flush=True)
-        os._exit(0)
+    seen = {"text": "", "raw": True}
+
+    def _unjudged(default: str) -> str:
+        # The always-on rules still hold when the full decision could not be
+        # reached: a linear scan of whatever text is at hand decides them.
+        text = seen["text"]
+        if seen.get("raw"):
+            try:
+                cmd = (json.loads(text).get("tool_input") or {}).get("command", "")
+                text = cmd if isinstance(cmd, str) else text
+            except Exception:
+                pass
+        try:
+            verdict = fallback_verdict(text)
+        except Exception:
+            verdict = "OK"
+        return verdict if verdict != "OK" else default
 
     try:
-        signal.signal(signal.SIGALRM, _deadline)
-        signal.setitimer(signal.ITIMER_REAL, deadline_seconds())
-    except (ValueError, AttributeError, OSError):
-        pass
+        seen["text"] = sys.stdin.read()
+    except Exception:
+        seen["text"] = ""
+    # Armed once the payload is in hand, so the fallback always has the text.
+    _arm_deadline(
+        lambda: _exit_with(_unjudged("BLOCK_UNATTENDED\tthe guard hit its internal deadline" if strict else "OK"))
+    )
     try:
-        data = json.load(sys.stdin)
+        data = json.loads(seen["text"])
         cmd = (data.get("tool_input") or {}).get("command", "")
+        if isinstance(cmd, str):
+            seen["text"], seen["raw"] = cmd, False
         verdict = decide(cmd) if isinstance(cmd, str) and cmd else "OK"
         if verdict == "OK" and strict:
             sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
@@ -547,7 +672,7 @@ def main() -> None:
         # Attended: a guard bug must not break a legitimate tool call.
         # Unattended: nobody is there to notice a gap, so an input the guard
         # cannot judge is refused.
-        print("BLOCK_PARSE" if strict else "OK")
+        print(_unjudged("BLOCK_PARSE" if strict else "OK"))
 
 
 if __name__ == "__main__":

package/pipeline/scripts/audit-log.sh

@@ -56,10 +56,9 @@ hash_url() {
   elif command -v shasum >/dev/null 2>&1; then
     printf '%s' "$url" | shasum -a 256 | awk '{print $1}'
   else
-    # The previous fallback printed `unhashed:<url>`, writing the plaintext remote into
-    # the audit log - the exact thing this hashing exists to prevent, and it would have
-    # carried any credentials embedded in the remote URL with it. Losing one field beats
-    # leaking one.
+    # No hash tool: record a fixed marker, never the URL itself. The plaintext
+    # remote is what the hashing keeps out of the log, and a remote URL can
+    # carry embedded credentials.
     echo "unhashable-no-sha256-tool"
   fi
 }

package/pipeline/scripts/autopilot-runner.mjs

@@ -263,10 +263,11 @@ const GUARD_MATCHERS = [
     ],
   ],
 ];
-// The hook command install/claude.mjs writes. Only this command, with $HOME
-// written literally or expanded, counts as the guard: a command that merely
-// mentions the script path can run anything and still look registered.
-const GUARD_COMMAND = "bash $HOME/.claude/scripts/agent-guard.sh";
+// The hook command install/claude.mjs writes (the path quoted, so a HOME with a
+// space still runs it). Only this command, quoted or not, with $HOME written
+// literally or expanded, counts as the guard: a command that merely mentions
+// the script path can run anything and still look registered.
+const GUARD_COMMAND = 'bash "$HOME/.claude/scripts/agent-guard.sh"';
 const MANAGED_SETTINGS = "/Library/Application Support/ClaudeCode/managed-settings.json";
 // A phase record without a model is priced at the most expensive tier: an
 // over-estimate stops the spend ceiling early, an under-estimate stops it late.
@@ -1334,7 +1335,15 @@ function matcherCovers(matcher, tool) {
 /** The guard script, when the hook command is exactly the installer's and the script exists. */
 function guardScriptOf(command, home) {
   const script = join(home, ".claude", "scripts", "agent-guard.sh");
-  const forms = [GUARD_COMMAND, GUARD_COMMAND.replace("$HOME", "${HOME}"), `bash ${script}`];
+  const unquoted = GUARD_COMMAND.replaceAll('"', "");
+  const forms = [
+    GUARD_COMMAND,
+    GUARD_COMMAND.replace("$HOME", "${HOME}"),
+    unquoted,
+    unquoted.replace("$HOME", "${HOME}"),
+    `bash "${script}"`,
+    `bash ${script}`,
+  ];
   return forms.includes(String(command || "").trim()) && existsSync(script) ? script : null;
 }
 

package/pipeline/scripts/doctor.mjs

@@ -465,8 +465,14 @@ function checkHookCoverage() {
       for (const h of entry.hooks || []) if (h.command) wantedCmds.add(h.command);
     }
   }
-  const haveStr = JSON.stringify(have?.hooks || {});
-  const absent = [...wantedCmds].filter((c) => !haveStr.includes(c));
+  const haveCmds = new Set();
+  for (const group of Object.values(have?.hooks || {})) {
+    for (const entry of Array.isArray(group) ? group : []) {
+      for (const h of entry?.hooks || [])
+        if (typeof h?.command === "string") haveCmds.add(h.command);
+    }
+  }
+  const absent = [...wantedCmds].filter((c) => !haveCmds.has(c));
   if (absent.length) {
     report(
       "hook-coverage",

package/pipeline/scripts/gen-skills-index.mjs

@@ -100,6 +100,18 @@ for (const k of order) {
   md += `\n`;
 }
 
-writeFileSync(join(SKILLS_ROOT, "README.md"), md);
+const target = join(SKILLS_ROOT, "README.md");
+if (process.argv.includes("--check")) {
+  const current = existsSync(target) ? readFileSync(target, "utf8") : "";
+  if (current !== md) {
+    console.error(
+      "gen-skills-index: pipeline/skills/shared/README.md is stale - run node pipeline/scripts/gen-skills-index.mjs",
+    );
+    process.exit(1);
+  }
+  console.log("gen-skills-index: README.md is current");
+  process.exit(0);
+}
+writeFileSync(target, md);
 const filledCategories = Object.values(buckets).filter((b) => b.length).length;
 console.log(`wrote ${total} skills (${breakdown}) across ${filledCategories} categories`);

package/pipeline/scripts/log-metric.sh

@@ -55,6 +55,12 @@ mkdir -p "$METRICS_DIR" 2>/dev/null || {
   exit 0
 }
 
+# Same escaping as audit-log.sh: backslash, quote, tab and CR escaped, and a
+# newline written as \n, so any caller text stays inside one JSON string.
+json_escape() {
+  printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g; s/	/\\t/g; s/\r/\\r/g' | awk 'NR > 1 { printf "\\n" } { printf "%s", $0 }'
+}
+
 # Build details object from key=value args. Keep it shell-portable: no jq required.
 DETAILS="{"
 SEP=""
@@ -65,10 +71,10 @@ for kv in "$@"; do
   # int or true/false becomes a JSON string.
   case "$VAL" in
     true|false) JSON_VAL="$VAL" ;;
-    ''|*[!0-9]*) JSON_VAL="\"$(printf '%s' "$VAL" | tr -d '\n\r' | sed 's/\\/\\\\/g; s/"/\\"/g; s/	/\\t/g')\"" ;;
+    ''|*[!0-9]*) JSON_VAL="\"$(json_escape "$VAL")\"" ;;
     *) JSON_VAL="$VAL" ;;
   esac
-  DETAILS="${DETAILS}${SEP}\"${KEY}\":${JSON_VAL}"
+  DETAILS="${DETAILS}${SEP}\"$(json_escape "$KEY")\":${JSON_VAL}"
   SEP=","
 done
 DETAILS="${DETAILS}}"
@@ -79,7 +85,7 @@ PHASE_SCHEMA="$(node -e 'const c=require("'"$(cd "$(dirname "$0")" && pwd)"'/../
 [ -n "$PHASE_SCHEMA" ] || PHASE_SCHEMA=2
 
 TS="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
-LINE="{\"ts\":\"${TS}\",\"task_id\":\"${TASK_ID}\",\"phase\":\"${PHASE}\",\"event\":\"${EVENT}\",\"details\":${DETAILS},\"phaseSchema\":${PHASE_SCHEMA}}"
+LINE="{\"ts\":\"${TS}\",\"task_id\":\"$(json_escape "$TASK_ID")\",\"phase\":\"$(json_escape "$PHASE")\",\"event\":\"$(json_escape "$EVENT")\",\"details\":${DETAILS},\"phaseSchema\":${PHASE_SCHEMA}}"
 
 # Caller-supplied values can carry a credential copied out of an error.
 # redact.mjs replaces it with a marker; without node the line is written as is.

package/pipeline/scripts/migrate-prefs.mjs

@@ -522,10 +522,23 @@ function migrateReportChannels(out, changes) {
   }
 }
 
+// Writes through a symlinked prefs file to its target, so a prefs file kept in
+// a dotfiles repo stays a link and the repo copy receives the migration.
 function atomicWrite(filePath, data) {
-  withFileLockSync(filePath, () => writeJsonAtomicSync(filePath, data, { mode: 0o600 }), {
-    timeoutMs: lockTimeoutFrom(process.env),
-  });
+  withFileLockSync(
+    filePath,
+    () => writeJsonAtomicSync(filePath, data, { mode: 0o600, followSymlink: true }),
+    { timeoutMs: lockTimeoutFrom(process.env) },
+  );
+}
+
+// The document as it was before this migration, beside the path given, so a
+// migration that went wrong can be undone by hand.
+function writeBackup(filePath, raw) {
+  const bak = `${filePath}.bak`;
+  fs.writeFileSync(bak, raw, { mode: 0o600 });
+  fs.chmodSync(bak, 0o600);
+  return bak;
 }
 
 function main() {
@@ -560,8 +573,9 @@ function main() {
     process.exit(0);
   }
 
+  const bak = writeBackup(args.file, raw);
   atomicWrite(args.file, out);
-  console.log(`✓ wrote migrated prefs to ${args.file}`);
+  console.log(`✓ wrote migrated prefs to ${args.file} (previous version: ${bak})`);
 }
 
 runMain("migrate-prefs", main);