@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.4

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

@@ -0,0 +1,180 @@
+/**
+ * Shell tokens.
+ *
+ * Ported from `.agents/hooks/pre-tool-use/utils/shell-parser.mjs:10-64`. A
+ * token remembers whether it was quoted (`quoted`), because several rules
+ * downstream need to tell a literal argument from one built by the shell —
+ * `dynamicToken` and `isTrustedRepoScript` both consult the token's raw value,
+ * not its post-quote-removal one, since a quoted `$(...)` is still dynamic.
+ */
+
+import { findMatchingBacktick, findMatchingParen } from './substitution.ts'
+
+/**
+ * A redirection operator: POSIX XCU 2.10.2 (`<`, `>`, `>>`, `>|`, `<>`, `<<`,
+ * `<<-`, `<&`, `>&`) plus bash's `<<<`, `&>`, `&>>`.
+ */
+export type RedirectOperator = '<' | '>' | '>>' | '>|' | '<>' | '<<' | '<<-' | '<<<' | '<&' | '>&' | '&>' | '&>>'
+
+export interface Token {
+  /** For a redirection, the IO_NUMBER (if any) followed by the operator, e.g. `2>&`. */
+  readonly value: string
+  readonly quoted: boolean
+  /** Set only on an unquoted redirection operator; its word is the NEXT token. */
+  readonly redirect?: RedirectOperator
+}
+
+export function tokenValue(token: Token): string {
+  return token.value
+}
+
+/** Lower-cased final path segment, for matching a command name regardless of directory or case. */
+export function basename(token: Token): string {
+  const segments = tokenValue(token).split(/[/\\]/)
+  return (segments[segments.length - 1] ?? '').toLowerCase()
+}
+
+/** Longest first, so maximal munch picks `&>>` over `&>` and `<<-` over `<<`. */
+const OPERATORS: readonly RedirectOperator[] = ['&>>', '<<<', '<<-', '&>', '>>', '>|', '>&', '<<', '<>', '<&', '<', '>']
+
+function operatorAt(piece: string, index: number): RedirectOperator | null {
+  const char = piece[index]
+  if (char !== '<' && char !== '>' && char !== '&') return null
+  // `<(`/`>(` open a process substitution, which is a word, not a redirection.
+  if (char !== '&' && piece[index + 1] === '(') return null
+  return OPERATORS.find((op) => piece.startsWith(op, index)) ?? null
+}
+
+/** End index (inclusive) of a `$(...)`, `${...}`, backtick or `<(...)`/`>(...)` starting at `index`, or null. */
+function expansionEnd(piece: string, index: number): number | null {
+  const char = piece[index]
+  const next = piece[index + 1]
+  if ((char === '$' || char === '<' || char === '>') && next === '(') {
+    const close = findMatchingParen(piece, index + 1)
+    return close < 0 ? piece.length - 1 : close
+  }
+  if (char === '$' && next === '{') {
+    const close = piece.indexOf('}', index + 2)
+    return close < 0 ? piece.length - 1 : close
+  }
+  if (char === '`') {
+    const close = findMatchingBacktick(piece, index)
+    return close < 0 ? piece.length - 1 : close
+  }
+  return null
+}
+
+export interface TokenizeResult {
+  readonly tokens: readonly Token[]
+  readonly invalid: boolean
+}
+
+/**
+ * Split one shell piece (already split at `;`/`|`/`&`/newline by split.ts)
+ * into words and redirection operators, honouring quotes, backslash escapes,
+ * and expansions. Operators need no surrounding whitespace (`x>.git/HEAD`);
+ * an unquoted all-digit word directly before `<`/`>` is its IO_NUMBER and is
+ * folded into the operator token (`2>`, `2>&`).
+ */
+export function tokenize(piece: string): TokenizeResult {
+  const text = piece.trim()
+  if (!text) return { tokens: [], invalid: false }
+  const tokens: Token[] = []
+  let current = ''
+  let quoted = false
+  let quote: '"' | "'" | null = null
+  const flush = (): void => {
+    // An empty word (`''`) is dropped, as it always was: see git-internals.ts's `sed -i ''`.
+    if (current) tokens.push({ value: current, quoted })
+    current = ''
+    quoted = false
+  }
+
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index] as string
+    if (quote === "'") {
+      if (char === "'") quote = null
+      else current += char
+      continue
+    }
+    if (char === '\\') {
+      if (index + 1 >= text.length) return { tokens, invalid: true }
+      current += text[index + 1]
+      index += 1
+      quoted = true
+      continue
+    }
+    const end = quote === '"' && char !== '$' && char !== '`' ? null : expansionEnd(text, index)
+    if (end !== null) {
+      current += text.slice(index, end + 1)
+      index = end
+      continue
+    }
+    if (quote === '"') {
+      if (char === '"') quote = null
+      else current += char
+      continue
+    }
+    if (char === "'" || char === '"') {
+      quote = char
+      quoted = true
+      continue
+    }
+    if (/\s/.test(char)) {
+      flush()
+      continue
+    }
+    const op = operatorAt(text, index)
+    if (op !== null) {
+      const ioNumber = !quoted && op[0] !== '&' && /^\d+$/.test(current) ? current : ''
+      if (ioNumber) current = ''
+      else flush()
+      tokens.push({ value: ioNumber + op, quoted: false, redirect: op })
+      index += op.length - 1
+      continue
+    }
+    current += char
+  }
+  if (quote) return { tokens, invalid: true }
+  flush()
+  return { tokens, invalid: false }
+}
+
+export function isAssignment(token: Token): boolean {
+  return /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokenValue(token))
+}
+
+export function isRedirection(token: Token): boolean {
+  return token.redirect !== undefined
+}
+
+/**
+ * Whether redirection `op` with word `target` opens a file for writing.
+ * `>&`/`<&` with a digit or `-` word duplicate/close a descriptor; bash's
+ * `>& word` with any other word is `&> word`, a write.
+ */
+export function redirectionWrites(op: RedirectOperator, target: string): boolean {
+  if (op === '>&') return !/^(?:\d+|-)$/.test(target)
+  return op === '>' || op === '>>' || op === '>|' || op === '<>' || op === '&>' || op === '&>>'
+}
+
+/** Every redirection operator takes exactly one word (a path, fd, delimiter or here-string). */
+export function skipRedirections(tokens: readonly Token[], start: number): number {
+  let index = start
+  while (index < tokens.length && isRedirection(tokens[index] as Token)) index += 2
+  return Math.min(index, tokens.length)
+}
+
+export function dynamicToken(token: Token): boolean {
+  const value = tokenValue(token)
+  return value.includes('$') || value.includes('`') || /[*?]/.test(value)
+}
+
+/** A repo script an agent may execute without inspection: not dynamic, not absolute, not `..`-escaping. */
+export function isTrustedRepoScript(token: Token, trustedPrefixes: readonly string[]): boolean {
+  if (dynamicToken(token)) return false
+  const value = tokenValue(token)
+  const normalized = value.startsWith('./') ? value.slice(2) : value
+  if (normalized.startsWith('/') || normalized.includes('..')) return false
+  return trustedPrefixes.some((prefix) => normalized.startsWith(prefix) && normalized.length > prefix.length)
+}

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

@@ -0,0 +1,81 @@
+/**
+ * `xargs` payload walking.
+ *
+ * Ported from `.agents/hooks/pre-tool-use/utils/shell-parser.mjs:475-503`.
+ * `xargs rm -rf` must be classified by what it runs, not by `xargs` itself —
+ * so this walks past `xargs`'s own options (bailing out, fail-closed, on any
+ * option shape it does not recognise or that carries a `$`/backtick/glob)
+ * until it finds the wrapped command and hands the remaining tokens to the
+ * caller's `walk`.
+ */
+
+import { dynamicToken, type Token, tokenValue } from './token.ts'
+import type { Invocation } from './invocation.ts'
+
+export const XARGS_OPTIONS_WITH_VALUE = new Set([
+  '-a',
+  '--arg-file',
+  '-d',
+  '--delimiter',
+  '-E',
+  '--eof',
+  '-I',
+  '--replace',
+  '-J',
+  '-L',
+  '--max-lines',
+  '-n',
+  '--max-args',
+  '-P',
+  '--max-procs',
+  '-s',
+  '--max-chars',
+])
+export const XARGS_FLAG_OPTIONS = new Set([
+  '-0',
+  '--null',
+  '-r',
+  '--no-run-if-empty',
+  '-t',
+  '--verbose',
+  '-p',
+  '--interactive',
+  '--show-limits',
+])
+
+export function uncertain(reason: string): readonly Invocation[] {
+  return [{ kind: 'uncertain', reason }]
+}
+
+type ReadOptionResult = { readonly done: true; readonly index: number } | { readonly error: string } | { readonly index: number }
+
+function readOptionWithValue(args: readonly Token[], value: string, index: number): ReadOptionResult | null {
+  if (!XARGS_OPTIONS_WITH_VALUE.has(value)) return null
+  return index + 1 >= args.length ? { error: 'incomplete xargs option' } : { index: index + 2 }
+}
+
+function readOption(args: readonly Token[], index: number): ReadOptionResult {
+  const value = tokenValue(args[index] as Token)
+  if (value === '--' || !value.startsWith('-')) return { done: true, index }
+  if (dynamicToken(args[index] as Token)) return { error: 'dynamic xargs execution' }
+  const withValue = readOptionWithValue(args, value, index)
+  if (withValue) return withValue
+  const attached = /^(-[a-zA-Z])(.+)$/.exec(value)
+  if (attached && attached[1] && XARGS_OPTIONS_WITH_VALUE.has(attached[1])) return { index: index + 1 }
+  if (XARGS_OPTIONS_WITH_VALUE.has(value.split('=', 1)[0] as string) || value.includes('=')) return { index: index + 1 }
+  return XARGS_FLAG_OPTIONS.has(value) ? { index: index + 1 } : { error: 'unparsed xargs option' }
+}
+
+/** Skip xargs's own options and hand the remaining argv to `walk`. */
+export function xargsInvocation(args: readonly Token[], walk: (tokens: readonly Token[]) => readonly Invocation[]): readonly Invocation[] {
+  let index = 0
+  while (index < args.length) {
+    const result = readOption(args, index)
+    if ('error' in result) return uncertain(result.error)
+    index = result.index
+    if ('done' in result) break
+  }
+  if (index >= args.length) return []
+  if (dynamicToken(args[index] as Token)) return uncertain('dynamic xargs execution')
+  return walk(args.slice(index))
+}

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

@@ -0,0 +1,152 @@
+/**
+ * The rule interface.
+ *
+ * Ported from enact-repo-controls's `src/rules/spec.ts`. This is the seam
+ * that replaces three files the old (pre-`controls`) tree had to edit in
+ * lockstep to add one rule: a Set in `constants.mjs`, a branch in
+ * `walk.mjs` or a predicate in `git-rules.mjs`, a case in `classifyReason`
+ * **and** matching cases in both `userMessageFor` and `agentMessageFor` in
+ * `deny.mjs`, plus corpus strings in `tests/self-test.mjs`. Missing one arm
+ * there produced a plausible but wrong message with no type error to catch
+ * it. Here `match` returns a structured `Finding` — no round trip through a
+ * string — and `message` is colocated with the `match` that produced its
+ * `Finding`, so a rule with no message literally does not compile.
+ *
+ * HARDCUT from the reference: `RuleId`/`RuleCategory`/`ParamCodec`/`noParams`
+ * are defined here directly instead of re-exported from a shared
+ * `kernel/config/` layer — adl hook has no config-decoding config layer
+ * beyond `../gating/config.ts`, which is where `RepoSection` (`ctx.repo`
+ * below) actually comes from. `EnvPort`/`RepoIndexPort` come from
+ * `./ports.ts`, itself a narrowed port set (see that file's header).
+ */
+
+import type { AgentSection, RepoSection } from '../gating/config.ts'
+import type { AgentPort, EnvPort, RepoIndexPort } from './ports.ts'
+import type { Invocation } from './shell/invocation.ts'
+
+export type RuleId = string
+export type Severity = 'deny' | 'advise'
+
+/**
+ * Rule categories, canonical. `uncertain` is the category for rules that
+ * fire when the shell parser cannot understand a command — `isRuleEnabled`
+ * (`../gating/config.ts`) treats it specially, refusing to let it resolve to
+ * disabled without `rules.unsafeAllowUncertain` set.
+ */
+export type RuleCategory = 'git' | 'filesystem' | 'tool' | 'tool-call' | 'uncertain' | 'advisory'
+
+export interface ParamDecodeIssue {
+  readonly pointer: string
+  readonly message: string
+}
+
+/**
+ * A parameter decoder. Every built-in rule in this package uses `noParams`
+ * (none of the ported rules take configurable parameters); the interface is
+ * kept general so a future rule with real parameters has a documented shape
+ * to decode into, matching the reference's own `ParamCodec`.
+ */
+export interface ParamCodec<T> {
+  decode(
+    raw: Readonly<Record<string, unknown>>,
+    pointer: string,
+  ): { readonly ok: true; readonly value: T } | { readonly ok: false; readonly issue: ParamDecodeIssue }
+}
+
+/** The codec for a spec that takes no parameters. */
+export const noParams: ParamCodec<Record<string, never>> = {
+  decode: () => ({ ok: true, value: {} }),
+}
+
+/** What a rule needs beyond the Invocation it is matching against. */
+export interface RuleContext<P> {
+  readonly params: P
+  readonly repo: RepoSection
+  /** Real git, not a boolean — see `./ports.ts`'s `RepoIndexPort` doc. */
+  readonly index: RepoIndexPort
+  /** For `fs.trash`'s `$HOME` check — an ambient global there, an argument here. */
+  readonly env: EnvPort
+  /**
+   * The agent identity that produced this call (`agent_type`, `agent_id` from
+   * the host payload). H2 rules 2 and 3 read this; every other rule ignores
+   * it. Defaulted to `noAgent` (no identity) for non-host callers — operator
+   * CLI, unit tests that don't care — and for the main session itself, which
+   * is the case the handoff treats as "uses any vault → deny".
+   */
+  readonly agent: AgentPort
+  /**
+   * Per-repo agent config from `[agent]` in `adl-config.toml`. H2 rules
+   * 2 and 3 read this for the declared user and the protected branches;
+   * every other rule ignores it. Defaults to the schema defaults (no user,
+   * `["main", "integration"]` protected branches) so callers that pass no
+   * `[agent]` section still get the safe default.
+   */
+  readonly agentConfig: AgentSection
+  /**
+   * The raw command line being decided (for a tool-call input, a synthetic
+   * `tool + JSON` description). The engine always supplies it; it is optional
+   * only so tests that call `match()` directly with a hand-built context keep
+   * compiling. Rules that match per-Invocation see the classified view;
+   * `adl.git-identity` needs the raw text — the leading environment
+   * assignments ahead of `git` are not part of a `'git'` Invocation, so a
+   * conflicting inline `ADL_AGENT_ID_AGENT=…` is only visible here.
+   */
+  readonly command?: string
+  /**
+   * The repository root the hook is running against (`HookInvocation.root`
+   * in `../pre-tool-use/handler.ts`, threaded through `EngineContext`).
+   * `tool.lean-ctx-global-state` needs a REAL filesystem path to resolve
+   * `[hooks] lean_ctx_dir` (`../lean-ctx/env.ts`'s `resolveLeanCtxDir`) and to
+   * compare an absolute `LEAN_CTX_CONFIG_DIR=` value against `<repo
+   * root>/<suffix>`; every other rule ignores it. Optional so a hand-built
+   * `RuleContext` in a test that predates this field, or a non-host caller
+   * with no known root, keeps compiling — absent or empty means "no real
+   * root available," which the lean-ctx rule treats as "only the
+   * root-independent path forms can match."
+   */
+  readonly root?: string
+}
+
+/** The structured outcome of a match — no prose, no reparsing. */
+export interface Finding {
+  readonly ruleId: RuleId
+  readonly severity: Severity
+  readonly detail: Readonly<Record<string, string | readonly string[]>>
+}
+
+export interface MessageContext {
+  /** The raw command line (or a synthetic description for a tool-call), for logging. */
+  readonly command: string
+  /** Whitespace-collapsed and length-capped, as shown to the user/agent. */
+  readonly snippet: string
+}
+
+export interface RuleMessage {
+  readonly user: string
+  readonly agent: string
+}
+
+export interface RuleSpec<P = Record<string, never>> {
+  readonly id: RuleId
+  readonly category: RuleCategory
+  readonly severity: Severity
+  readonly enabledByDefault: boolean
+  readonly summary: string
+  readonly params: ParamCodec<P>
+  match(inv: Invocation, ctx: RuleContext<P>): Finding | null
+  message(finding: Finding, ctx: MessageContext): RuleMessage
+  /** Required. See registry.ts's `registerAll` — a rule with no corpus fails to register. */
+  readonly corpus: { readonly deny: readonly string[]; readonly allow: readonly string[] }
+}
+
+/** Type-erased view used by the registry and engine, which hold rules of many different `P`s together. */
+export type AnyRuleSpec = RuleSpec<Record<string, unknown>>
+
+export function asAnyRuleSpec<P>(spec: RuleSpec<P>): AnyRuleSpec {
+  return spec as unknown as AnyRuleSpec
+}
+
+/** A corpus with nothing in it proves nothing. Used by registry.ts's registration check. */
+export function corpusIsEmpty(spec: RuleSpec<never> | AnyRuleSpec): boolean {
+  return spec.corpus.deny.length === 0 && spec.corpus.allow.length === 0
+}

package/packages/agent-hooks/src/surface-policy.ts

@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs'
+
+interface SurfacePolicy {
+  readonly deny: {
+    readonly paths: readonly string[]
+    readonly nativeTools: readonly string[]
+  }
+}
+
+// Hard cut, matching the marker rename: `packages/agent-settings/src/surface-policy.ts`
+// (the installer) now writes this file at `/etc/adl/surface-policy.json`
+// (confirmed 2026-09-27) — no fallback read of the old `/etc/enact/` path.
+let policyPath = process.env.ADL_HOOK_POLICY_PATH || '/etc/adl/surface-policy.json'
+let cached: SurfacePolicy | undefined
+
+/** Test-only seam. The production entry point has no policy-path flag. */
+export function setSurfacePolicyPathForTests(path: string): void {
+  policyPath = path
+  cached = undefined
+}
+
+export function loadSurfacePolicy(): SurfacePolicy {
+  if (cached) return cached
+  let raw: unknown
+  try {
+    raw = JSON.parse(readFileSync(policyPath, 'utf8'))
+  } catch (error) {
+    throw new Error(`adl hook: failed to load required surface policy ${policyPath}: ${String(error)}`)
+  }
+  const deny = (raw as { deny?: unknown }).deny
+  if (!deny || typeof deny !== 'object' || !Array.isArray((deny as { paths?: unknown }).paths)
+    || !Array.isArray((deny as { nativeTools?: unknown }).nativeTools)) {
+    throw new Error(`adl hook: invalid required surface policy ${policyPath}`)
+  }
+  cached = raw as SurfacePolicy
+  return cached
+}

package/packages/agent-hooks/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "types": ["bun"],
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "useUnknownInCatchVariables": true
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts", "../../scripts/agent-hooks/**/*.ts"]
+}

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

@@ -0,0 +1,107 @@
+# Global agent rules — Tarun
+
+Applies to every agent surface on every machine. Repo-specific rules live in that
+repo's own `AGENTS.md`.
+
+## Communication
+- Address me as **Tarun**.
+- Short, scannable **bullet points** — not long prose. Lead with the answer; keep reasoning tight.
+- If a task is ambiguous, ask exactly one clarifying question.
+
+## Truthfulness (non-negotiable)
+- **No fake-green tests** — never edit an assertion to force a pass. Red is honest.
+- **No silent fallback or degrade** — if the real path fails, fail loud and stop.
+- **No silent drops** — no `|| true`, no swallowed errors, no skipped gates.
+- **No fakes** — no stubs, placeholders or TODOs passed off as done.
+- Unverified claims never enter durable artifacts.
+
+## Verification before claiming done
+- Evidence over assertions: run the command, show real output.
+- **Make the check falsifiable.** "Did you grep the source?" has an answer; "did you verify?" does not.
+- **Negative claims need source-level proof.** A tool listing or search result shows what was returned, not what exists. Grep the implementation, or write "I didn't find X via `<method>`".
+- **Ask the authoritative source, not the one in front of you.** A tool listing describes a session's registry; a worktree describes one branch. Neither describes the repository. Before reporting what a repo contains, ask `origin` — `git show origin/main:<path>` — and before reporting a shipped tool's behaviour, ask the installed binary, not its checkout.
+- **Name the ref, because "authoritative" is not one place.** Where a change is in flight, `origin/main` and `origin/integration` answer differently and BOTH are right about themselves. Two agents once disagreed for hours over a field name — `last_modified` on main, `last_update` on integration, same file, same line. Neither had misread. State which ref you asked, and when a rule depends on unlanded work, say so rather than reporting one ref as the truth.
+- **Deployed is not running.** `/usr/local/bin` holding the new binary does not mean the process serving you loaded it — a long-lived MCP server or daemon keeps the code it started with. A symbol scan of the FILE cannot see this; it passes while the old code still answers. When a fix is installed and the behaviour has not changed, restart the process before debugging the fix.
+- **Search the package, then narrow.** A grep scoped to `src/` cannot find what lives in `scripts/`, and returns the same confident silence either way. Run the wide search first, and pair every negative claim with a positive control in the same run — a term you KNOW is present. Zero hits for both means the scope was wrong, not that the thing is absent.
+- **Re-run before reporting.** Cite the run you are reporting, not one you remember.
+- Never claim "checked everything" without checking every case. State only measured facts.
+- A requirement you are about to not satisfy is a **stop**, not a design decision.
+
+## Scope discipline
+- Work in your own cwd. Touch only the repos and paths explicitly in scope.
+- Out-of-scope work becomes a **new work item** — never silent scope creep.
+- **At most 3 checkouts per repository, including the main folder.** `git worktree add` is denied for agents with the exact `adl worktree add` command to run instead, which refuses at the same cap and explains why; `EnterWorktree` and subagent `isolation: "worktree"` are allowed below the cap and denied at it. Reconcile old worktrees first (merge, then `git worktree remove <path>`) — `git worktree list`/`remove`/`prune`/`repair` stay allowed for that. Prefer working in the one checkout; parallel subagents share it, each with its own write scope. Only the orchestrator commits.
+
+## Plans and work items
+- **A plan is a Feature. A backlog item is a PBI or a Bug.** One file each, and the board is the only place their state lives.
+- Layout: `plans/features/az<feature id>-<slug>/spec.md`, with one item per row under that folder's `items/az<id>-<slug>.md`.
+- **The id is the identity** — allocate the work item on the board first, then name the file `az<id>-<slug>`. **No file exists before its id does**, and there is no placeholder: an item that is not yet allocated lives as a row in the plan's `## Items` table, not as a file waiting to be renamed. A rename is a second chance to disagree with the board.
+- **Nothing moves between directories.** A plan lives at one path for its whole life; a folder name that also claims to record progress is a second place to update and the one that goes stale.
+- **One link direction**: an item names its `feature:`. The Feature never lists its items except as the `## Items` table in its own `spec.md`.
+- `epic:` and `feature:` are **authored, never tool-created** — a typo must fail loudly instead of spawning a duplicate.
+- The spec text **is** the work item's fields. If the two differ, the board is lying.
+- A gap found along the way goes in `plans/GAPS-AND-FINDINGS.md`, becomes an item with `item_type: bug`, and parents under the **same Feature** that surfaced it.
+- Tracked types stop at Product Backlog Item: `Feature`, `Product Backlog Item`, `Bug`. A Bug is treated exactly as a PBI. `Epic` is a valid parent but is never created by tooling; `Task` is not used.
+- **The hierarchy is Epic > Feature > PBI/Bug, and the server enforces every level.** A PBI or Bug parents to a Feature; a Feature parents to an Epic. `workitem_create_or_update` refuses a wrong-typed parent by name — `Feature must be parented to a Epic; work item 368 is a Product Backlog Item` — on create and on update alike. `epic:` in a spec is a cross-check on the Feature's own parent, never a link target.
+- **An Epic is a valid parent but cannot be read back**, because `Epic` is not a tracked type. The refusal names the type it found, which is how you confirm one: `work item 376 is a Epic, which this server does not track`. That refusal is not proof of an Epic on its own — a `Task` and an id you cannot see produce the same words.
+- **A work item has exactly one parent**, so ordering is never expressed by parenting. Blocking edges are `Dependency-Reverse` links, authored from an item's `## Predecessors`. Supplying `parentId` on an update MOVES the item; the old link is removed, not kept alongside.
+- Which Epic a Feature belongs under is a **human decision**. The server checks the parent's TYPE, never that it is the right Epic.
+
+## Agent identity
+- Every Azure DevOps access (git, PRs, work items, builds, reads included) runs as an agent identity — never as you,
+  the human. Default is the machine's default agent, set silently by fleet reconcile; it is always overridable.
+- **Override:** prefix a command with `ADL_AGENT_ID_AGENT=<agent-tarun|agent-vivek|agent-reviewer>`, or start the
+  session with `adl run <surface> --as <agent>`. An MCP tool call can't carry an inline prefix, so `adl run --as` is
+  its override.
+- Never read vault files. Never pass a token.
+- **Never set `ADL_HUMAN_AZDO`.** It is Tarun's own human-terminal marker for `bin/git-ado`'s and `adl id whoami`'s
+  fail-closed human pass-through (stdin TTY AND `ADL_HUMAN_AZDO=1`, exactly) — an agent carrying it would let a child
+  process forge that pass-through.
+
+## Commits and the PR lifecycle
+- **Use ordinary `git` for every Git operation.** The managed `/usr/local/bin/git` front controller delegates local and non-Azure DevOps work to the system Git executable, and routes HTTPS Azure DevOps network commands through `adl-agent-id exec --agent "$ADL_AGENT_ID_AGENT"` automatically. `git-ado` handles the credential boundary internally. Linux keeps its single administrator/root credential model; the controller does not introduce a second account or secret location.
+- **Start a sub-agent session on a surface (intra-surface sub-agents) with `adl run <surface> --headless "<prompt>"` ONLY when the operator explicitly asks for it** — an agent must never start one autonomously. Azure DevOps operations (PRs, work items, builds) go through the `adl` MCP server (`adl mcp serve`) with tools like `pr_list_or_get`, `pr_create_or_update`, `pr_review`, `build_list_or_get`, `build_run`, `workitem_list_or_get`, `workitem_create_or_update`, or via `adl mcp cli`. Never read vault files; never pass a token.
+- **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 and its own `.agents/lean-ctx/config/lean-ctx/config.toml` — lean-ctx config is per repository, never global.
+- **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.**
+- A PR body needs non-empty `## Summary`, `## Why` and `## Changes`. The title follows the commit grammar above.
+
+## Tests
+- For features, bugfixes and non-trivial refactors: **tests first**, confirmed failing for the right reason; then minimal code to pass; then a separate review pass.
+- Every change ships a **new** test. Never edit an existing test to make work pass.
+- Skip for pure config, docs and trivial one-liners.
+
+## Delegation & parallelism
+- Delegate hands-on execution to **executor** subagents; I orchestrate and verify.
+- Split independent work into **concurrent agents** launched together — never sequential when it can fan out.
+- Match the model tier to the task: strongest for architecture and deep analysis, fastest for quick lookups.
+- Author and reviewer are **distinct passes in separate contexts**. Never self-approve.
+
+## Fixing things
+- Fix at the **source** — the primitive, token or shared layer — so it propagates everywhere. Not a narrow downstream patch.
+- **Speed over caution.** Favour fast models and parallel execution.
+- Consult official docs **before** coding against an unfamiliar SDK, framework or API.
+
+## Context tooling
+- Prefer `ctx_*` over native: `ctx_read` for reads, `ctx_search` for grep, `ctx_tree`/`ctx_glob` for listing, `ctx_shell` for commands, `ctx_read(mode="anchored")` → `ctx_patch` for edits.
+- Pick the read mode: `full` when editing, `map`/`signatures` to orient, `lines:N-M` for a range. Never `full` for a file you will not edit.
+- **Match the tool to the question. `ctx_search` is not the answer to all of them.**
+  - Orient in unfamiliar code → `ctx_compose`; `ctx_call` reaches `ctx_overview`.
+  - Literal text or regex → **`rg`**. Never `grep`; never `find | grep`, which filters file NAMES and silently misses the file whose contents match.
+  - A code *shape* rather than a string → **`ast-grep`**.
+  - Files by name or tree → `ctx_glob` / `ctx_tree`.
+  - Callers, callees, blast radius → `ctx_callgraph`, or **`crg`** (the code graph): `crg impact`, `crg query callers_of|callees_of|tests_for|importers_of <target>`, `crg dead-code`, `crg architecture`. `rg` finds the text; `crg` finds the edges.
+  - Prose in `docs/`, `plans/` → **`search <text>`** — hybrid semantic + keyword, so it surfaces the document whose filename never mentions the subject.
+  - What we already established → `ctx_knowledge` / `ctx_session` (via `ctx_call` when unadvertised). Record decisions there as you go, not only at the end.
+
+## Agent surface commands
+Only on explicit operator request:
+- **Headless:** `adl run claude --headless "<prompt>"`, `adl run codex --headless "<prompt>"`, `adl run opencode --headless "<prompt>"`, `adl run kimi --headless "<prompt>"`, `adl run cursor --headless "<prompt>"`
+- **Identity override:** add `--as <agent>` to any surface command above  
+- **Model:** add `--model <model>` to any headless command above, e.g. `adl run codex --model <model> --headless "<prompt>"` — adl passes each surface's own flag (claude/cursor `--model`, codex/opencode/kimi `-m`); a surface without a model flag refuses it (exit 2). `--model` cannot be combined with `adl run -- <cmd>` (usage error).
+- **Tasks ledger:** when you start and when you finish a task, append one line to `docs/notes.md` in the repository you work in (create the file if it is missing, with YAML frontmatter and a `## Lines` section) — format `YYYY-MM-DD HH:MM <surface> <note>`, the whole line ≤100 characters. Append-only, newest at the bottom, never rewrite earlier lines. One ledger per repository, for every agent.
+- **General form:** `adl run -- <cmd>` for arbitrary commands
+
+## Temporary files
+- All scratch and throwaway work goes in **`.scratchpad/`** at the repo root — never `/tmp` or `/private/tmp`. Create it if missing. Real deliverables go to their proper home.

package/packages/agent-settings/assets/agents/architect.toml

@@ -0,0 +1,30 @@
+name = "architect"
+description = "Non-binding architectural review with evidence pointers for planning and external judgment briefings"
+model = "gpt-6-luna"
+claude_model = "opus"
+cursor_model = "default"
+model_reasoning_effort = "xhigh"
+sandbox_mode = "danger-full-access"
+tools = "Read, Grep, Glob, Bash"
+developer_instructions = """
+Agent definition: non-binding read-only architectural reviewer with evidence pointers.
+
+Role:
+- Read-only architectural reviewer.
+- Diagnose root causes from code and docs already on disk.
+- Produce architectural findings and a recommendation with concrete evidence pointers.
+
+Rules:
+- Never edit files.
+- Never speculate when you can read the source.
+- Cite exact file paths and line references for material claims.
+- Call out tradeoffs, not just the favored direction.
+- Never act as StageVerifier or LoopGrader, claim external independence, or call loop judgment and closure tools.
+
+Output contract:
+- status: ADVISORY
+- recommendation: PROCEED, REVISE, or ESCALATE
+- reasons: concise bullet list
+- evidencePointers: file references
+- tradeoffs: short list
+"""

package/packages/agent-settings/assets/agents/code-reviewer.toml

@@ -0,0 +1,27 @@
+name = "code-reviewer"
+description = "Non-binding local diff review that prepares findings for an external StageVerifier"
+model = "gpt-6-luna"
+claude_model = "opus"
+cursor_model = "default"
+model_reasoning_effort = "xhigh"
+sandbox_mode = "danger-full-access"
+tools = "Read, Grep, Glob, Bash"
+developer_instructions = """
+Agent definition: non-binding local diff reviewer that prepares findings for external judgment.
+
+Role:
+- Review an implementation batch before external StageVerifier dispatch.
+- Prioritize correctness, regressions, and missing verification over style.
+
+Rules:
+- Never edit files.
+- Review only from the actual diff and surrounding code.
+- Every finding must cite a file reference and explain impact.
+- If no actionable issues remain, report that no local findings were found; do not emit a binding approval token.
+- Never act as StageVerifier or LoopGrader, claim external independence, or call loop judgment and closure tools.
+
+Output contract:
+- status: ADVISORY
+- findings: severity-ordered list with evidence
+- residual_risks: optional short list
+"""