@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

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

@@ -0,0 +1,441 @@
+/**
+ * The single source of permission posture for every global agent surface.
+ *
+ * `surface-policy.json` states the intent once — "run wide open", with named
+ * exceptions — and this module translates it into each surface's own keys.
+ * Without it, posture lives in four files in four syntaxes and drifts: on
+ * 2026-09-15 m5 ran Claude `acceptEdits` against Codex `never` +
+ * `danger-full-access`, with nothing recording which was intended.
+ *
+ * Scope boundary, and the reason the file has two halves:
+ *
+ *   - `posture` cascades OUT to global surface configs. It is only ever a
+ *     permission MODE.
+ *   - `deny` does NOT. Codex and Kimi cannot express a path or tool deny at
+ *     all, so writing denies into surface configs would protect Claude and
+ *     OpenCode and silently leave the other two open. Denies are consumed by
+ *     `adl hook` (the folded-in enact-hook engine), which runs on every host
+ *     and is therefore the only place a deny is actually enforceable
+ *     fleet-wide.
+ *
+ * `deny` lists ONLY what a consumer actually reads. Reconcile atomically
+ * installs this file at `/etc/adl/surface-policy.json` before it installs
+ * the bun-compiled `adl` binary; `adl hook` requires that runtime file and
+ * fails closed if it is absent or invalid. An entry nobody consumes would be
+ * a claim this file drives something it does not, so the shell classifier's
+ * own finder vocabulary (`egrep`, `ack`, the `.exe` variants) deliberately
+ * stays in `adl hook`'s shell invocation classifier.
+ *
+ * Hooks are deliberately NOT part of this cascade. Hook wiring is repo-local
+ * (a per-repo installer places `.claude/settings.json` and
+ * `.codex/hooks.json` per repo — item 3, docs/specs/two-branch-standard-
+ * 2026-09-27.md, retires the old npm-distributed installer for this); the
+ * global `~/.codex/hooks.json` is intentionally left empty.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, isAbsolute, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const SURFACE_POLICY_PATH = join(dirname(dirname(fileURLToPath(import.meta.url))), 'surface-policy.json')
+
+/** The surfaces that have a machine-global permission mode worth cascading to. */
+export const POLICY_SURFACES = ['claude', 'codex', 'opencode', 'kimi'] as const
+export type PolicySurface = (typeof POLICY_SURFACES)[number]
+
+/**
+ * Only postures whose per-surface values were confirmed against the real
+ * surface are listed. `strict` is deliberately absent: a read-only Codex
+ * sandbox and an OpenCode "deny" were never exercised on this fleet, and a
+ * posture that has never been run is a guess wearing a name. Add it when it
+ * has been measured, not before.
+ */
+export const POSTURES = ['permissive', 'balanced'] as const
+export type Posture = (typeof POSTURES)[number]
+
+export interface SurfacePolicy {
+  readonly posture: Posture
+  readonly overrides: Readonly<Partial<Record<PolicySurface, Posture>>>
+  readonly deny: {
+    /**
+     * Repo directory names that no agent may reach into, in ANY spelling.
+     * Stored as bare names (`enact-vps`), not `~/enact-vps`: the consumer
+     * expands each into the absolute and tilde forms it needs, because the
+     * shell classifier compares literal tokens and does not expand `~`.
+     */
+    readonly paths: readonly string[]
+    /** Native tool-call names denied on every host. */
+    readonly nativeTools: readonly string[]
+  }
+}
+
+export interface SurfaceModeEdit {
+  /** Home-relative path of the surface's global config. */
+  readonly file: string
+  readonly format: 'json' | 'toml'
+  /**
+   * Keys to set. For `json`, a key may be a `/`-separated pointer
+   * (`permissions/defaultMode`); for `toml`, keys are top-level.
+   */
+  readonly set: Readonly<Record<string, string>>
+}
+
+/**
+ * Posture -> each surface's native spelling.
+ *
+ * Every value below was read off the real thing rather than a docs summary:
+ * Kimi's tokens out of the shipped binary at ~/.kimi-code/bin/kimi, OpenCode's
+ * bare-string `permission` off m3 (the machine confirmed working), and Codex's
+ * pair out of the live ~/.codex/config.toml. Change a value here only with the
+ * same standard of evidence.
+ */
+const TABLE: Readonly<Record<PolicySurface, Readonly<Record<Posture, SurfaceModeEdit>>>> = {
+  claude: {
+    permissive: {
+      file: '.claude/settings.json',
+      format: 'json',
+      set: { 'permissions/defaultMode': 'bypassPermissions' },
+    },
+    balanced: {
+      file: '.claude/settings.json',
+      format: 'json',
+      set: { 'permissions/defaultMode': 'auto' },
+    },
+  },
+  // Two keys, always written together: `approval_policy` alone still leaves an
+  // unrestricted sandbox, and `sandbox_mode` alone leaves approvals off.
+  codex: {
+    permissive: {
+      file: '.codex/config.toml',
+      format: 'toml',
+      set: { approval_policy: 'never', sandbox_mode: 'danger-full-access' },
+    },
+    balanced: {
+      file: '.codex/config.toml',
+      format: 'toml',
+      set: { approval_policy: 'on-request', sandbox_mode: 'workspace-write' },
+    },
+  },
+  opencode: {
+    permissive: {
+      file: '.config/opencode/opencode.jsonc',
+      format: 'json',
+      set: { permission: 'allow' },
+    },
+    balanced: {
+      file: '.config/opencode/opencode.jsonc',
+      format: 'json',
+      set: { permission: 'ask' },
+    },
+  },
+  kimi: {
+    permissive: {
+      file: '.kimi-code/config.toml',
+      format: 'toml',
+      set: { default_permission_mode: 'yolo' },
+    },
+    balanced: {
+      file: '.kimi-code/config.toml',
+      format: 'toml',
+      set: { default_permission_mode: 'manual' },
+    },
+  },
+}
+
+function fail(reason: string): never {
+  throw new Error(`surface-policy.json is invalid: ${reason}`)
+}
+
+function assertStringArray(value: unknown, field: string): readonly string[] {
+  if (!Array.isArray(value)) fail(`${field} must be an array of strings`)
+  for (const entry of value) {
+    if (typeof entry !== 'string' || entry.length === 0) fail(`${field} must contain only non-empty strings`)
+  }
+  return value as readonly string[]
+}
+
+/**
+ * Reads and validates the policy. Every failure throws — there is no built-in
+ * default to fall back to, because a silent default here would quietly set a
+ * permission posture nobody chose.
+ */
+export function loadSurfacePolicy(options: { readonly raw?: string; readonly path?: string } = {}): SurfacePolicy {
+  const text = options.raw ?? readFileSync(options.path ?? SURFACE_POLICY_PATH, 'utf8')
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch (error) {
+    fail(`not parseable as JSON (${error instanceof Error ? error.message : String(error)})`)
+  }
+
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) fail('the top level must be an object')
+  const raw = parsed as Record<string, unknown>
+
+  const posture = raw.posture
+  if (typeof posture !== 'string' || !(POSTURES as readonly string[]).includes(posture)) {
+    fail(`posture must be one of ${POSTURES.join(', ')}`)
+  }
+
+  const overridesRaw = raw.overrides ?? {}
+  if (typeof overridesRaw !== 'object' || overridesRaw === null || Array.isArray(overridesRaw)) {
+    fail('overrides must be an object')
+  }
+  const overrides: Partial<Record<PolicySurface, Posture>> = {}
+  for (const [surface, value] of Object.entries(overridesRaw as Record<string, unknown>)) {
+    if (!(POLICY_SURFACES as readonly string[]).includes(surface)) {
+      fail(`overrides names unknown surface "${surface}" (known: ${POLICY_SURFACES.join(', ')})`)
+    }
+    if (typeof value !== 'string' || !(POSTURES as readonly string[]).includes(value)) {
+      fail(`overrides.${surface} must be one of ${POSTURES.join(', ')}`)
+    }
+    overrides[surface as PolicySurface] = value as Posture
+  }
+
+  const denyRaw = raw.deny
+  if (typeof denyRaw !== 'object' || denyRaw === null || Array.isArray(denyRaw)) fail('deny must be an object')
+  const deny = denyRaw as Record<string, unknown>
+
+  return {
+    posture: posture as Posture,
+    overrides,
+    deny: {
+      paths: assertStringArray(deny.paths, 'deny.paths'),
+      nativeTools: assertStringArray(deny.nativeTools, 'deny.nativeTools'),
+    },
+  }
+}
+
+/** The posture that applies to one surface: its override if it has one, else the global posture. */
+export function postureFor(policy: Pick<SurfacePolicy, 'posture' | 'overrides'>, surface: PolicySurface): Posture {
+  return policy.overrides[surface] ?? policy.posture
+}
+
+/** Translate one posture into one surface's native config keys. */
+export function renderSurfaceMode(surface: PolicySurface, posture: Posture): SurfaceModeEdit {
+  const bySurface = TABLE[surface]
+  if (!bySurface) {
+    throw new Error(`unknown surface "${surface}" (known: ${POLICY_SURFACES.join(', ')})`)
+  }
+  const edit = bySurface[posture]
+  if (!edit) {
+    throw new Error(`unknown posture "${posture}" for surface "${surface}" (known: ${POSTURES.join(', ')})`)
+  }
+  return edit
+}
+
+/** Every surface's rendered edit under the policy — what the cascade writes. */
+export function renderAll(policy: SurfacePolicy): ReadonlyArray<{ readonly surface: PolicySurface } & SurfaceModeEdit> {
+  return POLICY_SURFACES.map((surface) => ({ surface, ...renderSurfaceMode(surface, postureFor(policy, surface)) }))
+}
+
+// ---------------------------------------------------------------------------
+// Writing the cascade into real config files.
+//
+// These files belong to the surfaces, not to us: they carry provider API keys,
+// OAuth blocks, MCP tables, managed hook marker regions and (for OpenCode)
+// comments. So each writer sets only the keys posture owns and leaves every
+// other byte alone. That rules out parse-and-re-serialise for the TOML and
+// JSONC paths — it would drop comments and reorder the user's file while still
+// producing something technically valid.
+// ---------------------------------------------------------------------------
+
+export interface ApplyResult {
+  readonly surface: PolicySurface
+  /** Absolute path of the config that was (or would be) written. */
+  readonly path: string
+  readonly changed: boolean
+  /** True when the surface's config does not exist; nothing is ever created. */
+  readonly missing: boolean
+}
+
+/** Index of the first table header (`[table]`), i.e. the end of the root scope. */
+function rootScopeEnd(lines: readonly string[]): number {
+  const index = lines.findIndex((line) => /^\s*\[/.test(line))
+  return index === -1 ? lines.length : index
+}
+
+/**
+ * Set top-level `key = "value"` pairs in TOML.
+ *
+ * Root scope only: a key of the same name inside a table (`[features] hooks`,
+ * Kimi's `[models."..."] provider`) must never be touched, so the search stops
+ * at the first table header.
+ */
+function setTomlRootKeys(text: string, set: Readonly<Record<string, string>>): string {
+  const lines = text.split('\n')
+
+  for (const [key, value] of Object.entries(set)) {
+    const rendered = `${key} = ${JSON.stringify(value)}`
+    const limit = rootScopeEnd(lines)
+    const pattern = new RegExp(`^\\s*${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*=`)
+
+    let found = false
+    for (let index = 0; index < limit; index += 1) {
+      if (pattern.test(lines[index]!)) {
+        lines[index] = rendered
+        found = true
+        break
+      }
+    }
+    if (found) continue
+
+    // Absent: append at the end of the root scope, so it stays above the first
+    // table where TOML requires it. Walk back over blank lines AND comment
+    // lines: a comment block sitting directly above a table header introduces
+    // that table, so inserting below it would land inside the block — for a
+    // managed region like `# BEGIN ADL KIMI HOOKS` that means writing our
+    // key into someone else's delimited, drift-checked territory.
+    let insertAt = limit
+    while (insertAt > 0) {
+      const previous = lines[insertAt - 1]!.trim()
+      if (previous !== '' && !previous.startsWith('#')) break
+      insertAt -= 1
+    }
+    lines.splice(insertAt, 0, rendered)
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Set a root-level `"key": "value"` in JSON or JSONC by line, so comments and
+ * formatting survive. Only top-level scalar keys are addressed this way.
+ */
+function setJsoncRootKey(text: string, key: string, value: string): string {
+  const lines = text.split('\n')
+  const pattern = new RegExp(`^(\\s*)"${key}"\\s*:\\s*(.*)$`)
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = pattern.exec(lines[index]!)
+    if (match === null) continue
+    // Preserve whatever followed the value: a trailing comma, a line comment.
+    const trailing = match[2]!.trimEnd().endsWith(',') ? ',' : ''
+    lines[index] = `${match[1]}"${key}": ${JSON.stringify(value)}${trailing}`
+    return lines.join('\n')
+  }
+
+  // Absent: insert directly after the opening brace. A trailing comma is
+  // correct because an object that lacked this key still has content after it;
+  // the empty-object case would be invalid JSON to begin with.
+  const open = lines.findIndex((line) => line.trim().endsWith('{'))
+  if (open === -1) throw new Error('cannot set a root key: no opening brace found')
+  const indent = /^(\s*)/.exec(lines[open + 1] ?? '')?.[1] ?? '  '
+  lines.splice(open + 1, 0, `${indent}"${key}": ${JSON.stringify(value)},`)
+  return lines.join('\n')
+}
+
+/** Set a `/`-separated pointer inside a parsed JSON object, creating containers as needed. */
+function setJsonPointer(root: Record<string, unknown>, pointer: string, value: string): void {
+  const parts = pointer.split('/')
+  let cursor = root
+  for (const part of parts.slice(0, -1)) {
+    const next = cursor[part]
+    if (typeof next !== 'object' || next === null || Array.isArray(next)) cursor[part] = {}
+    cursor = cursor[part] as Record<string, unknown>
+  }
+  cursor[parts[parts.length - 1]!] = value
+}
+
+/** Apply one surface's posture to its config under `home`. */
+export function applySurfaceMode(
+  home: string,
+  surface: PolicySurface,
+  posture: Posture,
+  options: { readonly dryRun?: boolean } = {},
+): ApplyResult {
+  const edit = renderSurfaceMode(surface, posture)
+  const path = join(home, edit.file)
+
+  if (!existsSync(path)) {
+    // Never create it: a surface with no global config is one the user may
+    // have deliberately uninstalled, and this project's whole job has been
+    // REMOVING unmanaged surfaces, not conjuring them.
+    return { surface, path, changed: false, missing: true }
+  }
+
+  const before = readFileSync(path, 'utf8')
+  let after: string
+
+  if (edit.format === 'toml') {
+    after = setTomlRootKeys(before, edit.set)
+  } else if (edit.file.endsWith('.jsonc')) {
+    after = Object.entries(edit.set).reduce((text, [key, value]) => setJsoncRootKey(text, key, value), before)
+  } else {
+    const parsed = JSON.parse(before) as Record<string, unknown>
+    for (const [pointer, value] of Object.entries(edit.set)) setJsonPointer(parsed, pointer, value)
+    after = `${JSON.stringify(parsed, null, 2)}\n`
+  }
+
+  const changed = after !== before
+  if (changed && options.dryRun !== true) writeFileSync(path, after)
+  return { surface, path, changed, missing: false }
+}
+
+/** Apply the whole policy: every surface, each at its resolved posture. */
+export function applySurfacePolicy(
+  home: string,
+  policy: Pick<SurfacePolicy, 'posture' | 'overrides'>,
+  options: { readonly dryRun?: boolean } = {},
+): readonly ApplyResult[] {
+  return POLICY_SURFACES.map((surface) => applySurfaceMode(home, surface, postureFor(policy, surface), options))
+}
+
+// ---------------------------------------------------------------------------
+// CLI — what `bin/reconcile` shells out to on every machine.
+//
+// Contract mirrors the other machine-global deployers (kimi-hooks,
+// global-agents): `--home` absolute, `--mode plan` reads only, `--mode apply`
+// writes. It never creates a surface's config file, so a machine without a
+// given surface installed simply reports it skipped instead of acquiring one.
+// ---------------------------------------------------------------------------
+
+function parseArguments(argv: readonly string[]): { readonly home: string; readonly mode: 'plan' | 'apply' } {
+  let home: string | null = null
+  let mode: string | null = null
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index]
+    if (flag === '--home') {
+      home = argv[index + 1] ?? null
+      index += 1
+    } else if (flag === '--mode') {
+      mode = argv[index + 1] ?? null
+      index += 1
+    } else {
+      throw new Error(`unknown argument: ${flag}`)
+    }
+  }
+
+  if (home === null) throw new Error('--home is required')
+  if (!isAbsolute(home)) throw new Error(`--home must be absolute: ${home}`)
+  if (mode !== 'plan' && mode !== 'apply') throw new Error(`--mode must be plan or apply (got ${mode ?? 'nothing'})`)
+  return { home, mode }
+}
+
+function main(argv: readonly string[]): number {
+  let parsed: { home: string; mode: 'plan' | 'apply' }
+  try {
+    parsed = parseArguments(argv)
+  } catch (error) {
+    console.error(`surface-policy: ${error instanceof Error ? error.message : String(error)}`)
+    return 2
+  }
+
+  const policy = loadSurfacePolicy()
+  const results = applySurfacePolicy(parsed.home, policy, { dryRun: parsed.mode === 'plan' })
+
+  console.log(`surface-policy: mode=${parsed.mode} home=${parsed.home} posture=${policy.posture}`)
+  for (const result of results) {
+    const posture = postureFor(policy, result.surface)
+    if (result.missing) {
+      console.log(`  ${result.surface}: skipped, no config at ${result.path}`)
+    } else if (result.changed) {
+      console.log(`  ${result.surface}: ${parsed.mode === 'plan' ? 'would set' : 'set'} ${posture} in ${result.path}`)
+    } else {
+      console.log(`  ${result.surface}: already ${posture}`)
+    }
+  }
+  return 0
+}
+
+if (import.meta.main) process.exit(main(process.argv.slice(2)))

package/packages/agent-settings/surface-policy.json

@@ -0,0 +1,20 @@
+{
+  "schema": 1,
+  "posture": "permissive",
+  "overrides": {
+    "claude": "balanced"
+  },
+  "deny": {
+    "paths": [
+      "enact-vps"
+    ],
+    "nativeTools": [
+      "Grep",
+      "grep",
+      "Glob",
+      "glob",
+      "Search",
+      "search"
+    ]
+  }
+}

package/packages/agent-skills/assets/code-review/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: code-review
+description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/PRD asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
+disable-model-invocation: false
+---
+
+# Code Review
+Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
+
+- **Standards** — does the code conform to this repo's documented coding standards?
+- **Spec** — does the code faithfully implement the originating issue / PRD / spec?
+
+Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
+
+## Use When
+
+- The user wants to review a branch, a PR, or work-in-progress changes against a fixed point.
+- The user asks to "review since X" (a commit, branch, tag, or merge-base).
+
+## Do Not Use When
+
+- There is no fixed point to diff against and the user won't supply one (pin one first, see Process step 1), or the work isn't implemented yet so there's no diff to review — use `implement` first.
+
+The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if `docs/agents/issue-tracker.md` is missing.
+
+## Process
+
+### 1. Pin the fixed point
+
+Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it.
+
+Capture the diff command once: `git diff <fixed-point>...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log <fixed-point>..HEAD --oneline`.
+
+Before going further, confirm the fixed point resolves (`git rev-parse <fixed-point>`) and the diff is non-empty. A bad ref or empty diff should fail here — not inside two parallel sub-agents.
+
+### 2. Identify the spec source
+
+Look for the originating spec, in this order:
+
+1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
+2. A path the user passed as an argument.
+3. A PRD/spec file under `docs/`, `specs/`, or `.adl/` matching the branch name or feature.
+4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available".
+
+### 3. Identify the standards sources
+
+Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`.
+
+On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it:
+
+- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.
+- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation — and, like any standard here, skip anything tooling already enforces.
+
+Each smell reads *what it is* → *how to fix*; match it against the diff:
+
+- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
+- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
+- **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies.
+- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
+- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
+- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
+- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
+- **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
+- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
+- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
+- **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.
+- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
+
+### 4. Spawn both sub-agents in parallel
+
+Send a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both.
+
+**Standards sub-agent prompt** — include:
+
+- The full diff command and commit list.
+- The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full — the sub-agent has no other access to it.
+- The brief: "Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words."
+
+**Spec sub-agent prompt** — include:
+
+- The diff command and commit list.
+- The path or fetched contents of the spec.
+- The brief: "Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
+
+If the spec is missing, skip the Spec sub-agent and note this in the final report.
+
+### 5. Aggregate
+
+Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see _Why two axes_).
+
+End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
+
+## Why two axes
+
+A change can pass one axis and fail the other:
+
+- Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**
+- Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**
+
+Reporting them separately stops one axis from masking the other.

package/packages/agent-skills/assets/codebase-design/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: codebase-design
+description: Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
+disable-model-invocation: false
+---
+
+# Codebase Design
+
+Design **deep modules**: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is being designed or restructured. The aim is reach for callers, locality for maintainers, and testability for everyone.
+
+## Use When
+
+- Designing or reviewing a module's interface, deciding where a seam should go, or hunting for deepening opportunities.
+- Making code more testable or AI-navigable, or another skill needs the deep-module vocabulary (module, interface, depth, seam, adapter).
+
+## Do Not Use When
+
+- There is no interface or seam decision to make — a pure data fix, a copy change, or a config tweak with no module boundary involved.
+
+## Glossary
+
+Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
+
+**Module** — anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. _Avoid_: unit, component, service.
+
+**Interface** — everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. _Avoid_: API, signature (too narrow — they refer only to the type-level surface).
+
+**Implementation** — what's inside a module, its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
+
+**Depth** — reach at the interface: the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface, **shallow** when the interface is nearly as complex as the implementation.
+
+**Seam** _(Michael Feathers)_ — a place where you can alter behaviour without editing in that place; the *location* at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. _Avoid_: boundary (overloaded with DDD's bounded context).
+
+**Adapter** — a concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).
+
+**Reach** — what callers get from depth: more capability per unit of interface they learn. One implementation pays back across N call sites and M tests.
+
+**Locality** — what maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place rather than spreading across callers. Fix once, fixed everywhere.
+
+## Deep vs shallow
+
+**Deep module** = small interface + lots of implementation:
+
+```
+┌─────────────────────┐
+│   Small Interface   │  ← Few methods, simple params
+├─────────────────────┤
+│                     │
+│  Deep Implementation│  ← Complex logic hidden
+│                     │
+└─────────────────────┘
+```
+
+**Shallow module** = large interface + little implementation (avoid):
+
+```
+┌─────────────────────────────────┐
+│       Large Interface           │  ← Many methods, complex params
+├─────────────────────────────────┤
+│  Thin Implementation            │  ← Just passes through
+└─────────────────────────────────┘
+```
+
+When designing an interface, ask:
+
+- Can I reduce the number of methods?
+- Can I simplify the parameters?
+- Can I hide more complexity inside?
+
+## Principles
+
+- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
+- **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
+- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.
+
+## Designing for testability
+
+Good interfaces make testing natural: accept dependencies instead of creating them, return results instead of producing side effects, and keep the surface small. See [references/TESTABILITY.md](references/TESTABILITY.md) for the three practices with testable/hard-to-test code examples.
+
+## Relationships
+
+- A **Module** has exactly one **Interface** (the surface it presents to callers and tests).
+- **Depth** is a property of a **Module**, measured against its **Interface**.
+- A **Seam** is where a **Module**'s **Interface** lives.
+- An **Adapter** sits at a **Seam** and satisfies the **Interface**.
+- **Depth** produces **Reach** for callers and **Locality** for maintainers.
+
+## Rejected framings
+
+- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-reach instead.
+- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know.
+- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**.
+
+## Going deeper
+
+- **Deepening a cluster given its dependencies** — see [references/DEEPENING.md](references/DEEPENING.md): dependency categories, seam discipline, and replace-don't-layer testing.
+- **Exploring alternative interfaces** — see [references/DESIGN-IT-TWICE.md](references/DESIGN-IT-TWICE.md): spin up parallel sub-agents to design the interface several radically different ways, then compare on depth, locality, and seam placement.