@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.29 → 0.1.32

package/packages/repo-controls/scripts/hooks/pre-push

@@ -22,8 +22,12 @@ push_updates="$(cat)"
 # released on EXIT, which serialised THIS HOOK rather than the network push,
 # so the window it claimed to close stayed open the whole time.
 PUSH_TREE=""
+PUSH_ARCHIVE=""
 cleanup_pre_push() {
   local status=$?
+  if [[ -n "${PUSH_ARCHIVE}" && -e "${PUSH_ARCHIVE}" ]]; then
+    rm -f -- "${PUSH_ARCHIVE}"
+  fi
   if [[ -n "${PUSH_TREE}" && -d "${PUSH_TREE}" ]]; then
     rm -rf -- "${PUSH_TREE}"
   fi
@@ -98,44 +102,58 @@ if [[ "$git_config_count" =~ ^[0-9]+$ ]]; then
 fi
 unset GIT_CONFIG_COUNT
 
-# Static checks run against HEAD (the tip being pushed), not the dirty index or
-# worktree, so same-checkout staged/unstaged foreign breakage cannot block delivery.
-# so same-checkout uncommitted foreign breakage cannot block delivery.
-# Reuse a prior pass for the same immutable tree OID under .coverage-cache/.
+# Static checks run against HEAD, keyed by tree + declared checks + export links (see README, No silent skips).
 HEAD_TREE_OID="$(git rev-parse 'HEAD^{tree}')"
-STATIC_CACHE="$ROOT/.coverage-cache/pre-push-static/${HEAD_TREE_OID}.ok"
+STATIC_CACHE_KEY="$(printf '%s\n%s\n%s\n' "$HEAD_TREE_OID" "${ADL_REPO_CONTROLS_STATIC_CHECKS?}" "${ADL_REPO_CONTROLS_EXPORT_LINKS:-}" | git hash-object --stdin)"
+STATIC_CACHE="$ROOT/.coverage-cache/pre-push-static/${HEAD_TREE_OID}-${STATIC_CACHE_KEY}.ok"
 if [[ -f "$STATIC_CACHE" ]]; then
   echo "pre-push: reusing static-check pass for tree ${HEAD_TREE_OID}"
 else
   echo 'pre-push: exporting HEAD tree for static checks'
   PUSH_TREE="$(mktemp -d "${TMPDIR:-/tmp}/adl-pre-push-head.XXXXXX")"
-  git archive HEAD | tar -x -C "$PUSH_TREE"
-  # Untracked paths the export needs, declared by the repository. This was
-  # `ln -s "$ROOT/node_modules"` -- a package that calls itself language
-  # agnostic assuming JavaScript. A Rust repo links `target/`, a Python one its
-  # virtualenv, and a repo with no ecosystem links nothing.
+  # Not `git archive HEAD | tar -x`: on the macOS CI agent that pipe failed
+  # pushes with 141 (SIGPIPE under pipefail) -- a tar that stops reading before
+  # git archive finishes writing kills the writer. A file has no reader to lose.
+  PUSH_ARCHIVE="${PUSH_TREE}.tar"
+  git archive --format=tar -o "$PUSH_ARCHIVE" HEAD
+  tar -xf "$PUSH_ARCHIVE" -C "$PUSH_TREE"
+  rm -f -- "$PUSH_ARCHIVE"
+  # Declared untracked paths the export needs; a missing target fails.
   while IFS= read -r export_link; do
     [[ -n "$export_link" ]] || continue
-    [[ -e "$ROOT/$export_link" ]] || continue
+    if [[ ! -e "$ROOT/$export_link" ]]; then
+      echo "pre-push: FAIL — export_links entry '${export_link}' does not exist in the checkout." >&2
+      exit 1
+    fi
     mkdir -p "$(dirname -- "$PUSH_TREE/$export_link")"
     ln -s "$ROOT/$export_link" "$PUSH_TREE/$export_link"
   done <<<"${ADL_REPO_CONTROLS_EXPORT_LINKS:-}"
 
   static_check_labels=()
-  while IFS=$'\t' read -r static_check_label static_check_command; do
-    [[ -n "$static_check_label" ]] || continue
+  while IFS= read -r static_check_line; do
+    [[ -n "$static_check_line" ]] || continue
+    # Split on the first tab by hand; `read` with a tab IFS collapses a leading tab.
+    static_check_label="${static_check_line%%$'\t'*}"
+    static_check_command=""
+    [[ "$static_check_line" == *$'\t'* ]] && static_check_command="${static_check_line#*$'\t'}"
+    if [[ -z "$static_check_label" ]]; then
+      echo 'pre-push: FAIL — static check has an empty label.' >&2
+      exit 1
+    fi
+    if [[ -z "$static_check_command" ]]; then
+      echo "pre-push: FAIL — static check '${static_check_label}' has an empty command." >&2
+      exit 1
+    fi
     echo "pre-push: ${static_check_label} (HEAD)"
     (cd "$PUSH_TREE" && bash -c "$static_check_command" </dev/null)
     static_check_labels+=("$static_check_label")
   done <<<"${ADL_REPO_CONTROLS_STATIC_CHECKS?}"
-  # The PreToolUse deny corpus is the only thing asserting that destructive
-  # commands stay denied, and nothing else ran it — `git update-ref` sat in
-  # its ALLOW list while being exactly what strands a shared checkout. Cheap
-  # enough to assert on every push.
 
-  mkdir -p "$ROOT/.coverage-cache/pre-push-static"
-  printf '%s\n%s\n' "${static_check_labels[*]}" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >"$STATIC_CACHE"
-  echo "pre-push: recorded static-check pass for tree ${HEAD_TREE_OID}"
+  if ((${#static_check_labels[@]} > 0)); then
+    mkdir -p "$ROOT/.coverage-cache/pre-push-static"
+    printf '%s\n%s\n' "${static_check_labels[*]}" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >"$STATIC_CACHE"
+    echo "pre-push: recorded static-check pass for tree ${HEAD_TREE_OID}"
+  fi
 fi
 
 # The outgoing-commit coverage ratchet moved to `coverageRatchetStep` in

package/packages/repo-controls/src/cli.ts

@@ -7,6 +7,7 @@ import { logHookEvent } from './hook-log.ts'
 import { isHookName, isToolName, runHook, runTool, TOOLS } from './hook.ts'
 import { resolveRepo } from './runtime.ts'
 import { type Action, install, uninstall } from './install.ts'
+import { gradeInstalledRepo, UvMissingError } from './install-compliance.ts'
 import type { Env } from './runtime.ts'
 
 export interface Io {
@@ -17,7 +18,8 @@ export interface Io {
 }
 
 const USAGE = `usage:
-  ${TOOL} install [--repo <path>] [--dry-run]
+  ${TOOL} install [--repo <path>] [--dry-run] [--json] [--no-grade] [--rewire]
+  ${TOOL} grade [--repo <path>]   (prints the compliance verdict as JSON; exit 0 whatever the verdict)
   ${TOOL} uninstall [--repo <path>] [--dry-run]
   ${TOOL} doctor [--repo <path>] [--json]
   ${TOOL} hook <${HOOK_NAMES.join('|')}> [git hook args...]
@@ -82,8 +84,14 @@ async function dispatch(argv: string[], io: Io): Promise<number> {
       io.out(USAGE)
       return 0
     case 'install': {
-      const parsed = parse(command, args, ['--dry-run'])
-      const result = install(parsed.repo, { dryRun: parsed.flags.has('--dry-run') })
+      const parsed = parse(command, args, ['--dry-run', '--json', '--no-grade', '--rewire'])
+      const rewire = parsed.flags.has('--rewire')
+      const grade = parsed.flags.has('--no-grade') || rewire ? {} : { grade: { env: io.env } }
+      const result = install(parsed.repo, { dryRun: parsed.flags.has('--dry-run'), rewire, ...grade })
+      if (parsed.flags.has('--json')) {
+        io.out(JSON.stringify(result))
+        return 0
+      }
       printActions(io, result.actions, result.dryRun)
       // Independent review, 2026-09-29, finding 8: a genuine no-op run (and
       // any --dry-run preview) never claims to have "installed" anything —
@@ -91,6 +99,17 @@ async function dispatch(argv: string[], io: Io): Promise<number> {
       if (!result.dryRun && result.actions.length > 0) {
         io.out(`${TOOL} ${VERSION} installed into ${result.repo}`)
       }
+      for (const line of result.compliance?.guidance ?? []) io.out(line)
+      return 0
+    }
+    case 'grade': {
+      const parsed = parse(command, args, [])
+      try {
+        io.out(JSON.stringify(gradeInstalledRepo(resolveRepo(parsed.repo), io.env)))
+      } catch (error) {
+        if (!(error instanceof UvMissingError)) throw error
+        io.out(JSON.stringify({ ok: false, skipped: 'uv-missing', enabled: [], failing: [], guidance: [error.message] }))
+      }
       return 0
     }
     case 'uninstall': {

package/packages/repo-controls/src/compliance-config.ts

@@ -1,4 +1,4 @@
-import { existsSync, lstatSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { isTable, Problems, type Table } from './config.ts'
 import { CONFIG_REL, INSTALL_HINT } from './constants.ts'
@@ -41,6 +41,8 @@ export interface ComplianceConfig {
    * non-empty `roots` into one `--declare markdown-roots=a,b` flag.
    */
   markdown?: MarkdownDeclaration
+  /** LAY-008's extra asset directories from `[controls.compliance.placement]`; omitted when undeclared. */
+  placement?: PlacementDeclaration
   /**
    * The manifest and lockfile paths REP-002 scans and grades, from
    * `[controls.compliance.lockfiles]`. OMITTED (not `undefined`-valued) when the
@@ -138,61 +140,69 @@ interface LimitsDeclaration {
  *
  * Nested under `controls`, not a root-level `[compliance]`: see `OWNED_TABLES`.
  */
-const ENABLED_SEED_COMMENT = `# Nothing is graded until a gate is named here. A gate id (RST-001), a
-# domain.name address (layout.references), or a whole domain (layout); an entry
-# matching no gate is a hard error, never a silent no-op. Point
-# [controls.compliance.trees] at this repository's layout before enabling a row —
-# the packaged defaults are shaped after the repo these checks were authored
-# against, so an enabled row with unpointed trees grades the wrong files.`
-
-const SEEDED_COMPLIANCE_ATTRIBUTES: SeededAttribute[] = [
-  {
-    key: 'enabled',
-    text: `${ENABLED_SEED_COMMENT}
-enabled = []
+const TREES_SEED: SeededAttribute = {
+  key: 'trees',
+  text: `
+# docs, plans, workflows and compliance are the four adl standard trees. Edit them
+# if this repository's layout differs; "" declares "this repository has no such
+# tree". compliance is the register folder: it appears when the first ratchet
+# or exemption register is written, not at install. Pre-commit protects it.
+[controls.compliance.trees]
+docs = "docs"
+plans = "plans"
+workflows = "workflows"
+compliance = "compliance"
 `,
-  },
-]
+}
 
-/**
- * Seeded by `install` when `[controls.compliance]` is missing; per-attribute
- * afterwards, like `[controls]`. `registry` and `[controls.compliance.trees]` are
- * deliberately NOT seeded: both have working defaults, and writing an empty table
- * into every repository is noise that says nothing.
- */
-export const DEFAULT_COMPLIANCE_CONFIG_TEXT = `[controls.compliance]\n${SEEDED_COMPLIANCE_ATTRIBUTES.map((a) => a.text).join('')}`
+// Every gate in the engine registry, one domain.name address each (strict-gates-registry.test.ts keeps them equal); see README, "Compliance seeding".
+export const STRICT_ENABLED_GATES = [
+  'docs.adr-lifecycle',
+  'docs.english-only',
+  'docs.index-updated',
+  'docs.markdown-ast',
+  'docs.okf-profile',
+  'docs.semantics',
+  'docs.indexes',
+  'docs.ledger',
+  'docs.closed-set',
+  'docs.filename',
+  'docs.directory-size',
+  'layout.agents-layout',
+  'layout.ci-paths',
+  'layout.directory-ratchet',
+  'layout.markdown-trees',
+  'layout.placement',
+  'layout.plans-layout',
+  'layout.references',
+  'layout.root-closed-set',
+  'layout.root-markdown-allowlist',
+  'layout.scripts-size-depth',
+  'layout.open-work-cap',
+  'lfs.integrity',
+  'repository.license-declared',
+  'repository.lockfile-integrity',
+  'repository.no-legacy-search',
+  'repository.ignored-paths',
+  'repository.no-vcs-in-scripts',
+  'repository.no-multiline-comments',
+] as const
 
-/**
- * `install`'s repo-aware `enabled` seed (gate-integrity finding, 2026-09-17:
- * "`docs.ledger` is armed in one repository only", closed 2026-09-27). A
- * repository that already has a `plans/` tree gets `docs.ledger` pre-armed —
- * the ledger contract (DOC-009) a `plans/` tree implies is never left for
- * someone to notice missing later. Still only ever scaffolds a MISSING
- * `enabled` key (installConfigTable's own "existing[key] === undefined"
- * gate) — this never rewrites a table the repository already owns, exactly
- * like every other seeded attribute.
- */
-export function seededComplianceAttributesFor(repo: string): SeededAttribute[] {
-  const plansPath = join(repo, 'plans')
-  const hasPlans = existsSync(plansPath) && lstatSync(plansPath).isDirectory()
-  if (!hasPlans) return SEEDED_COMPLIANCE_ATTRIBUTES
-  return [
-    {
-      key: 'enabled',
-      text: `${ENABLED_SEED_COMMENT}
-# This repository has a \`plans/\` tree, so \`docs.ledger\` is pre-armed: a
-# ledger contract with nowhere to enforce it is worse than none (gate-integrity
-# finding, 2026-09-17).
-enabled = ["docs.ledger"]
-`,
-    },
-  ]
-}
+const ENABLED_SEED_TEXT = `# Strict by default (Bug 570): every gate the engine defines is armed from the first commit.
+# To switch a gate off, delete its line; that is this repository's decision, and adl-config.toml
+# is a protected file landed by the owner. A gate id (RST-001), a domain.name address
+# (layout.references) or a whole domain (layout) is accepted; an entry matching no gate is a
+# hard error, never a silent no-op.
+enabled = [
+${STRICT_ENABLED_GATES.map((gate) => `  "${gate}",`).join('\n')}
+]
+`
 
-/** `[controls.compliance]`'s default text for a specific repository — see `seededComplianceAttributesFor`. */
-export function defaultComplianceConfigTextFor(repo: string): string {
-  return `[controls.compliance]\n${seededComplianceAttributesFor(repo).map((a) => a.text).join('')}`
-}
+/** Exported: `install` seeds each attribute the repository's `[controls.compliance]` lacks. */
+export const SEEDED_COMPLIANCE_ATTRIBUTES: SeededAttribute[] = [{ key: 'enabled', text: ENABLED_SEED_TEXT }, TREES_SEED]
+
+/** Seeded by `install` when `[controls.compliance]` is missing; see README, "Compliance seeding". */
+export const DEFAULT_COMPLIANCE_CONFIG_TEXT = `[controls.compliance]\n${SEEDED_COMPLIANCE_ATTRIBUTES.map((a) => a.text).join('')}`
 
 const ENABLED_RE = /^\S+$/
 
@@ -216,13 +226,11 @@ export function parseComplianceConfig(text: string): ComplianceConfig {
   const problems = new Problems()
   problems.unknownKeys(
     compliance,
-    ['enabled', 'registry', 'trees', 'inputs', 'license', 'root', 'limits', 'markdown', 'lockfiles', 'directory-ratchet'],
+    ['enabled', 'registry', 'trees', 'inputs', 'license', 'root', 'limits', 'markdown', 'placement', 'lockfiles', 'directory-ratchet'],
     '',
   )
 
-  // Absent is the documented default, never an error: install seeds only `version`
-  // and `enabled`, and `registry`/`trees` both have working defaults. Present but the
-  // wrong shape is still a hard error.
+  // Absent is the documented default, never an error; present but the wrong shape is a hard error (README, "Compliance seeding").
   const enabled = compliance.enabled === undefined ? [] : parseEnabled(compliance.enabled, problems)
   const registry = compliance.registry === undefined ? 'default' : parseRegistry(compliance.registry, problems)
   const trees = compliance.trees === undefined ? {} : parseTrees(compliance.trees, problems, 'trees', true)
@@ -245,6 +253,7 @@ export function parseComplianceConfig(text: string): ComplianceConfig {
   if (compliance.root !== undefined) config.root = parseRoot(compliance.root, problems)
   if (compliance.limits !== undefined) config.limits = parseLimits(compliance.limits, problems)
   if (compliance.markdown !== undefined) config.markdown = parseMarkdown(compliance.markdown, problems)
+  if (compliance.placement !== undefined) config.placement = parsePlacement(compliance.placement, problems)
   if (compliance.lockfiles !== undefined) {
     config.lockfiles = parseLockfiles(compliance.lockfiles, problems)
     rejectSupersededInputs(config.lockfiles, inputs, problems)
@@ -318,15 +327,13 @@ function parseTrees(
   return trees
 }
 
-/**
- * A root entry is a NAME directly under the repository root, and the whole list
- * travels to the engine as ONE comma-separated `--declare root-files=a,b` value.
- * So a name may not contain `,` (it would split into two names), `=` (it collides
- * with `--declare name=value`'s own separator) or `/` and `..` (a root name is not
- * a path: either would escape the root or reach below it). Empty and
- * whitespace-only names are refused because the engine rejects an empty item.
- */
+/** Root entry rules (dirs are bare names, files may be relative paths); see README, "Root declarations". */
 const ROOT_NAME_FORBIDDEN = /[,/=]|\.\./
+const ROOT_FILE_FORBIDDEN = /[,=*?[\]{}\\]/
+
+function isRootFilePath(item: string): boolean {
+  return !ROOT_FILE_FORBIDDEN.test(item) && item.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..')
+}
 
 function parseRoot(value: unknown, problems: Problems): RootDeclaration {
   const root: RootDeclaration = { files: [], dirs: [] }
@@ -346,7 +353,9 @@ function parseRoot(value: unknown, problems: Problems): RootDeclaration {
       const label = `root.${key}[${index}]`
       if (typeof item !== 'string') problems.add(`${label} must be a string`)
       else if (item.trim() === '') problems.add(`${label} must not be empty`)
-      else if (ROOT_NAME_FORBIDDEN.test(item)) problems.add(`${label} must not contain ',', '/', '=' or '..'`)
+      else if (key === 'files' && !isRootFilePath(item)) {
+        problems.add(`${label} must be a repository-relative path without a leading '/', a '.', '..' or empty segment, a glob character, ',' or '='`)
+      } else if (key === 'dirs' && ROOT_NAME_FORBIDDEN.test(item)) problems.add(`${label} must not contain ',', '/', '=' or '..'`)
       else root[key].push(item)
     })
   }
@@ -394,6 +403,46 @@ function parseLimits(value: unknown, problems: Problems): LimitsDeclaration {
  */
 const MARKDOWN_ROOT_FORBIDDEN = /[,=]/
 
+interface PlacementDeclaration {
+  asset_dirs: string[]
+}
+
+/** `[controls.compliance.placement].asset_dirs`: repository-relative directories, validated like markdown roots (no leading '/', no '.', '..' or empty segment, no ',' or '='). */
+function parsePlacement(value: unknown, problems: Problems): PlacementDeclaration {
+  const placement: PlacementDeclaration = { asset_dirs: [] }
+  if (!isTable(value)) {
+    problems.add('placement must be a table')
+    return placement
+  }
+  problems.unknownKeys(value, ['asset_dirs'], 'placement.')
+  const list = value.asset_dirs
+  if (list === undefined) return placement
+  if (!Array.isArray(list)) {
+    problems.add('placement.asset_dirs must be an array of strings')
+    return placement
+  }
+  list.forEach((item: unknown, index) => {
+    const label = `placement.asset_dirs[${index}]`
+    if (typeof item !== 'string') {
+      problems.add(`${label} must be a string`)
+      return
+    }
+    const trimmed = item.trim()
+    if (trimmed === '') {
+      problems.add(`${label} must not be empty`)
+      return
+    }
+    const dir = trimmed.replace(/\/+$/, '')
+    const bad = trimmed.startsWith('/') || dir.split('/').some((part) => part === '' || part === '.' || part === '..')
+    if (MARKDOWN_ROOT_FORBIDDEN.test(dir) || bad) {
+      problems.add(`${label} must be a repository-relative directory without a leading '/', a '.', '..' or empty segment, ',' or '='`)
+      return
+    }
+    placement.asset_dirs.push(dir)
+  })
+  return placement
+}
+
 function parseMarkdown(value: unknown, problems: Problems): MarkdownDeclaration {
   const markdown: MarkdownDeclaration = { roots: [] }
   if (!isTable(value)) {
@@ -601,6 +650,24 @@ function rejectSupersededInputs(
   }
 }
 
+/** The repo-relative folder `[controls.compliance.trees].compliance` declares; null when there is no such table, key or the value is `""`. A non-string value throws. */
+export function declaredComplianceTree(configText: string): string | null {
+  let raw: unknown
+  try {
+    raw = Bun.TOML.parse(configText)
+  } catch (error) {
+    throw new Error(`${CONFIG_REL} is not valid TOML: ${(error as Error).message}`)
+  }
+  const controls = isTable(raw) && isTable(raw.controls) ? raw.controls : undefined
+  const compliance = controls !== undefined && isTable(controls.compliance) ? controls.compliance : undefined
+  const trees = compliance !== undefined && isTable(compliance.trees) ? compliance.trees : undefined
+  const declared = trees?.compliance
+  if (declared === undefined) return null
+  if (typeof declared !== 'string') throw new Error(`${CONFIG_REL} [controls.compliance.trees] compliance must be a string`)
+  const folder = declared.replace(/^(\.\/)+/, '').replace(/\/+$/, '')
+  return folder === '' ? null : folder
+}
+
 export function loadComplianceConfig(repo: string): ComplianceConfig {
   const path = join(repo, CONFIG_REL)
   if (!existsSync(path)) throw new Error(`${CONFIG_REL} is missing — ${INSTALL_HINT}`)

package/packages/repo-controls/src/config.ts

@@ -79,7 +79,7 @@ export interface RepoControlsConfig {
   branches: { protected: string[]; prefixes: string[] }
   preCommit: { staticChecks: StaticCheck[]; stagedCoverage: boolean; docFreshness: boolean; compliance: boolean }
   commitMsg: { staticChecks: StaticCheck[] }
-  release: { source: string; target: string; mergeStrategy: MergeStrategy; preBump: string[] }
+  release: { optedOut: boolean; source: string; target: string; mergeStrategy: MergeStrategy; preBump: string[] }
   postCommit: { staticChecks: StaticCheck[] }
   prePush: {
     coverageRatchet: boolean
@@ -101,24 +101,7 @@ export interface RepoControlsConfig {
  * `extractTableSpan`/`removeTableSpan` — so it must start with the
  * `[controls]` header line and never contain another line starting with `[`.
  */
-/**
- * The `[controls]` attributes `install` SCAFFOLDS, each independently.
- *
- * Install wires the hooks; it does not arm a gate. Only the three attributes below
- * are written, and only when absent — an attribute already in the file is never
- * rewritten, reordered or reformatted, whatever its value. Everything else
- * (`pre_commit.*`, `pre_push.coverage_ratchet`, `pre_push.findings_ratchet`,
- * `pre_push.static_checks`) is omitted and defaults to off, so a first install
- * changes what no `git push` or `git commit` does until somebody opts in.
- *
- * `branches` and `pre_push.remote` are seeded rather than omitted because they are
- * not gates — they are the vocabulary the gates are phrased in — and because
- * `pre-push` reads their env vars with `${VAR:?}`, which aborts on an empty value.
- * "No branch policy" therefore cannot be spelled as an empty list.
- *
- * Granularity is the top-level key inside `[controls]`: an inline table is one
- * attribute, because editing inside one means rewriting bytes the user owns.
- */
+/** The `[controls]` attributes `install` scaffolds when absent; rationale in README, "No silent skips". */
 export interface SeededAttribute {
   key: string
   text: string
@@ -130,23 +113,40 @@ export const SEEDED_ATTRIBUTES: SeededAttribute[] = [
     text: `
 # pre-push refuses to push while one of these branches is checked out; prefixes: <prefix>/<kebab>.
 branches = { protected = ["main", "integration"], prefixes = ["feat", "fix", "docs", "chore"] }
+`,
+  },
+  {
+    key: 'pre_commit',
+    text: `
+# Every gate key is declared; a missing key is a config error. Switch a gate off with an explicit false.
+pre_commit = { staged_coverage = true, doc_freshness = true, compliance = true }
 `,
   },
   {
     key: 'pre_push',
     text: `
 # Remote that pre-push and azdo-push push to and read status from.
-#
-# Every gate is OFF until its key is added here: installing wires the hooks and arms
-# nothing. Opt in by adding pre_commit (static_checks, staged_coverage, doc_freshness) or the
-# remaining pre_push keys (coverage_ratchet, coverage_produce, findings_ratchet, static_checks). README,
-# "Configuration", lists each one. Deliberately no example assignments in this comment — commented TOML
-# is indistinguishable from a real setting to find-and-replace, in an editor or a script.
-pre_push = { remote = "origin" }
+pre_push = { remote = "origin", coverage_ratchet = true, coverage_produce = false, findings_ratchet = true }
+`,
+  },
+  {
+    key: 'release',
+    text: `
+# Promotion governance is opted out. To promote through a PR, replace this line with a [controls.release] table declaring source and target.
+release = false
 `,
   },
 ]
 
+/** The `[controls] integrity` seed for a compliance register folder (README, "Compliance seeding"); appended after `SEEDED_ATTRIBUTES`. */
+export function integritySeed(folder: string): SeededAttribute {
+  if (!/^[A-Za-z0-9._/-]+$/.test(folder)) throw new Error(`integrity seed folder has unsafe characters: ${folder}`)
+  return {
+    key: 'integrity',
+    text: `\n# Pre-commit refuses a commit touching the compliance register folder; the owner lands it.\nintegrity = { watched = ["${folder}/**"] }\n`,
+  }
+}
+
 /**
  * Seeded by `install` as the `[controls]` table of the shared `adl-config.toml`
  * when that table is missing; user-owned afterwards. When the table already exists,
@@ -261,14 +261,14 @@ export function extractTableSpan(text: string, tableName: string): string | null
  */
 function ownKeysEnd(found: TableRanges): { offset: number; atRangeEnd: boolean } | null {
   if (found.headerLine === -1) return null
-  const range = found.ranges.find((candidate) => candidate.startLine === found.headerLine)
+  const range = found.ranges.find((candidate) => candidate.startLine <= found.headerLine && found.headerLine < candidate.endLine)
   if (range === undefined) return null
-  let sub = range.startLine + 1
+  let sub = found.headerLine + 1
   while (sub < range.endLine && !/^\[/.test(found.lines[sub] ?? '')) sub++
   if (sub >= range.endLine) return { offset: range.end, atRangeEnd: true }
   let at = sub
-  while (at - 1 > range.startLine && (found.lines[at - 1] ?? '').trim().startsWith('#')) at--
-  while (at - 1 > range.startLine && (found.lines[at - 1] ?? '').trim() === '') at--
+  while (at - 1 > found.headerLine && (found.lines[at - 1] ?? '').trim().startsWith('#')) at--
+  while (at - 1 > found.headerLine && (found.lines[at - 1] ?? '').trim() === '') at--
   return { offset: found.starts[at] ?? found.text.length, atRangeEnd: false }
 }
 
@@ -313,12 +313,12 @@ export const RETIRED_ATTRIBUTES = ['version'] as const
 export function removeFromTableSpan(text: string, tableName: string, key: string): string {
   const found = findTableRanges(text, tableName)
   const where = ownKeysEnd(found)
-  const range = found.ranges.find((candidate) => candidate.startLine === found.headerLine)
-  if (where === null || range === undefined) return text
-  const body = text.slice(range.start, where.offset)
+  if (where === null) return text
+  const headerStart = found.starts[found.headerLine] ?? 0
+  const body = text.slice(headerStart, where.offset)
   const assignment = new RegExp(`^${escapeRegExp(key)}\\s*=.*\\n(\\n)?`, 'm')
   if (!assignment.test(body)) return text
-  return text.slice(0, range.start) + body.replace(assignment, '') + text.slice(where.offset)
+  return text.slice(0, headerStart) + body.replace(assignment, '') + text.slice(where.offset)
 }
 
 /** `text` with every range of a table removed (a no-op if there are none); other tables are untouched. */
@@ -392,7 +392,7 @@ export class Problems {
   }
   /**
    * A table this package SEEDS but does not require. Absent means "every control in
-   * it is off", never an error — installing wires the hooks and arms nothing, so a
+   * it is off", never an error — installing arms no push or commit gate, so a
    * repository that never opted into a control simply has no key for it. Present but
    * the wrong type is still a hard error, and unknown keys inside it still are too.
    */
@@ -400,6 +400,14 @@ export class Problems {
     if (parent[key] === undefined) return {}
     return this.table(parent, key, known)
   }
+  /** A gate key has no default: absent is a config error naming the key. */
+  requiredBool(table: Table, key: string, name: string): boolean {
+    if (table[key] === undefined) {
+      this.add(`${name} is required — declare ${name} = true or ${name} = false (a missing gate key is never defaulted)`)
+      return false
+    }
+    return this.bool(table, key, name)
+  }
   /** Absent is the documented default; present-but-not-a-boolean is still an error. */
   optionalBool(table: Table, key: string, name: string, fallback: boolean): boolean {
     if (table[key] === undefined) return fallback
@@ -481,8 +489,7 @@ export function parseConfig(text: string): RepoControlsConfig {
   const branches = problems.table(controls, 'branches', ['protected', 'prefixes'])
   // `branches` and `pre_push.remote` are REQUIRED: install always seeds them, and
   // `pre-push` reads their env vars with `${VAR:?}`, which aborts on an empty value —
-  // so "no branch policy" cannot be spelled as an empty list. Everything else is
-  // optional and defaults to off.
+  // so "no branch policy" cannot be spelled as an empty list.
   const preCommit = problems.optionalTable(controls, 'pre_commit', ['static_checks', 'staged_coverage', 'doc_freshness', 'compliance'])
   const prePush = problems.table(controls, 'pre_push', ['coverage_ratchet', 'coverage_produce', 'findings_ratchet', 'static_checks', 'export_links', 'remote'])
   // Optional, and every field defaults, so a repository that never writes this
@@ -520,7 +527,10 @@ export function parseConfig(text: string): RepoControlsConfig {
   // Which branch is promoted to which. No default pair: defaulting to
   // integration -> main would put one repository's branch names back into
   // this package by the back door.
-  const release = problems.optionalTable(controls, 'release', ['source', 'target', 'merge_strategy', 'pre_bump'])
+  const releaseOptedOut = controls.release === false || (isTable(controls.release) && controls.release.enabled === false)
+  if (isTable(controls.release) && controls.release.enabled !== undefined && typeof controls.release.enabled !== 'boolean') problems.add('release.enabled must be a boolean')
+  if (controls.release === true) problems.add('release must be a table, or false to opt out of promotion governance')
+  const release = controls.release === false || controls.release === true ? {} : problems.optionalTable(controls, 'release', ['enabled', 'source', 'target', 'merge_strategy', 'pre_bump'])
   const releaseMergeStrategy = problems.optionalString(release, 'merge_strategy', 'release.merge_strategy', 'squash')
   if (!Object.hasOwn(MERGE_STRATEGIES, releaseMergeStrategy)) {
     problems.add(`release.merge_strategy must be one of ${Object.keys(MERGE_STRATEGIES).join(', ')}`)
@@ -536,17 +546,17 @@ export function parseConfig(text: string): RepoControlsConfig {
       // Same shape as `pre_push.static_checks`; this package never interprets
       // the command and names no tool.
       staticChecks: preCommit.static_checks === undefined ? [] : parseStaticChecks(preCommit.static_checks, problems, 'pre_commit.static_checks'),
-      stagedCoverage: problems.optionalBool(preCommit, 'staged_coverage', 'pre_commit.staged_coverage', true),
-      docFreshness: problems.optionalBool(preCommit, 'doc_freshness', 'pre_commit.doc_freshness', true),
-      compliance: problems.optionalBool(preCommit, 'compliance', 'pre_commit.compliance', true),
+      stagedCoverage: problems.requiredBool(preCommit, 'staged_coverage', 'pre_commit.staged_coverage'),
+      docFreshness: problems.requiredBool(preCommit, 'doc_freshness', 'pre_commit.doc_freshness'),
+      compliance: problems.requiredBool(preCommit, 'compliance', 'pre_commit.compliance'),
     },
     prePush: {
-      coverageRatchet: problems.optionalBool(prePush, 'coverage_ratchet', 'pre_push.coverage_ratchet', true),
+      coverageRatchet: problems.requiredBool(prePush, 'coverage_ratchet', 'pre_push.coverage_ratchet'),
       // New gates opt in: the coverage measurement moved to pre-push, so a
       // repository that never writes this key keeps measuring (or not) exactly
       // where it did before.
-      coverageProduce: problems.optionalBool(prePush, 'coverage_produce', 'pre_push.coverage_produce', false),
-      findingsRatchet: problems.optionalBool(prePush, 'findings_ratchet', 'pre_push.findings_ratchet', true),
+      coverageProduce: problems.requiredBool(prePush, 'coverage_produce', 'pre_push.coverage_produce'),
+      findingsRatchet: problems.requiredBool(prePush, 'findings_ratchet', 'pre_push.findings_ratchet'),
       staticChecks: prePush.static_checks === undefined ? [] : parseStaticChecks(prePush.static_checks, problems, 'pre_push.static_checks'),
       // Untracked paths the HEAD export needs, e.g. a dependency directory.
       // The hook used to hardcode `node_modules`, which assumed JavaScript in a
@@ -571,6 +581,7 @@ export function parseConfig(text: string): RepoControlsConfig {
       staticChecks: commitMsg.static_checks === undefined ? [] : parseStaticChecks(commitMsg.static_checks, problems, 'commit_msg.static_checks'),
     },
     release: {
+      optedOut: releaseOptedOut,
       source: problems.optionalString(release, 'source', 'release.source', ''),
       target: problems.optionalString(release, 'target', 'release.target', ''),
       // The MCP server's PR tool admits only Squash, and that enum is the
@@ -757,7 +768,5 @@ export function configEnv(repo: string, config: RepoControlsConfig): Record<stri
       .map(([name, command]) => `${name}\t${command}`)
       .join('\n'),
   }
-  // enact-m5's pre-commit honours ADL_SKIP_STAGED_COVERAGE=1; disabled config sets it.
-  if (!config.preCommit.stagedCoverage) env.ADL_SKIP_STAGED_COVERAGE = '1'
   return env
 }

package/packages/repo-controls/src/constants.ts

@@ -69,6 +69,15 @@ export const VERSION_BUMP_REL = '.workflows/version-bump.sh'
 /** The standalone CI stage-2 guard: a PR branch must contain integration's tip and be at its version + 1 patch. */
 export const RECONCILE_GUARD_REL = '.workflows/reconcile-guard.sh'
 
+/** The folder skeleton `install` bootstraps for the adl standard trees; see README, "Scaffolding". */
+export const SCAFFOLD_ROOT = join(PACKAGE_ROOT, 'assets', 'scaffold')
+export const SCAFFOLD_TREES = ['docs', 'plans', 'workflows'] as const
+/** Repository-root entry files, scaffolded from `assets/scaffold/root/` when absent (never overwritten). */
+export const SCAFFOLD_ROOT_FILES = ['AGENTS.md', 'CLAUDE.md'] as const
+/** The invariants that apply to ALL repositories; install deploys it as `INVARIANTS.md` only when the target has none. */
+export const GLOBAL_INVARIANTS_SOURCE = join(PACKAGE_ROOT, 'assets', 'GLOBAL-INVARIANTS.md')
+export const GLOBAL_INVARIANTS_TARGET = 'INVARIANTS.md'
+
 export const MANAGED_ASSETS = [
   { rel: PROMOTE_REL, source: join(PACKAGE_ROOT, 'assets', 'promote.ts'), mode: 0o755, doctorId: 'promote' },
   {