@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.37 → 0.1.47

package/packages/fleet/src/install-adl-package.ts

@@ -19,15 +19,16 @@ import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
 // import cross-package by relative path — a package added to those imports
 // but not here breaks every managed repo's git hooks with "Cannot find module"
 // the next time reconcile projects this payload.
-// Every package apps/cli reads from /usr/local/libexec/adl (hooks.ts, skills.ts, settings.ts,
+// Every package apps/cli reads from /usr/local/libexec/adl (hooks.ts, settings.ts,
 // repo-controls.ts: DEFAULT_LIBEXEC_DIR) plus azdo, which they import by relative path.
+// skills.ts dropped its libexec fallback for agent-skills as part of az697
+// (fleet does not install skills; every skill comes from `adl skills deploy`).
 // install-adl-package.test.ts pins both against the real sources.
-export const payloadDirectories = ['packages/agent-skills', 'packages/repo-controls', 'packages/agent-hooks', 'packages/agent-settings', 'packages/azdo']
+export const payloadDirectories = ['packages/repo-controls', 'packages/agent-hooks', 'packages/agent-settings', 'packages/azdo']
 const payloadScripts = ['bin/git', 'bin/git-ado']
 const requiredFiles = [
   'bin/reconcile',
   'packages/fleet/manifest.json',
-  'packages/agent-skills/dist/index.js',
   'packages/repo-controls/bin/adl-repo-controls.ts',
   'packages/agent-hooks/src/log/writer.ts',
   'packages/agent-settings/deploy-profile.json',

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

@@ -1,5 +1,6 @@
 // Managed by adl-repo-controls, do not edit; regenerate with: adl-repo-controls install --repo . (README "Managed workflow scripts").
 
+
 /** Promote one branch to another through an Azure DevOps pull request; see README "Managed workflow scripts". */
 
 /** Azure DevOps' `mergeStrategy` by name; see README "Managed workflow scripts". */

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/okf_profile/fixtures/okf-profile-untyped/docs/research/no-type.md

@@ -3,7 +3,7 @@ title: "No type at all"
 description: "Declares no type: unconstrained does not mean optional."
 status: draft
 last_update: '2026-10-01T06:13:54Z'
-sources: plans/features/example/spec.md
+sources: plans/features/example/requirements.md
 ---
 
 # No type at all

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/okf_profile/fixtures/okf-profile-untyped/docs/research/typed-experiment.md

@@ -4,7 +4,7 @@ title: "Typed experiment"
 description: "Declares type Experiment."
 status: draft
 last_update: '2026-10-01T06:13:54Z'
-sources: plans/features/example/spec.md
+sources: plans/features/example/requirements.md
 ---
 
 # Typed experiment

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/okf_profile/fixtures/okf-profile-untyped/docs/research/typed-research.md

@@ -4,7 +4,7 @@ title: "Typed research"
 description: "Declares type Research."
 status: draft
 last_update: '2026-10-01T06:13:54Z'
-sources: plans/features/example/spec.md
+sources: plans/features/example/requirements.md
 ---
 
 # Typed research

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/okf_profile/fixtures/okf-research/docs/research/extra-key.md

@@ -6,7 +6,7 @@ status: draft
 created: 2026-10-01
 last_update: '2026-10-01T06:13:54Z'
 sources:
-  - plans/features/example/spec.md
+  - plans/features/example/requirements.md
 review_frequency: weekly
 ---
 

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/okf_profile/fixtures/okf-research/docs/research/extra-keys.md

@@ -6,7 +6,7 @@ status: draft
 created: 2026-10-01
 last_update: '2026-10-01T06:13:54Z'
 sources:
-  - plans/features/example/spec.md
+  - plans/features/example/requirements.md
 owner: someone
 review_frequency: weekly
 ---

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/okf_profile/fixtures/okf-research/docs/research/missing-created.md

@@ -5,7 +5,7 @@ description: "Research page with no created date."
 status: draft
 last_update: '2026-10-01T06:13:54Z'
 sources:
-  - plans/features/example/spec.md
+  - plans/features/example/requirements.md
 ---
 
 # Missing created

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/okf_profile/fixtures/okf-research/docs/research/missing-description.md

@@ -5,7 +5,7 @@ status: draft
 created: 2026-10-01
 last_update: '2026-10-01T06:13:54Z'
 sources:
-  - plans/features/example/spec.md
+  - plans/features/example/requirements.md
 ---
 
 # Missing description

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/okf_profile/fixtures/okf-research/docs/research/missing-last-update.md

@@ -5,7 +5,7 @@ description: "Research page with no last_update."
 status: draft
 created: 2026-10-01
 sources:
-  - plans/features/example/spec.md
+  - plans/features/example/requirements.md
 ---
 
 # Missing last_update

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/okf_profile/fixtures/okf-research/docs/research/missing-status.md

@@ -5,7 +5,7 @@ description: "Research page with no status."
 created: 2026-10-01
 last_update: '2026-10-01T06:13:54Z'
 sources:
-  - plans/features/example/spec.md
+  - plans/features/example/requirements.md
 ---
 
 # Missing status

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/okf_profile/fixtures/okf-research/docs/research/missing-title.md

@@ -5,7 +5,7 @@ status: draft
 created: 2026-10-01
 last_update: '2026-10-01T06:13:54Z'
 sources:
-  - plans/features/example/spec.md
+  - plans/features/example/requirements.md
 ---
 
 # Missing title

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/okf_profile/fixtures/okf-research/docs/research/optional-keys.md

@@ -6,7 +6,7 @@ status: draft
 created: 2026-10-01
 last_update: '2026-10-01T06:13:54Z'
 sources:
-  - plans/features/example/spec.md
+  - plans/features/example/requirements.md
 stale_after: '2027-01-01'
 verified: true
 ---

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/okf_profile/fixtures/okf-research/docs/research/research-ok.md

@@ -6,7 +6,7 @@ status: draft
 created: 2026-10-01
 last_update: '2026-10-01T06:13:54Z'
 sources:
-  - plans/features/example/spec.md
+  - plans/features/example/requirements.md
 ---
 
 # Fixture research input

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`