@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.4

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

@@ -0,0 +1,506 @@
+// Target-repository installer.  `adl-config.toml` enrolls a repository;
+// `.workflows` is then an authoritative repo-controls projection, rebuilt on
+// every install. The only preserved bytes are pre-hard-cut hook-log evidence;
+// there is no adoption, merge, or displaced-original path for managed content.
+import { createHash } from 'node:crypto'
+import { chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { defaultComplianceConfigTextFor, seededComplianceAttributesFor } from './compliance-config.ts'
+import {
+  appendToTableSpan,
+  DEFAULT_CONFIG_TEXT,
+  extractTableSpan,
+  isTable,
+  removeTableSpan,
+  removeFromTableSpan,
+  RETIRED_ATTRIBUTES,
+  SEEDED_ATTRIBUTES,
+  type Table,
+} from './config.ts'
+import {
+  ADL_NPM_INSTALL,
+  CONFIG_REL,
+  GITIGNORE_REL,
+  HOOK_NAMES,
+  HOOKS_PATH,
+  LOCK_REL,
+  MANAGED_ASSETS,
+  TOOL,
+  VERSION,
+  WORKFLOWS_ROOT,
+} from './constants.ts'
+import { applyGitignoreBlock, removeGitignoreBlock } from './gitignore-block.ts'
+import { gitConfigGet, gitOrThrow, resolveRepo } from './runtime.ts'
+
+export interface Action {
+  kind: 'create' | 'update' | 'chmod' | 'remove' | 'remove-dir' | 'git-config'
+  target: string
+  reason: string
+}
+
+/**
+ * Whether `install()` created `.gitignore` from nothing. That is now the
+ * only fact `uninstall()` needs: the adl-managed block is found and removed
+ * by its own start/end markers (`gitignore-block.ts`), not by replaying a
+ * remembered line list — so there is nothing else left to record.
+ */
+interface GitignoreRecord {
+  created: boolean
+}
+
+export type TableConfigRecord = { created: boolean; sha256: string } | null
+
+export interface Lock {
+  lockVersion: 1
+  tool: typeof TOOL
+  version: string
+  files: Record<string, { sha256: string }>
+  config: TableConfigRecord
+  /** Absent on a lock written before compliance support (commit 1809e8a) — readLock defaults it to null. */
+  complianceConfig: TableConfigRecord
+  gitignore: GitignoreRecord | null
+}
+
+/**
+ * Previous repo-controls log roots are quarantine evidence only. Install and
+ * uninstall preserve bytes already present there, but never read, copy, move,
+ * or write them. Both are unconditionally ignored by the adl-managed
+ * `.gitignore` block (see `gitignore-block.ts`) regardless of whether either
+ * still holds evidence in a given repository.
+ */
+const LEGACY_LOG_QUARANTINES = [{ rel: '.workflows/hooks/logs' }, { rel: '.enact-runtime/repo-controls/hooks' }] as const
+
+const sha256 = (bytes: string | Buffer): string => createHash('sha256').update(bytes).digest('hex')
+
+/** The vendored promoter's source, inside this package. */
+export function vendoredPromotePath(): string {
+  return MANAGED_ASSETS[0].source
+}
+
+/**
+ * The stub execs `adl repo controls hook <name>`, not a standalone
+ * `adl-repo-controls` binary (adl-m3-finish item 1, 2026-09-27): this
+ * package is folded into the `adl` binary's `repo controls` namespace
+ * (docs/architecture/cli-design.md §6, STATUS.md item 10) — hard cut, no compat shim, the
+ * same decision `adl hook` already made for agent-hooks. `adl` is what a
+ * repository's hooks now require on PATH, and `adl` is what the fleet
+ * actually installs (bin/reconcile's `bun-compile` manager); see
+ * ADL_NPM_INSTALL for how a machine outside the fleet gets it.
+ */
+export function stubText(name: string): string {
+  return `#!/bin/sh
+# Managed by adl-repo-controls — do not edit. Update with: adl repo controls install --repo .
+if ! command -v adl >/dev/null 2>&1; then
+  echo "adl: FAIL — 'adl' is not on PATH, so this repository's ${name} hook cannot run." >&2
+  echo "  Install it: ${ADL_NPM_INSTALL}   (then retry the git command)" >&2
+  exit 1
+fi
+exec adl repo controls hook ${name} "$@"
+`
+}
+
+const isRelative = (path: string): boolean =>
+  path !== '' && !path.startsWith('/') && !path.includes('\\') && !path.split('/').includes('..')
+
+export function readLock(repo: string): Lock | null {
+  const path = join(repo, LOCK_REL)
+  if (!existsSync(path)) return null
+  let raw: Partial<Lock>
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf8'))
+  } catch {
+    throw new Error(`${LOCK_REL} is not valid JSON`)
+  }
+  if (raw.tool !== TOOL) throw new Error(`${LOCK_REL} is not an adl-repo-controls lock`)
+  const lock: Lock = {
+    lockVersion: 1,
+    tool: TOOL,
+    version: String(raw.version),
+    files: raw.files ?? {},
+    config: raw.config ?? null,
+    complianceConfig: raw.complianceConfig ?? null,
+    gitignore: raw.gitignore ?? null,
+  }
+  for (const rel of Object.keys(lock.files)) {
+    if (!isRelative(rel)) throw new Error(`${LOCK_REL} records a non-repository-relative path: ${rel}`)
+  }
+  return lock
+}
+
+/**
+ * The lock is itself inside the authoritative root.  A corrupt or retired
+ * lock is stale root content, not authority to block a marked repository's
+ * reconciliation; install deletes it with the rest of `.workflows`.
+ */
+function priorLockForReconciliation(repo: string): Lock | null {
+  try {
+    return readLock(repo)
+  } catch {
+    return null
+  }
+}
+
+class Ops {
+  readonly actions: Action[] = []
+  private readonly removed = new Set<string>()
+  // Under --dry-run, writes never hit disk, so a second write() to the same target
+  // within one Ops session (e.g. [controls] then [compliance] both landing in
+  // adl-config.toml) must diff against what an EARLIER write() in this same
+  // session produced, not against the (unchanged) disk content, or it would report
+  // 'create' twice instead of 'create' then 'update' the way a real run would.
+  private readonly writtenSoFar = new Map<string, Buffer>()
+
+  constructor(
+    private readonly repo: string,
+    private readonly dryRun: boolean,
+  ) {}
+
+  private abs(rel: string): string {
+    return join(this.repo, rel)
+  }
+
+  private scheduledForRemoval(rel: string): boolean {
+    return [...this.removed].some((removed) => rel === removed || rel.startsWith(`${removed}/`))
+  }
+
+  write(rel: string, content: string | Buffer, reason: string, mode?: number): void {
+    const path = this.abs(rel)
+    const bytes = Buffer.from(content)
+    const previous = this.writtenSoFar.get(rel) ?? (this.scheduledForRemoval(rel) ? null : existsSync(path) ? readFileSync(path) : null)
+    const existed = previous !== null
+    if (existed && (previous as Buffer).equals(bytes)) {
+      if (mode !== undefined && (lstatSync(path).mode & 0o777) !== mode) {
+        this.actions.push({ kind: 'chmod', target: rel, reason })
+        if (!this.dryRun) chmodSync(path, mode)
+      }
+      return
+    }
+    this.actions.push({ kind: existed ? 'update' : 'create', target: rel, reason })
+    this.writtenSoFar.set(rel, bytes)
+    if (this.dryRun) return
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, bytes)
+    if (mode !== undefined) chmodSync(path, mode)
+  }
+
+  remove(rel: string, reason: string): void {
+    const path = this.abs(rel)
+    // `existsSync` follows links and reports false for a dangling link.  Owned
+    // roots must prune that stale link rather than letting a later mkdir follow
+    // or collide with it.
+    const stats = lstatSync(path, { throwIfNoEntry: false })
+    if (stats === undefined) return
+    const directory = stats.isDirectory() && !stats.isSymbolicLink()
+    this.actions.push({ kind: directory ? 'remove-dir' : 'remove', target: rel, reason })
+    this.removed.add(rel)
+    if (!this.dryRun) rmSync(path, { recursive: true, force: true })
+  }
+
+  git(target: string, args: string[], reason: string): void {
+    this.actions.push({ kind: 'git-config', target, reason })
+    if (!this.dryRun) gitOrThrow(this.repo, ['config', '--local', ...args])
+  }
+}
+
+export interface InstallOptions {
+  dryRun?: boolean
+}
+
+export interface InstallResult {
+  repo: string
+  actions: Action[]
+  dryRun: boolean
+}
+
+function readCentralMarker(repo: string): string {
+  const configPath = join(repo, CONFIG_REL)
+  if (!existsSync(configPath)) {
+    throw new Error(`${CONFIG_REL} is missing — this repository is not centrally managed`)
+  }
+  return readFileSync(configPath, 'utf8')
+}
+
+export function install(repoArg: string, options: InstallOptions): InstallResult {
+  const repo = resolveRepo(repoArg)
+  const initialConfigText = readCentralMarker(repo)
+  // Validate only repo-controls' declared tables before deleting its root.
+  // Other owners' tables remain deliberately opaque.
+  validateOwnedConfig(initialConfigText)
+  const dryRun = options.dryRun === true
+  // The lock is outside neither configuration nor runtime boundaries, so read
+  // its bookkeeping before replacing its containing root.  It is never used
+  // to preserve root content.
+  const prev = priorLockForReconciliation(repo)
+  const ops = new Ops(repo, dryRun)
+  const stubs = HOOK_NAMES.map((name) => [`${HOOKS_PATH}/${name}`, stubText(name)] as const)
+  const assets = MANAGED_ASSETS.map((asset) => ({ asset, bytes: readFileSync(asset.source) }))
+  const managedPaths = [...stubs.map(([rel]) => rel), ...assets.map(({ asset }) => asset.rel)]
+  if (managedPaths.length !== new Set(managedPaths).size || assets.some(({ bytes }) => bytes.length === 0)) {
+    throw new Error('authoritative .workflows source is incomplete')
+  }
+  // This root is a single owner, so drift, stale files, old lock formats, and
+  // removed managed files are pruned before the authoritative projection is
+  // rebuilt. Pre-hard-cut log evidence is quarantined in place.
+  reconcileWorkflowsRoot(repo, ops, 'authoritative repo-controls root reconciliation')
+
+  const files: Lock['files'] = {}
+  // Standalone CI assets are copied BYTE-FOR-BYTE, executable, and locked.
+  // No templating: one published hash verifies the same bytes in every repo.
+  for (const { asset, bytes } of assets) {
+    ops.write(asset.rel, bytes, 'vendored workflow asset', asset.mode)
+    files[asset.rel] = { sha256: sha256(bytes) }
+  }
+
+  for (const [rel, text] of stubs) {
+    ops.write(rel, text, 'managed hook stub', 0o755)
+    files[rel] = { sha256: sha256(text) }
+  }
+
+  const controlsResult = installConfigTable(
+    initialConfigText,
+    'controls',
+    DEFAULT_CONFIG_TEXT,
+    SEEDED_ATTRIBUTES,
+    prev?.config ?? null,
+    ops,
+  )
+  const complianceResult = installConfigTable(
+    controlsResult.text,
+    'controls.compliance',
+    defaultComplianceConfigTextFor(repo),
+    seededComplianceAttributesFor(repo),
+    prev?.complianceConfig ?? null,
+    ops,
+  )
+  // Both entries' hashes are computed from the SAME final merged text (not each call's
+  // intermediate view of it): appending [compliance] after [controls] can extend the byte
+  // span findTableSpan reports for [controls] (e.g. a trailing blank separator line before
+  // the next header), so hashing at each call's own intermediate text would immediately
+  // go stale the moment a later call appends more content to the same file.
+  const finalConfigText = complianceResult.text
+  const config: TableConfigRecord = { created: controlsResult.created, sha256: sha256(extractTableSpan(finalConfigText, 'controls') as string) }
+  const complianceConfig: TableConfigRecord = {
+    created: complianceResult.created,
+    sha256: sha256(extractTableSpan(finalConfigText, 'controls.compliance') as string),
+  }
+
+  const gitignore = installGitignore(repo, prev?.gitignore ?? null, ops)
+
+  const current = gitConfigGet(repo, 'core.hooksPath')
+  if (current !== HOOKS_PATH) ops.git('core.hooksPath', ['core.hooksPath', HOOKS_PATH], 'activate the committed hook stubs')
+
+  const lock: Lock = {
+    lockVersion: 1,
+    tool: TOOL,
+    version: VERSION,
+    files,
+    config,
+    complianceConfig,
+    gitignore,
+  }
+  ops.write(LOCK_REL, `${JSON.stringify(lock, null, 2)}\n`, 'install lock')
+  return { repo, actions: ops.actions, dryRun }
+}
+
+/** The value at a dotted table path (`controls.compliance`), or undefined if absent. */
+function atPath(document: Table, path: readonly string[]): unknown {
+  return path.reduce<unknown>((node, segment) => (isTable(node) ? node[segment] : undefined), document)
+}
+
+/** Parse only the table this package owns; foreign tables remain opaque bytes. */
+function ownedTable(text: string, tableName: string): Table | null {
+  const span = extractTableSpan(text, tableName)
+  if (span === null) return null
+  try {
+    const value = atPath(Bun.TOML.parse(span) as Table, tableName.split('.'))
+    if (!isTable(value)) throw new Error(`[${tableName}] did not decode to a table`)
+    return value
+  } catch (error) {
+    throw new Error(`${CONFIG_REL} [${tableName}] is invalid TOML: ${(error as Error).message}`)
+  }
+}
+
+/** Reject malformed text that declares itself to be this package's table. */
+function assertNoMalformedOwnedHeader(text: string): void {
+  for (const raw of text.split('\n')) {
+    const line = raw.trim()
+    const ownedArrayTable = /^\[\[\s*(controls(?:\.[A-Za-z0-9_-]+)*)\s*\]\]\s*(?:#.*)?$/.exec(line)
+    if (ownedArrayTable !== null) {
+      throw new Error(`${CONFIG_REL} declares unsupported owned array table: [[${ownedArrayTable[1]}]]`)
+    }
+    if (/^\[\[\s*controls(?:\.|\]|\s)/.test(line)) {
+      throw new Error(`${CONFIG_REL} [controls] is invalid TOML: malformed table header`)
+    }
+    if (line === '[controls' || /^\[controls(?=\.|\])/.test(line) && !/^\[controls(?:\.[A-Za-z0-9_-]+)*\]$/.test(line)) {
+      throw new Error(`${CONFIG_REL} [controls] is invalid TOML: malformed table header`)
+    }
+  }
+}
+
+function validateOwnedConfig(text: string): void {
+  assertNoMalformedOwnedHeader(text)
+  ownedTable(text, 'controls')
+  ownedTable(text, 'controls.compliance')
+}
+
+function assertOwnedTableAppended(beforeText: string, afterText: string, tableName: string, defaultText: string): void {
+  if (!afterText.startsWith(beforeText.endsWith('\n') ? beforeText : `${beforeText}\n`)) {
+    throw new Error(`Refusing to write ${CONFIG_REL}: appending [${tableName}] would change content it does not own`)
+  }
+  const intended = ownedTable(defaultText, tableName)
+  const actual = ownedTable(afterText, tableName)
+  if (JSON.stringify(actual) !== JSON.stringify(intended)) {
+    throw new Error(`Refusing to write ${CONFIG_REL}: appended [${tableName}] did not decode as intended`)
+  }
+}
+
+/**
+ * `adl-config.toml` is shared with adl hook ([hooks]/[rules]/[repo]) and
+ * adl-extensions ([skills]); this package only ever writes its own `[controls]`
+ * and `[compliance]` tables, each once, as a pure append — never a read-modify-write
+ * of the whole file. `currentText` is threaded explicitly (rather than re-read from
+ * disk) so that a second call in the same `install()` run sees the first call's
+ * result even under `--dry-run`, when nothing has actually hit disk yet.
+ */
+function installConfigTable(
+  currentText: string,
+  tableName: string,
+  defaultText: string,
+  attributes: { key: string; text: string }[],
+  prevEntry: TableConfigRecord,
+  ops: Ops,
+): { text: string; created: boolean } {
+  const existing = ownedTable(currentText, tableName)
+  if (existing !== null) {
+    // The table is the user's. Scaffold only the attributes it LACKS, appended at the
+    // end of its span; never rewrite, reorder or reformat one that is already there,
+    // whatever its value. `created` stays false — we did not create this table, so
+    // uninstall must not splice it out and drift detection does not apply to it.
+    let text = currentText
+    const changed: string[] = []
+    for (const retired of RETIRED_ATTRIBUTES) {
+      if (existing[retired] === undefined) continue
+      const stripped = removeFromTableSpan(text, tableName, retired)
+      if (stripped !== text) {
+        text = stripped
+        changed.push(`${retired} (retired)`)
+      }
+    }
+    for (const attribute of attributes) {
+      if (existing[attribute.key] === undefined) {
+        text = appendToTableSpan(text, tableName, attribute.text)
+        changed.push(attribute.key)
+      }
+    }
+    if (changed.length > 0) {
+      ops.write(CONFIG_REL, text, `scaffold [${tableName}] ${changed.join(', ')} (user attributes untouched)`)
+    }
+    return { text, created: prevEntry?.created ?? false }
+  }
+  const base = currentText.endsWith('\n') ? currentText : `${currentText}\n`
+  const appended = `${base}\n${defaultText}`
+  assertOwnedTableAppended(currentText, appended, tableName, defaultText)
+  ops.write(CONFIG_REL, appended, `append [${tableName}] table to shared adl-config.toml (user-owned after install)`)
+  return { text: appended, created: true }
+}
+
+function installGitignore(repo: string, prev: GitignoreRecord | null, ops: Ops): GitignoreRecord {
+  const path = join(repo, GITIGNORE_REL)
+  const exists = existsSync(path)
+  const text = exists ? readFileSync(path, 'utf8') : ''
+  const next = applyGitignoreBlock(text)
+  if (next !== text) ops.write(GITIGNORE_REL, next, 'write the adl-managed .gitignore block')
+  return { created: prev?.created ?? !exists }
+}
+
+function realDirectoryHasData(repo: string, rel: string): boolean {
+  let current = repo
+  for (const segment of rel.split('/')) {
+    current = join(current, segment)
+    const stats = lstatSync(current, { throwIfNoEntry: false })
+    if (stats === undefined || !stats.isDirectory() || stats.isSymbolicLink()) return false
+  }
+  return readdirSync(current).length > 0
+}
+
+function reconcileWorkflowsRoot(repo: string, ops: Ops, reason: string): void {
+  const workflowLogs = LEGACY_LOG_QUARANTINES[0]
+  if (!realDirectoryHasData(repo, workflowLogs.rel)) {
+    ops.remove(WORKFLOWS_ROOT, reason)
+    return
+  }
+  const root = join(repo, WORKFLOWS_ROOT)
+  for (const entry of readdirSync(root)) {
+    if (entry !== 'hooks') ops.remove(`${WORKFLOWS_ROOT}/${entry}`, reason)
+  }
+  const hooks = join(root, 'hooks')
+  for (const entry of readdirSync(hooks)) {
+    if (entry !== 'logs') ops.remove(`${HOOKS_PATH}/${entry}`, reason)
+  }
+  removeSymlinksBelow(repo, workflowLogs.rel, ops)
+}
+
+function removeSymlinksBelow(repo: string, relative: string, ops: Ops): void {
+  for (const entry of readdirSync(join(repo, relative))) {
+    const child = `${relative}/${entry}`
+    const stats = lstatSync(join(repo, child))
+    if (stats.isSymbolicLink()) {
+      ops.remove(child, 'remove symlink from managed workflow tree without traversing its target')
+    } else if (stats.isDirectory()) {
+      removeSymlinksBelow(repo, child, ops)
+    }
+  }
+}
+
+export type UninstallOptions = InstallOptions
+
+export interface UninstallResult extends InstallResult {
+  notes: string[]
+}
+
+export function uninstall(repoArg: string, options: UninstallOptions): UninstallResult {
+  const repo = resolveRepo(repoArg)
+  validateOwnedConfig(readCentralMarker(repo))
+  const dryRun = options.dryRun === true
+  const lock = priorLockForReconciliation(repo)
+  const ops = new Ops(repo, dryRun)
+  const notes: string[] = []
+  const configPath = join(repo, CONFIG_REL)
+  // Remove the managed projection while preserving quarantined pre-hard-cut
+  // log evidence in place.
+  reconcileWorkflowsRoot(repo, ops, 'remove authoritative repo-controls root')
+  // adl-config.toml is shared with other tools and must never be deleted — only the
+  // appended [controls]/[compliance] spans are spliced back out, leaving the rest of the
+  // file untouched. Each span is removed independently, based only on its own `created`
+  // flag, so an adopted (pre-existing, created: false) table is never touched here.
+  if ((lock?.config?.created || lock?.complianceConfig?.created) && existsSync(configPath)) {
+    let spliced = readFileSync(configPath, 'utf8')
+    if (lock?.config?.created) spliced = removeTableSpan(spliced, 'controls')
+    if (lock?.complianceConfig?.created) spliced = removeTableSpan(spliced, 'controls.compliance')
+    ops.write(CONFIG_REL, spliced, 'remove appended [controls]/[compliance] tables (adl-config.toml itself is never deleted)')
+  }
+
+  // Canonical logs and quarantined legacy evidence are runtime state, not
+  // uninstall targets — only the .gitignore block that ignores them is
+  // removed. `lock.gitignore` may be absent on a lock written before this
+  // module existed; nothing to strip back out in that case.
+  if (lock?.gitignore) removeGitignoreLines(repo, lock.gitignore, ops)
+
+  const current = gitConfigGet(repo, 'core.hooksPath')
+  if (current === HOOKS_PATH) {
+    ops.git('core.hooksPath', ['--unset', 'core.hooksPath'], 'deactivate the authoritative hook root')
+  } else if (current !== null) {
+    notes.push(`kept core.hooksPath=${current} (outside the authoritative root)`)
+  }
+
+  return { repo, actions: ops.actions, dryRun, notes }
+}
+
+function removeGitignoreLines(repo: string, record: GitignoreRecord, ops: Ops): void {
+  const path = join(repo, GITIGNORE_REL)
+  if (!existsSync(path)) return
+  const text = readFileSync(path, 'utf8')
+  const out = removeGitignoreBlock(text)
+  if (record.created && out.trim() === '') ops.remove(GITIGNORE_REL, 'adl managed .gitignore block removed (file now empty)')
+  else ops.write(GITIGNORE_REL, out, 'adl managed .gitignore block removed')
+}

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

@@ -0,0 +1,104 @@
+/**
+ * The control boundary at commit time.
+ *
+ * These paths define a repository's enforcement surface. Agents may edit them
+ * while preparing a reviewed change, but a normal commit must never land them.
+ * Git's `--no-verify` is intentionally outside this local hook's authority;
+ * adl hook is responsible for refusing that escape hatch to agents.
+ */
+
+export const WIRING: readonly string[] = ['adl-config.toml']
+
+const FIXED_ROOTS: readonly string[] = ['compliance', 'workflows']
+
+/** A declared pattern, as a regex. `*` stays in one directory; `**` crosses them. */
+function patternToRegExp(pattern: string): RegExp {
+  let out = ''
+  for (let i = 0; i < pattern.length; i++) {
+    const char = pattern[i] as string
+    if (char === '*') {
+      if (pattern[i + 1] === '*') {
+        i++
+        if (pattern[i + 1] === '/') {
+          i++
+          out += '(?:.*/)?'
+        } else {
+          out += '.*'
+        }
+      } else {
+        out += '[^/]*'
+      }
+      continue
+    }
+    out += char.replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+  }
+  return new RegExp(`^${out}$`)
+}
+
+/** Match the repository-declared portion of the protected set. */
+export function protectedMatchers(watched: readonly string[]): ((path: string) => boolean)[] {
+  const wiring = WIRING.map((name) => (path: string) => path === name)
+  const declared = watched.map((pattern) => {
+    const re = patternToRegExp(pattern)
+    return (path: string) => re.test(path)
+  })
+  return [...wiring, ...declared]
+}
+
+const isUnderFixedRoot = (path: string): boolean => FIXED_ROOTS.some((root) => path === root || path.startsWith(`${root}/`))
+
+/** Centrally managed repository files that must travel with the next commit. */
+export const isTopLevelDotPath = (path: string): boolean => path.startsWith('.')
+
+/**
+ * The single source of truth used for final-index and dirty-worktree checks.
+ * Fixed package policy protects root compliance/workflows and the enrollment
+ * file; each repository adds its own gate files through `watched`.
+ */
+export function isProtectedPath(path: string, watched: readonly string[]): boolean {
+  return isUnderFixedRoot(path) || protectedMatchers(watched).some((match) => match(path))
+}
+
+/**
+ * Diagnostics are deliberately path-only: callers combine index and worktree
+ * observations before calling this, so a staged-and-edited path appears once.
+ */
+export function integrityProblems(paths: readonly string[], watched: readonly string[]): string[] {
+  const protectedPaths = [...new Set(paths.filter((path) => isProtectedPath(path, watched)))].sort()
+  if (protectedPaths.length === 0) return []
+
+  return [
+    'pre-commit: FAIL — protected control changes require Tarun’s review and cannot be committed normally.',
+    '',
+    '  Do not stage or commit these paths yourself:',
+    ...protectedPaths.map((path) => `      ${path}`),
+    '',
+    '  Leave them uncommitted and ask Tarun to review and land the change.',
+  ]
+}
+
+/**
+ * A managed top-level dot path is not a human-only control surface. It may be committed
+ * normally, but cannot be silently left out of a commit that sees its edit.
+ */
+export function commitRequiredProblems(paths: readonly string[], watched: readonly string[]): string[] {
+  const requiredPaths = [
+    ...new Set(
+      paths.filter(
+        (path) =>
+          isTopLevelDotPath(path) &&
+          path !== '.scratchpad' &&
+          !path.startsWith('.scratchpad/') &&
+          !isProtectedPath(path, watched),
+      ),
+    ),
+  ].sort()
+  if (requiredPaths.length === 0) return []
+
+  return [
+    'pre-commit: FAIL — centrally managed dotfile changes are excluded from this commit.',
+    '',
+    '  Stage these paths, then commit them with the related change:',
+    ...requiredPaths.map((path) => `      ${path}`),
+  ]
+}

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

@@ -0,0 +1,25 @@
+/**
+ * The standalone asset is the canonical promoter implementation.
+ *
+ * Keeping the package API as a re-export means the implementation exercised by
+ * unit tests is byte-for-byte the implementation `install` copies into consumer
+ * repositories. Do not add a second implementation here.
+ */
+export {
+  BUILD_POLICY_TYPE,
+  MERGE_STRATEGIES,
+  MINIMUM_REVIEWER_POLICY_TYPE,
+  ensurePromotionPullRequest,
+  main,
+  promotionPolicyReceipts,
+  promotionTitle,
+  type FetchImpl,
+  type MergeStrategy,
+  type PolicyConfiguration,
+  type PolicyConfigurationList,
+  type PolicyScope,
+  type PromotionPolicyReceipts,
+  type PromotionPolicyRequirement,
+  type PromotionRequest,
+  type PromotionResult,
+} from '../assets/promote.ts'