@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.30 → 0.1.33

package/packages/agent-hooks/src/log/writer.ts

@@ -1,10 +1,10 @@
 /**
  * The `.adl/logs/` logger (docs/architecture/cli-design.md §5a, item 9). `agent-hooks`
- * "holds logs" (§12): this module lives here and writes `hooks.log` /
- * `hooks-deny.log` (`../hooks/log.ts`); `apps/cli/src/log.ts` re-exports it
- * unchanged so `adl run`'s `agents/tool-calls.log` writer keeps working. The module
- * is generic across all five documented files so a caller never has to
- * reinvent the format.
+ * "holds logs" (§12): this module lives here and writes
+ * `agent-hooks/hooks.log` / `agent-hooks/deny.log` (`../hooks/log.ts`);
+ * `apps/cli/src/log.ts` re-exports it so `adl run`'s `agents/tool-calls.log`
+ * writer and repo-controls' `git-hooks/` writer share it. One folder per
+ * owner under `.adl/logs/` (Bug 600); every stream rotates through here.
  *
  * - JSON Lines, one object per line. Fields are written in a fixed order;
  *   an absent field is OMITTED, never null-filled.
@@ -14,24 +14,35 @@
  *   must never fail the caller.
  * - `command` is redacted with `redact()` before it is written.
  * - Rotation: a file that would exceed `maxBytes` (10 MiB by default) is
- *   rotated to `.1` … `.5`, dropping `.5`, before the new line is written.
+ *   rotated to `.1` … `.5`, dropping `.5`, before the new line is written,
+ *   under a per-file lock (README, "Hook logs").
  */
+import { randomBytes } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import {
   appendFileSync,
   chmodSync,
   existsSync,
+  linkSync,
   mkdirSync,
+  readdirSync,
+  readFileSync,
   renameSync,
+  rmSync,
   statSync,
-  unlinkSync,
   writeFileSync,
 } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { ensureAdlGitignore } from "./adl-dir.ts";
 
-export type LogFileName = "hooks" | "hooks-deny" | "tool-rewrites" | "tool-calls" | "repo-controls";
+/** Every stream as `<owner folder>/<file>` under `.adl/logs/` (README, "Hook logs": one folder per owner, Bug 600). */
+export type LogFileName =
+  | "agent-hooks/hooks"
+  | "agent-hooks/deny"
+  | "git-hooks/activity"
+  | "git-hooks/deny"
+  | "agents/tool-calls";
 
 export interface LogEntryInput {
   /** Second column of every row: the host alone (`claude`, `codex`, `cursor`, `kimi`, `opencode`; `git` for git-hook rows). */
@@ -78,6 +89,8 @@ export interface WriteLogOptions {
   dir?: string;
   /** cwd used to resolve the git root when `dir` is not given. */
   cwd?: string;
+  /** How long to wait for the rotation lock before appending without rotating; defaults to 10 s. Tests inject a small value. */
+  lockTimeoutMs?: number;
   /** Rotation threshold in bytes; defaults to 10 MiB. Tests inject a small value. */
   maxBytes?: number;
   /** Clock override for deterministic `ts` values in tests. */
@@ -147,22 +160,154 @@ function ensureDirSecure(dir: string): void {
   ensureAdlGitignore(dir);
 }
 
+function isMissing(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
 function ensureFileSecure(filePath: string): void {
-  if (!existsSync(filePath)) {
-    writeFileSync(filePath, "", { mode: 0o600 });
+  writeFileSync(filePath, "", { mode: 0o600, flag: "a" });
+  try {
+    tightenMode(filePath, 0o600);
+  } catch (error) {
+    if (!isMissing(error)) throw error;
   }
-  tightenMode(filePath, 0o600);
 }
 
-function rotate(filePath: string): void {
-  const dropped = `${filePath}.${MAX_BACKUPS}`;
-  if (existsSync(dropped)) unlinkSync(dropped);
+function renameIfPresent(src: string, dst: string): boolean {
+  try {
+    renameSync(src, dst);
+    return true;
+  } catch (error) {
+    if (isMissing(error)) return false;
+    throw error;
+  }
+}
+
+const INSERT_ATTEMPTS = 5;
+
+function linkIfFree(src: string, dst: string): boolean {
+  try {
+    linkSync(src, dst);
+    return true;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "EEXIST" || code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function shiftBackups(filePath: string): void {
+  rmSync(`${filePath}.${MAX_BACKUPS}`, { force: true });
   for (let n = MAX_BACKUPS - 1; n >= 1; n--) {
-    const src = `${filePath}.${n}`;
-    const dst = `${filePath}.${n + 1}`;
-    if (existsSync(src)) renameSync(src, dst);
+    if (linkIfFree(`${filePath}.${n}`, `${filePath}.${n + 1}`)) rmSync(`${filePath}.${n}`, { force: true });
+  }
+}
+
+/** Moves `src` into slot `.1` without ever overwriting a backup; exported for tests, `afterShift` is their race hook. */
+export function insertBackup(filePath: string, src: string, afterShift?: () => void): void {
+  for (let attempt = 0; attempt < INSERT_ATTEMPTS; attempt++) {
+    shiftBackups(filePath);
+    afterShift?.();
+    if (linkIfFree(src, `${filePath}.1`)) {
+      rmSync(src, { force: true });
+      return;
+    }
+    if (!existsSync(src)) return;
+  }
+  throw new Error(`log rotation could not find a free backup slot for ${src}; file kept`);
+}
+
+function ownerAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+function orphanedAsides(filePath: string): string[] {
+  const prefix = `${basename(filePath)}.rotating-`;
+  const dir = dirname(filePath);
+  return readdirSync(dir)
+    .filter((name) => name.startsWith(prefix))
+    .map((name) => ({ path: join(dir, name), pid: Number(/^(\d+)-/.exec(name.slice(prefix.length))?.[1]) }))
+    .map((entry) => ({ ...entry, mtime: statSync(entry.path, { throwIfNoEntry: false })?.mtimeMs }))
+    .filter(({ pid, mtime }) => mtime !== undefined && (!Number.isInteger(pid) || !ownerAlive(pid) || Date.now() - mtime > LOCK_STALE_MS))
+    .sort((a, b) => (a.mtime as number) - (b.mtime as number))
+    .map(({ path }) => path);
+}
+
+function rotate(filePath: string): void {
+  for (const orphan of orphanedAsides(filePath)) insertBackup(filePath, orphan);
+  const aside = `${filePath}.rotating-${process.pid}-${randomBytes(4).toString("hex")}`;
+  if (!renameIfPresent(filePath, aside)) return;
+  insertBackup(filePath, aside);
+}
+
+/** A lock older than this was left by a crashed writer and is broken. */
+const LOCK_STALE_MS = 5_000;
+const LOCK_TIMEOUT_MS = 10_000;
+
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function readLockToken(lockPath: string): string | undefined {
+  try {
+    return readFileSync(lockPath, "utf8");
+  } catch (error) {
+    if (isMissing(error)) return undefined;
+    throw error;
+  }
+}
+
+export function breakStaleLock(lockPath: string, observed: string): void {
+  if (readLockToken(lockPath) === observed) rmSync(lockPath, { force: true });
+}
+
+/** Runs `body` holding `<filePath>.lock` (O_EXCL create); size check and rotation are one critical section (README, "Hook logs"). Exported for tests. */
+export function withRotationLock(filePath: string, lockTimeoutMs: number, body: () => void): void {
+  const lockPath = `${filePath}.lock`;
+  const token = `${process.pid}-${randomBytes(8).toString("hex")}`;
+  const deadline = Date.now() + lockTimeoutMs;
+  for (;;) {
+    try {
+      writeFileSync(lockPath, token, { flag: "wx", mode: 0o600 });
+      break;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+    const held = statSync(lockPath, { throwIfNoEntry: false });
+    if (held !== undefined && Date.now() - held.mtimeMs > LOCK_STALE_MS) {
+      const observed = readLockToken(lockPath);
+      if (observed !== undefined) breakStaleLock(lockPath, observed);
+    }
+    if (Date.now() > deadline) throw new Error(`log rotation lock ${lockPath} is held; refusing to rotate without it`);
+    sleepSync(2);
+  }
+  try {
+    body();
+  } finally {
+    if (readLockToken(lockPath) === token) rmSync(lockPath, { force: true });
   }
-  if (existsSync(filePath)) renameSync(filePath, `${filePath}.1`);
+}
+
+/** Rotates `filePath` to `.1` … `.5` when `incomingBytes` more would pass `maxBytes`, size re-read inside the lock; exported for raw-text streams (README, "Hook logs"). */
+export function rotateIfNeeded(
+  filePath: string,
+  incomingBytes: number,
+  maxBytes: number = DEFAULT_MAX_BYTES,
+  lockTimeoutMs: number = LOCK_TIMEOUT_MS,
+): void {
+  const over = () => {
+    const size = statSync(filePath, { throwIfNoEntry: false })?.size ?? 0;
+    return size > 0 && size + incomingBytes > maxBytes;
+  };
+  if (!over()) return;
+  withRotationLock(filePath, lockTimeoutMs, () => {
+    if (over()) rotate(filePath);
+  });
 }
 
 const USERINFO_RE = /(https?:\/\/)[^/\s:@]+:[^/\s@]+@/gi;
@@ -223,22 +368,23 @@ function serialize(entry: LogEntryInput, ts: string): string {
   return `${JSON.stringify(record)}\n`;
 }
 
-/** Appends one JSON-Lines entry to `<dir>/<file>.log`, rotating first if needed. Never throws for a missing repo — callers resolve `dir` with `resolveLogDir`. */
+/** Appends one JSON-Lines entry to `<dir>/<file>.log` (`file` is `<owner>/<name>`), rotating first if needed. Never throws for a missing repo — callers resolve `dir` with `resolveLogDir`. */
 export function writeLogEntry(file: LogFileName, entry: LogEntryInput, options: WriteLogOptions = {}): void {
   const dir = options.dir ?? resolveLogDir(options.cwd).dir;
   const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
   const ts = (options.now?.() ?? new Date()).toISOString();
   const line = serialize(entry, ts);
 
-  ensureDirSecure(dir);
   const filePath = join(dir, `${file}.log`);
+  ensureDirSecure(dirname(filePath));
   ensureFileSecure(filePath);
 
-  const currentSize = statSync(filePath).size;
-  if (currentSize + Buffer.byteLength(line, "utf8") > maxBytes) {
-    rotate(filePath);
-    ensureFileSecure(filePath);
+  try {
+    rotateIfNeeded(filePath, Buffer.byteLength(line, "utf8"), maxBytes, options.lockTimeoutMs);
+  } catch (error) {
+    process.stderr.write(`adl log: rotation deferred, row kept: ${error instanceof Error ? error.message : String(error)}\n`);
   }
+  ensureFileSecure(filePath);
 
   appendFileSync(filePath, line, { mode: 0o600 });
 }

package/packages/agent-hooks/src/main.ts

@@ -192,7 +192,7 @@ export async function run(argv: readonly string[], adlVersion?: string): Promise
   // `adl-config.toml` where `adl hooks deploy` has run — nowhere else. No
   // git root, or no `adl-config.toml` above `cwd`: a strict no-op (this
   // file's own header) — no rule evaluation, no identity check, no
-  // `hooks.log` write. There is no global identity baseline: a repo where
+  // `agent-hooks/hooks.log` write. There is no global identity baseline: a repo where
   // `adl-config.toml` does not exist has no business running hooks at all.
   // The same no-op applies when `[hooks] enabled = false` (below).
   const managed = resolveManagedRepo(realRootIO, cwd)

package/packages/agent-hooks/src/rules/impl/adl-git-push-policy.ts

@@ -39,14 +39,14 @@
  *     `classifyGitPushDestination`) — denied for EVERY identity, matching the
  *     matrix's ❌/❌ for this row. An unrecognized branch name (neither a
  *     protected name nor a recognized feature prefix) fails closed into this
- *     same bucket: the matrix only grants an exception for the four listed
+ *     same bucket: the matrix only grants an exception for the listed
  *     prefixes, not for "anything else". `develop` is retired
  *     (docs/specs/two-branch-standard-2026-09-27.md §1b.2 — the standard is
  *     two branches, not three) and is deliberately NOT a named protected
  *     branch any more; a push to it still lands in this same bucket, but as
  *     an ordinary unrecognized name, not a special case.
  *  3. Row 2 — the destination is a recognized feature branch
- *     (`feat/ fix/ docs/ chore/`): allowed for `agent-tarun`/`agent-vivek`
+ *     (`<commit type>/`, every type but `release` — packages/azdo/src/lib/commit-types.ts): allowed for `agent-tarun`/`agent-vivek`
  *     (Azure DevOps Contributors, and this is the ordinary way they ship
  *     work); denied for `agent-reviewer` (Azure DevOps Reader — cannot push
  *     at all, see docs/enact/handoff-enact-vps-global-tools-2026-09-25.md's
@@ -56,6 +56,7 @@
 import type { Invocation } from '../shell/invocation.ts'
 import type { Token } from '../shell/token.ts'
 import { tokenValue } from '../shell/token.ts'
+import { BRANCH_PREFIXES } from '../../../../azdo/src/lib/commit-types.ts'
 import type { Finding, MessageContext, RuleContext, RuleSpec } from '../spec.ts'
 import { noParams } from '../spec.ts'
 import { AGENT_REVIEWER, resolveFromEnvOrFile } from './adl-identity.ts'
@@ -134,7 +135,7 @@ function pushBypassesPolicy(rest: readonly Token[]): boolean {
 }
 
 const PROTECTED_BRANCHES: ReadonlySet<string> = new Set(['integration', 'main'])
-const FEATURE_PREFIXES: readonly string[] = ['feat/', 'fix/', 'docs/', 'chore/']
+const FEATURE_PREFIXES: readonly string[] = BRANCH_PREFIXES.map((prefix) => `${prefix}/`)
 
 function normalizeBranchRef(ref: string): string {
   return ref.startsWith('refs/heads/') ? ref.slice('refs/heads/'.length) : ref
@@ -229,7 +230,7 @@ export const adlGitPushBranchPolicy: RuleSpec = {
       const user = 'protected branch: push a feature branch and open a PR'
       return {
         user,
-        agent: `DENIED ${user}. \`integration\`/\`main\` (and any branch this hook cannot resolve from argv alone, including a retired name like \`develop\`) never take a direct push — push a \`feat/ fix/ docs/ chore/\` branch and open a PR. Blocked: ${ctx.snippet}`,
+        agent: `DENIED ${user}. \`integration\`/\`main\` (and any branch this hook cannot resolve from argv alone, including a retired name like \`develop\`) never take a direct push — push a \`${FEATURE_PREFIXES.join(' ')}\` branch and open a PR. Blocked: ${ctx.snippet}`,
       }
     }
 

package/packages/agent-hooks/src/rules/impl/mcp-tool.ts

@@ -55,7 +55,7 @@ export function toolNameEndingWithKnownSuffix(tool: string, knownSuffixes: Reado
  *
  * Prefix-less fallback (added 2026-09-28 with the one-agent-identity
  * standard): OpenCode's and Kimi's own MCP tool-call naming has never actually been
- * observed in production (`.adl/logs/hooks.log` shows only `mcp__`-prefixed
+ * observed in production (`.adl/logs/agent-hooks/hooks.log` shows only `mcp__`-prefixed
  * calls, from Claude/Codex/Cursor) — they MAY call an azdo tool with no
  * `mcp__` prefix at all, spelled `<server>_<tool>` / `<server>.<tool>` /
  * `<server>:<tool>`. When `tool` carries no `mcp__` prefix, this falls back

package/packages/agent-hooks/src/rules/shell/invocation.ts

@@ -501,7 +501,8 @@ function classifyGitArgv(argv: readonly Token[], binary: string): readonly Invoc
 
 function walkGit(tokens: readonly Token[], index: number, parser: Parser): readonly Invocation[] {
   const binary = tokenValue(tokens[index] as Token)
-  const argv = tokens.slice(index + 1)
+  // Redirections are the shell's, not git's: write targets are classified from the raw tokens elsewhere (Bug 626).
+  const argv = withoutRedirections(tokens.slice(index + 1))
   const scan = scanGitGlobals(argv, 0)
   if (scan.terminal) return [{ kind: 'read-only', name: 'git' }]
   if (scan.index >= argv.length) return uncertain('git command missing subcommand')

package/packages/agent-hooks/src/rules/shell/protected-carriers.ts

@@ -47,6 +47,12 @@ export const PROTECTED_CARRIER_PATHS: ReadonlySet<string> = new Set([
   // separate home-relative resolution needed — the suffix is the same
   // regardless of what resolves the leading `~`/`$HOME`/absolute prefix.
   '.kimi-code/config.toml',
+  // OpenCode's permission policy (surface-policy.ts); OpenCode reads both spellings (global-surface-sweep.ts).
+  '.config/opencode/opencode.jsonc',
+  '.config/opencode/opencode.json',
+  // Claude managed settings, macOS and Linux; suffix entries so /private/etc and ../ spellings match too.
+  'Library/Application Support/ClaudeCode/managed-settings.json',
+  'etc/claude-code/managed-settings.json',
 ])
 
 /**
@@ -105,10 +111,8 @@ export function protectedCarrierMatch(path: string): string | null {
 /**
  * The per-host carrier DIRECTORIES — deleting, moving away, or overwriting
  * the WHOLE directory removes (or replaces) the carrier file inside it too,
- * exactly as much as touching that file directly. `.claude`/`.codex`/`.cursor`/`.opencode` — Kimi's own
- * `~/.kimi-code/` is deliberately NOT included: `mv ~/.kimi-code /tmp` is a
- * genuinely different, much bigger blast radius (moving the user's whole
- * Kimi config directory, not a repo-scoped host-config directory).
+ * exactly as much as touching that file directly. All five surfaces, global and
+ * in the repo (Tarun, 2026-10-09): `.claude`/`.codex`/`.cursor`/`.opencode`, `.kimi-code`, `.config/opencode`.
  *
  * Covers `mv`/`cp -r` (destination)/`rsync` (destination) via
  * `protected-carrier-writes.ts`'s existing operand extraction — a
@@ -119,7 +123,17 @@ export function protectedCarrierMatch(path: string): string | null {
  * existing operand handlers, and covering them needs new, tool-specific
  * parsing; a known gap, recorded here rather than silently dropped.
  */
-const PROTECTED_CARRIER_DIRS: ReadonlySet<string> = new Set(['.claude', '.codex', '.cursor', '.opencode'])
+// The managed-settings folders are protected too: moving one away takes its managed-settings.json with it.
+const PROTECTED_CARRIER_DIRS: ReadonlySet<string> = new Set([
+  '.claude',
+  '.codex',
+  '.cursor',
+  '.opencode',
+  '.kimi-code',
+  '.config/opencode',
+  'Library/Application Support/ClaudeCode',
+  'etc/claude-code',
+])
 
 /**
  * The protected carrier directory `path` names — exact match or a trailing

package/packages/agent-settings/assets/GLOBAL-AGENTS.md

@@ -64,7 +64,7 @@ repo's own `AGENTS.md`.
 - **Repository controls run via `adl repo controls`.** Git hooks in controlled repositories run pre-commit (local checks) and pre-push (Azure DevOps governance). Each repository is reconciled on its own with its `.agents/`, `.claude/`, `.codex/`, `.cursor/`, `.kimi-code/`, `.opencode/` projections.
 - **The release flow (`integration` auto-complete; the `branch → PR → integration → main` promotion; the integration PR merging itself once green) applies to repositories whose root contains an `adl-config.toml`.** Other repositories follow the release flow declared in their own `AGENTS.md`. The human approval gate, where it exists, is the promotion from `integration` to `main`; everything before that is auto-complete once CI is green.
 - Keep each commit **independently green** and on one cohesive topic. Never use `git stash`. When "one topic" and "independently green" conflict, green wins — and say so.
-- Subjects are `<type>(<scope>): <lowercase subject>`. Types: `feat|fix|docs|refactor|perf|chore`. No `!` marker. `release:` is reserved for the promotion PR the pipeline raises — never write one by hand. **In repositories whose root contains an `adl-config.toml`, the pipeline opens `integration → main` once CI is green on `integration` — no agent opens it; the subject follows the commit grammar above.**
+- Subjects are `<type>(<scope>): <lowercase subject>`. Types: `feat|fix|docs|refactor|perf|chore`. Branch prefixes are exactly these types (`<type>/<kebab>`), not configurable per repository. No `!` marker. `release:` is reserved for the promotion PR the pipeline raises — never write one by hand. **In repositories whose root contains an `adl-config.toml`, the pipeline opens `integration → main` once CI is green on `integration` — no agent opens it; the subject follows the commit grammar above.**
 - A PR body needs non-empty `## Summary`, `## Why` and `## Changes`. The title follows the commit grammar above.
 
 ## Tests

package/packages/agent-skills/assets/agent-search-tool-audit/SKILL.md

@@ -91,7 +91,7 @@ ready for the next research-page review.
 
 | Metric | Source | Use |
 | --- | --- | --- |
-| Total decisions per host | `hooks.log` / `hooks.log.1` / `hooks-deny.log`, deduped by `(ts, command, rule)` | Volume baseline |
+| Total decisions per host | `agent-hooks/hooks.log*` / `agent-hooks/deny.log*` (plus the pre-Bug-600 top-level `hooks.log` / `hooks.log.1` / `hooks-deny.log`), deduped by `(ts, command, rule)` | Volume baseline |
 | Denials per host, broken down by `rule` field | same | Where the hook fires |
 | Search-tool denials (`tool.grep` / `tool.native-search` / `tool.find`) | same | The hook category this skill cares about |
 | `ast-grep` invocations (Bash command starting with `ast-grep`) | same | Whether the recommended tool is being used |
@@ -117,4 +117,26 @@ classifying them by tool). For the retry analysis, follow the
   — the hand-curated analysis this script would generate for today
 - `packages/agent-hooks/src/rules/impl/tool-grep.ts`,
   `tool-find.ts`, `tool-native-search.ts` — the deny messages the
-  audit is measuring
+  audit is measuring
+
+## Script notes
+
+Rationale moved out of `scripts/audit.sh` (REP-007: no multi-line comments).
+
+- Usage: `scripts/audit.sh [--days N] [--out DIR]`; defaults `--days 7`, `--out docs/research`.
+- Output: `<out>/research-YYYY-MM-DD-search-tool-usage-across-surfaces.md`, plus one new row appended
+  to `<out>/index.md`. Per-host, per-day tally of agent-hooks decisions, grouped by surface
+  (claude / codex / kimi / opencode), so the next weekly page in the series can compare against the
+  previous one. Reads only; never modifies the repo beyond those two files.
+- Source data: `.adl/logs/agent-hooks/hooks.log[.1-.5]` and `deny.log[.1-.5]` (one folder per owner,
+  Bug 600, Tarun 2026-10-08); the pre-Bug-600 top-level `.adl/logs/hooks.log`, `hooks.log.1` and
+  `hooks-deny.log` (read-only history, never migrated, deduped against the new ones);
+  `.adl/logs/agents/tool-calls.log` (`adl run` lifecycle).
+- Path discovery: the script lives in the agent-skills asset tree (5 levels deep in dev, 4 once
+  deployed to `.agents/skills/`), so it uses `git rev-parse --show-toplevel` to work in both layouts
+  and falls back to the dev layout if git is missing.
+- Required tools: `jq`, `python3` and `rg`; each is checked up front and the script fails loud
+  (exit 1) naming the missing one. `rg` is a protected bootstrap tool on every managed machine.
+- Cost: under 30 s on a typical 2-3 MB log set; no network.
+- An existing page for today is left untouched (it may be hand-curated); `index.md` is still updated
+  so the catalog stays current. Existing index rows are never disturbed; one row is appended.

package/packages/agent-skills/assets/agent-search-tool-audit/scripts/audit.sh

@@ -1,35 +1,5 @@
 #!/usr/bin/env bash
-# scripts/audit.sh — part of the agent-search-tool-audit skill
-# (packages/agent-skills/assets/agent-search-tool-audit/).
-#
-# Per-host, per-day tally of agent-hooks decisions in `.adl/logs/`,
-# grouped by surface (claude / codex / kimi / opencode). Writes one
-# dated markdown under `docs/research/` so the next weekly research
-# page in the "agent search-tool behaviour" series can compare against
-# the previous one. Reads only — never modifies the repo.
-#
-# Usage:
-#   scripts/audit.sh [--days N] [--out DIR]
-#
-# Defaults: --days 7, --out docs/research
-#
-# Output:
-#   <out>/research-YYYY-MM-DD-search-tool-usage-across-surfaces.md
-#   <out>/index.md  (one new row appended for the new page)
-#
-# Source data:
-#   .adl/logs/hooks.log            (current decision log)
-#   .adl/logs/hooks.log.1          (rotated decision log)
-#   .adl/logs/hooks-deny.log       (dedicated deny stream)
-#   .adl/logs/agents/tool-calls.log (adl run lifecycle)
-#
-# Path discovery: this script lives in the agent-skills asset tree
-# (5 levels deep in dev, 4 levels deep once deployed to
-# `.agents/skills/`). Use `git rev-parse --show-toplevel` so it
-# works in both layouts.
-#
-# Cost: <30 s on a typical 2-3 MB log set; no network, no new tools
-# beyond jq + python3 + the shell.
+# Usage and rationale: SKILL.md, "Script notes", in this skill's folder.
 
 set -euo pipefail
 
@@ -40,7 +10,7 @@ while [[ $# -gt 0 ]]; do
     --days) DAYS="$2"; shift 2;;
     --out)  OUT="$2"; shift 2;;
     -h|--help)
-      sed -n '2,30p' "$0"
+      echo "usage: audit.sh [--days N] [--out DIR]  (defaults: --days 7, --out docs/research)"
       exit 0
       ;;
     *)
@@ -52,10 +22,6 @@ done
 
 cd "$(dirname "$0")/../.."
 
-# `git rev-parse --show-toplevel` works in both dev (5 levels deep
-# under packages/agent-skills/assets/agent-search-tool-audit/scripts)
-# and deployed (4 levels deep under .agents/skills/). Fall back to
-# the dev layout if git is missing.
 if command -v git >/dev/null 2>&1; then
   if toplevel=$(git rev-parse --show-toplevel 2>/dev/null) && [[ -n "$toplevel" ]]; then
     cd "$toplevel"
@@ -63,9 +29,22 @@ if command -v git >/dev/null 2>&1; then
 fi
 
 command -v jq >/dev/null 2>&1 || { echo "jq is required and is not on PATH" >&2; exit 1; }
+command -v rg >/dev/null 2>&1 || { echo "rg is required and is not on PATH" >&2; exit 1; }
 command -v python3 >/dev/null 2>&1 || { echo "python3 is required and is not on PATH" >&2; exit 1; }
 
 LOG_FILES=(
+  .adl/logs/agent-hooks/hooks.log
+  .adl/logs/agent-hooks/hooks.log.1
+  .adl/logs/agent-hooks/hooks.log.2
+  .adl/logs/agent-hooks/hooks.log.3
+  .adl/logs/agent-hooks/hooks.log.4
+  .adl/logs/agent-hooks/hooks.log.5
+  .adl/logs/agent-hooks/deny.log
+  .adl/logs/agent-hooks/deny.log.1
+  .adl/logs/agent-hooks/deny.log.2
+  .adl/logs/agent-hooks/deny.log.3
+  .adl/logs/agent-hooks/deny.log.4
+  .adl/logs/agent-hooks/deny.log.5
   .adl/logs/hooks.log
   .adl/logs/hooks.log.1
   .adl/logs/hooks-deny.log
@@ -80,15 +59,12 @@ TODAY="$(date -u +%Y-%m-%d)"
 RUN_TS="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 OUT_FILE="${OUT}/research-${TODAY}-search-tool-usage-across-surfaces.md"
 
-# If today's page already exists, leave it alone — it might be a hand-curated
-# analysis from earlier in the day. Append / update `index.md` either way so
-# the catalog stays current.
 if [[ -f "$OUT_FILE" ]]; then
   echo "${OUT_FILE} already exists; leaving it untouched. Re-run after deleting it (or pass --out to a different dir)."
   # Still touch index.md so the catalog row stays current (idempotent).
   INDEX="${OUT}/index.md"
   ROW="| [Search-tool usage across surfaces — ${TODAY}](research-${TODAY}-search-tool-usage-across-surfaces.md) | Auto-generated weekly audit of per-host search-tool denials and recommended-tool invocations |"
-  if [[ -f "$INDEX" ]] && ! grep -q "research-${TODAY}-search-tool-usage-across-surfaces.md" "$INDEX"; then
+  if [[ -f "$INDEX" ]] && ! rg -q "research-${TODAY}-search-tool-usage-across-surfaces.md" "$INDEX"; then
     python3 - "$INDEX" "$ROW" <<'PYEOF' >/dev/null
 import sys
 path, row = sys.argv[1], sys.argv[2]
@@ -177,13 +153,13 @@ lines.append("type: Research")
 lines.append("created: {0}".format(today))
 lines.append("status: stable")
 lines.append("last_update: {0}".format(run_ts))
-lines.append("sources: .adl/logs/hooks.log, .adl/logs/hooks.log.1, .adl/logs/hooks-deny.log")
+lines.append("sources: .adl/logs/agent-hooks/hooks.log*, .adl/logs/agent-hooks/deny.log*, .adl/logs/hooks.log, .adl/logs/hooks.log.1, .adl/logs/hooks-deny.log")
 lines.append("related: ./index.md, ./research-2026-10-02-search-tool-usage-across-surfaces.md")
 lines.append("---")
 lines.append("")
 lines.append("# Agent interface search-tool usage across surfaces ({0})".format(today))
 lines.append("")
-lines.append("Auto-generated weekly audit. Window: trailing {0} UTC days ending {1}. Source: `.adl/logs/hooks*.log` and `.adl/logs/hooks-deny.log`. Re-run with `just research/weekly-search-audit`.".format(days, today))
+lines.append("Auto-generated weekly audit. Window: trailing {0} UTC days ending {1}. Source: `.adl/logs/agent-hooks/` (plus the pre-Bug-600 top-level `hooks.log*` and `hooks-deny.log`). Re-run with `just research/weekly-search-audit`.".format(days, today))
 lines.append("")
 lines.append("## Headline per host")
 lines.append("")
@@ -238,8 +214,6 @@ lines.append("")
 sys.stdout.write("\n".join(lines))
 PYEOF
 
-# Append / update index.md with the new page row. We don't disturb
-# other rows; we add one to the end of the table.
 INDEX="${OUT}/index.md"
 ROW="| [Search-tool usage across surfaces — ${TODAY}](research-${TODAY}-search-tool-usage-across-surfaces.md) | Auto-generated weekly audit of per-host search-tool denials and recommended-tool invocations |"
 
@@ -247,7 +221,7 @@ if [[ ! -f "$INDEX" ]]; then
   echo "index.md not present at ${INDEX}; not updating" >&2
   exit 0
 fi
-if grep -q "research-${TODAY}-search-tool-usage-across-surfaces.md" "$INDEX"; then
+if rg -q "research-${TODAY}-search-tool-usage-across-surfaces.md" "$INDEX"; then
   echo "index.md already has today's page; not appending"
 else
   # Insert before the closing fence (if any) or just append before EOF.

package/packages/agent-skills/assets/diagnosing-bugs/SKILL.md

@@ -98,3 +98,12 @@ Required before declaring done:
 - [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
 
 **Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.
+
+## HITL loop script
+
+`scripts/hitl-loop.template.sh` is the human-in-the-loop reproduction loop (usage notes moved out of the script so the deployed copy has no multi-line comment run).
+
+- Copy the file, edit the steps in it, and run it. The agent runs the script; the user follows prompts in their terminal.
+- Usage: `bash hitl-loop.template.sh`
+- Two helpers: `step "<instruction>"` shows the instruction and waits for Enter; `capture VAR "<question>"` shows the question and reads the response into `VAR`.
+- At the end, captured values are printed as `KEY=VALUE` for the agent to parse.

package/packages/agent-skills/assets/diagnosing-bugs/scripts/hitl-loop.template.sh

@@ -1,16 +1,5 @@
 #!/usr/bin/env bash
-# Human-in-the-loop reproduction loop.
-# Copy this file, edit the steps below, and run it.
-# The agent runs the script; the user follows prompts in their terminal.
-#
-# Usage:
-#   bash hitl-loop.template.sh
-#
-# Two helpers:
-#   step "<instruction>"          → show instruction, wait for Enter
-#   capture VAR "<question>"      → show question, read response into VAR
-#
-# At the end, captured values are printed as KEY=VALUE for the agent to parse.
+# Human-in-the-loop reproduction loop; usage in SKILL.md "HITL loop script".
 
 set -euo pipefail
 

package/packages/azdo/src/lib/commit-types.ts

@@ -0,0 +1,8 @@
+// The one list of commit types (Bug 651, Tarun 2026-10-09); every other list derives from it.
+export const COMMIT_TYPES = ['feat', 'fix', 'docs', 'refactor', 'perf', 'chore', 'release'] as const
+
+// `release` is reserved for the promotion PR the pipeline raises; agents and humans never author it.
+const RESERVED_COMMIT_TYPE = 'release'
+
+// Branch prefixes are exactly the commit types minus `release`; no repository overrides them.
+export const BRANCH_PREFIXES: readonly string[] = COMMIT_TYPES.filter((type) => type !== RESERVED_COMMIT_TYPE)

package/packages/azdo/src/lib/validate-pr-metadata.ts

@@ -1,4 +1,7 @@
-const TITLE_PATTERN = /^(feat|fix|docs|refactor|perf|chore)(\([a-z0-9][a-z0-9-]*\))?: .+$/
+import { BRANCH_PREFIXES } from './commit-types.ts'
+
+// A PR title never carries the pipeline-reserved `release`, so its types are the branch prefixes.
+const TITLE_PATTERN = new RegExp(`^(${BRANCH_PREFIXES.join('|')})(\\([a-z0-9][a-z0-9-]*\\))?: .+$`)
 const REQUIRED_SECTIONS = ['Summary', 'Why', 'Changes']
 
 export function validatePullRequestMetadata(title: string, description: string): string[] {

package/packages/fleet/manifest.json

@@ -33,7 +33,7 @@
       "remove_worktrees": true
     },
     "brew_upgrade_exclude": [],
-    "protected_tools": ["git", "jq"],
+    "protected_tools": ["git", "jq", "ripgrep"],
     "git_global_config": {
       "credential.helper": ["", "{git-credential-manager}"],
       "credential.https://dev.azure.com.useHttpPath": "true",
@@ -159,6 +159,7 @@
         "node": {"manager": "brew", "package": "node", "executable": "node"},
         "ripgrep": {"manager": "brew", "package": "ripgrep", "executable": "rg"},
         "search": {"manager": "shim", "package": "enact-docs-search", "executable": "/usr/local/bin/search"},
+        "shfmt": {"manager": "brew", "package": "shfmt", "executable": "shfmt"},
         "tailscale": {"manager": "apt", "package": "tailscale", "executable": "/usr/bin/tailscale"},
         "uv": {"manager": "brew", "package": "uv", "executable": "uv"},
         "yq": {"manager": "brew", "package": "yq", "executable": "yq"}