@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.35 → 0.1.46

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/cli.py

@@ -389,9 +389,9 @@ def main(argv: Sequence[str] | None = None) -> int:
              "`root-files=STATUS.md,DRIFT.md` or `root-dirs=apps,packaging`; and "
              "`scripts-direct-files` (LAY-014), a positive integer replacing the "
              "default limit of 15 direct files per scripts directory, as "
-             "`scripts-direct-files=20`; `open-gaps` and `open-plans` (LAY-016), "
-             "each a positive integer replacing the default cap of 10 open gaps "
-             "or open plans, as `open-gaps=37` and `open-plans=11`; and "
+             "`scripts-direct-files=20`; `open-plans` (LAY-016), "
+             "a positive integer replacing the default cap of 10 open plans, "
+             "as `open-plans=11`; and "
              "`markdown-roots` (LAY-006), a "
              "comma-separated list of repository-relative directories whose "
              "Markdown is allowed in addition to the declared docs trees "

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/policy/docs_shape.py

@@ -6,8 +6,7 @@ this", and the answer is declared once, here, so a second docs gate does not
 grow its own, independently drifting copy the way LAY-008/LAY-012 once did for
 the repository root (see `root_shape.py`'s module docstring).
 
-Every entry below is read off an EXISTING docs gate, except `notes.md`, which
-is declared by an explicit decision (see its entry):
+Every entry below is read off an EXISTING docs gate:
 
 ALLOWED_DOCS_DIRS
     architecture, research, compliance, operations
@@ -43,15 +42,6 @@ ALLOWED_DOCS_FILES
         no repository in this estate ships a top-level `docs/index.md` today,
         and declaring it costs nothing.
 
-    notes.md
-        the task ledger. Not read off a docs gate: Tarun's global agent rule
-        (decision of 2026-10-01) requires every agent to append one line to
-        `docs/notes.md` when it starts a task and one when it finishes
-        (append-only, at most 100 characters per line), so the file exists in
-        every repository an agent works in and this gate would otherwise flag
-        it as undeclared. `docs-okf-profiles.yaml` carries a matching
-        `docs/notes.md` profile so `docs.okf-profile` (DOC-006) grades it too.
-
 These are PERMITTED, not required — the same distinction `root_shape.py`
 draws for the repository root. A repository using only two of the five
 directories is not missing three findings; it has simply not written those
@@ -72,5 +62,4 @@ ALLOWED_DOCS_FILES: frozenset[str] = frozenset({
     "AGENTS.md",
     "CLAUDE.md",
     "index.md",
-    "notes.md",
 })

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/policy/gate-registry.alt.yaml

@@ -605,7 +605,7 @@ rows:
   - id: LAY-016
     name: open-work-cap
     domain: layout
-    title: Cap open plans and open gaps at ten
+    title: Cap open plans at ten
     severity: M
     controls:
       - EC-A.5.36

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/policy/gate-registry.yaml

@@ -605,7 +605,7 @@ rows:
   - id: LAY-016
     name: open-work-cap
     domain: layout
-    title: Cap open plans and open gaps at ten
+    title: Cap open plans at ten
     severity: M
     controls:
       - EC-A.5.36

package/packages/repo-controls/package.json

@@ -13,7 +13,7 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "bun test tests --coverage --timeout 30000",
+    "test": "bun test --isolate tests --coverage --timeout 30000",
     "check": "tsc --noEmit && bun test tests --coverage --timeout 30000"
   },
   "dependencies": {

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

@@ -78,7 +78,21 @@ export interface FindingsConfig {
 
 export interface RepoControlsConfig {
   branches: { protected: string[] }
-  preCommit: { staticChecks: StaticCheck[]; stagedCoverage: boolean; docFreshness: boolean; compliance: boolean }
+  preCommit: {
+    staticChecks: StaticCheck[]
+    stagedCoverage: boolean
+    docFreshness: boolean
+    compliance: boolean
+    /**
+     * Defense-in-depth branch gate at pre-commit (see
+     * `hook.ts:protectedBranchStep` and `tests/protected-branch-step.test.ts`).
+     * Defaults OFF because the agent-hooks `git.commit-protected-branch` rule
+     * already covers host-routed `git commit`; this opt-in is for repositories
+     * that want the same protection on the path that bypasses the host layer
+     * (a `Bun.spawn`-issued commit, a post-checkout hook that lands a commit).
+     */
+    branchProtection: boolean
+  }
   commitMsg: { staticChecks: StaticCheck[] }
   release: { optedOut: boolean; source: string; target: string; mergeStrategy: MergeStrategy; preBump: string[] }
   postCommit: { staticChecks: StaticCheck[] }
@@ -491,7 +505,7 @@ export function parseConfig(text: string): RepoControlsConfig {
   // `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.
-  const preCommit = problems.optionalTable(controls, 'pre_commit', ['static_checks', 'staged_coverage', 'doc_freshness', 'compliance'])
+  const preCommit = problems.optionalTable(controls, 'pre_commit', ['static_checks', 'staged_coverage', 'doc_freshness', 'compliance', 'branch_protection'])
   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
   // table behaves exactly as before. `pre_push.coverage_ratchet` stays where it
@@ -549,6 +563,11 @@ export function parseConfig(text: string): RepoControlsConfig {
       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'),
+      // Opt-in defense-in-depth: defaults to OFF so a config that doesn't
+      // declare the key keeps the agent-hooks layer as the only gate, and
+      // turning it on requires an explicit `branch_protection = true` line
+      // (or the install seed).
+      branchProtection: problems.optionalBool(preCommit, 'branch_protection', 'pre_commit.branch_protection', false),
     },
     prePush: {
       coverageRatchet: problems.requiredBool(prePush, 'coverage_ratchet', 'pre_push.coverage_ratchet'),

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

@@ -176,25 +176,20 @@ export function doctor(repoArg: string, env: Env, options: string | DoctorOption
         : null,
       'pre_push.coverage_produce is disabled or [controls.coverage].produce_push is declared',
     )
-    const findingsFloorExists = existsSync(join(repo, config.findings.floor))
+    // A missing floor file is a zero-grant declaration, not a configuration
+    // error. The gate is armed and every emitted finding from a counter
+    // is undeclared. The doctor is silent: the gate IS the loud part.
+    // Tarun, 2026-10-13: "the gate should not be dependent on a ratchet
+    // file. no ratchet file means zero grants."
     add(
       'findings-floor',
-      config.prePush.findingsRatchet && !findingsFloorExists
-        ? `pre_push.findings_ratchet is enabled but ${config.findings.floor} does not exist — every push fails until a floor lands; commit one or set pre_push.findings_ratchet = false`
-        : null,
-      `${config.findings.floor} is present or the ratchet is disabled`,
+      null,
+      `${config.findings.floor} is committed or absent (absent = zero grants); the ratchet is disabled`,
     )
-    if (config.prePush.findingsRatchet && findingsFloorExists && Object.keys(config.findings.counters).length === 0) {
-      add(
-        'findings-counters',
-        'pre_push.findings_ratchet is enabled and a floor is committed but [controls.findings.counters] declares none — a ratchet with nothing to measure grades nothing, so the push is rejected; declare at least one counter or set pre_push.findings_ratchet = false',
-        '',
-        'fail',
-      )
-    } else if (config.prePush.findingsRatchet && Object.keys(config.findings.counters).length === 0) {
+    if (config.prePush.findingsRatchet && Object.keys(config.findings.counters).length === 0) {
       add(
         'findings-counters',
-        'pre_push.findings_ratchet is enabled but [controls.findings.counters] declares none — every push fails until a counter is declared',
+        'pre_push.findings_ratchet is enabled but [controls.findings.counters] declares none — a ratchet with nothing to measure grades nothing, so the push is rejected; declare at least one counter or set pre_push.findings_ratchet = false',
         'at least one findings counter is declared, or the ratchet is disabled',
         'fail',
       )

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

@@ -34,6 +34,18 @@
  * NO TOOL NAME APPEARS IN THIS FILE. The repository declares its counters and
  * what each one runs; the package knows a name and a command, the same division
  * `pre_push.static_checks` already draws.
+ *
+ * ABSENT FLOOR = ZERO GRANTS
+ *   The floor file is bookkeeping, not a switch. A missing floor file is
+ *   read as an empty `Floor` (the strictest possible state): every
+ *   finding-bearing file a counter emits is undeclared, the push is
+ *   refused, each file is named. The gate is armed iff the pre-push flag
+ *   says so, full stop. Tarun, 2026-10-13: "the gate should not be
+ *   dependent on a ratchet file. no ratchet file means zero grants."
+ *   The runtime hook (`runFindingsRatchet`) and the doctor are aligned
+ *   on this; the previous behaviour — failing loud on a missing floor —
+ *   conflated "no file" with "misconfiguration" and made the gate's
+ *   ON state require a positive declaration. It does not.
  */
 
 /** `counter -> section -> declared files`. */

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

@@ -621,6 +621,37 @@ export function integrityStep(
   return 1
 }
 
+/**
+ * Returns 1 and reports a recovery action when `currentBranch` is in
+ * `protectedBranches`; 0 otherwise. The recovery line is what an agent
+ * (and the e2e test) needs to know which ref to move to.
+ */
+export function protectedBranchStep(
+  protectedBranches: readonly string[],
+  currentBranch: string,
+  err: (line: string) => void,
+): number {
+  if (!protectedBranches.includes(currentBranch)) return 0
+  err(`refusing to commit on the protected branch '${currentBranch}'`)
+  err(`switch to a feature branch (for example: git switch -c feat/<short-summary>) and retry the commit there`)
+  return 1
+}
+
+/**
+ * Gate wrapper that resolves the current branch from the working tree, then
+ * calls {@link protectedBranchStep}. Reads the protected list from the same
+ * `loadConfig` the rest of the hook chain uses, so the validator and the gate
+ * never disagree on what's protected.
+ */
+function protectedBranchGate(repo: string, env: Env, err: (line: string) => void): number {
+  const head = capture(['git', 'rev-parse', '--abbrev-ref', 'HEAD'], repo, env)
+  // Detached HEAD or fresh repo: nothing to compare. `git rev-parse --abbrev-ref
+  // HEAD` returns "HEAD" itself when detached, which is never in
+  // `branches.protected` (validated as a branch name), so the step is a no-op.
+  if (head.code !== 0) return 0
+  return protectedBranchStep(loadConfig(repo).branches.protected, head.stdout.trim(), err)
+}
+
 /**
  * The final-index gate plus the dirty-but-excluded check. The index reader is
  * separate from status because `git diff --cached --no-renames -z` is the
@@ -703,10 +734,17 @@ function runFindingsRatchet(repo: string, context: RunContext): number {
   return findingsRatchetReport(
     config.findings,
     () => {
-      if (!existsSync(join(repo, config.findings.floor))) {
-        throw new Error(`${config.findings.floor} does not exist; commit a floor or set pre_push.findings_ratchet = false`)
-      }
-      return readFileSync(join(repo, config.findings.floor), 'utf8')
+      // A missing floor file is the strictest possible floor: zero grants.
+      // Returning an empty `parseFloor`-shaped document (just the schema
+      // line) means `findingsProblems` reports every emitted finding as a
+      // regression. The doctor and the runtime gate are aligned: a missing
+      // file is not a configuration error, it is a zero-grant declaration
+      // — the gate is armed and every finding-bearing file from a counter
+      // is undeclared. Tarun, 2026-10-13: "the gate should not be
+      // dependent on a ratchet file. no ratchet file means zero grants."
+      const floorPath = join(repo, config.findings.floor)
+      if (!existsSync(floorPath)) return 'schema: adl.findings-ratchet/v2\n'
+      return readFileSync(floorPath, 'utf8')
     },
     (command) => capture(['bash', '-c', command], repo, context.env),
     context.err,
@@ -785,6 +823,25 @@ export function runHook(name: HookName, args: string[], context: RunContext): nu
     )
     if (code !== 0) return code
   }
+  // Defense-in-depth branch gate (see tests/protected-branch-step.test.ts).
+  // The agent-hooks `git.commit-protected-branch` rule is the authoritative
+  // gate for host-routed `git commit` calls, but that hook only sees commits
+  // forwarded by the host's tool layer. A `git commit` invoked from a
+  // Bun.spawn, a post-checkout hook that lands a commit, or any other path
+  // that bypasses the host would never reach that rule. The repo-controls
+  // pre-commit chain refuses the commit itself by reading the same
+  // `[controls].branches.protected` declaration the rest of the package keys
+  // off, so a non-host-routed commit still hits the same wall.
+  //
+  // Opt-in via `[controls].pre_commit.branch_protection = true` (defaults OFF
+  // in the install seed): the agent-hooks layer already covers host-routed
+  // commits; this gate is for repositories that want the same protection on
+  // the host-bypass path. Runs LAST in the pre-commit chain so file-level
+  // gates deny a commit on content grounds first.
+  if (name === 'pre-commit' && loadConfig(repo).preCommit.branchProtection) {
+    const code = protectedBranchGate(repo, context.env, context.err)
+    if (code !== 0) return code
+  }
   // The Azure DevOps promotion-governance checks, moved here from pre-commit
   // (2026-09-28, Tarun): network access and a minted token are already
   // expected at push time, unlike at commit time. `azureDevOpsPromotionGovernanceChecks`