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

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

@@ -0,0 +1,97 @@
+import { readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+export const TOOL = 'adl-repo-controls'
+/**
+ * Never published (adl-m3-finish item 1, 2026-09-27): kept only as this
+ * package's own internal identity (USAGE text, error messages, the lock
+ * file's `tool` field) — none of that is a claim that `adl-repo-controls`
+ * is installable. NPM_INSTALL/PACKAGE_NAME describe a registry package that
+ * does not exist; do not point a user-facing "how do I get this on PATH"
+ * message at them (see ADL_NPM_INSTALL below for the one that is real).
+ */
+export const PACKAGE_NAME = '@amsterdamdatalabs/adl-repo-controls'
+export const NPM_INSTALL = `npm i -g ${PACKAGE_NAME}`
+/**
+ * How a repository's committed git-hook stubs actually get `adl` onto
+ * PATH: this package is folded into the `adl` binary's `repo controls`
+ * namespace (docs/architecture/cli-design.md §6, STATUS.md item 10) and is never itself
+ * a standalone global command. `adl` is either fleet-installed
+ * (bin/reconcile's `bun-compile` manager) or, for a machine not yet pinned
+ * to the fleet, this published wrapper — see
+ * workflows/scripts/release/npm-package-template.ts's NAME_STEM and
+ * packaging/npm/wrapper-bin.js.
+ */
+export const ADL_NPM_INSTALL = 'npm install -g @amsterdamdatalabs/adl-agent-control'
+export const PACKAGE_ROOT = resolve(import.meta.dir, '..')
+export const VERSION: string = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')).version
+
+/** Package-owned hook implementations, flattened in commit 20ec790. */
+// Was `scripts/verbatim/`, a tree shaped like a
+// CONSUMER's (`workflows/`, `infra/`) and holding byte-copies of enact-m5's
+// files. That shape was the coupling: `workflows/` is the tree a repository
+// declares and owns, so a package directory mirroring it was the package
+// claiming a surface that is not its own. Flattened 2026-09-16.
+export const BUNDLE_ROOT = join(PACKAGE_ROOT, 'scripts')
+
+/** Bundled Python compliance engine (a `uv`-managed project), installed alongside this package. */
+export const COMPLIANCE_ROOT = join(PACKAGE_ROOT, 'package', 'adl-compliance')
+
+// `post-checkout` added 2026-09-27 (adl-m3-items item 2): the only backstop
+// for the repo's worktree-count limit (see `MAX_WORKTREES` below and
+// `worktree-guard.ts`) that runs regardless of which agent host or shell path
+// created the worktree — see that file's header for why git has no
+// pre-worktree hook and `post-checkout` is the earliest hook a `git worktree
+// add` actually triggers.
+export const HOOK_NAMES = ['pre-commit', 'commit-msg', 'pre-push', 'post-commit', 'post-checkout'] as const
+export type HookName = (typeof HOOK_NAMES)[number]
+
+export { MAX_WORKTREES } from './worktree-limit.ts'
+
+// Repository-relative paths written into target repositories.
+export const HOOKS_PATH = '.workflows/hooks'
+/**
+ * An enrolled repository delegates this entire root to repo-controls.  Nothing
+ * below it is user content: reconciliation removes it, then recreates the
+ * package's complete projection.
+ */
+export const WORKFLOWS_ROOT = '.workflows'
+
+/** The standalone promoter, deployed so CI needs nothing on PATH. */
+export const PROMOTE_REL = '.workflows/promote.ts'
+/** The standalone integration PR auto-complete helper. */
+export const AUTO_COMPLETE_REL = '.workflows/scripts/enable-integration-auto-complete.mjs'
+/** The standalone immutable package-version allocator for integration CI. */
+export const VERSION_BUMP_REL = '.workflows/version-bump.sh'
+
+export const MANAGED_ASSETS = [
+  { rel: PROMOTE_REL, source: join(PACKAGE_ROOT, 'assets', 'promote.ts'), mode: 0o755, doctorId: 'promote' },
+  {
+    rel: AUTO_COMPLETE_REL,
+    source: join(PACKAGE_ROOT, 'assets', 'enable-integration-auto-complete.mjs'),
+    mode: 0o755,
+    doctorId: 'integration-auto-complete',
+  },
+  {
+    rel: VERSION_BUMP_REL,
+    source: join(PACKAGE_ROOT, 'assets', 'version-bump.sh'),
+    mode: 0o755,
+    doctorId: 'version-bump',
+  },
+] as const
+/** Shared with adl hook ([hooks]/[rules]/[repo]) and adl-extensions ([skills]); this package owns only [controls]. */
+export const CONFIG_REL = 'adl-config.toml'
+export const LOCK_REL = '.workflows/repo-controls.lock.json'
+export const GITIGNORE_REL = '.gitignore'
+/**
+ * Legacy, pre-hard-cut repository-local log root (owner-qualified filenames
+ * prevented collisions there). Nothing writes here any more: git-hook logs
+ * moved to the shared `.adl/logs/` JSON-Lines format (Tarun, 2026-09-27,
+ * docs/architecture/cli-design.md §5a — see `hook-log.ts`). Kept only so existing evidence
+ * in an already-installed repository can still be named and quarantined in
+ * place (`install.ts`'s `LEGACY_LOG_QUARANTINES`, `gitignore-block.ts`);
+ * never read or written by this package.
+ */
+export const LOGS_ROOT_REL = '.enact/logs'
+
+export const INSTALL_HINT = `run: ${TOOL} install --repo .`

package/packages/repo-controls/src/coverage-ratchet.ts

@@ -0,0 +1,153 @@
+/**
+ * Coverage, as far as this package is concerned: a NAME, a SHAPE, and a RATCHET.
+ *
+ * Owner ruling, 2026-09-16: "adl-repo-controls should only care about the
+ * coverage file name, shape, ratchet mechanism. But how the coverage json file
+ * will be created has to be repo owned."
+ *
+ * So the division is:
+ *
+ *   NAME     `[controls.coverage].summary` — the repository says where it is.
+ *   SHAPE    the types below — what a summary must look like to be gradeable.
+ *   RATCHET  `coverageRegressions` — did anything get worse.
+ *
+ * and everything else is the repository's: measuring, instrumenting, selecting
+ * tests, producing the JSON, and the locks around all of that. None of it lives
+ * in this package, because none of it can. Instrumentation is language-bound —
+ * a Rust repo needs different machinery than a Svelte one — and a package that
+ * shipped one repository's would be standardising that repository rather than
+ * the convention.
+ *
+ * This replaces nine bundled scripts that were byte-copies of enact-m5's
+ * coverage stack, shipped under `scripts/verbatim/workflows/`. `workflows/` is
+ * the tree a repository declares and owns, so a package directory mirroring it
+ * was the package claiming a surface that is not its own.
+ */
+
+export interface MetricSummary {
+  total: number
+  covered: number
+  skipped?: number
+  pct: number
+}
+
+export type CoverageMetric = 'lines' | 'statements' | 'functions' | 'branches'
+export const COVERAGE_METRICS: readonly CoverageMetric[] = ['lines', 'statements', 'functions', 'branches']
+
+export type FileSummary = Record<CoverageMetric, MetricSummary>
+
+/**
+ * A summary is a map of repo-relative path -> per-file metrics, plus two
+ * reserved keys: `total` (the aggregate) and `srcTestRatio` (a bare number).
+ * Both are excluded from per-file grading; `srcTestRatio` is graded separately.
+ */
+export interface CoverageSummary {
+  [path: string]: FileSummary | number | undefined
+  srcTestRatio?: number
+}
+
+const RESERVED = new Set(['total', 'srcTestRatio'])
+
+const isFileSummary = (value: unknown): value is FileSummary =>
+  typeof value === 'object' && value !== null && COVERAGE_METRICS.every((m) => m in (value as object))
+
+/** Untested units. The only quantity this ratchet compares. */
+const uncovered = (m: MetricSummary): number => m.total - m.covered
+
+const round2 = (value: number): number => Math.round((value + Number.EPSILON) * 100) / 100
+
+/**
+ * Reads and validates a summary.
+ *
+ * Any failure throws. A missing or unparseable summary must never degrade to an
+ * empty object: an empty baseline forgives every regression at once, which is
+ * the same empty-scope false pass the compliance engine had to remove.
+ */
+export function readSummary(read: () => string): CoverageSummary {
+  let text: string
+  try {
+    text = read()
+  } catch (error) {
+    throw new Error(`coverage summary could not be read: ${error instanceof Error ? error.message : String(error)}`)
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch (error) {
+    throw new Error(`coverage summary is not valid JSON: ${error instanceof Error ? error.message : String(error)}`)
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error('coverage summary must be a JSON object of path -> metrics')
+  }
+  return parsed as CoverageSummary
+}
+
+/**
+ * Every way `current` is worse than `baseline`, as human-readable lines.
+ *
+ * ONE QUESTION: did the amount of untested code grow? `uncovered = total -
+ * covered`, per metric, per file. Owner decision 2026-09-16, after two other
+ * rules were tried and both failed on cases the other handled.
+ *
+ * Percentage is DERIVED, so it moves whenever the denominator moves — a file
+ * that grows flags even when nothing got worse. Absolute COVERED is worse
+ * still: it falls whenever code is deleted, so it calls deletion a regression.
+ * That is not merely a false positive. The producer throws before it writes the
+ * candidate summary, so a flagged deletion never reaches disk, the baseline
+ * keeps the old larger numbers, and the same deletion fails forever. You cannot
+ * remove code because removing it fails the gate, and the gate cannot learn the
+ * new shape because it failed.
+ *
+ * Counting untested lines dissolves all of it. Deletion and shrinkage lower the
+ * count and pass by construction, not by special case. A file that gains a
+ * little coverage and a lot of untested code still flags, which both other
+ * rules missed in one direction or the other.
+ *
+ * Two asymmetries remain deliberate:
+ *
+ *   a file with NO baseline is not graded — new code cannot exceed a count it
+ *   never had, so enrolling a file is never blocked by this gate.
+ *
+ *   a file that DISAPPEARS is not graded — there is nothing left to be untested.
+ *
+ * `srcTestRatio` is the exception: if the baseline reported one and the current
+ * summary does not, that is a measurement that stopped happening, and silence
+ * is never a pass.
+ *
+ * The cost, stated rather than hidden: this is STRICT. Adding 100 lines with 95
+ * covered flags, because untested rose by 5. In a file that already has a
+ * baseline, new code must be fully covered. It also makes measurement
+ * instability consequential — a host-dependent branch that flips now adds an
+ * uncovered line and flags every time, where a percentage could absorb it in
+ * rounding.
+ */
+export function coverageRegressions(baseline: CoverageSummary, current: CoverageSummary): string[] {
+  const errors: string[] = []
+
+  for (const [path, entry] of Object.entries(current)) {
+    if (RESERVED.has(path) || !isFileSummary(entry)) continue
+    const prior = baseline[path]
+    if (!isFileSummary(prior)) continue
+    for (const metric of COVERAGE_METRICS) {
+      const was = uncovered(prior[metric])
+      const now = uncovered(entry[metric])
+      if (now > was) {
+        errors.push(
+          `${path}: ${metric} — untested went ${was} -> ${now} ` +
+            `(${entry[metric].covered}/${entry[metric].total}, was ${prior[metric].covered}/${prior[metric].total})`,
+        )
+      }
+    }
+  }
+
+  const priorRatio = baseline.srcTestRatio
+  const nowRatio = current.srcTestRatio
+  if (typeof priorRatio === 'number') {
+    if (typeof nowRatio !== 'number') {
+      errors.push('src:test ratio missing from the current coverage summary')
+    } else if (round2(nowRatio) < round2(priorRatio)) {
+      errors.push(`src:test ratio regressed ${round2(priorRatio).toFixed(2)} -> ${round2(nowRatio).toFixed(2)}`)
+    }
+  }
+  return errors
+}

package/packages/repo-controls/src/doc-freshness.ts

@@ -0,0 +1,172 @@
+/**
+ * `last_update` freshness for documentation pages, graded on the STAGED INDEX.
+ *
+ * The rule is DOC-003's, unchanged: a page carries a `last_update` in its
+ * frontmatter, spelled `YYYY-MM-DDTHH:MM:SSZ`, and that stamp is neither in the
+ * future nor more than five hours old. What changed is the set it grades.
+ *
+ * As a compliance row this scoped `<docs>/**`, so every page in the tree was
+ * graded on every run and a document went red five hours after anyone touched
+ * it — an unbounded, permanently-reddening sweep that no amount of editing kept
+ * green. Here the set is the files this commit stages, so the question becomes
+ * the one the field was written to answer: you are editing this page right now,
+ * is its stamp current? A page nobody is touching is nobody's problem.
+ *
+ * The grading itself is pure — callers hand in text, never paths to read — so
+ * `now` is an argument and there is no clock, no `git`, and no filesystem here.
+ */
+
+/** DOC-003's window, carried over unchanged. */
+export const MAX_AGE_HOURS = 5
+
+/**
+ * Trees whose Markdown carries a published `last_update`.
+ *
+ * `plans/` was here and is deliberately gone, for the reason already written
+ * below about `docs/templates/` and `docs/maps/`: a document that stays open
+ * across weeks while its tickets are resolved one at a time is failed by a
+ * freshness window for doing exactly what it is for. A Feature spec is that
+ * shape by definition -- it is open until every one of its items is Done.
+ *
+ * It also resolved a collision between two gates this package owns. DOC-003
+ * required `last_update` on `plans/**`; LAY-009 requires `last_modified` on the
+ * same files. Both formats are identical (`YYYY-MM-DDTHH:MM:SSZ`) -- only the
+ * key differed -- so every plans document had to carry the same timestamp
+ * twice, under two names, to satisfy one package arguing with itself.
+ *
+ * Scope was the right thing to yield rather than either name. Renaming LAY-009's
+ * key would have turned 24 existing files red at once for a rule that should not
+ * have applied to them; dropping the tree fixes the collision and the
+ * mis-scoping in the same move, and no file changes. `plans/` keeps a timestamp
+ * requirement -- LAY-009 still demands `last_modified` and still validates it is
+ * ISO-8601 UTC. What it loses is a staleness window it should never have had.
+ */
+const ROOTS = ['docs/'] as const
+
+/** Structural pages: they describe a directory's contents, not a moment. */
+const EXCLUDED_NAMES = new Set(['AGENTS.md', 'CLAUDE.md', 'GAPS-AND-EVIDENCES.md', 'FUTURE_FEATURES_NOT_GAPS.md'])
+
+/**
+ * `docs/maps/` holds wayfinder decision maps and `docs/templates/` the blanks
+ * pages are cut from. Both stay open across weeks while their tickets are
+ * resolved one at a time, so a freshness window fails them for doing exactly
+ * what they are for. `docs/architecture/product/` is roadmap material with the
+ * same shape.
+ */
+const EXCLUDED_SUBTREES = ['docs/architecture/product/', 'docs/templates/', 'docs/maps/'] as const
+
+const LAST_UPDATE = /^last_update:\s*(.*)$/m
+/** Exact, like `strptime`: a lone date, a missing `Z` or a space separator is malformed, not lenient. */
+const TIMESTAMP = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})Z$/
+
+export interface StagedDoc {
+  path: string
+  text: string
+}
+
+export interface FreshnessProblem {
+  path: string
+  message: string
+  hint: string
+}
+
+/** Every staged page that fails the rule, ordered by path. One problem per page: the first that applies. */
+export function docFreshnessProblems(docs: StagedDoc[], now: Date): FreshnessProblem[] {
+  return docs
+    .filter((doc) => inScope(doc.path))
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+    .flatMap((doc) => {
+      const problem = grade(doc, now)
+      return problem ? [problem] : []
+    })
+}
+
+/**
+ * Whether this rule grades `path` at all. Exported so a caller can narrow the staged
+ * list before reading blobs out of the index — reading a file only to discard it is
+ * the whole cost of this check.
+ */
+export function inScope(path: string): boolean {
+  if (!path.endsWith('.md')) return false
+  if (!ROOTS.some((root) => path.startsWith(root))) return false
+  if (EXCLUDED_SUBTREES.some((subtree) => path.startsWith(subtree))) return false
+  return !EXCLUDED_NAMES.has(path.slice(path.lastIndexOf('/') + 1))
+}
+
+function grade(doc: StagedDoc, now: Date): FreshnessProblem | null {
+  const match = LAST_UPDATE.exec(frontmatter(doc.text))
+  if (match === null) {
+    return {
+      path: doc.path,
+      message: 'no last_update in frontmatter',
+      hint: 'add a last_update: YYYY-MM-DDTHH:MM:SSZ field to the frontmatter',
+    }
+  }
+
+  const value = unquote(match[1] ?? '')
+  const stamp = parseStamp(value)
+  if (stamp === null) {
+    return {
+      path: doc.path,
+      message: `last_update '${value}' is not YYYY-MM-DDTHH:MM:SSZ`,
+      hint: 'set last_update to a valid YYYY-MM-DDTHH:MM:SSZ UTC timestamp',
+    }
+  }
+
+  const hours = (now.getTime() - stamp.getTime()) / 3_600_000
+  if (hours < 0) {
+    return {
+      path: doc.path,
+      message: `last_update '${value}' is ${Math.abs(hours).toFixed(2)}h in the FUTURE`,
+      hint: 'set last_update to the current UTC time, not a future timestamp',
+    }
+  }
+  if (hours > MAX_AGE_HOURS) {
+    return {
+      path: doc.path,
+      message: `last_update '${value}' is ${hours.toFixed(2)}h old (limit ${MAX_AGE_HOURS}h)`,
+      hint: 'update last_update to the current UTC time when editing this page',
+    }
+  }
+  return null
+}
+
+/** The opening `---` block only. A `last_update:` line in the body is prose, not metadata. */
+function frontmatter(text: string): string {
+  if (!text.startsWith('---\n')) return ''
+  const end = text.indexOf('\n---\n', 4)
+  return end === -1 ? '' : text.slice(4, end)
+}
+
+function unquote(value: string): string {
+  const trimmed = value.trim()
+  const quoted = (trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  return quoted && trimmed.length >= 2 ? trimmed.slice(1, -1) : trimmed
+}
+
+/**
+ * `Date.parse` is lenient — it accepts `2026-02-30` and rolls it into March — so the
+ * fields are compared back against the string. A stamp that does not round-trip is
+ * not a date this rule recognises.
+ */
+function parseStamp(value: string): Date | null {
+  const match = TIMESTAMP.exec(value)
+  if (match === null) return null
+  const [year, month, day, hour, minute, second] = match.slice(1).map(Number) as [
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+  ]
+  const stamp = new Date(Date.UTC(year, month - 1, day, hour, minute, second))
+  const roundTrips =
+    stamp.getUTCFullYear() === year &&
+    stamp.getUTCMonth() === month - 1 &&
+    stamp.getUTCDate() === day &&
+    stamp.getUTCHours() === hour &&
+    stamp.getUTCMinutes() === minute &&
+    stamp.getUTCSeconds() === second
+  return roundTrips ? stamp : null
+}