@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.9 → 0.1.12

package/packages/repo-controls/assets/version-bump.sh

@@ -1,13 +1,22 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# The integration build owns package version allocation, exactly as every
-# other repo on this standard does it (enact-extensions, enact-combined):
-# after a PR merges, bump the patch version on `integration`, commit it with
-# ***NO_CI*** and push it straight back to `integration`. The build service
-# has "bypass policies when pushing"; ***NO_CI*** stops the push from
-# triggering another pipeline run. No npm query, no second PR, no second
-# test run (Tarun, 2026-09-29).
+# STAGE 1 of the PR pipeline (PR -> integration): the PR build owns package
+# version allocation. Every PR into `integration` must carry exactly
+# `<integration version> + patch 1`; this script makes it so, on the PR's
+# SOURCE branch, before anything else validates it:
+#
+#   version-bump.sh --file package.json --pr-source <feature branch> \
+#     --base integration --push
+#
+# The Azure Pipelines PR build checks out the detached refs/pull/N/merge
+# commit with persisted credentials, so `git push` authenticates as the
+# project build service. The bump commit is created on the source branch's own
+# tip (never on the merge commit), carries no ***NO_CI*** (feature branches
+# have no CI trigger, so the push re-queues the PR build, which then
+# validates the bumped commit), and is pushed with a plain push — never
+# forced. When the source is already at the target version nothing is
+# committed and the run continues. No npm query, no second PR.
 
 # CI never carries an agent identity: the push below authenticates as the
 # project build service through the checkout's persisted System.AccessToken.
@@ -20,8 +29,8 @@ die() {
 }
 
 version_file=''
-integration_branch=''
-integration_mode=false
+pr_source=''
+base_branch=''
 push_bump=false
 
 while [[ $# -gt 0 ]]; do
@@ -31,14 +40,15 @@ while [[ $# -gt 0 ]]; do
       version_file="$2"
       shift 2
       ;;
-    --branch)
-      [[ $# -ge 2 ]] || die '--branch requires a name'
-      integration_branch="$2"
+    --pr-source)
+      [[ $# -ge 2 ]] || die '--pr-source requires a branch ref'
+      pr_source="$2"
       shift 2
       ;;
-    --integration)
-      integration_mode=true
-      shift
+    --base)
+      [[ $# -ge 2 ]] || die '--base requires a branch name'
+      base_branch="$2"
+      shift 2
       ;;
     --push)
       push_bump=true
@@ -51,46 +61,73 @@ while [[ $# -gt 0 ]]; do
 done
 
 [[ "$version_file" == 'package.json' ]] || die 'only --file package.json is supported'
-[[ -f "$version_file" ]] || die "manifest not found: $version_file"
-[[ -n "$integration_branch" ]] || die '--branch is required'
-[[ "$integration_mode" == true ]] || die '--integration is required'
+[[ -n "$pr_source" ]] || die '--pr-source is required'
+[[ -n "$base_branch" ]] || die '--base is required'
 [[ "$push_bump" == true ]] || die '--push is required'
 
-current_branch="$(git branch --show-current)"
-if [[ -z "$current_branch" ]]; then
-  # Azure Pipelines' `checkout: self` leaves the working tree on a detached
-  # HEAD (build 4822, integration, 2026-09-27: `git branch --show-current`
-  # came back empty even though the checkout was the right commit on
-  # `integration`). Fall back to Build.SourceBranch (env BUILD_SOURCEBRANCH,
-  # e.g. `refs/heads/integration`) rather than requiring the pipeline to
-  # `git checkout -B` a real branch first.
-  case "${BUILD_SOURCEBRANCH:-}" in
-    refs/heads/*)
-      current_branch="${BUILD_SOURCEBRANCH#refs/heads/}"
-      ;;
-    '')
-      die 'cannot determine the current branch: HEAD is detached (git branch --show-current is empty) and BUILD_SOURCEBRANCH is not set'
-      ;;
-    *)
-      die "BUILD_SOURCEBRANCH '$BUILD_SOURCEBRANCH' is not a branch ref (expected 'refs/heads/<name>')"
-      ;;
-  esac
+# Accept `refs/heads/x` (Build.SourceBranch / System.PullRequest.SourceBranch)
+# or a bare `x`; anything else under refs/ is not a branch.
+source_branch="${pr_source#refs/heads/}"
+case "$source_branch" in
+  '') die '--pr-source names an empty branch' ;;
+  refs/*) die "--pr-source '$pr_source' is not a branch ref (expected 'refs/heads/<name>' or '<name>')" ;;
+esac
+base_branch="${base_branch#refs/heads/}"
+if [[ "$source_branch" == "$base_branch" || "$source_branch" == 'main' || "$source_branch" == 'integration' ]]; then
+  die "refusing to bump '$source_branch': the PR source must be a feature branch, not the base ('$base_branch'), main or integration"
 fi
-[[ "$current_branch" == "$integration_branch" ]] || \
-  die "integration mode expects branch '$integration_branch', currently on '$current_branch'"
-
-current_version="$(node -e 'const version = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8")).version; if (typeof version !== "string") process.exit(1); process.stdout.write(version)' "$version_file")" || \
-  die "cannot read a string version from $version_file"
 
-if [[ ! "$current_version" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
-  die "cannot parse '$current_version' as a release version x.y.z"
+git diff --quiet || die 'working tree is not clean before version bump'
+git diff --cached --quiet || die 'index is not clean before version bump'
+repo_root="$(git rev-parse --show-toplevel)" || die 'cannot resolve the repository root'
+# The script runs from the package directory (e.g. apps/cli); the manifest's
+# repository-relative path is how it is read from the base branch.
+repo_prefix="$(git rev-parse --show-prefix)" || die 'cannot resolve the working directory inside the repository'
+repo_relative_file="${repo_prefix}${version_file}"
+
+# Read both tips fresh from origin. The PR build's checkout is the detached
+# merge commit; bumping that would push a commit that is not the branch's own
+# history, so the working tree is moved onto a REAL branch at the source tip.
+git fetch origin \
+  "refs/heads/$base_branch:refs/remotes/origin/$base_branch" \
+  "refs/heads/$source_branch:refs/remotes/origin/$source_branch" || \
+  die "cannot fetch '$base_branch' and '$source_branch' from origin"
+
+# The source must already contain the base's tip: the version it is bumped to
+# is derived from that tip, so a source behind it would be validated against a
+# merge the bump never saw.
+if ! git merge-base --is-ancestor "refs/remotes/origin/$base_branch" "refs/remotes/origin/$source_branch"; then
+  missing_count="$(git rev-list --count "refs/remotes/origin/$source_branch..refs/remotes/origin/$base_branch")"
+  base_short="$(git rev-parse --short "refs/remotes/origin/$base_branch")"
+  echo "version-bump: FAIL — $source_branch does not contain $base_branch's tip ($base_short); reconcile first: git pull origin $base_branch && git push" >&2
+  echo "version-bump: $missing_count commit(s) on $base_branch are missing from $source_branch" >&2
+  exit 1
 fi
 
+git checkout -q -B "$source_branch" "refs/remotes/origin/$source_branch" || \
+  die "cannot check out '$source_branch' at its origin tip"
+
+[[ -f "$version_file" ]] || die "manifest not found: $version_file"
+
+read_version() {
+  node -e 'const version = JSON.parse(require("node:fs").readFileSync(0, "utf8")).version; if (typeof version !== "string") process.exit(1); process.stdout.write(version)'
+}
+
+base_version="$(git show "refs/remotes/origin/$base_branch:$repo_relative_file" | read_version)" || \
+  die "cannot read a string version from $repo_relative_file on origin/$base_branch"
+if [[ ! "$base_version" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
+  die "cannot parse '$base_version' (origin/$base_branch) as a release version x.y.z"
+fi
 next_version="${BASH_REMATCH[1]}.${BASH_REMATCH[2]}.$((BASH_REMATCH[3] + 1))"
 
-git diff --quiet || die 'working tree is not clean before version bump'
-git diff --cached --quiet || die 'index is not clean before version bump'
-repo_root="$(git rev-parse --show-toplevel)" || die 'cannot resolve the repository root'
+current_version="$(read_version < "$version_file")" || die "cannot read a string version from $version_file"
+
+if [[ "$current_version" == "$next_version" ]]; then
+  echo "version-bump: $source_branch already at $next_version (integration $base_version); nothing to bump"
+  echo '##vso[task.setvariable variable=bumped;isOutput=true]false'
+  exit 0
+fi
+
 node -e '
   const fs = require("node:fs")
   const [file, version] = process.argv.slice(1)
@@ -105,7 +142,7 @@ node -e '
 # package.json can reach. No file, or no `pre_bump` key: no scripts, and
 # everything below this comment is a no-op, so the resulting commit is
 # byte-identical to the behaviour before this feature existed (see
-# packages/repo-controls/tests/version-bump-pre-bump.test.ts).
+# packages/repo-controls/tests/version-bump-pr-source-pre-bump.test.ts).
 config_path="$repo_root/adl-config.toml"
 pre_bump_list=''
 if [[ -f "$config_path" ]]; then
@@ -189,6 +226,9 @@ fi
 
 git -C "$repo_root" add -A
 git diff --cached --quiet && die "version bump produced no staged change (expected at least $version_file)"
-git commit -m "chore: bump version $current_version to $next_version ***NO_CI***"
-git push origin "HEAD:$integration_branch"
-echo "Bumped $version_file from $current_version to $next_version on $integration_branch."
+# No ***NO_CI***: a feature branch has no CI trigger, so this push is what
+# re-queues the PR build against the bumped commit.
+git commit -m "chore: bump version $current_version to $next_version"
+git push origin "HEAD:refs/heads/$source_branch"
+echo "version-bump: bumped $source_branch from $current_version to $next_version (integration $base_version); pushed — this run ends, the re-queued PR build validates the bumped commit"
+echo '##vso[task.setvariable variable=bumped;isOutput=true]true'

package/packages/repo-controls/package.json

@@ -14,7 +14,6 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "bun test tests --coverage --timeout 30000",
-    "test:coverage": "bun test tests --coverage --timeout 30000",
     "check": "tsc --noEmit && bun test tests --coverage --timeout 30000",
     "coverage:ratchet": "bun workflows/scripts/coverage/ci-ratchet.ts",
     "coverage:produce": "bun test tests --coverage --timeout 30000 && bun workflows/scripts/coverage/command.ts"

package/packages/repo-controls/src/azure-devops-governance.ts

@@ -168,9 +168,12 @@ export interface AzureDevOpsGovernanceOptions {
 }
 
 /**
- * One read-only receipt per promotion guard. Unreadable evidence is a failure,
- * never a warning: a commit cannot claim the remote guard is armed when that
- * fact could not be established.
+ * One read-only receipt per promotion guard. The only required guard on the
+ * target branch is the minimum-reviewer policy (Tarun, 2026-09-30): a build
+ * policy is NOT required, because the integration -> main promotion PR gets no
+ * build validation and CD runs after the merge. Unreadable evidence is a
+ * failure, never a warning: a commit cannot claim the remote guard is armed
+ * when that fact could not be established.
  */
 export function azureDevOpsGovernanceChecks(options: AzureDevOpsGovernanceOptions): AzureDevOpsGovernanceCheck[] {
   const checks: AzureDevOpsGovernanceCheck[] = []
@@ -231,18 +234,16 @@ export function azureDevOpsGovernanceChecks(options: AzureDevOpsGovernanceOption
           message: `missing blocking minimum-reviewer policy requiring one approval and resetOnSourcePush=true for ${prefix}`,
         },
   )
-  checks.push(
-    receipts.build
-      ? {
-          id: 'azure-devops.build-policy',
-          status: 'ok',
-          message: `blocking build policy #${id(receipts.build)} uses definition ${receipts.build.settings?.buildDefinitionId} for ${prefix}`,
-        }
-      : {
-          id: 'azure-devops.build-policy',
-          status: 'fail',
-          message: `missing blocking build policy with a build definition for ${prefix}`,
-        },
-  )
+  // No build-policy requirement on `main` (Tarun, 2026-09-30): the promotion PR
+  // gets no build validation, so an absent build policy is not a failure. A
+  // present one is only recorded, never flagged here (the azdo repo doctor
+  // owns that).
+  if (receipts.build) {
+    checks.push({
+      id: 'azure-devops.build-policy',
+      status: 'ok',
+      message: `blocking build policy #${id(receipts.build)} uses definition ${receipts.build.settings?.buildDefinitionId} for ${prefix}`,
+    })
+  }
   return checks
 }

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

@@ -63,6 +63,8 @@ export const PROMOTE_REL = '.workflows/promote.ts'
 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'
+/** 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'
 
 export const MANAGED_ASSETS = [
   { rel: PROMOTE_REL, source: join(PACKAGE_ROOT, 'assets', 'promote.ts'), mode: 0o755, doctorId: 'promote' },
@@ -78,6 +80,12 @@ export const MANAGED_ASSETS = [
     mode: 0o755,
     doctorId: 'version-bump',
   },
+  {
+    rel: RECONCILE_GUARD_REL,
+    source: join(PACKAGE_ROOT, 'assets', 'reconcile-guard.sh'),
+    mode: 0o755,
+    doctorId: 'reconcile-guard',
+  },
 ] 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'

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

@@ -430,8 +430,9 @@ function dirtyPaths(porcelain: string): string[] {
     const hasOrigin = staged === 'R' || staged === 'C' || worktree === 'R' || worktree === 'C'
     const origin = hasOrigin ? records[++index] : undefined
     // An untracked path has no index entry, so it is necessarily omitted from
-    // this commit. Keep it: centrally managed dot paths must be staged rather
-    // than silently left behind.
+    // this commit. Keep it: other top-level dot paths must be staged rather than
+    // silently left behind, and a protected root (.workflows, .agents, .claude,
+    // .codex, .cursor, .kimi-code, .opencode) is refused outright (integrity.ts).
     if (staged === '?' && worktree === '?') {
       paths.push(record.slice(3))
       continue

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

@@ -9,7 +9,21 @@
 
 export const WIRING: readonly string[] = ['adl-config.toml']
 
-const FIXED_ROOTS: readonly string[] = ['compliance', 'workflows']
+// Tarun, 2026-09-30: `.workflows/` and every agent surface root are protected
+// like `workflows/` — a dirty path under any of them blocks a normal commit and
+// only Tarun lands it. They were "centrally managed dotfiles" an agent could
+// commit alongside a related change; that let an agent land gate-defining files.
+const FIXED_ROOTS: readonly string[] = [
+  'compliance',
+  'workflows',
+  '.workflows',
+  '.agents',
+  '.claude',
+  '.codex',
+  '.cursor',
+  '.kimi-code',
+  '.opencode',
+]
 
 /** A declared pattern, as a regex. `*` stays in one directory; `**` crosses them. */
 function patternToRegExp(pattern: string): RegExp {