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

package/packages/fleet/systemd/adl-azure-agent-update.service

@@ -0,0 +1,13 @@
+[Unit]
+Description=Request latest stable Azure Pipelines agent for the Default pool
+After=network-online.target adl-global-tools.service
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+WorkingDirectory=/root/enact-vps
+Environment=HOME=/root
+Environment=AZURE_CONFIG_DIR=/root/.azure
+Environment=XDG_CACHE_HOME=/root/.cache
+ExecStart=/root/enact-vps/bin/update-azure-agent-pool /root/enact-vps/packages/fleet/manifest.json
+TimeoutStartSec=10m

package/packages/fleet/systemd/adl-azure-agent-update.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=Request Azure Pipelines agent updates every six hours
+
+[Timer]
+OnCalendar=*-*-* 01,07,13,19:10:00
+Persistent=true
+Unit=adl-azure-agent-update.service
+
+[Install]
+WantedBy=timers.target

package/packages/repo-controls/AGENTS.md

@@ -0,0 +1,96 @@
+## Repository ownership
+
+**Where a file lives decides which repo owns the rule that governs it.**
+
+| Location | Owner |
+| --- | --- |
+| Under `$HOME` or `/usr/local` | `enact-vps` |
+| Inside a repo, about agents | `adl-extensions` |
+| Inside a repo, about git or workflow | `adl-repo-controls` |
+
+Work in your own cwd. If a change belongs to another repo, raise it there — do
+not reach across.
+
+### The shared config file — decided, in progress
+
+`adl-config.toml` at the repo root, its presence marking a repo
+adl-hook-managed. It HARDCUT-replaced `.agents/enact-repo.toml` and
+`.workflows/repo-controls.toml`. **Live since 2026-09-15** — `loadConfig` reads
+`<repo>/adl-config.toml` and both old markers are gone.
+
+Root tables are flat, each with one owner: `version`/`hooks`/`rules`/`repo`
+belong to `adl hook`, `skills` to `adl-extensions`, `controls` to
+`adl-repo-controls`.
+
+Two rules bind every writer:
+
+1. **No tool parses another tool's table** — not even to validate it.
+2. **Never rewrite the whole document.** Parse-and-reserialize destroys comments
+   and tables the writer does not understand. Do text-level surgery on your own
+   block only.
+
+### This repo — repo-local workflow and git conventions
+
+**Rebuilt on `main`** as enact-m5's git workflow controls with a global CLI. No
+connection to `enact-vps`.
+
+- Global npm CLI `adl-repo-controls`: `install` / `uninstall` / `doctor --repo`,
+  `hook <name>`, `run <…>`. Requires bun ≥ 1.4 and bash ≥ 4.
+- **Distributed via Azure Artifacts, internal only — never the public npm
+  registry.** The package is not marked private (Tarun: no secrets in the
+  package, publishing is fine); it is a deliberate decision, not an oversight —
+  the Azure Artifacts distribution is the intended channel regardless.
+
+**This repo's own layout versus what it writes.** Package-owned hook sources
+live under `scripts/hooks/`; commit `20ec790` removed the former
+`scripts/verbatim/` mirror and its manifest when mechanism moved into the
+package. The `.workflows/hooks/` stubs, the `.adl/logs/{repo-controls,
+hooks-deny}.log` JSON-Lines streams (written via `adl-repo-controls log`,
+`src/hook-log.ts` — `.enact/logs/` is a 2026-09-27 hard cut, no longer
+written) and the `core.hooksPath` setting are what `install --repo` wires in
+**target** repos.
+
+**Rule values are defaults, not universals.** The bundled defaults are enact-m5's:
+branch prefixes `feat|fix|docs|chore`, protected `main` and `integration`,
+lowercase kebab-case descriptions, lowercase commit subject with an 80-character
+limit and a fixed type list, plus the coverage ratchet and the behind-origin push
+check. Per-repo values are config-driven, in `adl-config.toml`'s `[controls]`
+table. Installing seeds `branches` and `pre_push.remote` only and arms no gate;
+every other control is absent and therefore off until someone adds it.
+
+**`doctor --repo` must detect a dangling `core.hooksPath`.** If the directory it
+points at is missing, git silently runs no hooks and does not error. That is the
+canonical presence-is-not-armedness case, and enact-m5 is currently in exactly
+that state as a deliberate test fixture — detection is the pass criterion, not
+repair.
+
+Git hooks, the coverage ratchet and the push checks originated in enact-m5.
+Commit `20ec790` is the hard cut that removed the byte-copy model; current
+behaviour is package-owned and locked by the hook end-to-end and focused unit
+tests, so a change is reviewed as product code rather than a manifest delta.
+
+`[controls]` is **written once** on first install and never touched again, so
+other tools' bytes and comments survive by construction.
+
+enact-m5's commit-msg, coverage-ratchet and azdo-push checks have already moved
+here.
+
+### Conventions
+
+- **Scratch work goes in `.scratchpad/`** at the repo root — never `/tmp` or
+  `/private/tmp`.
+- **Two logs, deliberately separate:** a deny log where every row is something
+  blocked, and an activity log recording every invocation with the rule that
+  fired. Mixing routine passes into the deny log buries the signal.
+
+### Presence is not armedness
+
+A file existing, a block being present, a tool being on `PATH` — none of these
+establish that the gate runs. Real instances from this system: a `core.hooksPath`
+pointing at a renamed directory, which git silently ignores; a Cursor matcher
+naming a tool that does not exist, so the guard never fires; MCP servers losing
+`required`, turning a fatal failure into a silent degrade; lean-ctx resolving
+built-in defaults instead of the repo config; a binary never rebuilt because the
+check compared only a version string. Each looked configured. None were running.
+
+Verify a gate by its own mechanism, never by a file being present.

package/packages/repo-controls/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/packages/repo-controls/LICENSE

@@ -0,0 +1,20 @@
+Proprietary License
+
+Copyright (c) 2026 Amsterdam Data Labs B.V.
+
+All rights reserved.
+
+This software and its accompanying source code, documentation and configuration
+are the confidential and proprietary property of Amsterdam Data Labs B.V..
+
+No part of this work may be reproduced, copied, modified, distributed,
+published, sublicensed or transmitted in any form or by any means, electronic
+or mechanical, without the prior written permission of the copyright holder.
+
+Unauthorised use, reproduction or distribution of this work, or any portion of
+it, is a breach of that copyright and may result in civil and criminal
+penalties.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

package/packages/repo-controls/README.md

@@ -0,0 +1,493 @@
+# adl-repo-controls
+
+Repo-local **git workflow conventions** — the enact-m5 git hooks, commit-message
+rules, coverage ratchet, push checks and CI hygiene scripts — packaged as one
+global binary and installed into any repository through git's own
+`core.hooksPath`.
+
+Scope: workflow/git conventions only. Agent setup lives in adl-extensions;
+the agent guard lives in adl hook. No lefthook, no husky, no npm lifecycle magic.
+
+## How it works
+
+```
+target repo (committed)                      adl (fleet-installed; see below)
+.workflows/hooks/pre-commit    ─┐             adl repo controls hook <name>
+.workflows/hooks/commit-msg     ├─ sh stub ──▶    ├─ validates adl-config.toml [controls]
+.workflows/hooks/pre-push       │  exec           ├─ checks bash >= 4
+.workflows/hooks/post-commit    │                 └─ runs scripts/hooks/<name>
+.workflows/hooks/post-checkout ─┘
+adl-config.toml [controls]   (config, shared file — see below)   (package-owned script, config via env)
+.workflows/repo-controls.lock.json (hashes)
+local .git/config: core.hooksPath = .workflows/hooks
+```
+
+- **Stubs** are POSIX `sh`, contain no paths, and fail loudly (with the install
+  command) when `adl` is not on `PATH` — never a silent skip. This package is
+  folded into the `adl` binary's `repo controls` namespace
+  (docs/architecture/cli-design.md §6, STATUS.md item 10); it is never itself a
+  standalone global command — hard cut, no `adl-repo-controls` compat shim
+  (adl-m3-finish item 1, 2026-09-27).
+- **Bundled scripts** in `scripts/hooks/` are package-owned implementations.
+  They originated in enact-m5; commit `20ec790` removed the former byte-copy
+  tree and manifest when mechanism moved into this package. Their current
+  behaviour is exercised by `tests/hooks-e2e.test.ts` and focused unit tests.
+- **Logs** (gitignored): `.adl/logs/repo-controls.log` gets a JSON-Lines row
+  for every hook invocation; `.adl/logs/hooks-deny.log` gets only `FAIL`
+  rows — shared with agent-hooks' own PreToolUse denies, so a human `git
+  commit` denial and an agent's blocked shell command land in one timeline.
+  Written via `adl repo controls log` (`src/hook-log.ts`), the same shared
+  `writeLogEntry` format every `.adl/logs/*.log` file uses
+  (docs/architecture/cli-design.md §5a). `.enact/logs/` is a hard cut: nothing writes
+  there any more; pre-existing evidence is left in place, never migrated.
+
+## Hooks and gates: what runs where
+
+`doctor` proves two different kinds of thing, and they run in two different
+hooks (Tarun, 2026-09-28 — this split replaced a live bug where an ordinary
+local `git commit` failed on a missing Agent Vault credential it should never
+have needed):
+
+- **`pre-commit`** runs `doctor` with the Azure DevOps promotion-governance
+  checks EXCLUDED (`azure-devops.remote`, `azure-devops.policy-read`,
+  `azure-devops.minimum-review`, `azure-devops.build-policy`). Every other
+  doctor check — the local hook surface, `adl-config.toml`, the lock, `bash`/
+  `bun`/`adl` on PATH — stays here, unchanged: these are offline and a commit
+  must never require network access or a minted token to succeed.
+- **`pre-push`** runs the Azure DevOps promotion-governance checks alone,
+  fail-closed by name, same contract as every other doctor check: unreadable
+  evidence blocks the push, never a warning, never a silent pass. A push
+  already requires network access to the remote, so a network + token
+  requirement here is not a new cost the way it would be at commit time.
+- **A bare `adl-repo-controls doctor` run** (not through either hook) keeps
+  reporting everything, exactly as before — this split only changes which
+  hook exercises which checks, never what `doctor` itself is capable of
+  reporting.
+
+See `src/doctor.ts`'s `azureDevOpsPromotionGovernanceChecks` (the checks,
+factored out of `doctor()` so pre-push can run them alone) and `src/hook.ts`'s
+`azureDevOpsPromotionGovernanceGate` (the pre-push gate) plus `runHook`'s
+`pre-commit`/`pre-push` wiring. `tests/doctor-gate.test.ts` proves both halves:
+a release-configured pre-commit commits successfully with no network-capable
+binary on `PATH` at all, and pre-push blocks by name when the token mint
+fails and permits the push once it succeeds.
+
+## Worktree-count backstop (`post-checkout`)
+
+`MAX_WORKTREES` (`src/constants.ts`) is `3` — a repository may have at most 3
+`git worktree list` entries at once, **counting the main working tree
+itself**, so at most 2 linked worktrees beyond the main checkout.
+
+Git has no pre-worktree hook — nothing runs *before* `git worktree add`
+creates the checkout. `post-checkout` is the earliest hook it actually fires
+(inside the *new* worktree, with the previous-HEAD argument set to the
+all-zero OID and the branch-checkout flag set to `1` — see
+`src/worktree-guard.ts`'s header for the full signature, including how it
+tells a `worktree add` apart from an ordinary `git clone`'s own first
+checkout). So "deny" here means: let the worktree get created, count what
+`git worktree list --porcelain` now reports, and if that is over the limit,
+actively run `git worktree remove --force <path>` on the just-created
+worktree — from the *main* worktree, since git refuses to remove the
+worktree a process's own cwd is inside — then exit non-zero. `git worktree
+add` itself then reports failure, and no 4th worktree survives on disk.
+
+Branch deletion (`git worktree add -b <branch>`) is **never** attempted: by
+the time `post-checkout` runs, the branch ref already exists, indistinguishable
+here from a branch that existed before and was merely checked out into a new
+worktree. Only the worktree directory and its registration are removed; the
+branch is always left in place.
+
+This is the backstop for a **human** running `git worktree add` directly, or
+for any agent path the hook-engine in `packages/agent-hooks` cannot see.
+Agent-driven worktree creation itself is denied outright (not merely
+limited) by that package's `git.worktree` rule, on every surface it can
+observe (shell commands *and* native tools like Claude Code's `EnterWorktree`
+or a `Task`/`Agent` launch with `isolation: "worktree"`) — see
+[`../agent-hooks/README.md`](../agent-hooks/README.md).
+
+## Requirements
+
+- **bun >= 1.4** on `PATH` — runtime of the CLI and of the bundled enact-m5
+  TypeScript scripts (coverage ratchet, push lock, `azure-devops-push.ts` all use
+  `Bun.*` / `bun:sqlite`).
+- **bash >= 4** first on `PATH` — the enact-m5 scripts use `${var,,}` (commit-msg) and `mapfile`
+  (repo-hygiene). macOS ships `/bin/bash` 3.2: install a newer bash
+  (`brew install bash`) and make sure GUI git clients see it. `doctor` and every
+  `hook` run check this and fail loudly on 3.x.
+- git, and npm only to install the package.
+- **`adl-agent-id` + `adl`** — only when `[controls.release]` is declared, and
+  only for a `doctor` run or `pre-push` (never `pre-commit` — see "Hooks and
+  gates: what runs where" below). The Azure DevOps promotion-governance checks
+  authenticate as the session's own agent identity (Tarun, 2026-09-28,
+  replacing a retired per-vault env file this package used to read directly):
+  `ADL_AGENT_ID_AGENT` from the environment when set (an `adl run` session, or
+  the fleet's managed shell rc exporting it from the machine default-agent
+  file), else the machine default-agent file itself — the identical fallback
+  `adl run` uses when `--as` is omitted. Neither present is a named failure,
+  never a silent default identity. The resolved agent is handed to
+  `adl-agent-id exec --agent <agent> -- adl id token <agent> --json`, the same
+  two-hop exec `bin/git-ado` and `packages/azdo` use for every other credentialed
+  Azure DevOps call; this package never sees the vault proxy, a CA, or a client
+  secret — only the finished bearer token, confined to the child process that
+  reads the target branch's remote policies. See
+  `docs/operations/agent-vault-environment.md` for the host-side broker
+  contract underneath `adl-agent-id`/`agent-vault` itself.
+- **uv** — only if `[controls.compliance].enabled` is non-empty; see below.
+- **ast-grep** — optional; only 3 of the compliance registry's 93 checks use it,
+  and the Python runner degrades those specific rows gracefully (not a hard failure)
+  when it is absent. `doctor` warns, never fails, on a missing `ast-grep`.
+
+### Why bun (and not node)
+
+This package is never distributed standalone (adl-m3-finish item 1/2, 2026-09-27):
+`adl repo controls <command>` folds it into the one `adl` binary
+(docs/architecture/cli-design.md §6), which the fleet installs via `bin/reconcile`'s
+`bun-compile` manager; `apps/cli/src/commands/repo-controls.ts` resolves this
+package's own unmodified root — this checkout's `packages/repo-controls`, or
+`bin/reconcile`'s `repo-dir`-synced copy at `<libexec>/repo-controls` — and runs
+`bin/adl-repo-controls.ts` (`src/cli.ts` only EXPORTS `main()`; it never calls
+it) as a `bun` subprocess. That indirection exists because the scripts this
+package must run verbatim are enact-m5's bun scripts (`bun
+.../coverage/command.ts`, `#!/usr/bin/env bun` push wrapper, `Bun.spawnSync`,
+`bun:sqlite`) plus real files on disk (vendored CI assets, the bundled hook
+scripts, the uv-managed compliance engine) that a single compiled binary
+cannot embed. Bun is therefore a hard runtime dependency no matter what the
+CLI is written in; writing the CLI in bun keeps **one** runtime, lets the
+`bin` entry run TypeScript directly (no build step, no `dist/` drift), and
+gives the 100% lines/functions coverage gate natively via `bunfig.toml`.
+
+### A second runtime — only if compliance is enabled
+
+`package/adl-compliance` is a separate, bundled Python project (managed by
+`uv`, which provisions its own Python 3.14+ — no system Python required). This
+is not a contradiction of the "one runtime" point above: bash ≥ 4 is *already* a
+second hard external dependency today, for the bundled enact-m5 hook scripts —
+`uv`/Python simply joins bash in that same "externally invoked bundled tool"
+category. Nothing about the CLI's own runtime changes; `adl-repo-controls`
+itself still runs in-process under bun exactly as before.
+
+`uv` is required **only** when `[controls.compliance].enabled` is non-empty (`run
+compliance` will fail loudly, naming `uv`, if it's absent and needed) — installing
+this package and running every other command (`install`, `uninstall`, `doctor`
+with compliance disabled, `hook`, and the other `run` tools) never touches it.
+
+The UI gate design and the source-to-sink proof required for genuine appearance
+centralization are documented in
+[`docs/architecture/ui-centralization-compliance.md`](docs/architecture/ui-centralization-compliance.md).
+
+## CLI
+
+```
+adl-repo-controls install   --repo <path> [--dry-run]
+adl-repo-controls uninstall --repo <path> [--dry-run]
+adl-repo-controls doctor    --repo <path> [--json]
+adl-repo-controls hook <pre-commit|commit-msg|pre-push|post-commit> [git hook args]
+adl-repo-controls log <hook-name> <reason> [context] [message]   (internal — called by the bundled hooks)
+adl-repo-controls promote --repo <path>
+adl-repo-controls run <azdo-push|coverage|repo-hygiene|validate-pr-metadata> --repo <path> [-- args]
+adl-repo-controls run compliance --repo <path> [-- <gate-id or domain.name> | --summary | --files LIST | --log-dir DIR]
+adl-repo-controls --version | help
+```
+
+**install** requires an existing root `adl-config.toml`: that is the central
+management marker. It deletes and rebuilds the complete adl-owned
+`.workflows/` root, then appends its `[controls]` table only when that table is
+missing. It appends the single shared root ignore `/.enact/logs/` and
+`/.coverage-cache/` to `.gitignore`, writes the lock, and sets
+`core.hooksPath=.workflows/hooks` with `git config --local`.
+- Re-running is state-idempotent: the rebuilt root is byte-identical.
+- `--dry-run` prints every action and changes nothing (files or git config).
+- Extra, altered, missing, and retired managed files below `.workflows/` are
+  deleted or repaired on the next install. Pre-hard-cut log evidence is kept in
+  place as quarantine; it is never read, written, copied, moved, or deleted.
+- Written files contain no absolute paths and no `$HOME`.
+
+**uninstall** removes the authoritative `.workflows/` projection and
+deactivates its hook path. Canonical logs, their root ignore, quarantined log
+evidence, and runtime caches remain. `adl-config.toml` itself is never deleted — only the
+`[controls]` span this package appended is ever spliced back out.
+
+**doctor** is read-only and exits 1 on any failure: bash >= 4, bun, binary on
+PATH, the bundled compliance package present at its packaged path, repository
+root, `[controls]` config validity, (warning) `coverage/coverage-summary.json`
+exists whenever `pre_push.coverage_ratchet` is enabled, `[controls.compliance]` config
+validity, `uv` on PATH (only checked once `[controls.compliance].enabled` is non-empty;
+otherwise reported ok unconditionally, same off-by-default posture as the
+coverage-summary check), (warning only, same conditioning) `ast-grep` on PATH,
+lock, each stub (present, unedited, executable), `core.hooksPath`, `.gitignore`
+lines, and (warning) lock version skew. When `[controls.release]` is declared,
+it also derives the configured `origin` remote, loads the validated canonical
+Agent Vault file before reading Azure DevOps, and records separate fail-closed receipts for the HTTPS handle,
+required owner reviewer, minimum-review reset, and build policy.
+
+**run** executes a bundled enact-m5 tool against the repository with the config
+exported: `azdo-push` (Azure DevOps push with push lock + behind-origin refusal),
+`coverage <check-push|prewarm-push|status|unlock|...>`, `repo-hygiene` (CI
+entrypoint), `validate-pr-metadata` (Azure PR title/description policy).
+
+**run compliance** runs the bundled `adl-compliance` Python engine (via `uv`)
+against the repository. `--root <repo>` is always injected first from `--repo`;
+once `[controls.compliance].enabled` is non-empty, `--only <the enabled list, comma-joined>`
+is injected right after it. Both are injected *before* any args given after `--`,
+so a user-supplied `--root` or `--only` there overrides the injected one — last
+flag wins, matching Python `argparse` semantics; this is intentional, not a bug to
+guard against. Everything else (a bare gate id or `domain.name` target, `--summary`,
+`--files LIST`, `--log-dir DIR`) passes straight through.
+
+## Configuration — `adl-config.toml` `[controls]`
+
+`adl-config.toml` (repository root) is a **shared file**: three separate tools
+converge their config into it, one top-level table each — `[hooks]`/`[rules]`/
+`[repo]` for `adl hook`, `[skills]` for `adl-extensions`, `[controls]` for
+this package. A bare root-level `version = 1` is a tool-agnostic marker every
+tool accepts and ignores. This package reads and writes **only its own
+`[controls]` table**; every other byte of the file (including other tools'
+comments) is opaque and is never inspected, reordered, or dropped.
+
+`adl-config.toml`'s mere presence marks a repository as adl-hook-managed —
+running `install` may effectively create that marker even if `adl hook` itself
+is not installed there. `adl-config.toml` itself is never deleted by uninstall.
+
+### Install wires the hooks. It arms nothing.
+
+`install` seeds exactly three attributes — `version`, `branches` and
+`pre_push.remote` — and **every gate is off**. A first install changes what no
+`git push` and no `git commit` does until somebody opts in. `branches` and
+`pre_push.remote` are seeded rather than omitted because they are not gates but the
+vocabulary gates are phrased in, and because `pre-push` reads their env vars with
+`${VAR:?}`, which aborts on an empty value: "no branch policy" cannot be spelled as
+an empty list.
+
+Seeding is **per attribute, and only when absent**. An attribute already in the file
+is never rewritten, reordered or reformatted, whatever its value — so re-running
+install (or a scheduled job that does) can add a missing key but can never arm,
+disarm or restyle one you set. Granularity is the top-level key inside `[controls]`:
+an inline table is one attribute, because editing inside one means rewriting bytes
+you own. Nothing is parsed and re-serialized; text is spliced into the table's span.
+
+`[controls]` is strictly validated: unknown keys and wrong types are errors. An
+**absent** optional key is its documented default, never an error.
+
+| Key | Seeded by install | Default when absent | enact-m5 | Effect |
+|---|---|---|---|---|
+| `branches.protected` | yes | *required* | `["main", "integration"]` | pre-push refuses while on these branches |
+| `branches.prefixes` | yes | *required* | `["feat", "fix", "docs", "chore"]` | pre-push / azdo-push branch pattern `<prefix>/<kebab>` |
+| `pre_push.remote` | yes | *required* | `"origin"` | remote azdo-push pushes to and reads status from |
+| `pre_commit.biome` | no | `false` | `true` | Biome format+lint on the staged index snapshot |
+| `pre_commit.staged_coverage` | no | `false` | `true` | enact-m5-only staged coverage measurement |
+| `pre_commit.doc_freshness` | no | `false` | opt in | a staged `docs/` or `plans/` `.md` carries a `last_update` stamped within 5h |
+| `pre_push.coverage_ratchet` | no | `false` | `true` | per outgoing commit, `coverage/coverage-summary.json` must exist and not regress |
+| `pre_push.findings_ratchet` | no | `false` | opt in | per outgoing commit, every declared static-analysis counter's findings must not exceed the committed floor |
+| `pre_push.static_checks` | no | `[]` | tsc, knip, svelte-check | `{ label, run }` commands run on an export of HEAD, pass cached per tree OID |
+| `release.source` | no | `""` | `"integration"` | source branch for the managed promotion PR; no branch pair is guessed |
+| `release.target` | no | `""` | `"main"` | target branch for the managed promotion PR |
+| `release.merge_strategy` | no | `"squash"` | `"no-fast-forward"` | one of `squash`, `rebase`, `rebase-merge`, or `no-fast-forward` — sent to Azure DevOps as the matching wire value (`squash`, `rebase`, `rebaseMerge`, `noFastForward`) |
+| `release.pre_bump` | no | `[]` | — | ordered, repository-relative script paths `version-bump.sh` runs from the repo root before the bump commit |
+
+### `release.pre_bump` — multi-language version bumps
+
+`version-bump.sh` only knows how to write to one JSON file's `version` field
+(`--file package.json`). A repository whose version lives somewhere else too —
+a Go `const`, a `Cargo.toml`, a generated changelog header — declares
+`pre_bump` scripts to update that second place in the SAME commit, instead of
+forking a second bump mechanism per language.
+
+Each entry is a repository-relative path (rejected if absolute or containing
+a `..` segment — the same check `[controls.integrity].watched` and
+`pre_push.export_links` already apply) to a script `version-bump.sh` runs,
+IN ORDER, with `bash`, from the repository root, after computing the next
+unpublished version and before the bump commit. A path that does not exist on
+disk is a validation error, checked for every declared script before any of
+them run — a bad declaration fails clearly instead of leaving the repo
+half-bumped.
+
+Each script sees:
+
+| Env var | Value |
+|---|---|
+| `ADL_CURRENT_VERSION` | the version being replaced |
+| `ADL_NEXT_VERSION` | the version being allocated |
+| `ADL_REPO_ROOT` | the repository root (also the script's cwd) |
+
+...and does NOT see `SYSTEM_ACCESSTOKEN`, `AZURE_DEVOPS_EXT_PAT`, or any other
+variable whose name ends `_TOKEN`, `_PAT`, `_SECRET`, or `_PASSWORD`
+(case-insensitive) — a `pre_bump` script is repository-authored and
+unreviewed by this package, and has no business seeing the pipeline's push or
+PR credentials. A script that exits non-zero aborts the whole bump: no
+commit, no push, no PR. Whatever a script writes inside the repository tree
+is staged into the SAME commit as the `package.json` bump (`git add -A` from
+the repo root, so nothing outside the repository or a script's own declared
+path is ever swept in by accident); a script that writes into `.git` itself
+(hooks, config, refs) is refused before any commit happens. There is no
+equivalent guarantee against a script writing to an absolute path outside the
+repository entirely — a plain shell script has no sandbox to enforce that,
+and this package does not claim one. No `pre_bump` declared (the key absent,
+or no `adl-config.toml` at all) is byte-identical to the behaviour before
+this key existed: nothing extra runs, nothing extra is staged.
+
+A Rust repository whose canonical version is `Cargo.toml`'s
+`[package].version`, kept in sync with `package.json` on every bump:
+
+```toml
+[controls.release]
+source = "integration"
+target = "main"
+pre_bump = ["scripts/bump-cargo-version.sh"]
+```
+
+```sh
+#!/usr/bin/env bash
+# scripts/bump-cargo-version.sh
+set -euo pipefail
+sed -i.bak -E "s/^version = \".*\"/version = \"${ADL_NEXT_VERSION}\"/" "${ADL_REPO_ROOT}/Cargo.toml"
+rm -f "${ADL_REPO_ROOT}/Cargo.toml.bak"
+```
+
+The real case this was built for: agent-identities' Go binary has no
+`package.json` version at all — its version is
+`const Version = "0.4.1"` in
+`adl-agent-id/cmd/adl-agent-id/main.go`. Its `pre_bump` script rewrites that
+line instead:
+
+```sh
+#!/usr/bin/env bash
+# scripts/bump-agentid-version.sh
+set -euo pipefail
+file="${ADL_REPO_ROOT}/adl-agent-id/cmd/adl-agent-id/main.go"
+sed -i.bak -E "s/^const Version = \".*\"/const Version = \"${ADL_NEXT_VERSION}\"/" "$file"
+rm -f "${file}.bak"
+```
+
+`install` copies two package-owned standalone CI assets byte-for-byte:
+
+- `.workflows/promote.ts`
+- `.workflows/scripts/enable-integration-auto-complete.mjs`
+
+Both installed assets are real executable files, never symlinks. Their SHA-256
+hashes live in `.workflows/repo-controls.lock.json`, and `doctor` fails if either
+file, mode, or lock entry drifts from the canonical source under `assets/`. A
+repository opts into promotion by declaring `[controls.release]` and wiring its
+pipeline to run the installed promoter with the matching branch pair and merge
+strategy. The helper creates or reuses the active PR and arms auto-complete
+without deleting the source branch or transitioning work items — it never
+names a reviewer on the PR (Tarun, 2026-09-27: naming one, typically the
+person who pushed to `integration`, is a self-approval risk and contradicts
+"agent-reviewer is optional, never required"). Before it reads or mutates PRs,
+it proves the exact target branch has enabled blocking repository-wide
+policies for at least one approval with `resetOnSourcePush = true` (the
+author's own vote does not count towards it) and a build definition; a
+missing or weaker policy fails promotion. Pre-commit calls the same read-only
+doctor report and never repairs or stages the managed surface: run
+`adl repo controls install --repo .` explicitly to repair it.
+
+`[controls.compliance]` follows the same rule: install seeds `version` and
+`enabled = []` only. `registry` and `[controls.compliance.trees]` have working
+defaults and are not written into every repository.
+
+Fixed conventions (enact-m5, not configurable): commit subject
+`^(feat|fix|docs|refactor|perf|chore|release)(\([a-z0-9][a-z0-9-]*\))?: .+`, at most 80
+characters, lowercase description without trailing period; `Merge `, `Revert "`
+and `X.Y.Z` subjects exempt; no staged `.scratchpad` paths or new references;
+`git diff --cached --check`; git environment scrubbed before push checks.
+
+### Managed dot paths and protected controls
+
+The pre-commit gate has two deliberately different outcomes:
+
+- A changed or untracked **top-level** dot path is **commit-required**.
+  When it is omitted from the index, the hook names it and tells the author to
+  stage it. Once staged, it can be committed normally. This covers centrally
+  managed paths such as `.agents/**`, `.claude/**`, `.codex/**`, `.cursor/**`,
+  `.mcp.json`, and future top-level dot paths. Nested paths such as
+  `tools/.claude/**` are ordinary repository content. The designated ephemeral
+  scratch storage is never committable.
+- A **protected control** requires human approval even when staged: every path
+  under `compliance/` or `workflows/`, `adl-config.toml`, and the repository's
+  explicit `[controls.integrity].watched` patterns. The same controls cannot be
+  left dirty while committing other work.
+
+Git cannot make a pre-commit hook run for `git commit --no-verify`. That is the
+reviewed human-only escape hatch for protected controls: `adl hook` denies
+agents' uses of that flag, while Tarun may review a protected diff and commit it
+manually with the flag. This package intentionally does not claim to enforce
+that actor boundary itself.
+
+Note: `doc_freshness` is this package's own check, not a bundled enact-m5 script —
+the verbatim `workflows/hooks/pre-commit` is untouched and the check runs in
+`runHook` before it. It carries the rule that used to be compliance row `DOC-003`
+(same 5h window, same `YYYY-MM-DDTHH:MM:SSZ` format, same exclusions), graded on
+the staged index instead of the whole `docs/` tree: as a registry row it reddened
+every page five hours after anyone touched it, which no amount of editing kept
+green. Blobs are read with `git show :<path>`, so the work-tree copy is irrelevant.
+
+Note: with `coverage_ratchet = true` every pushed commit and its parent must
+contain `coverage/coverage-summary.json` (Istanbul json-summary); commit a
+baseline first or set it to `false`.
+
+Note: with `findings_ratchet = true`, `[controls.findings]` says where the
+floor lives (`floor`, default `compliance/ratchets/static-analysis-findings.yaml`)
+and `[controls.findings.counters]` names the repository's own static-analysis
+commands — a name -> command map the repository authors itself (e.g.
+`lint = "just check-biome-lint"`), so no tool name is ever written into this
+package; only the repository's own config names one. Each counter's command
+must print one repository-relative path per line to stdout for a run that
+completed (exit 0), one line per finding location — any other exit is that
+counter failing to run, never zero findings and never a pass. The gate only
+reads: it runs every declared counter fresh and fails naming the counter and
+what regressed if its findings moved past the committed floor. It never
+writes the floor — lowering it, to record an improvement, is a change a
+human makes in the same commit as the fix, the same discipline
+`coverage-floor.json` already keeps.
+
+## Configuration — `adl-config.toml` `[controls.compliance]`
+
+`install` also appends a `[controls.compliance]` table to the same shared
+`adl-config.toml`, independently of `[controls]` (each table is its own
+append-once/user-owned-afterwards span; installing, editing, or uninstalling one
+never disturbs the other).
+
+It is nested **under** `controls` rather than being a root-level `[compliance]`,
+and that is load-bearing rather than cosmetic: `adl hook` decodes this same
+shared file and rejects the whole document on an unrecognized **root** key, so a
+root-level `[compliance]` turned every `adl hook` invocation in a repository
+carrying it into a decode error. Keeping this package's config inside the one
+root key it already owns needs no coordination with the other two tools — the
+same "no tool parses another tool's table" rule the shared file is built on.
+`tests/compliance-config.test.ts` guards this: the rendered config must only
+ever use root keys `adl hook` accepts.
+
+`[controls.compliance]` is strictly validated like `[controls]`
+— unknown keys and wrong types are errors — except `[controls.compliance.trees]`, which is
+a genuinely open string map: any key is accepted, only its value must be a
+non-empty string.
+
+| Key | Default | Effect |
+|---|---|---|
+| `version` | `1` | config schema version |
+| `enabled` | `[]` | gate ids (`RST-001`) or `domain.name` addresses (`rust.acp-boundary`) to grade; empty = installed, nothing runs |
+| `registry` | `"default"` | forward-compatible; today both values point at the same packaged registry YAML |
+| `[controls.compliance.trees]` | `{}` (no entries) | per-key path overrides; a key absent here keeps the packaged (source-shaped) default for that key |
+
+### Registry curation
+
+The full compliance registry (145 rows) always ships and loads — `enabled` is
+what decides which of those rows is ever graded, not what's present. The
+packaged `[controls.compliance.trees]` defaults are shaped after the *original* source
+repository the checks were authored against, not any arbitrary target repo. A
+repository enabling any row needs its own `[controls.compliance.trees]` overrides for
+whatever that row's scope actually needs in that repository's layout — this
+package does **not** ship a pre-vetted "safe for any repo" subset; enabling a
+row without pointing its trees at the right paths will simply grade the wrong
+(or nonexistent) files.
+
+## Development
+
+```
+bun install
+bunx tsc --noEmit
+bun test --coverage     # 100% lines + functions gate (bunfig.toml)
+```
+
+Tests run real git in temporary repositories under `.scratchpad/test-tmp/`
+(gitignored), exercising the installed stubs end to end. CI:
+`azure-pipelines.yml` (publishing present but disabled).