@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.30 → 0.1.33

package/packages/fleet/src/repo-maintain.ts

@@ -328,8 +328,8 @@ export function maintainRepositories(options: MaintainOptions): MaintainResult {
     if (maxAgeDays !== undefined) pruneStale(repo, name, current, maxAgeDays)
 
     // 5. the per-repo enrolment.
-    const argv = [...options.install.leadingArgs, 'install', '--repo', repo]
-    const shown = `adl install --repo ${repo}`
+    const argv = [...options.install.leadingArgs, 'install', '--repo', repo, '--rewire']
+    const shown = `adl install --repo ${repo} --rewire`
     if (dry) {
       info(`${name}: [dry] would run ${shown}`)
       return
@@ -341,6 +341,9 @@ export function maintainRepositories(options: MaintainOptions): MaintainResult {
       fail(`${name}: ${shown} exited ${result.status}: ${(result.stderr ?? '').trim()}`, repo)
     } else {
       info(`${name}: ${shown}: ok`)
+      for (const line of `${result.stdout}${result.stderr}`.split('\n')) {
+        if (/WARNING|FAIL|COULD-NOT-RUN/.test(line)) warn(`${name}: ${line.trim()}`)
+      }
     }
   }
 

package/packages/repo-controls/AGENTS.md

@@ -44,19 +44,22 @@ connection to `enact-vps`.
 **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`,
+package. The `.workflows/hooks/` stubs, the `.adl/logs/git-hooks/{activity,
+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`,
+branch prefixes fixed to the commit types minus `release` (`packages/azdo/src/lib/commit-types.ts`), protected `main` and `integration`,
 lowercase kebab-case descriptions, lowercase commit subject with an 80-character
 limit and a fixed type list, plus the coverage ratchet and the behind-origin push
 check. Per-repo values are config-driven, in `adl-config.toml`'s `[controls]`
-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.
+table. Installing seeds `branches` and `pre_push.remote` for `[controls]` and arms no
+push or commit gate there; every other `[controls]` key is absent and therefore off
+until someone adds it. `[controls.compliance]` is the opposite: install seeds the standard
+trees and arms the strict gate set (see
+`docs/architecture/compliance-controls.md#strict-activation-and-switching-a-gate-off`).
 
 **`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

package/packages/repo-controls/README.md

@@ -33,12 +33,10 @@ local .git/config: core.hooksPath = .workflows/hooks
   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
+- **Logs** (gitignored): `.adl/logs/git-hooks/activity.log` gets a JSON-Lines row
+  for every hook invocation; `.adl/logs/git-hooks/deny.log` gets only `FAIL`
+  rows. Written via `adl repo controls log` (`src/hook-log.ts`), the same shared
+  `writeLogEntry` format every `.adl/logs/<owner>/*.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.
 
@@ -186,9 +184,9 @@ or a `Task`/`Agent` launch with `isolation: "worktree"`) — 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`.
+- **ast-grep** and **shfmt** — only REP-007 (`no_multiline_comments`) requires
+  them (`requires` in `package/adl-compliance/src/adl_compliance/checks/repository/no_multiline_comments/check.py`).
+  `doctor` warns, never fails, on a missing `ast-grep`.
 
 ### Why bun (and not node)
 
@@ -251,8 +249,9 @@ reading those mtimes) — a path whose content is already byte- and
 mode-identical is left alone untouched, and anything else (missing,
 altered, or retired) is still deleted or repaired. It 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
+one marker-bounded block to `.gitignore` (`/.adl/`, the agent scratch folder,
+`/.coverage-cache/` and the retired log roots kept as quarantine; the list is
+`src/gitignore-block.ts`), writes the lock, and sets `core.hooksPath=.workflows/hooks` with
 `git config --local`.
 - Re-running is a true no-op: the rebuilt root is byte-identical AND no
   managed file's mtime changes when nothing needed correcting.
@@ -276,15 +275,14 @@ merge into `integration`) runs.
 
 **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 (`coverage_ratchet`
-defaults ON; the gate is a no-op until the file lands, so this is informational
-rather than blocking), (warning) `pre_push.coverage_produce` enabled with no
-`[controls.coverage].produce_push` declared (the push gate fails loud there, so
-doctor names it first), `[controls.compliance]` config validity, `uv` on PATH
+root, `[controls]` config validity, (fail) `coverage/coverage-summary.json`
+exists whenever `pre_push.coverage_ratchet` is enabled, (fail)
+`pre_push.coverage_produce` enabled with no `[controls.coverage].produce_push`
+declared, (fail) the findings floor and counters whenever `pre_push.findings_ratchet`
+is enabled (see "No silent skips" below), `[controls.compliance]` config validity, `uv` on PATH
 (only checked once `[controls.compliance].enabled` is non-empty; otherwise
 reported ok unconditionally, same on-by-default posture as the coverage-summary
-check), (warning only, same conditioning) `ast-grep` on PATH, lock, each stub
+check), (fail, 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
@@ -350,12 +348,24 @@ comments) is opaque and is never inspected, reordered, or dropped.
 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
+### Install wires the hooks, then arms the strict compliance set
+
+`install` seeds the `[controls]` vocabulary (`version`, `branches`,
+`pre_push.remote`) and arms **no push or commit gate** of its own: the
+`[controls]` gates below are absent until somebody adds them. Compliance is the
+opposite. `install` seeds `[controls.compliance]` strict: the standard trees, the
+strict `enabled` set, the folder skeleton, the root entry files and printed
+guidance (see [Compliance seeding](#compliance-seeding) below). The decisions
+and the gate list live in
+[`docs/architecture/compliance-controls.md`](../../docs/architecture/compliance-controls.md#strict-activation-and-switching-a-gate-off).
+`install --rewire` (what fleet reconcile runs on every enrolled repo) seeds nothing,
+scaffolds nothing and does not grade: it only re-deploys the hook stubs, `.workflows`
+and the lock, and leaves adl-config.toml byte-identical. Without `uv`, the `adl install`
+wrapper prints a one-line warning that grading is skipped, finishes deploying and exits 0;
+pre-commit still fails loudly without `uv`. See
+[`docs/architecture/compliance-controls.md`](../../docs/architecture/compliance-controls.md#install-and-re-wire).
+
+`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.
@@ -367,24 +377,23 @@ disarm or restyle one you set. Granularity is the top-level key inside `[control
 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** key takes its documented default, never an error. Most gates default
-ON; the matching `[controls.<gate>]` keys are what configure them. A gate whose
-wrapper is ON but whose configuration is missing is a no-op at hook time and a
-*warning* at `doctor` time — informational, never blocking.
+`[controls]` is strictly validated: unknown keys, wrong types and missing gate keys are
+errors. A gate key has no default: an absent one fails config load naming the key, and a
+gate is switched off by an explicit `false`. See "No silent skips" below.
 
-| Key | Seeded by install | Default when absent | enact-m5 | Effect |
+| Key | Seeded by install | When absent | enact-m5 | Effect |
 |---|---|---|---|---|
 | `branches.protected` | yes | *required* | `["main", "integration"]` | pre-push refuses while on these branches |
-| `branches.prefixes` | yes | *required* | `["feat", "fix", "docs", "chore"]` | pre-push / azdo-push branch pattern `<prefix>/<kebab>` |
+| `branches.prefixes` | removed | a config error naming the key | n/a | not configurable: branch prefixes are the commit types minus `release` (`packages/azdo/src/lib/commit-types.ts`); pre-push / azdo-push enforce `<prefix>/<kebab>`; delete the key |
 | `pre_push.remote` | yes | *required* | `"origin"` | remote azdo-push pushes to and reads status from |
-| `pre_commit.staged_coverage` | no | `true` | `true` | enact-m5-only staged coverage measurement (no-op until `[controls.coverage].produce` is declared) |
-| `pre_commit.doc_freshness` | no | `true` | opt in | a staged `docs/` or `plans/` `.md` carries a `last_update` stamped within 5h (no-op when no docs are staged) |
-| `pre_commit.compliance` | no | `true` | `true` | staged adl-compliance gates (no-op until `[controls.compliance].enabled` is non-empty) |
-| `pre_push.coverage_ratchet` | no | `true` | `true` | per outgoing commit, `coverage/coverage-summary.json` must exist and not regress (no-op until the file lands) |
-| `pre_push.coverage_produce` | no | `false` | opt in | run the coverage MEASUREMENT at push via `[controls.coverage].produce_push` (fails the push when armed with no command declared) |
-| `pre_push.findings_ratchet` | no | `true` | opt in | per outgoing commit, every declared static-analysis counter's findings must not exceed the committed floor (no-op until `[controls.findings].counters` is declared and the floor file lands) |
+| `pre_commit.staged_coverage` | yes (`true`) | config error | `true` | enact-m5-only staged coverage measurement (fails when `[controls.coverage].produce` is not declared) |
+| `pre_commit.doc_freshness` | yes (`true`) | config error | opt in | a staged `docs/` or `plans/` `.md` carries a `last_update` stamped within 5h (nothing to grade when no docs are staged) |
+| `pre_commit.compliance` | yes (`true`) | config error | `true` | staged adl-compliance gates (fails when `[controls.compliance].enabled`, read from the staged config, is empty) |
+| `pre_push.coverage_ratchet` | yes (`true`) | config error | `true` | per outgoing commit, `coverage/coverage-summary.json` must exist and not regress (fails when missing) |
+| `pre_push.coverage_produce` | yes (`false`) | config error | opt in | run the coverage MEASUREMENT at push via `[controls.coverage].produce_push` (fails the push when armed with no command declared) |
+| `pre_push.findings_ratchet` | yes (`true`) | config error | opt in | per outgoing commit, every declared static-analysis counter's findings must not exceed the committed floor (fails when the floor file or counters are missing) |
 | `pre_push.static_checks` | no | `[]` | tsc, knip, svelte-check | `{ label, run }` commands run on an export of HEAD, pass cached per tree OID |
+| `release` | yes (`false`) | promotion governance fails at pre-push | `[controls.release]` table | `release = false` opts out of promotion governance; a `[controls.release]` table declares it |
 | `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`) |
@@ -508,12 +517,123 @@ runs no build; the approval is the only gate). Pre-commit calls the same read-on
 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.
+#### Compliance seeding
+
+`[controls.compliance]` follows the same per-attribute rule. Install seeds:
+
+- `[controls.compliance.trees]` with the four adl standard trees `docs`, `plans`,
+  `workflows` and `compliance` (default paths `docs/`, `plans/`, `workflows/`,
+  `compliance/`); `""` declares "this repository has no such tree". Never a
+  deleted tree such as `rust`, `frontend`, `typescript`, `infra` or `dev`. What each tree
+  is: [`#standard-trees`](../../docs/architecture/compliance-controls.md#standard-trees),
+  and `compliance` as the register folder:
+  [`#register-folder-and-ratchets`](../../docs/architecture/compliance-controls.md#register-folder-and-ratchets).
+- `enabled` with **every gate in the engine registry**, one `domain.name` address per
+  line, `STRICT_ENABLED_GATES` in `src/compliance-config.ts` (Tarun, 2026-10-08). That
+  includes `repository.no-vcs-in-scripts` (GIT-001), `repository.license-declared`,
+  `repository.lockfile-integrity`, `docs.adr-lifecycle` and
+  `repository.no-multiline-comments`. `tests/strict-gates-registry.test.ts` fails when
+  the registry gains a gate the seed lacks, so the two cannot drift; the gates and why
+  each is on: [`#gate-catalogue`](../../docs/architecture/compliance-controls.md#gate-catalogue).
+  Armed from the first commit with NO ratchet baseline for existing violations, so an
+  existing repository reports its violations as guidance. Measured on a fresh install
+  (see "Fresh-install result" below), the one gate this package's own install leaves
+  failing is `repository.license-declared` (REP-001: no `license` declared). An existing `enabled` key, even `[]`, is never rewritten, and
+  switching a gate off is the repository's own decision, made by removing its one line
+  from `enabled`
+  ([`#strict-activation-and-switching-a-gate-off`](../../docs/architecture/compliance-controls.md#strict-activation-and-switching-a-gate-off)).
+  `registry` has a working default and is not written.
+- `[controls] integrity = { watched = ["<compliance tree>/**"] }`, the declared
+  compliance register folder, so the protection is visible in the file (see
+  [Managed dot paths and protected controls](#managed-dot-paths-and-protected-controls)).
+  Not written when the tree is declared `""`; an existing `integrity` is never rewritten.
+
+An existing `[controls.compliance]` with no `trees` table gets it appended; one
+that already has a `trees` table (any keys) is left byte-identical.
+
+Install also scaffolds the repository entry files `AGENTS.md` and `CLAUDE.md`
+(`@AGENTS.md`) at the root when absent (never overwritten) — `SCAFFOLD_ROOT_FILES` in
+`src/constants.ts` is the list. `INVARIANTS.md` is deployed from
+`assets/GLOBAL-INVARIANTS.md`, the invariants that apply to ALL repositories, only when
+the target has none (never overwritten); the engine's root gate still requires
+`INVARIANTS.md`. See Scaffolding below
+for which folders it creates.
+
+#### Grading
+
+`install` run with `grade: { env }` (what `adl repo controls install` passes) grades
+the repository once its own wiring is written and returns `compliance`:
+`{ ok, enabled, failing[], guidance[] }`. Each failing gate carries its `id`,
+`address`, `status` (`FAIL`, or `ERROR` = could not run, never a pass), summary and
+findings, each with the engine's `fix`. `guidance` is the printable form:
+"This repository now enforces N compliance gates; K failing. Fix the findings below
+before committing." then one block per gate, then the line "To switch a gate off, remove it
+from [controls.compliance] enabled in adl-config.toml — that is this repository's decision,
+and adl-config.toml is a protected file landed by the owner." The engine runs through
+`runTool` (the way `compliance run` and the hooks run it, trees and declarations included)
+with its own `--log-dir`; the `failures.log` there is the structured channel `install`
+parses. `RunContext.quietEngine` discards the engine's stdout rows, because Install prints
+its own guidance and the engine's row listing would otherwise land in the caller's stdout
+and corrupt `install --json`. `ok` is `true` only when every enabled gate passed. Install
+still completes its wiring when gates fail (exit 0, `ok: false`); a missing `uv` is a loud
+error naming `uv` and the real command to re-run (`adl repo controls compliance run --repo .`),
+raised after the wiring is written, and an empty `enabled` reports "nothing is enforced". A
+`--dry-run` never grades.
+
+`adl install` (the all-in-one command) is not one repo-controls call: it runs repo-controls
+install with `--no-grade`, then hooks, skills, settings and doctor, and only then grades
+through the `grade` command (`adl repo controls grade --repo <path>`, which prints the
+verdict as JSON and exits 0 whatever the verdict). Grading inside the repo-controls step
+would run before the hooks, skills and settings deploy, so it would under-report what the
+finished install contains. `adl install` prints one report at the end, its top-level `ok`
+means the wiring succeeded (exit 0 when gates fail), and `compliance.ok` stays separate and
+truthful. A `uv`-less machine errors out of the grade step, after everything is wired.
+
+#### Scaffolding
+
+Install bootstraps the minimal skeleton of `docs`, `plans` and `workflows` from the
+package's `assets/scaffold/<tree>/` (Bug 570, Tarun 2026-10-08):
+`docs/{AGENTS.md,CLAUDE.md,notes.md,decisions/index.md}`,
+`plans/{AGENTS.md,CLAUDE.md,GAPS-AND-FINDINGS.md,LEDGER.md,features/.gitkeep}`, and
+`workflows/{AGENTS.md,CLAUDE.md,pipelines/.gitkeep,scripts/.gitkeep}`. Rules:
+
+- **An existing tree folder is ignored entirely** (Tarun, 2026-10-08). If `docs/`,
+  `plans/` or `workflows/` (or wherever the tree is declared) already exists at the
+  target, empty or not, install adds NOTHING inside it: no missing file, no
+  `.gitkeep`. Only a missing folder gets the whole skeleton, so
+  `plans/features/.gitkeep` appears only when `plans/` itself is created fresh. Other
+  trees are still scaffolded independently. A non-directory in the way of the tree path
+  (or a parent) fails the install loudly.
+- The root entry files (`AGENTS.md`, `CLAUDE.md`, `INVARIANTS.md`) are created one by one
+  only when absent, never overwritten.
+- `docs/decisions/index.md` makes `docs/decisions/` exist, which `docs.adr-lifecycle`
+  (DOC-001) requires; the gate only grades `adr-*.md` files, so the index passes and the
+  gate runs on a fresh repository instead of reporting could-not-run.
+- **A tree pointed elsewhere is scaffolded there, never duplicated.** The paths
+  come from the effective `[controls.compliance.trees]` after the config step: with
+  `docs = "documentation"` the skeleton lands in `documentation/` and no `docs/`
+  is created; a tree declared `""`, or not declared, is not scaffolded at all. A
+  path that is not repository-relative is refused.
+- **The skeleton is user-owned**: unlike `.workflows/` it is not recorded in the
+  lock, uninstall never removes it, and an edited scaffold file is never drift.
+- `compliance` is seeded as a tree but its folder is **not** scaffolded here: it is the
+  register folder (ratchets, exemptions) and appears when the first register is
+  written. An absent register means "no grants" to the gates that read it.
+- `--dry-run` lists every scaffold file as `create` and writes nothing.
+
+#### Fresh-install result
+
+The scaffold gates (DOC-001, DOC-002, DOC-004 to DOC-012, LAY-002, LAY-004, LAY-009,
+LAY-011, LAY-014, LAY-016, LFS-001) pass on a fresh install
+(`tests/install-scaffold.test.ts`). Of the 29 enabled gates, the package-level result of a
+fresh install is exactly one failing gate, REP-001 `repository.license-declared`
+(`tests/install-strict.test.ts`). `adl install` also deploys skills, hooks and plugins into
+the repository, and any of their files with consecutive comment lines fail REP-007
+`repository.no-multiline-comments`; that is a defect of the deployed assets, not an expected
+result.
 
 Fixed conventions (enact-m5, not configurable): commit subject
-`^(feat|fix|docs|refactor|perf|chore|release)(\([a-z0-9][a-z0-9-]*\))?: .+`, at most 80
+`^(<commit type>)(\([a-z0-9][a-z0-9-]*\))?: .+` (types `feat|fix|docs|refactor|perf|chore|release`, defined once in `packages/azdo/src/lib/commit-types.ts` and handed to the hook as `ADL_REPO_CONTROLS_COMMIT_TYPES`; `release` is the pipeline's only), at most 80
 characters, lowercase description without trailing period; `Merge `, `Revert "`
 and `X.Y.Z` subjects exempt; no staged `.scratchpad` paths or new references;
 `git diff --cached --check`; git environment scrubbed before push checks.
@@ -529,14 +649,18 @@ 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
+  stage it. Once staged, it can be committed normally. This covers top-level dot
+  paths that are not protected, such as `.mcp.json`, `.workflows/` and the agent surface roots
+  (`.agents/`, `.claude/`, `.codex/`, `.cursor/`, `.kimi-code/`, `.opencode/`): those hold a
+  repository's own hooks and skills, so they are not protected as a whole (Bug 644). Nested paths such as
   `tools/.claude/**` are ordinary repository content. The designated ephemeral
   scratch storage is never committable.
 - A **protected control** requires human approval even when staged: every path
-  under `compliance/` or `workflows/`, `adl-config.toml`, and the repository's
-  explicit `[controls.integrity].watched` patterns. The same controls cannot be
+  under `compliance/` or `workflows/`, `adl-config.toml`, the folder declared as `[controls.compliance.trees].compliance`
+  (in addition to the fixed `compliance/` root, so a relocated register folder stays
+  protected: `integrityWatched` in `src/hook.ts`), and the repository's explicit
+  `[controls.integrity].watched` patterns (`PROTECTED_ROOTS` and `WIRING` in `src/integrity.ts`). A repository protects any dot path it chooses through `watched`. The full definition and the
+  owner override: [`#protected-paths-and-owner-override`](../../docs/architecture/compliance-controls.md#protected-paths-and-owner-override). The same controls cannot be
   left dirty while committing other work.
 
 Git cannot make a pre-commit hook run for `git commit --no-verify`. That is the
@@ -581,6 +705,8 @@ human makes in the same commit as the fix, the same discipline
 
 ## Configuration — `adl-config.toml` `[controls.compliance]`
 
+**Root declarations.** `[controls.compliance.root]` `dirs` are bare names directly under the repository root. `files` may also be relative paths with `/` (for example `.donors/MANIFEST.md`); install refuses an absolute path, a `.`, `..` or empty segment, a glob character, `,` and `=`. The list travels as one comma-separated `--declare root-files=a,b` value, so `,` and `=` would corrupt it, and `dirs` keep the stricter rule because a directory name is matched as a single entry.
+
 `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
@@ -604,24 +730,22 @@ 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 |
+| `enabled` | the strict standard set (see above) | gate ids (ids such as `DOC-001`) or `domain.name` addresses (`layout.references`) 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 |
+| `[controls.compliance.trees]` | the four standard trees (seeded) | per-key path overrides; the bundled engine ships NO tree defaults (`policy/config.toml` `[trees]` is empty), so a tree a gate reads that the repository has not declared is could-not-run naming what to add. See [`#standard-trees`](../../docs/architecture/compliance-controls.md#standard-trees) |
 | `[controls.compliance.limits]` | absent (engine defaults) | per-repository engine limits, strictly validated. `scripts_direct_files` (positive integer) replaces LAY-014's default of 15 direct files per scripts directory and reaches the engine as `--declare scripts-direct-files=N`; a value the engine cannot read as a positive integer is could-not-run, never a fall back to 15. The depth limit is not configurable. `open_gaps` and `open_plans` (each a positive integer) replace LAY-016's default cap of 10 open gaps and 10 open plans, independently, and reach the engine as `--declare open-gaps=N` / `--declare open-plans=N`; the same could-not-run rule applies to each, and a finding names the effective cap as `N open gaps, cap is M`. The engine default stays 10: a repository declares today's measured count and ratchets it down |
 | `[controls.compliance.markdown]` | absent (no extra Markdown roots) | extra Markdown roots for LAY-006 (`layout.markdown-trees`), strictly validated. `roots` is an array of repository-relative directories whose Markdown is site or application content rather than documentation (an Astro site's `src/content/**/*.md`); LAY-006 admits `.md` and `.mdx` beneath each, in addition to the docs trees, so a declared root only ever widens the allowlist and absent is the stricter grade. Reaches the engine as one `--declare markdown-roots=a,b`. An entry that is empty, absolute, contains `,` or `=`, or has a `.`, `..` or empty path segment is rejected when the config loads (a trailing `/` is dropped); the engine refuses the same values as could-not-run (exit 2) |
-| `[controls.compliance.lockfiles]` | absent (REP-002 keeps its tree-derived scope) | exactly which manifest and lockfile paths REP-002 (`repository.lockfile-integrity`) scans and grades, strictly validated. Four arrays: `bun_manifests` / `bun_lockfiles` and `cargo_manifests` / `cargo_lockfiles`. A manifest entry is a repository-relative path or glob ending in `package.json` (`Cargo.toml`), such as `package.json` or `apps/*/package.json`; a lockfile entry is a literal path (a missing one is reported by name). An ecosystem is declared as a pair, and a declared pair replaces that ecosystem's default (`<typescript>/package.json` + `<typescript>/bun.lock`, the `<rust>` pair) in both what selects the gate and what it grades; an undeclared ecosystem is unchanged. Reaches the engine as `--declare bun-manifests=a,b`, `bun-lockfiles=`, `cargo-manifests=`, `cargo-lockfiles=` (a list is omitted when empty); a declared manifest that matches no file is could-not-run naming it. An entry that is empty, absolute, duplicated, contains `,` `=` `\` `<` `>` `{` `}`, starts with `!`, has a `.`, `..` or empty path segment, ends in the wrong file name, or (for a lockfile) is a glob, an ecosystem with only one of its two lists, and a `REP-002:bun_lock` / `cargo_lock` / `cargo_manifest` / `workspace` input beside the pair it supersedes are all rejected when the config loads; the engine refuses the same values as could-not-run (exit 2) |
+| `[controls.compliance.placement]` | absent (LAY-008 uses its built-in asset directories) | extra asset directories for LAY-008 (`layout.placement`), strictly validated. `asset_dirs` is an array of repository-relative directories; reaches the engine as one `--declare asset-dirs=a,b` (omitted when empty). An entry that is empty, absolute, contains `,` or `=`, or has a `.`, `..` or empty path segment is rejected when the config loads (a trailing `/` is dropped); an unknown key is an error |
+| `[controls.compliance.lockfiles]` | absent (REP-002 grades only the repository-root pairs) | exactly which manifest and lockfile paths REP-002 (`repository.lockfile-integrity`) scans and grades, strictly validated. Four arrays: `bun_manifests` / `bun_lockfiles` and `cargo_manifests` / `cargo_lockfiles`. A manifest entry is a repository-relative path or glob ending in `package.json` (`Cargo.toml`), such as `package.json` or `apps/*/package.json`; a lockfile entry is a literal path (a missing one is reported by name). REP-002 always grades the repository-root pairs itself (`package.json` -> `bun.lock`, `Cargo.toml` -> `Cargo.lock`); every other lockfile is graded only when declared here, because the engine does not guess where a repository keeps its workspaces. An ecosystem is declared as a pair. Reaches the engine as `--declare bun-manifests=a,b`, `bun-lockfiles=`, `cargo-manifests=`, `cargo-lockfiles=` (a list is omitted when empty); a declared manifest that matches no file is could-not-run naming it. An entry that is empty, absolute, duplicated, contains `,` `=` `\` `<` `>` `{` `}`, starts with `!`, has a `.`, `..` or empty path segment, ends in the wrong file name, or (for a lockfile) is a glob, an ecosystem with only one of its two lists, and a `REP-002:bun_lock` / `cargo_lock` / `cargo_manifest` / `workspace` input beside the pair it supersedes are all rejected when the config loads; the engine refuses the same values as could-not-run (exit 2) |
 
 ### 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.
+The bundled registry (29 rows, counted from `gate-registry.yaml` and
+`len(CHECKS)`) always ships and loads — `enabled` is what decides which row is
+ever graded, not what is present. The engine ships no tree defaults: a repository
+declares its own in `[controls.compliance.trees]`, and a gate whose tree is
+undeclared is could-not-run, never a pass. The catalogue of gates is
+[`#gate-catalogue`](../../docs/architecture/compliance-controls.md#gate-catalogue).
 
 ## Development
 
@@ -634,3 +758,169 @@ 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 runs them through
 the repository's root pipelines under `workflows/pipelines/`.
+
+## Managed workflow scripts
+
+Rationale moved out of the scripts that `install` deploys into `.workflows/`, so the
+deployed copies stay free of multi-line comments (REP-007).
+
+### `promote.ts`
+
+- Managed by adl-repo-controls; do not edit. Regenerate with `adl-repo-controls install --repo .`.
+- Vendored into `.workflows/` byte-for-byte so CI depends on nothing: no adl-repo-controls on PATH,
+  no MCP client, no package install. A pipeline agent is a cold environment, and a promotion that
+  needs a global npm binary fails there for reasons that have nothing to do with the promotion.
+- Byte-identical in every repository, deliberately. Refs come from the environment, never baked in;
+  otherwise each consumer's copy would hash differently and one published hash could not verify any
+  of them.
+- No reviewer is named on the promotion PR, deliberately (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". The gate is the target branch's own minimum-reviewer policy (verified
+  earlier in the script), which excludes the author's own vote.
+
+### `reconcile-guard.sh`
+
+- Stage 1 of the CI pipeline for pull requests into `integration` (stage 2 runs the tests). It forces
+  the PR author, usually an agent, to reconcile with integration before anything merges.
+- The only check: the PR source branch contains integration's tip. The version bump is not a PR
+  concern any more; the integration-merge pipeline bumps after the merge (Tarun, 2026-10-01).
+- Read-only: it only fetches and reads. It never pushes, and the only refs it writes are the two
+  remote-tracking refs it fetches.
+- CI never carries an agent identity: the script unsets `ADL_AGENT_ID_AGENT` and never inherits one
+  from the caller.
+
+Further `promote.ts` rationale (moved from its doc comments):
+
+- Standard, not repo-local: every repository in this estate is on Azure DevOps, and promoting a
+  branch to its trunk is find-or-reuse a PR, then set auto-complete. Ported from enact-m5's
+  `workflows/scripts/release/promote-main.ts`, where the mechanism was already injectable (fetch,
+  collection, project, repository and token were all parameters); only three module-scoped literals
+  made it that repository's: `SOURCE_REF = 'refs/heads/integration'`, `TARGET_REF =
+  'refs/heads/main'`, and `title = 'release: promote integration to main'`.
+- The refs are declared as `[controls.release].source` / `.target`. The title is DERIVED from them
+  rather than being a third key: a title that can disagree with the refs it describes is a bug
+  waiting for someone to change one and forget the other, and the derived form satisfies this
+  package's own commit-msg grammar for any pair.
+- The target branch's gate is Tarun's approval alone (Tarun, 2026-09-30): the promotion PR gets NO
+  build validation and CD runs after the merge into the target. The pre-flight proves the
+  minimum-reviewer policy (>=1 approver, resetOnSourcePush=true) and does not require a build
+  policy. `build` is still reported so a caller can show one that happens to be present, but
+  nothing demands it.
+- There is no default pair. Defaulting to integration -> main would put one repository's branch
+  names back into the package by the back door.
+- Merge strategy: Azure's `GitPullRequestCompletionOptions.mergeStrategy` is sent by name. The REST
+  wire values are the camelCase strings; sending the numeric `GitPullRequestMergeStrategy` enum
+  ordinal is silently accepted by the type system but is not what the API expects (PR 1477,
+  2026-09-27, armed auto-complete with `rebase` although "no-fast-forward" was intended). `squash`
+  is the standard, matching the MCP server's PR tool, which admits `enum: ['Squash']` only. A
+  repository wanting something else declares it, so the deviation is visible.
+- Policy contract: one contract is used by both promotion and doctor. A configuration only counts
+  when it is enabled, blocking, and scoped exactly to the target branch; a project-wide or
+  path-filtered lookalike cannot guard a promotion.
+- No named-reviewer policy is checked (Tarun, 2026-09-27): the two-branch standard's `main` gate is
+  "exactly one human reviewer, author's vote excluded" via the minimum-reviewer policy, never a
+  specific named individual. A required-reviewer-by-identity policy on `main` was PR 1477's second
+  live bug: it named the person who pushed to `integration` as a mandatory approver, which both
+  self-approves (that person is usually the change's author) and contradicts "agent-reviewer is
+  optional, never required".
+- Standalone entry point: reads the refs from the ENVIRONMENT, not from config. The file is vendored
+  into `.workflows/` byte-for-byte, so its content must be identical in every repository or a single
+  published hash cannot verify any of them; the pipeline supplies repository-specific values through
+  environment variables.
+
+### `version-bump.sh`
+
+- Stage 1 of the promote pipeline (push to `integration`): the integration-merge build owns package
+  version allocation (Tarun, 2026-10-01). A PR's build-validation policy ignores `[skip ci]`, so a
+  bump pushed from PR CI re-queued itself; a push to a branch honours it. After a merge lands on
+  `integration` the script sets the manifest to that commit's version + patch 1:
+  `version-bump.sh --file package.json --integration --push`.
+- The Azure Pipelines build checks out the detached triggering commit with persisted credentials, so
+  `git push` authenticates as the project build service (needs Contribute and "Bypass policies when
+  pushing" on `integration`). The bump commit is created on that checkout, carries `[skip ci]` so the
+  push does not trigger this pipeline again, and is pushed as a plain fast-forward, never forced. If
+  integration moved since the checkout the push is rejected and the script fails loud; the newer
+  merge's own run bumps. No npm query, no PR.
+- CI never carries an agent identity: the push authenticates as the build service through the
+  checkout's persisted `System.AccessToken`. The script unsets `ADL_AGENT_ID_AGENT` and never
+  inherits one.
+- `[controls.release].pre_bump` (`adl-config.toml`, repo root): ordered, repository-relative scripts a
+  multi-language repo runs before the bump commit, for example a Go version constant that nothing in
+  `package.json` can reach. No file, or no `pre_bump` key: no scripts, and the resulting commit is
+  byte-identical to the behaviour before the feature existed
+  (`tests/version-bump-integration-pre-bump.test.ts`).
+- Declared scripts are all validated before any runs, so a bad declaration fails clearly instead of
+  leaving the repo half-way through a partial run.
+- Every variable whose name ends `_TOKEN`, `_PAT`, `_SECRET` or `_PASSWORD` (any case), plus
+  `SYSTEM_ACCESSTOKEN` and the Azure DevOps credentials by exact name, is stripped from each script's
+  environment: a pre_bump script is repo-authored, unreviewed by this package, and has no business
+  seeing the pipeline's push credentials. The match is plain bash (no search tool, no `${var^^}`)
+  because Azure Pipelines agents do not guarantee ripgrep and macOS ships bash 3.2.
+- A pre_bump script that edits `.git` directly (hooks, config, refs) never shows in `git status`, so
+  it is checked separately and the bump refuses. There is no equivalent check for a script writing
+  to an absolute path outside the repository: a plain shell script has no sandbox, so only `.git`
+  tampering is refused, honestly. Every add is scoped to `$repo_root`, so nothing outside it is staged.
+- `[skip ci]` (Azure DevOps: a push whose commits contain it does not trigger CI pipelines) keeps the
+  push from re-running the promote pipeline that made it.
+
+## Log folders
+
+Bug 600 (Tarun, 2026-10-08): `.adl/logs/` has one folder per owner and no file
+is written by two owners. The git hooks write `git-hooks/activity.log` (every
+invocation) and `git-hooks/deny.log` (FAIL rows only); they no longer share a
+deny file with agent-hooks (`agent-hooks/deny.log`). The old top-level
+`repo-controls.log` and `hooks-deny.log` are left where they are, never
+migrated. A git-hook row has `host: git` and is written by the same writer as
+agent-hook rows (`packages/agent-hooks/src/log/writer.ts`).
+
+`.enact/logs/` is pre-hard-cut evidence only: nothing writes there, and the
+managed `.gitignore` block keeps ignoring it alongside the two legacy hook-log
+roots. Hook and session logs live under `.adl/logs/<owner>/` (`agent-hooks/`,
+`git-hooks/`, `agents/`), covered by the block's `/.adl/` line.
+
+A log write that fails never changes a git hook's exit code; `hook-log.ts`
+prints one `adl repo controls: could not write log row: ...` line to stderr.
+
+## No silent skips
+
+Tarun, 2026-10-09: an armed gate whose input is missing fails loud; switching a gate off is an
+explicit `false` in `adl-config.toml`, an owner decision.
+
+- Install seeds every gate key under `[controls]` (`pre_commit.*`, `pre_push.coverage_ratchet`,
+  `coverage_produce`, `findings_ratchet`) and `release = false`. A consumer config missing a gate key
+  fails to load, naming the key. `release` is the exception: an absent `[controls.release]` loads, and
+  fails the pre-push promotion check instead, telling the owner to declare source/target or set
+  `release = false`.
+- Coverage ratchet: with the gate on, a summary missing from both HEAD and the work tree fails, and so does
+  a missing HEAD~1 baseline unless the summary is added in HEAD (a loud first-baseline note). A file with
+  no baseline entry is reported as "new, now baselined"; a file dropped from the summary while it still
+  exists on disk fails.
+- Findings ratchet: a missing floor file fails, and so does a floor entry for a counter not declared in
+  `[controls.findings.counters]`.
+- Staged coverage with an empty `[controls.coverage].produce` fails at commit.
+- Compliance: the flag and `enabled` are both read from the staged `adl-config.toml`; flag true with
+  `enabled` empty fails.
+- `doctor` reports these prerequisites as `fail` (not `warn`) while the governing gate is on, and the
+  pre-commit doctor gate prints them.
+- `ADL_SKIP_STAGED_COVERAGE` was a dead export (nothing read it) and is removed.
+
+## No silent skips
+
+Tarun, 2026-10-09: an armed gate with a missing input fails loudly; it never
+degrades to a pass.
+
+- The pre-push static-check pass marker is keyed by the HEAD tree OID plus a
+  hash of the declared `static_checks` (label and command) and the
+  `export_links` list, so editing a check invalidates a cached pass. No marker
+  is written when zero static checks ran.
+- A declared `export_links` entry whose target is missing in the checkout fails
+  the push instead of being skipped.
+- A static check with an empty label or an empty command fails the push. The
+  entry is split on its first tab by hand because `read` with a tab `IFS`
+  collapses a leading tab and would shift the command into the label.
+- In `workflows/scripts/coverage`, a full or `--merge-only` run with no
+  committed baseline at `HEAD:coverage/coverage-summary.json` fails unless
+  `--first-baseline` is passed; `--only` legs still never grade. The ratchet
+  reports a measured file with no baseline entry as "new file, baselined", the
+  sanitize step says when HEAD has no summary, and auto-publish no longer
+  falls back to the working summary or the candidate as its own baseline.

package/packages/repo-controls/assets/GLOBAL-INVARIANTS.md

@@ -0,0 +1,21 @@
+# Invariants
+
+The things this repository must never regress. These apply to every repository
+adl manages; add this repository's own below, one bullet each, stating the rule
+and how it is verified.
+
+- The compliance gates enabled in `adl-config.toml` pass before every commit
+  (verified by `adl repo controls` pre-commit and CI). A gate is switched off by
+  removing it from `[controls.compliance] enabled`, which is the owner's decision.
+- Protected paths (`adl-config.toml`, `.workflows/`, the agent surface folders,
+  `workflows/` and the declared compliance register folder) are landed only by the
+  owner. An agent leaves them uncommitted and asks (verified by the pre-commit
+  integrity gate).
+- Ratchets only shrink. A register names the specific files granted, and a grant
+  is removed once its file is clean, never added to (verified by the gate that reads
+  the register).
+- No multi-line comments in code. The explanation lives in `docs/`, and the code
+  keeps at most a one-line pointer (verified by `repository.no-multiline-comments`).
+- The standard trees `docs`, `plans`, `workflows` and `compliance` are declared in
+  `[controls.compliance.trees]`, and layout rules follow those declarations
+  (verified by the layout and docs gates).