@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.32 → 0.1.34

package/bin/adl

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/bin/adl
-size: 82920928 bytes
-sha256: f63a82963b12de92399625846d611dc9a469ceec692522e95fbae7ff3f702acb
+size: 82945504 bytes
+sha256: b6594d01b2ebea8949f80faa8da029598f8be7513fb1e3c7b63ddc01df4c8f02

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amsterdamdatalabs/adl-agent-control-linux-x64",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "description": "adl CLI binary for linux/x64 (agent identity + Azure DevOps front door — see docs/architecture/cli-design.md)",
   "license": "UNLICENSED",
   "os": [

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/git-branch.ts

@@ -0,0 +1,63 @@
+// PBI 661 (Tarun, 2026-10-09): agents never change branches; both denies say "ask the user for git branch operations". See docs/architecture/agent-git-branch-rules.md
+
+import type { Invocation } from '../shell/invocation.ts'
+import type { Finding, MessageContext, RuleContext, RuleSpec } from '../spec.ts'
+import { noParams } from '../spec.ts'
+import { branchMutates, isHelpOnlyInvocation, isSequencerRecoveryOnly, switchCheckoutCreatesBranch } from './git-helpers.ts'
+import { LANDING_SUBCOMMANDS, resolveGitTarget } from './git-target.ts'
+import { gitAgentTail } from './messages.ts'
+
+const ASK_USER = 'ask the user for git branch operations'
+
+const UNRESOLVED =
+  'The commit target (which repository and branch this would land on) could not be determined statically from this command line. ' +
+  'Run `git commit` as its own command, or with `git -C <path>`, so the target is explicit. '
+
+function askUserMessage(ctx: MessageContext, unresolved = false) {
+  return { user: ASK_USER, agent: `DENIED ${ASK_USER}. ${unresolved ? UNRESOLVED : ''}${gitAgentTail(ctx.snippet)}` }
+}
+
+export const gitBranchMutation: RuleSpec = {
+  id: 'git.branch-mutation',
+  category: 'git',
+  severity: 'deny',
+  enabledByDefault: true,
+  summary: 'Deny every mutating git branch form and branch creation via git switch -c / git checkout -b.',
+  params: noParams,
+  match(inv: Invocation): Finding | null {
+    if (inv.kind !== 'git') return null
+    const hit =
+      inv.subcommand === 'branch' ? branchMutates(inv.rest) : inv.subcommand === 'switch' || inv.subcommand === 'checkout' ? switchCheckoutCreatesBranch(inv.subcommand, inv.rest) : false
+    return hit ? { ruleId: 'git.branch-mutation', severity: 'deny', detail: {} } : null
+  },
+  message: (_finding: Finding, ctx: MessageContext) => askUserMessage(ctx),
+  corpus: {
+    deny: ['git branch foo', 'git branch -D old-feature', 'git branch -aD', 'git branch --delete --force old-feature', 'git branch -m old new', 'git switch -c new-branch', 'git checkout -b new-branch'],
+    allow: ['git branch', 'git branch -a', 'git branch -vv', 'git branch --show-current', "git branch --list 'feat/*'", 'git switch main', 'git checkout feature-x'],
+  },
+}
+
+export const gitCommitProtectedBranch: RuleSpec = {
+  id: 'git.commit-protected-branch',
+  category: 'git',
+  severity: 'deny',
+  enabledByDefault: true,
+  summary: 'Deny git commit (and merge, cherry-pick, revert, am) while the target repo is on a protected branch, or when the target or its branch cannot be resolved.',
+  params: noParams,
+  match(inv: Invocation, ctx: RuleContext<Record<string, never>>): Finding | null {
+    if (inv.kind !== 'git' || !LANDING_SUBCOMMANDS.has(inv.subcommand)) return null
+    if (isHelpOnlyInvocation(inv.rest)) return null // prints text, commits nothing
+    if (inv.subcommand !== 'commit' && isSequencerRecoveryOnly(inv.rest)) return null // --abort / --quit only end an operation
+    const target = resolveGitTarget(inv, ctx.command)
+    // null target or branch = unresolved: fail closed (docs/architecture/agent-git-branch-rules.md)
+    const branch = target === null ? null : ctx.index.currentBranch(target)
+    if (branch !== null && !ctx.agentConfig.protectedBranches.includes(branch)) return null
+    return { ruleId: 'git.commit-protected-branch', severity: 'deny', detail: { unresolved: branch === null ? 'yes' : 'no' } }
+  },
+  message: (finding: Finding, ctx: MessageContext) => askUserMessage(ctx, finding.detail['unresolved'] === 'yes'),
+  // Fixture branch is never protected, so deny entries are the fail-closed ones (docs/architecture/agent-git-branch-rules.md)
+  corpus: {
+    deny: ['cd "$REPO" && git commit -m x', 'git -C "$REPO" commit -m x', 'GIT_DIR="$D" git merge origin/integration'],
+    allow: ["git commit -m 'feat(x): y'", 'git status'],
+  },
+}

package/packages/agent-hooks/src/rules/impl/git-helpers.ts

@@ -61,9 +61,97 @@ export function commitAmends(rest: readonly Token[]): boolean {
   return hasFlag(rest, '--amend')
 }
 
-export function branchForceDeletes(rest: readonly Token[]): boolean {
-  if (hasFlagOrCluster(rest, [], ['D'])) return true
-  return hasFlagOrCluster(rest, ['--delete'], ['d']) && hasFlagOrCluster(rest, ['--force'], ['f'])
+/**
+ * Every long option `git branch -h` lists on git 2.56 (positive forms), plus the
+ * legacy `--set-upstream`. Used ONLY to resolve unique prefixes the way git's
+ * parse-options does; whether an option is allowed is `BRANCH_READ_ONLY_OPTIONS`.
+ */
+const BRANCH_POSITIVE_OPTIONS: readonly string[] = [
+  'verbose', 'quiet', 'track', 'set-upstream-to', 'set-upstream', 'unset-upstream', 'color', 'remotes', 'contains', 'no-contains', 'abbrev', 'all',
+  'delete', 'move', 'omit-empty', 'copy', 'list', 'show-current', 'create-reflog', 'edit-description', 'delete-merged', 'dry-run', 'force', 'merged',
+  'no-merged', 'forked', 'column', 'sort', 'points-at', 'ignore-case', 'recurse-submodules', 'format', 'help',
+]
+const BRANCH_ALL_OPTIONS: readonly string[] = [...new Set([...BRANCH_POSITIVE_OPTIONS, ...BRANCH_POSITIVE_OPTIONS.filter((name) => !name.startsWith('no-') && name !== 'help' && name !== 'remotes' && name !== 'all').map((name) => `no-${name}`)])]
+/** PBI 661 allowlist: the only `git branch` options that read and never write. Anything else (known or not) is a deny. */
+const BRANCH_READ_ONLY_OPTIONS: ReadonlySet<string> = new Set([
+  'verbose', 'quiet', 'color', 'remotes', 'all', 'list', 'show-current', 'omit-empty', 'ignore-case', 'dry-run', 'abbrev', 'column', 'help',
+  'contains', 'no-contains', 'merged', 'no-merged', 'forked', 'sort', 'points-at', 'format',
+  'no-verbose', 'no-quiet', 'no-color', 'no-abbrev', 'no-column', 'no-sort', 'no-points-at', 'no-format', 'no-omit-empty', 'no-ignore-case', 'no-dry-run',
+])
+/** Read-only options whose separate next token is their value. */
+const BRANCH_VALUE_OPTIONS: ReadonlySet<string> = new Set(['contains', 'no-contains', 'merged', 'no-merged', 'forked', 'sort', 'points-at', 'format'])
+/** Read-only options that put `git branch` in list mode, where positionals are patterns, not new branch names. */
+const BRANCH_LIST_OPTIONS: ReadonlySet<string> = new Set(['list', 'show-current', 'contains', 'no-contains', 'merged', 'no-merged', 'points-at', 'forked'])
+/** `-v -q -r -a -l -i`, alone or clustered; every other short letter writes or is unknown. */
+const BRANCH_READ_ONLY_LETTERS: readonly string[] = ['v', 'q', 'r', 'a', 'l', 'i']
+
+/** git's parse-options rule: an exact name wins, else the unique name that starts with `name`; `null` when unknown or ambiguous. */
+function resolveLongOption(name: string, table: readonly string[]): string | null {
+  if (table.includes(name)) return name
+  const candidates = table.filter((candidate) => candidate.startsWith(name))
+  return candidates.length === 1 ? (candidates[0] as string) : null
+}
+
+/**
+ * PBI 661: does this `git branch` argv change branches, or might it? Fail
+ * closed: only an argv made entirely of known read-only options (long options
+ * resolved by unique prefix as git does) is false. A bare positional with no
+ * list-mode option is a branch name to CREATE, so it is true.
+ */
+export function branchMutates(rest: readonly Token[]): boolean {
+  if (isHelpOnlyInvocation(rest)) return false
+  let listMode = false
+  let positionals = 0
+  for (let index = 0; index < rest.length; index++) {
+    const value = tokenValue(rest[index] as Token)
+    if (value === '--') {
+      positionals += rest.length - index - 1
+      break
+    }
+    if (value.startsWith('--')) {
+      const name = resolveLongOption(value.slice(2).split('=')[0] as string, BRANCH_ALL_OPTIONS)
+      if (name === null || !BRANCH_READ_ONLY_OPTIONS.has(name)) return true
+      if (BRANCH_LIST_OPTIONS.has(name)) listMode = true
+      if (BRANCH_VALUE_OPTIONS.has(name) && !value.includes('=')) index++
+    } else if (value.startsWith('-') && value.length > 1) {
+      const letters = [...value.slice(1)]
+      if (letters.some((letter) => !BRANCH_READ_ONLY_LETTERS.includes(letter))) return true
+      if (letters.includes('l')) listMode = true
+    } else {
+      positionals++
+    }
+  }
+  return positionals > 0 && !listMode
+}
+
+/** Long options that create a branch, per subcommand; `NON_CREATING` are the long options whose exact name must win over a longer creating one. */
+const CREATING_LONG_OPTIONS: Readonly<Record<string, readonly string[]>> = {
+  switch: ['create', 'force-create', 'orphan', 'track'],
+  checkout: ['orphan', 'track'],
+}
+const NON_CREATING_LONG_OPTIONS: readonly string[] = ['force', 'detach', 'discard-changes', 'merge', 'conflict', 'quiet', 'progress', 'no-progress', 'guess', 'no-guess', 'no-track', 'ignore-other-worktrees', 'recurse-submodules', 'no-recurse-submodules', 'overlay', 'no-overlay', 'ours', 'theirs', 'patch']
+
+/**
+ * PBI 661: `git switch -c/-C/-t/--create/--force-create/--orphan/--track` and
+ * `git checkout -b/-B/-t/--orphan/--track` create a branch, including any
+ * unique (or ambiguous-with-a-creating) long-option prefix (`--cr`, `--force-c`,
+ * `--orp`, `--tr`). Plain `git switch|checkout <existing>` is not matched.
+ */
+export function switchCheckoutCreatesBranch(subcommand: string, rest: readonly Token[]): boolean {
+  const longs = CREATING_LONG_OPTIONS[subcommand] ?? []
+  const letters = subcommand === 'switch' ? ['c', 'C', 't'] : ['b', 'B', 't']
+  for (const token of rest) {
+    const value = tokenValue(token)
+    if (value === '--') return false
+    if (value.startsWith('--')) {
+      const name = value.slice(2).split('=')[0] as string
+      if (longs.includes(name)) return true
+      if (name.length > 0 && !NON_CREATING_LONG_OPTIONS.includes(name) && longs.some((long) => long.startsWith(name))) return true
+    } else if (value.startsWith('-') && value.length > 1 && [...value.slice(1)].some((letter) => letters.includes(letter))) {
+      return true
+    }
+  }
+  return false
 }
 
 export function tagDeletes(rest: readonly Token[]): boolean {

package/packages/agent-hooks/src/rules/impl/git-history.ts

@@ -1,18 +1,18 @@
 /**
- * `branch -D`, `tag -d`, `switch -f`, `gc --prune[=<date>]`.
+ * `tag -d`, `switch -f`, `gc --prune[=<date>]`.
  * (`update-ref` in every form lives in git-plumbing.ts.)
  *
  * Ported from `blockedGitHistoryReason` in blocked-reason.mjs:78-86. None of
  * these bypass on a bare `--help`/`--version` the way the "core" rules do —
  * the original's `blockedGitPolicyReason` is called unconditionally, with no
- * `rmIsHelpOnly` gate — so neither does this. All four fall through
+ * `rmIsHelpOnly` gate — so neither does this. All three fall through
  * `classifyReason`'s default arm.
  */
 
 import type { Invocation } from '../shell/invocation.ts'
 import type { Finding, MessageContext, RuleSpec } from '../spec.ts'
 import { noParams } from '../spec.ts'
-import { branchForceDeletes, gcPrunesExplicitly, switchIsForced, tagDeletes } from './git-helpers.ts'
+import { gcPrunesExplicitly, switchIsForced, tagDeletes } from './git-helpers.ts'
 import { defaultGitMessage, detailString } from './messages.ts'
 
 function git(inv: Invocation): (Invocation & { kind: 'git' }) | null {
@@ -40,15 +40,6 @@ function make(id: string, subcommand: string, reasonFor: () => string, hits: (g:
   }
 }
 
-export const gitBranchForceDelete = make(
-  'git.branch-force-delete',
-  'branch',
-  () => 'git branch -D',
-  (g) => branchForceDeletes(g.rest),
-  ['git branch -D old-feature', 'git branch -aD', 'git branch --delete --force old-feature'],
-  ['git branch -d merged-feature', 'git branch feature-x', 'git branch -a'],
-)
-
 export const gitTagDelete = make(
   'git.tag-delete',
   'tag',
@@ -64,7 +55,7 @@ export const gitSwitchForce = make(
   () => 'git switch -f',
   (g) => switchIsForced(g.rest),
   ['git switch -f main', 'git switch --force main'],
-  ['git switch main', 'git switch -c new-branch'],
+  ['git switch main', 'git switch feat/existing'],
 )
 
 export const gitGcPrune = make(

package/packages/agent-hooks/src/rules/impl/git-target.ts

@@ -0,0 +1,423 @@
+// Best-effort static resolver of the repository a commit-like git command lands on. See docs/architecture/agent-git-branch-rules.md#resolver
+
+import { statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import type { BranchTarget } from '../ports.ts'
+import type { Invocation } from '../shell/invocation.ts'
+import { withoutRedirections } from '../shell/git-internals.ts'
+import { splitShell } from '../shell/split.ts'
+import { findMatchingBacktick, findMatchingParen } from '../shell/substitution.ts'
+import { type Token, basename, tokenValue, tokenize } from '../shell/token.ts'
+
+// Subcommands that add history to the current branch (pull, rebase, reset, amend are excluded: see docs/architecture/agent-git-branch-rules.md)
+export const LANDING_SUBCOMMANDS: ReadonlySet<string> = new Set(['commit', 'merge', 'cherry-pick', 'revert', 'am'])
+
+const ASSIGNMENT_RE = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/
+const SHELLS: ReadonlySet<string> = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh'])
+/** Commands that re-run another command: a shell `-c` script behind one is followed. */
+const RE_EXECUTORS: ReadonlySet<string> = new Set(['xargs', 'parallel', 'env', 'nice', 'nohup', 'timeout', 'sudo', 'doas'])
+
+// Bash builtins and reserved words: `compgen -b` + `compgen -k` on bash 5.3 (docs/architecture/agent-git-branch-rules.md#closed-builtin-sets-and-their-provenance)
+const BASH_BUILTINS_AND_KEYWORDS: readonly string[] = (
+  '. : [ alias bg bind break builtin caller cd command compgen complete compopt continue declare dirs disown echo enable eval exec exit export false fc fg getopts hash help history jobs kill let local logout mapfile popd printf pushd pwd read readarray readonly return set shift shopt source suspend test times trap true type typeset ulimit umask unalias unset wait if then else elif fi case esac for select while until do done in function time { } ! [[ ]] coproc').split(' ')
+// zsh builtins and reserved words: `zsh -c 'print ${(k)builtins} ${(k)reswords}'` on zsh 5.9 (same doc section)
+const ZSH_BUILTINS_AND_RESERVED_WORDS: readonly string[] = (
+  'unset rehash popd ulimit local jobs disable [ compfiles printf autoload noglob pushln zle readonly exit false times sched setopt getln builtin let bg which unhash pwd zparseopts logout disown type source eval comptags compdescribe compctl r zmodload zregexparse history return exec compadd emulate chdir ttyctl test comparguments pushd functions float zstyle print declare comptry alias shift - . bindkey typeset true hash compset cd compvalues getopts compgroups export enable limit echotc echo wait dirs unsetopt read : integer bye echoti compquote unfunction fc vared unalias kill compcall where fg zformat suspend unlimit break set continue command zcompile whence umask trap log private if else end do then { select coproc } ! case [[ repeat done for while time esac until fi nocorrect foreach elif function'
+).split(' ')
+/** The closed set of shell builtins and reserved words (bash 5.3 + zsh 5.9): a head outside it is an external command or a function. */
+const SHELL_BUILTINS_AND_KEYWORDS: ReadonlySet<string> = new Set([...BASH_BUILTINS_AND_KEYWORDS, ...ZSH_BUILTINS_AND_RESERVED_WORDS])
+/** Builtins that only print or test: neutral (`printf -v` / `print -v` assign a variable and are not). */
+const READ_ONLY_BUILTINS: ReadonlySet<string> = new Set(['echo', 'printf', 'print', 'which', 'whence', 'where', 'true', 'false', 'test', '[', '[[', 'pwd', 'type', 'hash', 'help', ':', 'times', 'dirs', 'jobs'])
+/** Variables whose assignment (or export, or unset) changes what a later cd, `~` or shell startup does: unknown. */
+const SENSITIVE_VARIABLES: ReadonlySet<string> = new Set(['BASH_ENV', 'ENV', 'HOME', 'CDPATH', 'ZDOTDIR', 'PATH'])
+/** Variables that, as a prefix on a launched shell, change what that shell runs or means. */
+const SHELL_STARTUP_VARIABLES: ReadonlySet<string> = new Set(['BASH_ENV', 'ENV', 'ZDOTDIR', 'HOME', 'CDPATH'])
+/** git subcommands that move HEAD (or the worktree it is read from): after one, the branch a later landing command hits is unknown. */
+const HEAD_MOVERS: ReadonlySet<string> = new Set(['switch', 'checkout', 'worktree', 'stash', 'bisect', 'rebase', 'reset'])
+const GIT_VALUE_GLOBALS: ReadonlySet<string> = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--super-prefix', '--config-env'])
+
+/** Does this piece run `git <HEAD_MOVER> ...` (behind any wrapper)? */
+function movesHead(rest: readonly Token[]): boolean {
+  const gitAt = rest.findIndex((token) => ['git', 'git.exe'].includes(basename(token)))
+  if (gitAt < 0) return false
+  for (let i = gitAt + 1; i < rest.length; i++) {
+    const value = tokenValue(rest[i] as Token)
+    if (value.startsWith('-')) {
+      if (GIT_VALUE_GLOBALS.has(value)) i++
+      continue
+    }
+    const subcommand = value.toLowerCase()
+    if (!HEAD_MOVERS.has(subcommand)) return false
+    // Read-only forms of stash/worktree do not move HEAD: `stash list|show`, `worktree list`.
+    const action = rest.slice(i + 1).map((token) => tokenValue(token)).find((arg) => !arg.startsWith('-'))
+    if (subcommand === 'stash' && (action === 'list' || action === 'show')) return false
+    if (subcommand === 'worktree' && action === 'list') return false
+    return true
+  }
+  return false
+}
+
+function namesDirectory(word: string): boolean {
+  try {
+    return statSync(word).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+interface Mutable {
+  dirs: string[]
+  gitDir?: string
+  workTree?: string
+  /** `HOME=` was assigned for this command: `~` no longer means the home directory we know. */
+  homeUnknown?: boolean
+}
+
+/** `~`, `~/x`, `$HOME`, `${HOME}` expand to the home directory; any other `$` or backtick is not static (`null`). */
+function expandPath(value: string, target: Mutable): string | null {
+  const home = homedir()
+  const tilde = value === '~' || value.startsWith('~/')
+  if (tilde) return target.homeUnknown === true ? null : home + value.slice(1)
+  for (const prefix of ['${HOME}', '$HOME']) {
+    if (value === prefix || value.startsWith(`${prefix}/`)) return target.homeUnknown === true ? null : home + value.slice(prefix.length)
+  }
+  return /[$`]/.test(value) || value === '' ? null : value
+}
+
+/** Apply `NAME=value` env assignments we care about; false when one is not static. */
+function applyEnv(target: Mutable, assignments: readonly string[]): boolean {
+  for (const assignment of assignments) {
+    const match = ASSIGNMENT_RE.exec(assignment)
+    if (!match) continue
+    const name = match[1] as string
+    if (name !== 'GIT_DIR' && name !== 'GIT_WORK_TREE') continue
+    const value = expandPath(match[2] as string, target)
+    if (value === null) return false
+    if (name === 'GIT_DIR') target.gitDir = value
+    else target.workTree = value
+  }
+  return true
+}
+
+function leadingAssignments(tokens: readonly Token[]): { assignments: string[]; rest: Token[] } {
+  let index = 0
+  const assignments: string[] = []
+  while (index < tokens.length && ASSIGNMENT_RE.test(tokenValue(tokens[index] as Token))) assignments.push(tokenValue(tokens[index++] as Token))
+  return { assignments, rest: tokens.slice(index) as Token[] }
+}
+
+/** `--git-dir`, `--work-tree`, `-C` among git's globals; false when one is not static. */
+function applyGlobals(target: Mutable, globals: readonly Token[]): boolean {
+  const values = globals.map((token) => tokenValue(token))
+  for (let index = 0; index < values.length; index++) {
+    const value = values[index] as string
+    const take = (long: string): string | null => {
+      if (value === long) return values[++index] ?? ''
+      if (value.startsWith(`${long}=`)) return value.slice(long.length + 1)
+      return null
+    }
+    const gitDir = take('--git-dir')
+    if (gitDir !== null) {
+      const expanded = expandPath(gitDir, target)
+      if (expanded === null) return false
+      target.gitDir = expanded
+      continue
+    }
+    const workTree = take('--work-tree')
+    if (workTree !== null) {
+      const expanded = expandPath(workTree, target)
+      if (expanded === null) return false
+      target.workTree = expanded
+      continue
+    }
+    if (value === '-C' || (value.startsWith('-C') && value.length > 2)) {
+      const dir = expandPath(value === '-C' ? (values[++index] ?? '') : value.slice(2), target)
+      if (dir === null) return false
+      target.dirs.push(dir)
+    }
+  }
+  return true
+}
+
+/** Does this piece run our git invocation (possibly behind `env`/`command`/`builtin`/another wrapper)? */
+function runsInvocation(piece: readonly Token[], inv: Invocation & { kind: 'git' }): boolean {
+  const tokens = withoutRedirections(piece) // the classifier's `rest` has none either (`git commit -F - <<EOF`)
+  const values = tokens.map((token) => tokenValue(token))
+  const wanted = inv.rest.map((token) => tokenValue(token))
+  const tail = wanted.length === 0 ? values : values.slice(-wanted.length)
+  const gitAt = tokens.findIndex((token) => ['git', 'git.exe'].includes(basename(token)))
+  return gitAt >= 0 && values.indexOf(inv.subcommand, gitAt) > gitAt && tail.length === wanted.length && tail.every((value, index) => value === wanted[index])
+}
+
+/** Assignments reaching git from the piece: leading `NAME=v`, and `env NAME=v ...`. `null` when `env` carries options we do not model. */
+function pieceAssignments(tokens: readonly Token[]): string[] | null {
+  const { assignments, rest } = leadingAssignments(tokens)
+  let index = 0
+  while (index < rest.length && !['git', 'git.exe'].includes(basename(rest[index] as Token))) {
+    const name = basename(rest[index] as Token)
+    if (name === 'env') {
+      index++
+      while (index < rest.length && ASSIGNMENT_RE.test(tokenValue(rest[index] as Token))) assignments.push(tokenValue(rest[index++] as Token))
+      if (index < rest.length && tokenValue(rest[index] as Token).startsWith('-') && !['git', 'git.exe'].includes(basename(rest[index] as Token))) return null
+    } else if (name === 'command' || name === 'builtin') {
+      index++
+      while (index < rest.length && ['-p', '--'].includes(tokenValue(rest[index] as Token))) index++
+    } else {
+      index++ // another wrapper (nohup, time, ...): no environment of ours
+    }
+  }
+  return assignments
+}
+
+interface Parsed {
+  readonly tokens: readonly (readonly Token[] | null)[]
+  /** Text between consecutive pieces (operators, group characters, comments); `null` when the pieces could not be located in the source. */
+  readonly gaps: readonly string[] | null
+  /** Names of functions defined anywhere in the command (`f() {`, `function f`): a piece headed by one is unknown. */
+  readonly functions: ReadonlySet<string>
+}
+
+/** Heredoc delimiters opened by `<<` / `<<-` at the top level of one piece, or `'unparsable'`. Quotes, `\x` and `$(...)` are skipped. */
+function heredocDelimiters(piece: string): string[] | 'unparsable' {
+  const delimiters: string[] = []
+  for (let i = 0; i < piece.length; i++) {
+    const char = piece[i] as string
+    if (char === '\\') i++
+    else if (char === "'") {
+      const close = piece.indexOf("'", i + 1)
+      if (close < 0) return 'unparsable'
+      i = close
+    } else if (char === '"') {
+      let j = i + 1
+      while (j < piece.length && piece[j] !== '"') j += piece[j] === '\\' ? 2 : 1
+      if (j >= piece.length) return 'unparsable'
+      i = j
+    } else if (char === '`') {
+      const close = findMatchingBacktick(piece, i)
+      if (close < 0) return 'unparsable'
+      i = close
+    } else if (char === '$' && piece[i + 1] === '(') {
+      const close = findMatchingParen(piece, i + 1)
+      if (close < 0) return 'unparsable'
+      i = close
+    } else if (char === '<' && piece[i + 1] === '<' && piece[i + 2] !== '<' && piece[i - 1] !== '<') {
+      i += 2
+      if (piece[i] === '-') i++
+      while (piece[i] === ' ' || piece[i] === '\t') i++
+      let word = ''
+      let sawWord = false
+      for (; i < piece.length && !/[\s;|&<>()]/.test(piece[i] as string); i++) {
+        sawWord = true
+        const c = piece[i] as string
+        if (c === '\\') word += piece[++i] ?? ''
+        else if (c === "'" || c === '"') {
+          const close = piece.indexOf(c, i + 1)
+          if (close < 0) return 'unparsable'
+          word += piece.slice(i + 1, close)
+          i = close
+        } else word += c
+      }
+      if (!sawWord) return 'unparsable'
+      delimiters.push(word)
+      i--
+    }
+  }
+  return delimiters
+}
+
+/** `null`: unparseable (parse.uncertain refuses it). `'closed'`: a heredoc we cannot account for -- fail closed. */
+function parse(command: string): Parsed | null | 'closed' {
+  const split = splitShell(command)
+  if (split.invalid) return null
+  const tokens: (readonly Token[] | null)[] = split.pieces.map((piece) => {
+    const tokenized = tokenize(piece)
+    return tokenized.invalid ? null : tokenized.tokens
+  })
+  const functions = new Set<string>()
+  for (const match of command.matchAll(/([A-Za-z_][\w.:-]*)\s*\(\s*\)/g)) functions.add(match[1] as string)
+  for (const match of command.matchAll(/\bfunction\s+([A-Za-z_][\w.:-]*)/g)) functions.add(match[1] as string)
+  const gaps: string[] = []
+  let cursor = 0
+  for (const piece of split.pieces) {
+    const at = command.indexOf(piece, cursor)
+    if (at < 0) return { tokens, gaps: null, functions }
+    gaps.push(command.slice(cursor, at))
+    cursor = at + piece.length
+  }
+  // Heredoc body lines are not commands: drop them (docs/architecture/agent-git-branch-rules.md#resolver)
+  for (let i = 0; i < split.pieces.length; i++) {
+    const delimiters = heredocDelimiters(split.pieces[i] as string)
+    if (delimiters === 'unparsable') return 'closed'
+    if (delimiters.length === 0) continue
+    let body = i + 1
+    while (body < split.pieces.length && !(gaps[body] as string).includes('\n')) body++ // rest of the marker's own line
+    for (const delimiter of delimiters) {
+      let closed = false
+      for (; body < split.pieces.length && !closed; body++) {
+        closed = (split.pieces[body] as string).trim() === delimiter
+        tokens[body] = null
+        gaps[body] = '\n'
+      }
+      if (!closed) return 'closed'
+    }
+    i = body - 1
+  }
+  return { tokens, gaps, functions }
+}
+
+/** The gap as an operator when it is exactly `&&`, `;` or a newline; `null` for anything else (`||`, `|`, `&`, `(`, `{`, ...). */
+function plainGap(gap: string): '&&' | ';' | null {
+  const normalized = gap.replace(/#[^\n]*/g, '').replace(/\s*\n\s*/g, ';').replace(/\s+/g, '').replace(/;+/g, ';')
+  return normalized === '&&' ? '&&' : normalized === ';' || normalized === '' ? ';' : null
+}
+
+type StatePiece =
+  | { kind: 'cd'; dir: string }
+  | { kind: 'export'; assignments: string[] }
+  | { kind: 'unset'; names: string[] }
+  | { kind: 'bad' }
+  | { kind: 'neutral' }
+
+const NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/
+const SET_CLUSTER_RE = /^[-+][eux]*$/
+const SET_O_VALUES: readonly string[] = ['pipefail', 'errexit', 'nounset']
+
+/** `set` with only -e/-u/-x/+e/+u/+x (clusters allowed, `-euo pipefail`) and `-o|+o pipefail|errexit|nounset`. */
+function harmlessSet(args: readonly string[]): boolean {
+  if (args.length === 0) return false
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string
+    const cluster = /^([-+][eux]*)o$/.exec(arg)
+    if (cluster !== null || arg === '-o' || arg === '+o') {
+      if (!SET_O_VALUES.includes(args[++i] ?? '')) return false
+    } else if (!SET_CLUSTER_RE.test(arg) || arg.length < 2) {
+      return false
+    }
+  }
+  return true
+}
+
+function classify(piece: readonly Token[] | null, functions: ReadonlySet<string>): StatePiece {
+  if (piece === null) return { kind: 'neutral' }
+  const { assignments, rest } = leadingAssignments(withoutRedirections(piece))
+  const names = assignments.map((assignment) => assignment.split('=')[0] as string)
+  if (names.some((name) => name.startsWith('GIT_'))) return rest.length === 0 ? { kind: 'bad' } : classifyHead(rest, assignments, functions)
+  if (rest.length === 0) return names.some((name) => SENSITIVE_VARIABLES.has(name)) ? { kind: 'bad' } : { kind: 'neutral' }
+  return classifyHead(rest, assignments, functions)
+}
+
+function classifyHead(rest: readonly Token[], assignments: readonly string[], functions: ReadonlySet<string>): StatePiece {
+  const head = tokenValue(rest[0] as Token)
+  const args = rest.slice(1).map((token) => tokenValue(token))
+  if (/[$`]/.test(head) || functions.has(head)) return { kind: 'bad' }
+  if (!SHELL_BUILTINS_AND_KEYWORDS.has(head)) {
+    if (movesHead(rest)) return { kind: 'bad' }
+    // zsh autocd: a path (or a bare word naming a directory) used as a command changes directory.
+    if (head.includes('/') && !['git', 'git.exe'].includes(basename(rest[0] as Token))) return { kind: 'bad' }
+    if (head.startsWith('~') || head === '..' || (!head.includes('/') && namesDirectory(head))) return { kind: 'bad' }
+    // An external command cannot change this shell, but a shell it launches runs its startup files first.
+    const startup = assignments.some((assignment) => SHELL_STARTUP_VARIABLES.has(assignment.split('=')[0] as string))
+    return startup && (SHELLS.has(basename(rest[0] as Token)) || RE_EXECUTORS.has(basename(rest[0] as Token))) ? { kind: 'bad' } : { kind: 'neutral' }
+  }
+  if (READ_ONLY_BUILTINS.has(head)) return (head === 'printf' || head === 'print') && args.includes('-v') ? { kind: 'bad' } : { kind: 'neutral' }
+  if (head === 'command' && (args[0] === '-v' || args[0] === '-V')) return { kind: 'neutral' }
+  if (head === 'set') return harmlessSet(args) ? { kind: 'neutral' } : { kind: 'bad' }
+  if (head === 'cd' || head === 'pushd') return args.length !== 1 || args[0] === '' || (args[0] as string).startsWith('-') ? { kind: 'bad' } : { kind: 'cd', dir: args[0] as string }
+  if (head === 'export') {
+    if (args.length > 0 && args.every((arg) => /^GIT_(DIR|WORK_TREE)=/.test(arg))) return { kind: 'export', assignments: args }
+    return args.every((arg) => NAME_RE.test(arg.split('=')[0] as string) && !arg.startsWith('GIT_') && !SENSITIVE_VARIABLES.has(arg.split('=')[0] as string)) ? { kind: 'neutral' } : { kind: 'bad' }
+  }
+  if (head === 'unset') return args.every((arg) => NAME_RE.test(arg) && !SENSITIVE_VARIABLES.has(arg)) ? { kind: 'unset', names: args } : { kind: 'bad' }
+  return { kind: 'bad' }
+}
+
+// Credit or reject the pieces before `until`; fail closed on anything unknown. // See docs/architecture/agent-git-branch-rules.md#resolver
+function applyState(parsed: Parsed, until: number, target: Mutable): boolean {
+  for (let i = 0; i < until; i++) {
+    const state = classify(parsed.tokens[i] ?? null, parsed.functions)
+    if (state.kind === 'neutral') continue
+    if (state.kind === 'bad') return false
+    if (state.kind === 'unset') {
+      if (state.names.includes('GIT_DIR')) delete target.gitDir
+      if (state.names.includes('GIT_WORK_TREE')) delete target.workTree
+      continue
+    }
+    if (parsed.gaps === null) return false
+    const before = plainGap(parsed.gaps[i] as string)
+    if (before === null) return false
+    if (before === '&&' && (i === 0 || !['cd', 'export'].includes(classify(parsed.tokens[i - 1] ?? null, parsed.functions).kind))) return false
+    for (let j = i + 1; j <= Math.min(until, parsed.gaps.length - 1); j++) if (plainGap(parsed.gaps[j] as string) === null) return false
+    if (state.kind === 'cd') {
+      const dir = expandPath(state.dir, target)
+      if (dir === null) return false
+      target.dirs.push(dir)
+    } else if (!applyEnv(target, state.assignments)) {
+      return false
+    }
+  }
+  return true
+}
+
+// The `-c` script of a (re-executor-wrapped) shell piece, or 'unsafe' when a startup-file variable is set. // See docs/architecture/agent-git-branch-rules.md#resolver
+function shellScript(tokens: readonly Token[]): string | null | 'unsafe' {
+  const { rest } = leadingAssignments(tokens)
+  if (rest[0] === undefined) return null
+  let shellAt = 0
+  if (!SHELLS.has(basename(rest[0]))) {
+    if (!RE_EXECUTORS.has(basename(rest[0]))) return null
+    shellAt = rest.findIndex((token, index) => index > 0 && SHELLS.has(basename(token)))
+    if (shellAt < 0) return null
+  }
+  for (let index = shellAt + 1; index < rest.length - 1; index++) {
+    if (/^-[a-zA-Z]*c$/.test(tokenValue(rest[index] as Token))) {
+      const assignments = pieceAssignments(tokens)
+      return assignments === null || assignments.some((assignment) => SHELL_STARTUP_VARIABLES.has(assignment.split('=')[0] as string)) ? 'unsafe' : tokenValue(rest[index + 1] as Token)
+    }
+  }
+  return null
+}
+
+/** `undefined`: the invocation is not in `command`. `null`: it is, but its target is not static. */
+function walk(command: string, inv: Invocation & { kind: 'git' }, inherited: Mutable): BranchTarget | null | undefined {
+  const parsed = parse(command)
+  if (parsed === null) return undefined // unparseable: parse.uncertain's job to refuse
+  if (parsed === 'closed') return null
+  for (let i = 0; i < parsed.tokens.length; i++) {
+    const tokens = parsed.tokens[i]
+    if (tokens === null || tokens === undefined) continue
+    const target: Mutable = { ...inherited, dirs: [...inherited.dirs] }
+    if (runsInvocation(tokens, inv)) {
+      const assignments = pieceAssignments(tokens)
+      if (assignments === null || !applyState(parsed, i, target)) return null
+      if (assignments.some((assignment) => assignment.startsWith('HOME='))) target.homeUnknown = true
+      if (!applyEnv(target, assignments) || !applyGlobals(target, inv.globals)) return null
+      return target
+    }
+    const script = shellScript(tokens)
+    if (script === null) continue
+    if (script === 'unsafe') {
+      // The startup file may do anything, but only matters when our git is in there.
+      const unsafeInner = tokens.some((token) => tokenValue(token).includes(inv.subcommand))
+      if (unsafeInner) return null
+      continue
+    }
+    const probe: Mutable = { ...inherited, dirs: [...inherited.dirs] }
+    const inner = walk(script, inv, probe)
+    if (inner === undefined) continue
+    if (inner === null || !applyState(parsed, i, target)) return null
+    const nested = walk(script, inv, target)
+    return nested ?? null
+  }
+  return undefined
+}
+
+/** The statically resolved target of `inv` inside `command`, or `null` when it cannot be resolved. */
+export function resolveGitTarget(inv: Invocation & { kind: 'git' }, command: string | undefined): BranchTarget | null {
+  const found = command === undefined ? undefined : walk(command, inv, { dirs: [] })
+  if (found !== undefined) return found
+  // Not found as a piece (xargs, find -exec, ...): its own globals, after any unconditional cd/export before it.
+  const target: Mutable = { dirs: [] }
+  const parsed = command === undefined ? null : parse(command)
+  if (parsed === 'closed' || (parsed !== null && !applyState(parsed, parsed.tokens.length, target))) return null
+  return applyGlobals(target, inv.globals) ? target : null
+}

package/packages/agent-hooks/src/rules/ports.ts

@@ -45,6 +45,14 @@ export interface AgentPort {
  * `git.protected-tree-commit` can fail closed on "could not read the index"
  * instead of silently treating an unreadable index as a clean one.
  */
+/** Where a git invocation points, statically resolved from its command line (see `impl/git-target.ts`). */
+export interface BranchTarget {
+  /** `cd <dir>` and `git -C <dir>` values, in the order git applies them. */
+  readonly dirs: readonly string[]
+  readonly gitDir?: string
+  readonly workTree?: string
+}
+
 export interface RepoIndexPort {
   stagedPaths(): readonly string[] | null
   trackedModifiedPaths(): readonly string[] | null
@@ -64,6 +72,14 @@ export interface RepoIndexPort {
    * absent) the same as `null` (present, resolved to nothing).
    */
   configuredAlias?(verb: string): string | null
+  /**
+   * The checked-out branch of the repo a git invocation targets: the hook's
+   * root with `target.dirs` applied as `-C <dir>` values in order (relative
+   * ones composed), then `--git-dir` / `--work-tree` when given. `''` for a detached HEAD, `null` when it cannot be read (not a
+   * repository, git missing, timeout) so `git.commit-protected-branch` can
+   * fail closed instead of treating an unreadable HEAD as a safe one.
+   */
+  currentBranch(target: BranchTarget): string | null
 }
 
 export const liveEnv: EnvPort = {
@@ -159,6 +175,26 @@ export function liveRepoIndex(root: string): RepoIndexPort {
       }
     },
     resolveRemoteUrl: rewriteUrl,
+    currentBranch: (target) => {
+      try {
+        const out = execFileSync('git', [
+          '-C',
+          root,
+          ...target.dirs.flatMap((dir) => ['-C', dir]),
+          ...(target.gitDir === undefined ? [] : ['--git-dir', target.gitDir]),
+          ...(target.workTree === undefined ? [] : ['--work-tree', target.workTree]),
+          'branch',
+          '--show-current',
+        ], {
+          encoding: 'utf8',
+          timeout: 10_000,
+          stdio: ['ignore', 'pipe', 'ignore'],
+        })
+        return out.replace(/\n+$/, '')
+      } catch {
+        return null
+      }
+    },
     configuredAlias: (verb) => {
       try {
         const out = execFileSync('git', ['-C', root, 'config', '--get', `alias.${verb}`], {

package/packages/agent-hooks/src/rules/registry.ts

@@ -29,11 +29,11 @@ import { gitStash, gitClean, gitRebase, gitFilterBranch, gitRestore, gitReset, g
 import { gitNoVerify, gitAmend } from './impl/git-verify.ts'
 import { gitProtectedTreeCommit } from './impl/git-protected-tree.ts'
 import {
-  gitBranchForceDelete,
   gitTagDelete,
   gitSwitchForce,
   gitGcPrune,
 } from './impl/git-history.ts'
+import { gitBranchMutation, gitCommitProtectedBranch } from './impl/git-branch.ts'
 import {
   gitUpdateRef,
   gitSymbolicRefWrite,
@@ -95,7 +95,8 @@ export const GIT_RULES: readonly AnyRuleSpec[] = [
   gitNoVerify,
   gitAmend,
   gitProtectedTreeCommit,
-  gitBranchForceDelete,
+  gitBranchMutation,
+  gitCommitProtectedBranch,
   gitTagDelete,
   gitSwitchForce,
   gitWorktree,

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

@@ -6,6 +6,11 @@ repo's own `AGENTS.md`.
 ## Communication
 - Address me as **Tarun**.
 - Short, scannable **bullet points** — not long prose. Lead with the answer; keep reasoning tight.
+- **Every reply has three parts, in this order:**
+  - a **TL;DR** of a few lines; information stays brief, and detail is given only when asked;
+  - an explicit **Recommendation**: what you would do and why, in one line;
+  - **one ask**: the single question or decision you need next.
+- **Keep a numbered list of open points** and show it when it changes. I answer them one at a time, so never bundle several questions into one reply.
 - If a task is ambiguous, ask exactly one clarifying question.
 
 ## Truthfulness (non-negotiable)
@@ -64,7 +69,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/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/repo-controls/AGENTS.md

@@ -51,7 +51,7 @@ written) and the `core.hooksPath` setting are what `install --repo` wires in
 **target** repos.
 
 **Rule values are defaults, not universals.** The bundled defaults are enact-m5's:
-branch prefixes `feat|fix|docs|chore`, protected `main` and `integration`,
+branch prefixes fixed to the commit types minus `release` (`packages/azdo/src/lib/commit-types.ts`), protected `main` and `integration`,
 lowercase kebab-case descriptions, lowercase commit subject with an 80-character
 limit and a fixed type list, plus the coverage ratchet and the behind-origin push
 check. Per-repo values are config-driven, in `adl-config.toml`'s `[controls]`

package/packages/repo-controls/README.md

@@ -384,7 +384,7 @@ gate is switched off by an explicit `false`. See "No silent skips" below.
 | Key | Seeded by install | When absent | enact-m5 | Effect |
 |---|---|---|---|---|
 | `branches.protected` | yes | *required* | `["main", "integration"]` | pre-push refuses while on these branches |
-| `branches.prefixes` | yes | *required* | `["feat", "fix", "docs", "chore"]` | pre-push / azdo-push branch pattern `<prefix>/<kebab>` |
+| `branches.prefixes` | removed | a config error naming the key | n/a | not configurable: branch prefixes are the commit types minus `release` (`packages/azdo/src/lib/commit-types.ts`); pre-push / azdo-push enforce `<prefix>/<kebab>`; delete the key |
 | `pre_push.remote` | yes | *required* | `"origin"` | remote azdo-push pushes to and reads status from |
 | `pre_commit.staged_coverage` | yes (`true`) | config error | `true` | enact-m5-only staged coverage measurement (fails when `[controls.coverage].produce` is not declared) |
 | `pre_commit.doc_freshness` | yes (`true`) | config error | opt in | a staged `docs/` or `plans/` `.md` carries a `last_update` stamped within 5h (nothing to grade when no docs are staged) |
@@ -633,7 +633,7 @@ the repository, and any of their files with consecutive comment lines fail REP-0
 result.
 
 Fixed conventions (enact-m5, not configurable): commit subject
-`^(feat|fix|docs|refactor|perf|chore|release)(\([a-z0-9][a-z0-9-]*\))?: .+`, at most 80
+`^(<commit type>)(\([a-z0-9][a-z0-9-]*\))?: .+` (types `feat|fix|docs|refactor|perf|chore|release`, defined once in `packages/azdo/src/lib/commit-types.ts` and handed to the hook as `ADL_REPO_CONTROLS_COMMIT_TYPES`; `release` is the pipeline's only), at most 80
 characters, lowercase description without trailing period; `Merge `, `Revert "`
 and `X.Y.Z` subjects exempt; no staged `.scratchpad` paths or new references;
 `git diff --cached --check`; git environment scrubbed before push checks.
@@ -650,16 +650,16 @@ The pre-commit gate has two deliberately different outcomes:
 - A changed or untracked **top-level** dot path is **commit-required**.
   When it is omitted from the index, the hook names it and tells the author to
   stage it. Once staged, it can be committed normally. This covers top-level dot
-  paths that are not protected, such as `.mcp.json` and future ones. Nested paths such as
+  paths that are not protected, such as `.mcp.json`, `.workflows/` and the agent surface roots
+  (`.agents/`, `.claude/`, `.codex/`, `.cursor/`, `.kimi-code/`, `.opencode/`): those hold a
+  repository's own hooks and skills, so they are not protected as a whole (Bug 644). Nested paths such as
   `tools/.claude/**` are ordinary repository content. The designated ephemeral
   scratch storage is never committable.
 - A **protected control** requires human approval even when staged: every path
-  under `compliance/`, `workflows/`, `.workflows/` or an agent surface root
-  (`.agents/`, `.claude/`, `.codex/`, `.cursor/`, `.kimi-code/`, `.opencode/`),
-  `adl-config.toml`, the folder declared as `[controls.compliance.trees].compliance`
+  under `compliance/` or `workflows/`, `adl-config.toml`, the folder declared as `[controls.compliance.trees].compliance`
   (in addition to the fixed `compliance/` root, so a relocated register folder stays
   protected: `integrityWatched` in `src/hook.ts`), and the repository's explicit
-  `[controls.integrity].watched` patterns (`FIXED_ROOTS` and `WIRING` in `src/integrity.ts`). The full definition and the
+  `[controls.integrity].watched` patterns (`PROTECTED_ROOTS` and `WIRING` in `src/integrity.ts`). A repository protects any dot path it chooses through `watched`. The full definition and the
   owner override: [`#protected-paths-and-owner-override`](../../docs/architecture/compliance-controls.md#protected-paths-and-owner-override). The same controls cannot be
   left dirty while committing other work.
 

package/packages/repo-controls/scripts/hooks/commit-msg

@@ -2,7 +2,7 @@
 # Enforce the conventional commit subject contract.
 set -euo pipefail
 
-ALLOWED_TYPES='feat|fix|docs|refactor|perf|chore|release'
+ALLOWED_TYPES="${ADL_REPO_CONTROLS_COMMIT_TYPES:?}"
 ALLOWED_TYPES_DISPLAY="${ALLOWED_TYPES//|/, }"
 FORMAT_RE="^(${ALLOWED_TYPES})"'(\([a-z0-9][a-z0-9-]*\))?: .+'
 TYPE_RE='^([A-Za-z0-9]+)(\(|:)'

package/packages/repo-controls/src/config.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { BRANCH_PREFIXES, COMMIT_TYPES } from '../../azdo/src/lib/commit-types.ts'
 import { CONFIG_REL, INSTALL_HINT } from './constants.ts'
 import { MERGE_STRATEGIES, type MergeStrategy } from './promote.ts'
 
@@ -76,7 +77,7 @@ export interface FindingsConfig {
 }
 
 export interface RepoControlsConfig {
-  branches: { protected: string[]; prefixes: string[] }
+  branches: { protected: string[] }
   preCommit: { staticChecks: StaticCheck[]; stagedCoverage: boolean; docFreshness: boolean; compliance: boolean }
   commitMsg: { staticChecks: StaticCheck[] }
   release: { optedOut: boolean; source: string; target: string; mergeStrategy: MergeStrategy; preBump: string[] }
@@ -111,8 +112,8 @@ export const SEEDED_ATTRIBUTES: SeededAttribute[] = [
   {
     key: 'branches',
     text: `
-# pre-push refuses to push while one of these branches is checked out; prefixes: <prefix>/<kebab>.
-branches = { protected = ["main", "integration"], prefixes = ["feat", "fix", "docs", "chore"] }
+# pre-push refuses to push while one of these branches is checked out; branch prefixes are fixed to the commit types.
+branches = { protected = ["main", "integration"] }
 `,
   },
   {
@@ -340,7 +341,6 @@ export function extractControlsSpan(text: string): string | null {
 }
 
 const BRANCH_RE = /^[a-z0-9][a-z0-9/-]*$/
-const PREFIX_RE = /^[a-z0-9][a-z0-9-]*$/
 const LABEL_RE = /^[a-z0-9][a-z0-9-]*$/
 const REMOTE_RE = /^\S+$/
 
@@ -487,6 +487,7 @@ export function parseConfig(text: string): RepoControlsConfig {
   problems.unknownKeys(controls, ['branches', 'pre_commit', 'pre_push', 'commit_msg', 'post_commit', 'compliance', 'coverage', 'findings', 'integrity', 'release'], '')
 
   const branches = problems.table(controls, 'branches', ['protected', 'prefixes'])
+  if (branches.prefixes !== undefined) problems.add('branches.prefixes is no longer configurable — delete it; branch prefixes are fixed to the commit types')
   // `branches` and `pre_push.remote` are REQUIRED: install always seeds them, and
   // `pre-push` reads their env vars with `${VAR:?}`, which aborts on an empty value —
   // so "no branch policy" cannot be spelled as an empty list.
@@ -539,7 +540,6 @@ export function parseConfig(text: string): RepoControlsConfig {
   const config: RepoControlsConfig = {
     branches: {
       protected: problems.names(branches, 'protected', 'branches.protected', BRANCH_RE),
-      prefixes: problems.names(branches, 'prefixes', 'branches.prefixes', PREFIX_RE),
     },
     preCommit: {
       // The repository declares WHAT runs at commit and WHICH hook it runs in.
@@ -747,7 +747,8 @@ export function configEnv(repo: string, config: RepoControlsConfig): Record<stri
   const env: Record<string, string> = {
     ADL_REPO_CONTROLS_ROOT: repo,
     ADL_REPO_CONTROLS_PROTECTED_BRANCHES: config.branches.protected.join('|'),
-    ADL_REPO_CONTROLS_BRANCH_PREFIXES: config.branches.prefixes.join('|'),
+    ADL_REPO_CONTROLS_BRANCH_PREFIXES: BRANCH_PREFIXES.join('|'),
+    ADL_REPO_CONTROLS_COMMIT_TYPES: COMMIT_TYPES.join('|'),
     ADL_REPO_CONTROLS_COVERAGE_RATCHET: config.prePush.coverageRatchet ? '1' : '0',
     ADL_REPO_CONTROLS_FINDINGS_RATCHET: config.prePush.findingsRatchet ? '1' : '0',
     ADL_REPO_CONTROLS_EXPORT_LINKS: config.prePush.exportLinks.join('\n'),

package/packages/repo-controls/src/integrity.ts

@@ -9,21 +9,8 @@
 
 const WIRING: readonly string[] = ['adl-config.toml']
 
-// Tarun, 2026-09-30: `.workflows/` and every agent surface root are protected
-// like `workflows/` — a dirty path under any of them blocks a normal commit and
-// only Tarun lands it. They were "centrally managed dotfiles" an agent could
-// commit alongside a related change; that let an agent land gate-defining files.
-const FIXED_ROOTS: readonly string[] = [
-  'compliance',
-  'workflows',
-  '.workflows',
-  '.agents',
-  '.claude',
-  '.codex',
-  '.cursor',
-  '.kimi-code',
-  '.opencode',
-]
+// Only these folders are protected as a whole; dot folders hold a repository's own hooks and skills (Bug 644).
+const PROTECTED_ROOTS: readonly string[] = ['compliance', 'workflows']
 
 /** A declared pattern, as a regex. `*` stays in one directory; `**` crosses them. */
 function patternToRegExp(pattern: string): RegExp {
@@ -59,18 +46,18 @@ function protectedMatchers(watched: readonly string[]): ((path: string) => boole
   return [...wiring, ...declared]
 }
 
-const isUnderFixedRoot = (path: string): boolean => FIXED_ROOTS.some((root) => path === root || path.startsWith(`${root}/`))
+const isUnderProtectedRoot = (path: string): boolean => PROTECTED_ROOTS.some((root) => path === root || path.startsWith(`${root}/`))
 
 /** Centrally managed repository files that must travel with the next commit. */
 const isTopLevelDotPath = (path: string): boolean => path.startsWith('.')
 
 /**
  * The single source of truth used for final-index and dirty-worktree checks.
- * Fixed package policy protects root compliance/workflows and the enrollment
+ * Package policy protects root compliance/workflows and the enrollment
  * file; each repository adds its own gate files through `watched`.
  */
 export function isProtectedPath(path: string, watched: readonly string[]): boolean {
-  return isUnderFixedRoot(path) || protectedMatchers(watched).some((match) => match(path))
+  return isUnderProtectedRoot(path) || protectedMatchers(watched).some((match) => match(path))
 }
 
 /**