@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.37 → 0.1.47

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

@@ -9,6 +9,30 @@
  * body either way; the allowance is stated in the message for the human,
  * not enforced here).
  *
+ * az365 (Scope A — JS-toolchain mutation policy, 2026-10-13): the matcher
+ * was a binary-name-only `deny` returning a Finding for every
+ * `frontend-tool` invocation regardless of effect. The OLD corpus
+ * contained 14 read-only invocations (lint, typecheck, coverage, test
+ * runs without snapshot updates, help-only) as `deny`, which is the bug:
+ * a legitimate "look at my code" call was refused with the same Finding
+ * as a file-rewriting one. The new matcher inspects `inv.args` and
+ * returns `null` (allow) for read-only invocations, returning a Finding
+ * only for the mutating ones:
+ *
+ *   deny  biome format … --write   (file rewrite)
+ *   deny  vitest run -u / --update  (snapshot mutation)
+ *   deny  tsc <file>               (no --noEmit; emits .js/.d.ts)
+ *   allow tsc --noEmit             (type-check, no emit)
+ *   allow biome check …            (read)
+ *   allow biome lint …             (read)
+ *   allow vitest run               (test runner, no source write)
+ *   allow vitest --coverage run    (writes only to coverage/)
+ *   allow jest --testPathPattern=  (test runner, no source write)
+ *
+ * The matcher does NOT inspect the `just` recipe body — the gate runs at
+ * the recipe boundary, not inside it. `--help`/`--version` are already
+ * short-circuited at classification time and never reach this matcher.
+ *
  * Tarun's decision (2026-09-27, feature az372): the message must not name a
  * particular recipe — see messages.ts's `JUST_RECIPES_POINTER`.
  */
@@ -18,37 +42,231 @@ import type { Finding, MessageContext, RuleSpec } from '../spec.ts'
 import { noParams } from '../spec.ts'
 import { detailString, JUST_RECIPES_POINTER } from './messages.ts'
 
+/** `biome format … --write` rewrites files in place. The flag may appear anywhere on the command line (`--write foo` or `foo --write`); the `--write=foo` and `-wX` concatenated forms arrive as single tokens. */
+function biomeFormatWritesFile(args: readonly { readonly value: string }[]): boolean {
+  return args.some((arg) => {
+    if (arg.value === '--write' || arg.value === '-w') return true
+    if (arg.value.startsWith('--write=')) return true
+    // Concatenated short-flag form: `-wX` where X is anything. The shell
+    // does not split the token; the matcher sees `-wX` as one element.
+    if (arg.value.startsWith('-w') && arg.value.length > 2) return true
+    return false
+  })
+}
+
+/**
+ * `tsc <file>` without `--noEmit` emits `.js` and `.d.ts` files into the
+ * working tree. `tsc --noEmit` is the read intent. A bare `tsc` (no
+ * file operand, no flags) does nothing the matcher cares about — tsc
+ * without operands reads `tsconfig.json` and may emit based on its
+ * `noEmit` setting; we treat the no-operand case as ambiguous and let
+ * it through (the engine's `uncertain` category would catch it if a
+ * future rule needs that).
+ */
+const TSC_VALUE_FLAGS: ReadonlySet<string> = new Set([
+  '-p', '--project', // config file
+  '--build',          // takes a project reference; value can be 'false'
+  '-t', '--target',
+  '--module',
+  '--moduleResolution',
+  '--jsx',
+  '--outDir',
+  '--rootDir',
+  '--baseUrl',
+  '--paths',
+  '--types',
+  '--lib',
+])
+
+function tscWritesFiles(args: readonly { readonly value: string }[]): boolean {
+  // --noEmit is the read intent; --noEmit=false is the write intent.
+  if (args.some((arg) => arg.value === '--noEmit')) return false
+  // Explicit emit flags are the write intent regardless of the file operand.
+  if (args.some((arg) => arg.value === '--emit' || arg.value.startsWith('--emit='))) return true
+  // Walk the args, skipping a value-taking flag's operand, and look for a
+  // positional file operand that names a .ts/.tsx file. That is the
+  // write intent: tsc defaults to emit when given a source file.
+  // `tsc -p tsconfig.json` is read-only because `-p` only names the
+  // config; tsc respects the config's own `noEmit` setting.
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index] as { readonly value: string }
+    if (arg.value.startsWith('-')) {
+      // Flag with a value takes the next word; skip it so we do not
+      // mistake the flag's value (`tsconfig.json` after `-p`) for a
+      // positional file operand.
+      if (TSC_VALUE_FLAGS.has(arg.value)) index += 1
+      continue
+    }
+    // Positional operand that names a TypeScript source file is the
+    // write intent. Anything else (a config, a glob, an empty) is not.
+    if (/\.tsx?$/.test(arg.value)) return true
+  }
+  return false
+}
+
+/**
+ * `vitest run -u` / `vitest run --update` mutates snapshot files in place.
+ * The shell hands the matcher individual tokens; the `-uX` / `--update=now`
+ * / `-u=foo` concatenation forms arrive as a single token whose value
+ * starts with `-u` or `--update=`. Treat any token that starts with `-u`
+ * or `--update` (and is not a different flag like `--updateSnapshot`
+ * which is a different binary's flag) as the snapshot-write trigger.
+ */
+function vitestUpdatesSnapshots(args: readonly { readonly value: string }[]): boolean {
+  return args.some((arg) => {
+    if (arg.value === '-u' || arg.value === '--update') return true
+    if (arg.value === '-u=' || arg.value.startsWith('--update=')) return true
+    // Concatenated short-flag form: `-uX` where X is anything (rare in
+    // practice; vitest doesn't combine `-u` with other short flags, but
+    // the shell hands the matcher the token unsplit). Match `-u` as a
+    // prefix only when the rest is a non-flag char, so `-update` (long
+    // option) does not match.
+    if (arg.value.startsWith('-u') && arg.value.length > 2) return true
+    return false
+  })
+}
+
+/** `jest --testPathPattern=… -u` / `jest -u` / `jest --updateSnapshot` mutates snapshots. */
+function jestUpdatesSnapshots(args: readonly { readonly value: string }[]): boolean {
+  return args.some((arg) => {
+    if (arg.value === '-u' || arg.value === '--updateSnapshot') return true
+    if (arg.value === '-u=' || arg.value.startsWith('--updateSnapshot=')) return true
+    // Concatenated short-flag form: `-uX` as above.
+    if (arg.value.startsWith('-u') && arg.value.length > 2) return true
+    return false
+  })
+}
+
 export const toolFrontend: RuleSpec = {
   id: 'tool.frontend',
   category: 'tool',
   severity: 'deny',
   enabledByDefault: true,
-  summary: "Deny direct npx/vitest/jest/biome/tsc; steer at the repository's just recipes.",
+  summary: "Deny mutating npx/vitest/jest/biome/tsc invocations; reads and tests are permitted.",
   params: noParams,
   match(inv: Invocation): Finding | null {
     if (inv.kind !== 'frontend-tool') return null
-    return { ruleId: 'tool.frontend', severity: 'deny', detail: { tool: inv.tool } }
+    const args = inv.args
+    // The mutating surfaces. Each is the only binary-name whose flag
+    // shape can change the working tree; if the rule's matcher here
+    // grows, the corpus deny list below is the place to add the new
+    // fixture so the engine's verdict stays testable.
+    switch (inv.tool.replace(/\.exe$/i, '')) {
+      case 'biome':
+        // `biome format … --write` is the file-rewrite path. `biome
+        // check` and `biome lint` are reads and must NOT be denied. The
+        // matcher inspects the args to distinguish; without this
+        // inspection every biome invocation is denied, which is the
+        // az365 Scope A bug.
+        if (biomeFormatWritesFile(args)) {
+          return { ruleId: 'tool.frontend', severity: 'deny', detail: { tool: inv.tool, action: 'biome-format-write' } }
+        }
+        return null
+      case 'tsc':
+        // `tsc --noEmit` is a read. `tsc <file>` without --noEmit emits
+        // .js and .d.ts into the working tree. Match the absence of
+        // --noEmit as the write intent.
+        if (tscWritesFiles(args)) {
+          return { ruleId: 'tool.frontend', severity: 'deny', detail: { tool: inv.tool, action: 'tsc-emit' } }
+        }
+        return null
+      case 'vitest':
+        // `vitest run` is a test runner. The .vitest cache directory and
+        // any coverage output live under node_modules / coverage/, not in
+        // project source. `-u` / `--update` is the snapshot-mutation
+        // path; the snapshot files live alongside the test files and ARE
+        // project source.
+        if (vitestUpdatesSnapshots(args)) {
+          return { ruleId: 'tool.frontend', severity: 'deny', detail: { tool: inv.tool, action: 'vitest-snapshot-write' } }
+        }
+        return null
+      case 'jest':
+        if (jestUpdatesSnapshots(args)) {
+          return { ruleId: 'tool.frontend', severity: 'deny', detail: { tool: inv.tool, action: 'jest-snapshot-write' } }
+        }
+        return null
+      case 'npx':
+        // `npx biome check …` is a read; `npx vitest run` is a test
+        // runner; `npx tsc --noEmit` is a typecheck. None mutate source.
+        // The mutating shape (browser automation, file rewrites) is
+        // Scope B (az365's split into a separate Feature for browser
+        // automation); this rule's match() does not cover it today and
+        // the agent-hooks `adl-human-azdo-bypass` rule plus the future
+        // `tool.browser-automation` rule (Feature azTBA) are the right
+        // place for it.
+        return null
+      default:
+        // Unknown `frontend-tool` name (a new addition to
+        // ClassifyConfig.frontendToolNames the rule does not yet know
+        // about). Default to allow and let the corpus surface it as a
+        // chosen behaviour on the next pass.
+        return null
+    }
   },
   message(finding: Finding, ctx: MessageContext) {
     const tool = detailString(finding, 'tool')
+    const action = detailString(finding, 'action')
+    const actionLabel =
+      action === 'biome-format-write' ? 'file rewrite'
+      : action === 'tsc-emit' ? 'tsc emit (.js / .d.ts write)'
+      : action === 'vitest-snapshot-write' ? 'snapshot update'
+      : action === 'jest-snapshot-write' ? 'snapshot update'
+      : 'mutating invocation'
     return {
-      user: `Blocked direct ${tool}. Run it through ${JUST_RECIPES_POINTER} instead; it carries the same arguments and runs through the gate profile.`,
+      user: `Blocked ${tool} (${actionLabel}). Run it through ${JUST_RECIPES_POINTER} instead; it carries the same arguments and runs through the gate profile.`,
       agent:
-        `DENIED direct ${tool}. Do not invoke ${tool} from Bash/Shell, including through sh -c, xargs, find -exec, or command substitution. ` +
+        `DENIED ${tool} (${actionLabel}). Do not invoke ${tool} from Bash/Shell, including through sh -c, xargs, find -exec, or command substitution. ` +
         `Run it through ${JUST_RECIPES_POINTER} instead - the recipe carries the same arguments and runs the gate profile rather than skipping it. ` +
-        '--help and --version remain allowed (they print text and run nothing), ' +
-        'and invoking the tool from inside a `just` recipe body is allowed because the gate runs at the recipe boundary. ' +
+        'Read-only invocations of the same tool (lint, typecheck, test runs without snapshot updates) are permitted. ' +
         `Blocked command: ${ctx.snippet}`,
     }
   },
   corpus: {
+    // The mutating invocations — the only ones `match()` returns a Finding
+    // for. 6 entries; the az388 corpus floor in tests/unit/rules-corpus-floors.test.ts
+    // was lowered from 15 to 6 on 2026-10-13 (az365 Scope A) and the file
+    // header explains why.
     deny: [
+      'biome format packages/desktop/src --write',
+      'biome format --write packages/desktop/src',
+      'biome format --write src/foo.ts',
+      // Concatenated short-flag form: the shell hands the matcher a
+      // single `-wX` token; the predicate's prefix check catches it.
+      'biome format src/foo.ts -w',
+      'vitest run -u',
+      'vitest run --update',
+      // Concatenated form: the shell hands the matcher a single `-uX`
+      // token; the predicate's prefix check catches it. The corpus entry
+      // is the value the shell actually produces (`-uX`); vitest does
+      // not combine `-u` with other short flags, but the matcher has
+      // to handle the form anyway.
+      'vitest run -uX',
+      // `=`-form: `--update=now` arrives as a single token, predicate
+      // catches via `startsWith('--update=')`.
+      'vitest run --update=now',
+      'tsc src/foo.ts',
+      // jest's snapshot-mutation flag form; covers the jest branch of
+      // match() and the jest action label in message(). The flag is
+      // either `-u` or `--updateSnapshot`; both must be denied.
+      'jest -u',
+      'jest --updateSnapshot',
+      'jest -uX',
+    ],
+    // The read-only invocations — every one `match()` returns null for.
+    // The 14 the OLD corpus mis-classified as denied move here as the
+    // audit-trail entry that pins "this is a read, the deny is over-broad
+    // and a future narrowing should permit it" — the future narrowing is
+    // THIS rule's match(), already implemented; these entries are the
+    // proof the test suite pins against.
+    allow: [
       'npx biome check packages/desktop/src',
+      'npx vitest run',
+      'npx tsc --noEmit',
       'vitest run',
       'vitest --coverage run',
       'jest --testPathPattern=adl-conversation',
+      'biome check packages/desktop/src',
       'biome lint packages/desktop/src',
-      'biome format packages/desktop/src --write',
       'tsc --noEmit',
       'tsc -p tsconfig.json',
       'xargs npx tsc --noEmit',
@@ -56,12 +274,13 @@ export const toolFrontend: RuleSpec = {
       "sh -c 'npx tsc --noEmit'",
       "bash -lc 'npx tsc --noEmit'",
       'echo $(biome lint src/)',
-      // Not help-only: isHelpOrVersionOnly requires EVERY token to be a
-      // help/version flag, and 'lint'/'--noEmit' are real arguments.
+      // The two help-only entries are already short-circuited by
+      // isHelpOrVersionOnly at classification time; they never reach
+      // `match()`. Listed under `allow` for the same audit-trail reason
+      // as the reads above: chosen behaviour, not merely a passing test.
       'biome lint --help',
       'tsc --noEmit --help',
-    ],
-    allow: [
+      // Pre-existing allow entries preserved.
       'npx --version',
       'vitest --version',
       'jest --version',

package/packages/agent-hooks/src/rules/shell/git-identity.ts

@@ -869,7 +869,7 @@ export interface GitInvocationPiece {
 /**
  * One `adl mcp cli <command> …` invocation found while scanning a command,
  * paired with the effective identity for THAT specific piece. `command` is the gated command name
- * (e.g. `workitem-create-or-update`), lower-cased; `rest` is the dequoted
+ * (e.g. `workitem-create-or-update-pbi`), lower-cased; `rest` is the dequoted
  * values after it, the same shape `impl/adl-mcp-cli.ts`'s `adlMcpCliCall`
  * reads off `Invocation.args.slice(3)`, so a role rule can correlate a
  * specific `Invocation` to its own piece here by comparing values, exactly

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

@@ -86,7 +86,19 @@ export type Invocation =
   | { readonly kind: 'azure-devops'; readonly args: readonly Token[] }
   | { readonly kind: 'find' }
   | { readonly kind: 'grep' }
-  | { readonly kind: 'frontend-tool'; readonly tool: string }
+  /**
+   * `npx`/`vitest`/`jest`/`biome`/`tsc` and their Windows spellings (the
+   * `.exe` variants, see `ClassifyConfig.frontendToolNames`). The
+   * `args` field carries the tokenized post-name argument list so
+   * `tool.frontend.match()` (and any future `tool.browser-automation`
+   * rule) can inspect flags — `--write` on `biome format`, `--noEmit`
+   * on `tsc`, `-u`/`--update` on `vitest run`, etc. — instead of
+   * denying every binary-name invocation regardless of effect. Threaded
+   * through by `walkToolCommand` below; the args are not consumed by
+   * `isHelpOrVersionOnly` (which has already run before this producer),
+   * they are what remains of the post-name token stream.
+   */
+  | { readonly kind: 'frontend-tool'; readonly tool: string; readonly args: readonly Token[] }
   /**
    * `bun test` (any arguments, including a file/pattern operand) — the
    * `test` subcommand specifically, after skipping bun's own `-C <dir>` /
@@ -638,7 +650,7 @@ function walkToolCommand(name: string, args: readonly Token[], cfg: ClassifyConf
     return [{ kind: 'azure-devops', args }]
   }
   if (cfg.cargoNames.has(name)) return isHelpOrVersionOnly(args) ? [] : [{ kind: 'cargo' }]
-  if (cfg.frontendToolNames.has(name)) return isHelpOrVersionOnly(args) ? [] : [{ kind: 'frontend-tool', tool: name }]
+  if (cfg.frontendToolNames.has(name)) return isHelpOrVersionOnly(args) ? [] : [{ kind: 'frontend-tool', tool: name, args }]
   if (cfg.bunNames.has(name)) return isBunTestSubcommand(args) ? [{ kind: 'bun-test' }] : null
   if (cfg.justNames.has(name)) return walkJustCommand(args)
   if (name === 'xargs' || name === 'xargs.exe') return xargsInvocation(args, walk)

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

@@ -10,9 +10,16 @@
  * `agent-tamper-protection.ts` imports it, rather than two copies that could
  * drift.
  *
- * Still hard-coded on purpose (not configurable): see
- * `impl/agent-tamper-protection.ts`'s header for why an `adl-config.toml`
- * allowlist for this rule would be the same "switch the gate off" hole it
+ * `adl-config.toml` is NOT in this set. It is a runtime configuration file
+ * the agent must be able to edit (Tarun, 2026-10-13: "adl-config.toml can be
+ * editted but not committed by the agents"). The COMMIT side is enforced by
+ * repo-controls' `integrity.ts` (`WIRING`, refuses a normal commit of
+ * `adl-config.toml`) and by `agent-hooks`' `git.protected-tree-commit` rule
+ * (Bug 373/PBI 679); both fire on the staged index, not on the working
+ * tree.
+ *
+ * Still hard-coded on purpose (not configurable): a per-repo allowlist in
+ * `adl-config.toml` would be the same "switch the gate off" hole this rule
  * exists to close.
  */
 
@@ -29,14 +36,6 @@ export const PROTECTED_CARRIER_PATHS: ReadonlySet<string> = new Set([
   '.claude/settings.json',
   '.claude/settings.local.json',
   '.codex/config.toml',
-  // `adl-config.toml` is the repo's hook switch — every hook run re-reads it,
-  // so an agent that writes `[hooks] enabled = false` or disables any rule
-  // flips the gate off before the next tool call lands. Re-listed here on
-  // 2026-10-12 (Tarun: "we left a door open, close it"). The earlier
-  // 'human-only at commit time' assumption was wrong: the commit-time gate
-  // fires for the COMMITTED file, not for edits that never stage, and the
-  // working-tree copy is what every running hook reads.
-  'adl-config.toml',
   '.codex/hooks.json',
   '.cursor/hooks.json',
   '.opencode/plugins/adl-repo.ts',

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

@@ -6,8 +6,8 @@ Where a repository has its own AGENTS.md, that file and the files it links add t
 ## Communication
 - Address me as **Tarun**.
 - **Answer first.** No greeting, no "let me", no recap of what was just done, no closers.
-- One idea per sentence. Short beats polite. Articles can go; not, never, no, only never do. Numbers, paths, commands exact.
-- Bullet points over prose.
+- One idea per sentence. Short beats polite. Articles can go; not, never, no, only never do. Numbers, paths, commands exact. **Maximum 100 words** per response
+- **Bullet points over prose**.
 - **Open points:** one numbered list of open decisions per conversation. Show it only when it changes — item added or resolved. After a long gap or compaction, restate the full list. That is when it gets lost.
 - **Questions:** one at a time, one or two sentences. Options inline: `A) … B) …`. A long multi-part question means split the work, not more prose.
 - Full sentences for security warnings, irreversible actions, step-by-step orders, and when I'm confused. Then short resumes.

package/packages/agent-settings/package.json

@@ -6,7 +6,7 @@
   "description": "Machine-global agent surface tooling (sweep, global-agents, kimi-hooks, surface-policy) run by the fleet bin wrappers under bun; also holds GLOBAL-AGENTS.md, surface policy, and the protected list. Subagent definitions (Claude/Codex/Cursor/Kimi/OpenCode) are canonical in packages/agent-skills/extensions/adl-factory/agents/*.toml and projected per repo by that package's installer; this package does not generate or hold its own copy.",
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "bun test --coverage",
+    "test": "bun test --isolate --coverage",
     "check": "bun run typecheck && bun run test --coverage"
   },
   "dependencies": {

package/packages/agent-settings/src/deploy/agents-deploy.ts

@@ -25,6 +25,13 @@ export interface DeployAgentsOptions {
   readonly agents?: readonly AgentDef[];
   /** Computes the exact same written/unchanged/removed/conflicts result without writing anything (independent review, 2026-09-29, finding 6). */
   readonly dryRun?: boolean;
+  /**
+   * When set, deploy only the named surface (profile.agents.surfaces[].name) —
+   * the deploy half of the per-surface knob (az567). Other surfaces are
+   * left untouched: their files are not written, their conflicts are not
+   * reported, the lock is not rewritten for them.
+   */
+  readonly surfaceFilter?: string;
 }
 
 interface AgentConflict {
@@ -71,6 +78,10 @@ export function deployAgents(options: DeployAgentsOptions): DeployAgentsResult {
   let anyLegacyTakeover = false;
 
   for (const surface of profile.agents.surfaces) {
+    // az567 surfaceFilter: only iterate the named surface. Other
+    // surfaces' deploy paths, conflicts, and lock entries are out of
+    // scope and never appear in this result.
+    if (options.surfaceFilter !== undefined && surface.name !== options.surfaceFilter) continue;
     const ext = extensionFor(surface);
     const kept: string[] = [];
 
@@ -126,7 +137,14 @@ export function deployAgents(options: DeployAgentsOptions): DeployAgentsResult {
     newAgentEntries[surface.folder] = kept.sort();
   }
 
-  if (!dryRun) writeLock(targetRepo, { schema: 1, mcp: lock.mcp, agents: newAgentEntries });
+  // az567 surfaceFilter: when only one surface is in scope, the
+  // `newAgentEntries` map only carries that surface. The lock write
+  // must keep every other surface's previous lock entry byte-identical
+  // so non-target surfaces are not "unwritten" by a per-surface deploy.
+  const lockAgents = options.surfaceFilter === undefined
+    ? newAgentEntries
+    : { ...lock.agents, ...newAgentEntries };
+  if (!dryRun) writeLock(targetRepo, { schema: 1, mcp: lock.mcp, agents: lockAgents });
 
   // Once anything was actually taken over, this package's own footprint in
   // the legacy lock's `files` section for these exact agent paths is stale:

package/packages/agent-settings/src/deploy/index.ts

@@ -1,6 +1,7 @@
 export { type DoctorResult } from "./doctor.js";
 export { listSettings } from "./list.js";
 export { deploySettings, doctorSettings, type DeploySettingsResult } from "./settings.js";
+export { deployAgents, type DeployAgentsResult } from "./agents-deploy.js";
 export { loadProfile } from "./profile.js";
 export { loadMcpSource, type McpServerSpec } from "./mcp-source.js";
 export { loadAgentSources, type AgentDef } from "./agent-toml.js";

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

@@ -26,8 +26,7 @@ and its evidence siblings.
 - The repo has no `.adl/logs/` (no agent-hooks hooks installed).
 - The question is about a non-search tool (use a different audit
   script).
-- The repo is not a git repo and the script's `git rev-parse
-  --show-toplevel` fallback cannot find the project root — pass
+- The repo has no project root the script can find — pass
   `--out <absolute-dir>` to write the report elsewhere.
 
 ## Process
@@ -42,8 +41,7 @@ After deploy, the script lives at:
 
 In dev (this repo's `packages/agent-skills/`), the equivalent path is
 `packages/agent-skills/assets/agent-search-tool-audit/scripts/audit.sh`.
-The script finds the project root via `git rev-parse --show-toplevel`,
-so it works in both layouts.
+The script locates the project root, so it works in both layouts.
 
 ### 2. Run with the desired window
 
@@ -133,8 +131,8 @@ Rationale moved out of `scripts/audit.sh` (REP-007: no multi-line comments).
   `hooks-deny.log` (read-only history, never migrated, deduped against the new ones);
   `.adl/logs/agents/tool-calls.log` (`adl run` lifecycle).
 - Path discovery: the script lives in the agent-skills asset tree (5 levels deep in dev, 4 once
-  deployed to `.agents/skills/`), so it uses `git rev-parse --show-toplevel` to work in both layouts
-  and falls back to the dev layout if git is missing.
+  deployed to `.agents/skills/`), so it locates the project root to work in both layouts
+  and falls back to the dev layout if it cannot.
 - Required tools: `jq`, `python3` and `rg`; each is checked up front and the script fails loud
   (exit 1) naming the missing one. `rg` is a protected bootstrap tool on every managed machine.
 - Cost: under 30 s on a typical 2-3 MB log set; no network.

package/packages/agent-skills/assets/finalize-feature/SKILL.md

@@ -24,13 +24,13 @@ Load `workitems-process` first. You are a leaf sub-agent of `lead` (`implement-f
 
 ## Preconditions
 
-1. `git rev-parse HEAD` equals `H` and the worktree is clean; else return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
+1. The branch head equals `H` and the worktree is clean; else return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
 2. The Feature-final verify is `PASS` and code is `APPROVE` and architecture `CLEAR`/`WATCH`, all at `H`; else return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
 
 ## Procedure
 
-1. **Docs check.** For each entry in `design.md` `## Docs impact` (per-Bug run: the docs the fix touches), find the matching path in `git diff --name-only origin/integration...H` and read the hunk, not just the filename. "No docs impact" counts as covered. Any missing entry: verdict `REWORK`, finding `docs-missing` (`where`: doc path or section; `fix`: what to write). Stop.
-2. **PR body.** The five non-empty sections in [ado-and-git.md](../workitems-process/references/ado-and-git.md#7-git), filled as below. Every claim links to evidence (a report, a commit, a run); no unverified statements.
+1. **Docs check.** For each entry in `design.md` `## Docs impact` (per-Bug run: the docs the fix touches), find the matching path in the diff against `H` and read the hunk, not just the filename. "No docs impact" counts as covered. Any missing entry: verdict `REWORK`, finding `docs-missing` (`where`: doc path or section; `fix`: what to write). Stop.
+2. **PR body.** The five non-empty sections (Summary, Why, Changes, Test plan, Security impact considered), filled as below. Every claim links to evidence (a report, a commit, a run); no unverified statements.
    - `## Summary`: what the Feature delivers, by item (id, title).
    - `## Why`: from `intent.md` and `requirements.md`, in the plan's words, not new claims.
    - `## Changes`: per item, the files and behaviour changed; design updates made during the run; docs touched.

package/packages/agent-skills/assets/implement-feature/SKILL.md

@@ -14,8 +14,8 @@ Load `workitems-process` first. This card is the lead's whole procedure. Sub-age
 ## When to use
 
 - The dispatcher started you for one Feature: every in-scope item (not Parked/Removed) is at Approved or later, at least one is not Done, every predecessor Feature is at Awaiting Release or Done.
-- **Per-Bug run.** The dispatcher may instead start you for one Fixes Bug at Approved through Updating Docs, until its PR merges, keyed by the Bug **[pending L5, X2]**, on branch `fix/az<bug id>-<slug>`. A Bug has no plan folder, no Plan Hash and no Design Validation: skip only Preconditions 4-5 and procedure step 1. Preconditions 1-3 apply in their per-Bug form (below). The Bug's ladder and moves are in [Bug states](../workitems-process/references/workitem-states.md#5-bug-states). A Bug at In Reproduction or later is a resumed run: continue from its state (Resume, below). On a fresh run (Bug at Approved) your first board write is Approved → **In Reproduction**. Then spawn `executor` (`implement-item`, reproduce mode, `reproduce` brief in `references/briefs.md`): its first commit is the Bug's item file, written from the G1-approved Bug Description, with its LEDGER row; its next commit is the regression test, proved red on the base and committed marked as an expected failure so the commit stays green, and that brief writes nothing else. Post the executor's unmarked red run on the base as a comment on the Bug, as evidence. Then move In Reproduction → **In Fixing**; the `fix` brief (bug mode) writes the minimal fix until green, in the loop, and its fix commit removes the expected-failure mark. Every commit stays independently green, with no exception. Run the loop and the one PR as usual. You write no file yourself. Won't reproduce: post what you tried as a comment on the Bug and move it to Parked for Removal (G3 is the human's). You resolve everything else in the run ([No block](../workitems-process/SKILL.md#no-block)).
-- One run = one worktree, one branch, one lead session (you), **one implementation PR** to `integration`.
+- **Per-Bug run.** The dispatcher may instead start you for one Fixes Bug at Approved through Updating Docs, until its PR merges, keyed by the Bug **[pending L5, X2]**, on the per-Bug branch. A Bug has no plan folder, no Plan Hash and no Design Validation: skip only Preconditions 4-5 and procedure step 1. Preconditions 1-3 apply in their per-Bug form (below). The Bug's ladder and moves are in [Bug states](../workitems-process/references/workitem-states.md#5-bug-states). A Bug at In Reproduction or later is a resumed run: continue from its state (Resume, below). On a fresh run (Bug at Approved) your first board write is Approved → **In Reproduction**. Then spawn `executor` (`implement-item`, reproduce mode, `reproduce` brief in `references/briefs.md`): its first commit is the Bug's item file, written from the G1-approved Bug Description, with its LEDGER row; its next commit is the regression test, proved red on the base and committed marked as an expected failure so the commit stays green, and that brief writes nothing else. Post the executor's unmarked red run on the base as a comment on the Bug, as evidence. Then move In Reproduction → **In Fixing**; the `fix` brief (bug mode) writes the minimal fix until green, in the loop, and its fix commit removes the expected-failure mark. Every commit stays independently green, with no exception. Run the loop and the one PR as usual. You write no file yourself. Won't reproduce: post what you tried as a comment on the Bug and move it to Parked for Removal (G3 is the human's). You resolve everything else in the run ([No block](../workitems-process/SKILL.md#no-block)).
+- One run = one worktree, one branch, one lead session (you), **one implementation PR**.
 - Resume is not a separate mode: if the trigger still holds on a later tick you are started again in the **same worktree on the same branch**. Read the board and the branch, continue (Resume, below).
 
 ## Inputs
@@ -27,21 +27,18 @@ Load `workitems-process` first. This card is the lead's whole procedure. Sub-age
 | Plan folder | `plans/features/az<id>-<slug>/`: `intent.md`, `requirements.md` (EARS criteria `AC-n`, `## Items`), `design.md`, `file-map-reference.md`, `items/az<id>-<slug>.md` |
 | Feature fields | `BaselineSha`, `PlanHash`, `PlanRevision` **[pending T3: named arguments; reference names not yet confirmed through the API]** |
 
-Identity `agent-tarun`.
-
 ## Preconditions
 
-1. `git rev-parse --show-toplevel` equals `worktree`; the branch is the Feature's `<type>/az<id>-<slug>` (per-Bug run: `fix/az<bug id>-<slug>`); `git status --porcelain` is empty, or the dirt is your own previous attempt.
-2. `adl id whoami` reports `agent-tarun`.
-3. Read the Feature's children (`workitem_list_or_get`). Every in-scope item is at Approved or later; if not, the trigger does not hold: report the item and its state on the Feature and end the run. Per-Bug run: read only the Bug; it must be at Approved through Updating Docs with its PR not merged (other Bugs in the Fixes Feature do not matter); if not, report its state on the Bug and end the run.
-4. The plan folder is on the branch (planning PR merged into `integration`): the four plan documents and every `items/az<id>-*.md` exist. If the planning PR is not merged yet, end the run and report it; the next tick re-evaluates.
-5. `sha256` of `requirements.md` equals `PlanHash` (the hash covers `requirements.md` only). On a mismatch, post both hashes as a Feature comment and do not start Design Validation: the approved plan is not the one on the branch. **[pending F7: the tool will refuse the Design Validation move on a mismatch; the field reference name is not yet confirmed through the API.]**
+1. The worktree matches `worktree`; the branch is the Feature's implementation branch (per-Bug run: the per-Bug branch); the tree is clean, or the dirt is your own previous attempt.
+2. Read the Feature's children (`workitem_list_or_get`). Every in-scope item is at Approved or later; if not, the trigger does not hold: report the item and its state on the Feature and end the run. Per-Bug run: read only the Bug; it must be at Approved through Updating Docs with its PR not merged (other Bugs in the Fixes Feature do not matter); if not, report its state on the Bug and end the run.
+3. The plan folder is on the branch (planning PR merged): the four plan documents and every `items/az<id>-*.md` exist. If the planning PR is not merged yet, end the run and report it; the next tick re-evaluates.
+4. `sha256` of `requirements.md` equals `PlanHash` (the hash covers `requirements.md` only). On a mismatch, post both hashes as a Feature comment and do not start Design Validation: the approved plan is not the one on the branch. **[pending F7: the tool will refuse the Design Validation move on a mismatch; the field reference name is not yet confirmed through the API.]**
 
 ## Procedure
 
 ### 1. Design Validation
 
-1. The run starts by merging `origin/integration` into its branch: `git fetch origin`, then `git merge origin/integration` (a fast-forward on a fresh start; never rebase, never force). The worktree `HEAD` then contains the current `integration`, and Design Validation diffs `<BaselineSha>..HEAD`.
+1. The run starts by merging the integration base into its branch (a fast-forward on a fresh start; never rebase, never force). The worktree `HEAD` then contains the current integration, and Design Validation diffs `<BaselineSha>..HEAD`.
 2. Move every Approved item → **Design Validation** (adjacent forward move; the fence allows it). This is your first board write.
 3. Spawn `architect` with the `validate-design` brief. It checks `design.md` and its `file-map-reference.md` by diffing `<BaselineSha>..HEAD`, records `head_sha`, and rules `FRESH`, or `DRIFT` (with the exact delta). `requirements.md` is **not** re-validated: it was validated in planning and approved at G1.
 4. `FRESH`: continue. `DRIFT`: **drift never leaves the run**. Spawn `planner` (skill `plan-feature`, Mode B: design update) with the delta. It updates `design.md`, `file-map-reference.md` (the `## Map` rows the drift moves, and the `## Baseline` section) and the Feature's Baseline Sha to the new `integration` base, adds the LEDGER row `az<id>-design-update`, and commits on the Feature branch; Plan Hash is unchanged. You write no file: record the update in the implementation report and the PR. Then re-validate once. Items never go to New or In Planning.
@@ -54,7 +51,7 @@ The four states **In Implementation, In Testing, In Review, Updating Docs** are
 
 - **Order is yours.** Pick the item order from `design.md` (shared files, risk first). Default staffing is conservative: one executor at a time on the shared branch. Fan out only items with disjoint file scopes in `file-map-reference.md`, as native sub-agents of this session, never the adl-workflow `team` worker pool. You may also spawn read-only explore sub-agents on the fast tier.
 - The usual order is In Testing before In Review (green code before a reviewer's time). A default, not a rule.
-- **Every commit is on the run's one branch** (the Feature branch, or `fix/az<bug id>-<slug>` in a per-Bug run). No per-item branch, worktree or PR. Commits carry `AB#<item id>`.
+- **Every commit is on the run's one branch** (the Feature branch, or the per-Bug branch in a per-Bug run). No per-item branch, worktree or PR. Commits carry `AB#<item id>`.
 
 Per item, in the order you chose:
 
@@ -70,7 +67,7 @@ Per item, in the order you chose:
 - **Mid-loop drift** (executor returns `DRIFT`): the item moves In Implementation → **Design Validation** **[pending F1]** ([States at a glance](../workitems-process/SKILL.md#states-at-a-glance)), run step 1.3 to 1.6 for that item, then back to In Implementation.
 - **In Review** = reviewer sub-agents in fresh contexts. No PR reviewer, no votes, no PR threads before the merge ([Human gates](../workitems-process/SKILL.md#human-gates)). Findings go to **item comments and the implementation report**. `REQUEST_CHANGES` or `BLOCK` sends the item back. `WATCH` and medium/low are recorded, not blocking.
 - Sub-agents return a report (format in `references/briefs.md`). **You** post it on the item as a comment and keep it for the implementation report.
-- Push the branch (plain `git push`, never force) after each item's executor reports `DONE` so that heads are durable for resume. Verifiers, reviewers, the validate lane and the writer record `head_sha` at their start and finish against it; compare each report's `head_sha` with the branch head, and re-run the lane at the new head when the head moved ([Evidence and reports](../workitems-process/SKILL.md#evidence-and-reports), the head rule).
+- Push the branch (plain push, never force) after each item's executor reports `DONE` so that heads are durable for resume. Verifiers, reviewers, the validate lane and the writer record `head_sha` at their start and finish against it; compare each report's `head_sha` with the branch head, and re-run the lane at the new head when the head moved ([Evidence and reports](../workitems-process/SKILL.md#evidence-and-reports), the head rule).
 - A later commit voids earlier test and review evidence for what it touches. The Feature-final check is the evidence the merge relies on.
 
 ### 3. Feature-final check
@@ -78,14 +75,14 @@ Per item, in the order you chose:
 When every item has been through Build, Test and Review and the tree is clean and pushed:
 
 1. Record the final head `H`.
-2. Spawn `verifier` in **Feature-final mode** (every `AC-n` of `requirements.md`, the full suite; in a per-Bug run, the Bug item file's `## Expected behaviour` (EARS) plus `## Behaviour that must not change`, base = the `integration` SHA the `fix/` branch was created from) and both review lanes (code, architecture) over `origin/integration...H`.
+2. Spawn `verifier` in **Feature-final mode** (every `AC-n` of `requirements.md`, the full suite; in a per-Bug run, the Bug item file's `## Expected behaviour` (EARS) plus `## Behaviour that must not change`, base = the integration SHA the per-Bug branch was created from) and both review lanes (code, architecture) over the integration..H range.
 3. All pass at `H` → continue. Any finding → fix loop as above (the same 3-round cap, counted per finding), then repeat this step at the new head. Evidence binds to the head it ran at.
 
 ### 4. Finalize and raise the PR
 
 1. Spawn `writer` (`finalize-feature`): docs-impact check against `design.md`, then the **PR body** (five sections) and the **implementation report** content. It returns text; it pushes and writes nothing. Finding `docs-missing` → an executor writes it, then repeat 3.
-2. PR body: the five sections in [ado-and-git.md](../workitems-process/references/ado-and-git.md#7-git). Title in commit grammar. Branch `feat/az<id>-<slug>`, or `fix/az<bug id>-<slug>` in a per-Bug run (the `-plan` suffix marks a planning PR and is never used here).
-3. `git push` the branch. `pr_create_or_update` (action create, target `integration`) with the body and the report content. **The tool does the wiring [pending P1/P2/P4]** ([PR wiring](../workitems-process/references/ado-and-git.md#6-pr-wiring)); you pass nothing for it. Until built, report which parts you could not observe.
+2. PR body: the five sections (Summary, Why, Changes, Test plan, Security impact considered). Title in commit grammar. The branch is the Feature's implementation branch, or the per-Bug branch in a per-Bug run (the `-plan` suffix marks a planning PR and is never used here).
+3. Push the branch. `pr_create_or_update` (action create, target `integration`) with the body and the report content. **The tool does the wiring [pending P1/P2/P4]** ([PR wiring](../workitems-process/references/ado-and-git.md#6-pr-wiring)); you pass nothing for it. Until built, report which parts you could not observe.
 4. Read the PR and the items back: items at Updating Docs, PR linked. A mismatch is reported in the Feature comment, never patched by hand-linking or hand-moving to Done.
 
 ### 5. CI stage (the last gate)
@@ -95,9 +92,9 @@ CI is the gate before the merge (ADR-019). Poll `pr_list_or_get` and `build_list
 | Result | You do |
 |---|---|
 | Green, PR completes | Read the items back; they should be **Done** with the PR link (V2 not yet verified on a real PR). Never set Done yourself. End `MERGED` |
-| Red | Spawn `executor` (`fix-ci`): smallest fix, no skip, no `\|\| true`, no loosened test. Push. Then `verifier` and `code-reviewer` re-check the **delta** at the new head. Append the round to the implementation report (`pr_create_or_update` update). Cap **3** rounds; past it, post the reason as a Feature comment and change approach. Expired check: scoped `build_run` (pending H1). Integration moved: merge `origin/integration` |
+| Red | Spawn `executor` (`fix-ci`): smallest fix, no skip, no `\|\| true`, no loosened test. Push. Then `verifier` and `code-reviewer` re-check the **delta** at the new head. Append the round to the implementation report (`pr_create_or_update` update). Cap **3** rounds; past it, post the reason as a Feature comment and change approach. Expired check: scoped `build_run` (pending H1). Integration moved: merge the integration base into the branch |
 | Cancelled or infrastructure failure with log proof | Re-queue only your own PR's validation on the PR's source branch with `build_run` **[pending H1; refusal = report it, stop]**. A failing test or check is never re-queued to get a lucky green |
-| Merge conflict | Executor merges `origin/integration` into the branch (`git merge`, never a force-push), re-runs checks, then the delta is re-verified and re-reviewed as for red |
+| Merge conflict | Executor merges the integration base into the branch (never a force-push), re-runs checks, then the delta is re-verified and re-reviewed as for red |
 
 ## Board moves (yours)
 
@@ -119,8 +116,8 @@ Never move an item to Approved, Done or Removed. Never move a Feature. `pr_creat
 
 The trigger holds until the merge, so you may be restarted in the same worktree on the same branch (session died, run ended with the PR open, merge conflict). Do not restart finished work.
 
-1. Read every child's board state and its comments (the earlier sub-agent reports are there) **[pending T1: no comment-read tool yet; without it, work from board states, `git log` and the PR, and re-run any evidence whose head is stale]**.
-2. `git log origin/integration..HEAD` with `AB#` ids shows which items have commits. `pr_list_or_get` shows whether the PR exists.
+1. Read every child's board state and its comments (the earlier sub-agent reports are there) **[pending T1: no comment-read tool yet; without it, work from board states and the PR, and re-run any evidence whose head is stale]**.
+2. The commit log on the implementation branch with `AB#` ids shows which items have commits. `pr_list_or_get` shows whether the PR exists.
 3. PR open: go to step 5. No PR: for each item resume from its board state (In Testing means run Test at the current head; In Review means run Review; and so on). Evidence at an older head is stale: re-run. Per-Bug run: a Bug at In Reproduction gets the `reproduce` brief again (it keeps the commits already made); a Bug at In Fixing or later resumes from its state in the loop.
 4. Reuse the branch and the PR. Never recreate either.
 
@@ -128,7 +125,7 @@ The trigger holds until the merge, so you may be restarted in the same worktree
 
 | Verdict | When |
 |---|---|
-| `MERGED` | PR completed into `integration` |
+| `MERGED` | PR completed |
 | `PR_OPEN` | PR raised and CI not finished when the session must end; the next tick resumes at step 5 |
 
 ## Stop rules