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

package/packages/repo-controls/README.md

@@ -16,7 +16,8 @@ target repo (committed)                      adl (fleet-installed; see below)
 .workflows/hooks/commit-msg     ├─ sh stub ──▶    ├─ validates adl-config.toml [controls]
 .workflows/hooks/pre-push       │  exec           ├─ checks bash >= 4
 .workflows/hooks/post-commit    │                 └─ runs scripts/hooks/<name>
-.workflows/hooks/post-checkout ─┘
+.workflows/hooks/post-checkout  │
+.workflows/hooks/post-merge    ─┘
 adl-config.toml [controls]   (config, shared file — see below)   (package-owned script, config via env)
 .workflows/repo-controls.lock.json (hashes)
 local .git/config: core.hooksPath = .workflows/hooks
@@ -25,9 +26,9 @@ local .git/config: core.hooksPath = .workflows/hooks
 - **Stubs** are POSIX `sh`, contain no paths, and fail loudly (with the install
   command) when `adl` is not on `PATH` — never a silent skip. This package is
   folded into the `adl` binary's `repo controls` namespace
-  (docs/architecture/cli-design.md §6, STATUS.md item 10); it is never itself a
+  (docs/architecture/cli-design.md §6); it is never itself a
   standalone global command — hard cut, no `adl-repo-controls` compat shim
-  (adl-m3-finish item 1, 2026-09-27).
+  (2026-09-27).
 - **Bundled scripts** in `scripts/hooks/` are package-owned implementations.
   They originated in enact-m5; commit `20ec790` removed the former byte-copy
   tree and manifest when mechanism moved into this package. Their current
@@ -77,6 +78,53 @@ a release-configured pre-commit commits successfully with no network-capable
 binary on `PATH` at all, and pre-push blocks by name when the token mint
 fails and permits the push once it succeeds.
 
+## Git LFS chaining (`pre-push`, `post-checkout`, `post-commit`, `post-merge`)
+
+Installed repositories set `core.hooksPath=.workflows/hooks`, so git never runs
+the `.git/hooks/{pre-push,post-checkout,post-commit,post-merge}` that
+`git lfs install` writes. Before 2026-10-01 nothing in adl called git-lfs, so a
+push of a commit carrying an LFS pointer succeeded **without uploading the
+object** and left a broken pointer on the remote (live, enact-combined: a
+broken WebM pointer had to be deleted by hand). `runHook` (`src/hook.ts`) now
+chains each of those four hooks to `git lfs <hook> "$@"` (`src/lfs.ts`):
+
+- **Only when the repository uses LFS:** a `filter=lfs` attribute in any
+  `.gitattributes` (tracked or untracked, nested included) or in
+  `.git/info/attributes`, a `.lfsconfig`, or `lfs.*` in the repository's own git
+  config. A repository without LFS never calls `git lfs`.
+- **Fail loud, never skip:** LFS in use and no `git-lfs` on `PATH` is a hard
+  failure with the install command in the message; a failing `git lfs <hook>`
+  fails the hook (for `pre-push`, the push). A FAIL row is also written to the
+  hook log, because the bundled script has already logged its PASS by then.
+- **`pre-push` order and stdin:** git writes the pushed ref lines once. `runHook`
+  reads them once and feeds the same bytes to the bundled script (branch rules)
+  and to `git lfs pre-push`. The LFS upload is the LAST step, after every adl
+  check passed, so a refused push uploads nothing. `post-merge` is a new hook
+  (`HOOK_NAMES`) whose only job is this chain; `doctor` therefore reports
+  `hook:post-merge`, and an already-installed repository needs `adl repo
+  controls install --repo .` once to project the stub.
+- **Credentials — one boundary, no second path.** `bin/git-ado` authenticates an
+  agent's `git push` by exporting `GIT_CONFIG_COUNT` and a
+  `GIT_CONFIG_KEY_n=http.https://<host>/.extraHeader` /
+  `GIT_CONFIG_VALUE_n=Authorization: Bearer <token>` pair (`bin/git-ado`, the
+  two `exec env ... GIT_CONFIG_COUNT=` blocks); git passes its environment to
+  the hook. `runBundled` strips every `GIT_CONFIG_*` (`childEnv`) so adl's own
+  checks never hold the token, which is why the chain is TypeScript and not
+  bash: `runHook` still has the unstripped environment, and the one
+  `git lfs` spawn (`spawnGitLfs`) is the only child given it. git-lfs therefore
+  authenticates with exactly the pairs the parent `git push` had: same
+  mechanism, no second token mint, never the human's credential helper.
+  `tests/lfs-credential-boundary.test.ts` is the proof (real git-lfs, a local
+  LFS endpoint that requires the Bearer token and answers 401 otherwise, a
+  credential helper that records every call): every request carried the header,
+  the helper was never called, and with the header absent the helper IS called
+  (the control that makes the first claim falsifiable).
+- **Explicit `git lfs push|pull|fetch` for agents** was refused in `bin/git-ado`
+  until that proof existed; it now takes the ordinary agent path. The refusal
+  must come back if `lfs-credential-boundary.test.ts` ever goes red. No agent-hooks
+  rule mentions LFS, so `git push` -> hook -> `git lfs pre-push` is not a
+  command an agent types and is not intercepted by any rule.
+
 ## Worktree-count backstop (`post-checkout`)
 
 `MAX_WORKTREES` (`src/constants.ts`) is `3` — a repository may have at most 3
@@ -144,7 +192,7 @@ or a `Task`/`Agent` launch with `isolation: "worktree"`) — see
 
 ### Why bun (and not node)
 
-This package is never distributed standalone (adl-m3-finish item 1/2, 2026-09-27):
+This package is never distributed standalone (since 2026-09-27):
 `adl repo controls <command>` folds it into the one `adl` binary
 (docs/architecture/cli-design.md §6), which the fleet installs via `bin/reconcile`'s
 `bun-compile` manager; `apps/cli/src/commands/repo-controls.ts` resolves this
@@ -186,7 +234,7 @@ centralization are documented in
 adl-repo-controls install   --repo <path> [--dry-run]
 adl-repo-controls uninstall --repo <path> [--dry-run]
 adl-repo-controls doctor    --repo <path> [--json]
-adl-repo-controls hook <pre-commit|commit-msg|pre-push|post-commit> [git hook args]
+adl-repo-controls hook <pre-commit|commit-msg|pre-push|post-commit|post-checkout|post-merge> [git hook args]
 adl-repo-controls log <hook-name> <reason> [context] [message]   (internal — called by the bundled hooks)
 adl-repo-controls promote --repo <path>
 adl-repo-controls run <azdo-push|coverage|repo-hygiene|validate-pr-metadata> --repo <path> [-- args]
@@ -229,21 +277,56 @@ merge into `integration`) runs.
 **doctor** is read-only and exits 1 on any failure: bash >= 4, bun, binary on
 PATH, the bundled compliance package present at its packaged path, repository
 root, `[controls]` config validity, (warning) `coverage/coverage-summary.json`
-exists whenever `pre_push.coverage_ratchet` is enabled, `[controls.compliance]` config
-validity, `uv` on PATH (only checked once `[controls.compliance].enabled` is non-empty;
-otherwise reported ok unconditionally, same off-by-default posture as the
-coverage-summary check), (warning only, same conditioning) `ast-grep` on PATH,
-lock, each stub (present, unedited, executable), `core.hooksPath`, `.gitignore`
-lines, and (warning) lock version skew. When `[controls.release]` is declared,
-it also derives the configured `origin` remote, loads the validated canonical
-Agent Vault file before reading Azure DevOps, and records separate fail-closed receipts for the HTTPS handle,
-required owner reviewer, minimum-review reset, and (only when one is present) build policy.
+exists whenever `pre_push.coverage_ratchet` is enabled (`coverage_ratchet`
+defaults ON; the gate is a no-op until the file lands, so this is informational
+rather than blocking), (warning) `pre_push.coverage_produce` enabled with no
+`[controls.coverage].produce_push` declared (the push gate fails loud there, so
+doctor names it first), `[controls.compliance]` config validity, `uv` on PATH
+(only checked once `[controls.compliance].enabled` is non-empty; otherwise
+reported ok unconditionally, same on-by-default posture as the coverage-summary
+check), (warning only, same conditioning) `ast-grep` on PATH, lock, each stub
+(present, unedited, executable), `core.hooksPath`, `.gitignore` lines, and
+(warning) lock version skew. When `[controls.release]` is declared, it also
+derives the configured `origin` remote, loads the validated canonical Agent
+Vault file before reading Azure DevOps, and records separate fail-closed
+receipts for the HTTPS handle, required owner reviewer, minimum-review reset,
+and (only when one is present) build policy.
 
 **run** executes a bundled enact-m5 tool against the repository with the config
 exported: `azdo-push` (Azure DevOps push with push lock + behind-origin refusal),
 `coverage <check-push|prewarm-push|status|unlock|...>`, `repo-hygiene` (CI
 entrypoint), `validate-pr-metadata` (Azure PR title/description policy).
 
+#### azdo-push: one credential boundary
+
+`azdo-push` mints and injects **no credential** (Tarun, 2026-10-01). Its git
+children run through the managed front controller (`/usr/local/bin/git` ->
+`bin/git-ado`), the only place a token is minted and a header added. What
+`azdo-push` does contribute is `ADL_AGENT_ID_AGENT=<resolved agent>` on every
+git spawn (so the controller mints for the right agent) and the removal of any
+inherited `ADL_HUMAN_AZDO`. It refuses, before any network call, when no agent
+identity resolves, and when the `git` on `PATH` does not carry the
+`# Managed by adl global-tools.` marker (a plain git would fall to the human
+credential helper).
+
+**Verify on the wire** that a request carries exactly one `Authorization`
+header. Git redacts the value by default (`GIT_TRACE_REDACT`, on unless set to
+`0` -- never set it), so the trace is safe to read and to paste:
+
+```
+GIT_TRACE_CURL=1 GIT_TRACE_CURL_NO_DATA=1 git ls-remote origin HEAD 2>&1 \
+  | rg '=> Send header: (GET|POST|Authorization)'
+```
+
+Expect each `GET`/`POST` line to be followed by exactly one
+`=> Send header: Authorization: Bearer <redacted>` line. Count them with
+`... | rg -c '=> Send header: Authorization'` -- 1 for the single request of
+`ls-remote`. Two per request means a second credential path is back (the old
+behaviour was a global `http.extraheader` from `azdo-push` plus git-ado's own
+URL-scoped header). `ls-remote` is read-only; to trace the push path itself, run
+`GIT_TRACE_CURL=1 GIT_TRACE_CURL_NO_DATA=1 adl repo controls azdo-push` on a
+branch you mean to push.
+
 **run compliance** runs the bundled `adl-compliance` Python engine (via `uv`)
 against the repository. `--root <repo>` is always injected first from `--repo`;
 once `[controls.compliance].enabled` is non-empty, `--only <the enabled list, comma-joined>`
@@ -285,41 +368,47 @@ an inline table is one attribute, because editing inside one means rewriting byt
 you own. Nothing is parsed and re-serialized; text is spliced into the table's span.
 
 `[controls]` is strictly validated: unknown keys and wrong types are errors. An
-**absent** optional key is its documented default, never an error.
+**absent** key takes its documented default, never an error. Most gates default
+ON; the matching `[controls.<gate>]` keys are what configure them. A gate whose
+wrapper is ON but whose configuration is missing is a no-op at hook time and a
+*warning* at `doctor` time — informational, never blocking.
 
 | Key | Seeded by install | Default when absent | enact-m5 | Effect |
 |---|---|---|---|---|
 | `branches.protected` | yes | *required* | `["main", "integration"]` | pre-push refuses while on these branches |
 | `branches.prefixes` | yes | *required* | `["feat", "fix", "docs", "chore"]` | pre-push / azdo-push branch pattern `<prefix>/<kebab>` |
 | `pre_push.remote` | yes | *required* | `"origin"` | remote azdo-push pushes to and reads status from |
-| `pre_commit.biome` | no | `false` | `true` | Biome format+lint on the staged index snapshot |
-| `pre_commit.staged_coverage` | no | `false` | `true` | enact-m5-only staged coverage measurement |
-| `pre_commit.doc_freshness` | no | `false` | opt in | a staged `docs/` or `plans/` `.md` carries a `last_update` stamped within 5h |
-| `pre_push.coverage_ratchet` | no | `false` | `true` | per outgoing commit, `coverage/coverage-summary.json` must exist and not regress |
-| `pre_push.findings_ratchet` | no | `false` | opt in | per outgoing commit, every declared static-analysis counter's findings must not exceed the committed floor |
+| `pre_commit.staged_coverage` | no | `true` | `true` | enact-m5-only staged coverage measurement (no-op until `[controls.coverage].produce` is declared) |
+| `pre_commit.doc_freshness` | no | `true` | opt in | a staged `docs/` or `plans/` `.md` carries a `last_update` stamped within 5h (no-op when no docs are staged) |
+| `pre_commit.compliance` | no | `true` | `true` | staged adl-compliance gates (no-op until `[controls.compliance].enabled` is non-empty) |
+| `pre_push.coverage_ratchet` | no | `true` | `true` | per outgoing commit, `coverage/coverage-summary.json` must exist and not regress (no-op until the file lands) |
+| `pre_push.coverage_produce` | no | `false` | opt in | run the coverage MEASUREMENT at push via `[controls.coverage].produce_push` (fails the push when armed with no command declared) |
+| `pre_push.findings_ratchet` | no | `true` | opt in | per outgoing commit, every declared static-analysis counter's findings must not exceed the committed floor (no-op until `[controls.findings].counters` is declared and the floor file lands) |
 | `pre_push.static_checks` | no | `[]` | tsc, knip, svelte-check | `{ label, run }` commands run on an export of HEAD, pass cached per tree OID |
 | `release.source` | no | `""` | `"integration"` | source branch for the managed promotion PR; no branch pair is guessed |
 | `release.target` | no | `""` | `"main"` | target branch for the managed promotion PR |
 | `release.merge_strategy` | no | `"squash"` | `"no-fast-forward"` | one of `squash`, `rebase`, `rebase-merge`, or `no-fast-forward` — sent to Azure DevOps as the matching wire value (`squash`, `rebase`, `rebaseMerge`, `noFastForward`) |
-| `release.pre_bump` | no | `[]` | — | ordered, repository-relative script paths `version-bump.sh` runs from the repo root before the bump commit (the CI pipeline's Bump stage, on the PR's source branch) |
-
-### Release scripts — Bump and Guard (Tarun, 2026-09-30)
-
-One clean hard cutover to three pipelines (CI on PRs into `integration`,
-Promote on `integration`, CD on `main`; `docs/architecture/cli-design.md` §6a).
-Two managed scripts run in the CI pipeline, and neither ever pushes to
-`integration`:
-
-- **`.workflows/version-bump.sh --file package.json --pr-source <source> --base
-  integration --push`** (Bump stage) sets the PR's SOURCE branch to
-  `integration`'s version + 1 patch, running `release.pre_bump` scripts in the
-  same commit, and pushes it (a plain push as the build service, never an
-  agent identity, never force). It refuses a source that does not contain
-  `integration`'s tip. The old `--integration` mode is gone: it is an unknown
-  argument.
-- **`.workflows/reconcile-guard.sh`** (Guard stage) fails, printing the
-  reconcile command (`git pull origin integration && git push`), unless the
-  source contains `integration`'s tip and is at `integration` + 1.
+| `release.pre_bump` | no | `[]` | — | ordered, repository-relative script paths `version-bump.sh` runs from the repo root before the bump commit (the Promote pipeline's Bump stage, on the checkout of the `integration` commit that triggered it) |
+
+### Release scripts — Guard and Bump (Tarun, 2026-09-30; bump moved 2026-10-01)
+
+Three pipelines (CI on PRs into `integration`, Promote on `integration`, CD on
+`main`; `docs/architecture/cli-design.md` §6a). Two managed scripts:
+
+- **`.workflows/reconcile-guard.sh --pr-source <source> --base integration`**
+  (CI pipeline, Guard stage) is read-only and fails, printing the reconcile
+  command (`git pull origin integration, then push`), unless the source
+  contains `integration`'s tip. It checks no version: PR CI bumps nothing,
+  because a PR's build-validation policy ignores `[skip ci]`.
+- **`.workflows/version-bump.sh --file package.json --integration --push`**
+  (Promote pipeline, Bump stage) sets the manifest to the checked-out
+  `integration` commit's version + 1 patch, runs `release.pre_bump` scripts in
+  the same commit, commits `chore: bump version A to B [skip ci]` and pushes
+  `HEAD:refs/heads/integration` (a plain fast-forward as the build service,
+  which needs Contribute and "Bypass policies when pushing" there; never an
+  agent identity, never force). If `integration` moved since the checkout the
+  push is rejected and the script fails loud; the next merge's run bumps. The
+  old `--pr-source` mode is gone: it is an unknown argument.
 
 ### `release.pre_bump` — multi-language version bumps
 
@@ -395,10 +484,9 @@ sed -i.bak -E "s/^const Version = \".*\"/const Version = \"${ADL_NEXT_VERSION}\"
 rm -f "${file}.bak"
 ```
 
-`install` copies four package-owned standalone CI assets byte-for-byte:
+`install` copies three package-owned standalone CI assets byte-for-byte:
 
 - `.workflows/promote.ts`
-- `.workflows/scripts/enable-integration-auto-complete.mjs`
 - `.workflows/version-bump.sh`
 - `.workflows/reconcile-guard.sh`
 
@@ -469,6 +557,13 @@ Note: with `coverage_ratchet = true` every pushed commit and its parent must
 contain `coverage/coverage-summary.json` (Istanbul json-summary); commit a
 baseline first or set it to `false`.
 
+Note: with `coverage_produce = true` the coverage MEASUREMENT runs at push too,
+through `[controls.coverage].produce_push` — measurement at push, grading at
+push, so commits stay fast. `produce_push` is the push-appropriate command: it
+runs against immutable HEAD before the push, so a check-mode run that never
+mutates the index is the shape. Armed with no command declared, the gate fails
+the push by name — a step that measures nothing is not a pass.
+
 Note: with `findings_ratchet = true`, `[controls.findings]` says where the
 floor lives (`floor`, default `compliance/ratchets/static-analysis-findings.yaml`)
 and `[controls.findings.counters]` names the repository's own static-analysis
@@ -512,6 +607,9 @@ non-empty string.
 | `enabled` | `[]` | gate ids (`RST-001`) or `domain.name` addresses (`rust.acp-boundary`) to grade; empty = installed, nothing runs |
 | `registry` | `"default"` | forward-compatible; today both values point at the same packaged registry YAML |
 | `[controls.compliance.trees]` | `{}` (no entries) | per-key path overrides; a key absent here keeps the packaged (source-shaped) default for that key |
+| `[controls.compliance.limits]` | absent (engine defaults) | per-repository engine limits, strictly validated. `scripts_direct_files` (positive integer) replaces LAY-014's default of 15 direct files per scripts directory and reaches the engine as `--declare scripts-direct-files=N`; a value the engine cannot read as a positive integer is could-not-run, never a fall back to 15. The depth limit is not configurable. `open_gaps` and `open_plans` (each a positive integer) replace LAY-016's default cap of 10 open gaps and 10 open plans, independently, and reach the engine as `--declare open-gaps=N` / `--declare open-plans=N`; the same could-not-run rule applies to each, and a finding names the effective cap as `N open gaps, cap is M`. The engine default stays 10: a repository declares today's measured count and ratchets it down |
+| `[controls.compliance.markdown]` | absent (no extra Markdown roots) | extra Markdown roots for LAY-006 (`layout.markdown-trees`), strictly validated. `roots` is an array of repository-relative directories whose Markdown is site or application content rather than documentation (an Astro site's `src/content/**/*.md`); LAY-006 admits `.md` and `.mdx` beneath each, in addition to the docs trees, so a declared root only ever widens the allowlist and absent is the stricter grade. Reaches the engine as one `--declare markdown-roots=a,b`. An entry that is empty, absolute, contains `,` or `=`, or has a `.`, `..` or empty path segment is rejected when the config loads (a trailing `/` is dropped); the engine refuses the same values as could-not-run (exit 2) |
+| `[controls.compliance.lockfiles]` | absent (REP-002 keeps its tree-derived scope) | exactly which manifest and lockfile paths REP-002 (`repository.lockfile-integrity`) scans and grades, strictly validated. Four arrays: `bun_manifests` / `bun_lockfiles` and `cargo_manifests` / `cargo_lockfiles`. A manifest entry is a repository-relative path or glob ending in `package.json` (`Cargo.toml`), such as `package.json` or `apps/*/package.json`; a lockfile entry is a literal path (a missing one is reported by name). An ecosystem is declared as a pair, and a declared pair replaces that ecosystem's default (`<typescript>/package.json` + `<typescript>/bun.lock`, the `<rust>` pair) in both what selects the gate and what it grades; an undeclared ecosystem is unchanged. Reaches the engine as `--declare bun-manifests=a,b`, `bun-lockfiles=`, `cargo-manifests=`, `cargo-lockfiles=` (a list is omitted when empty); a declared manifest that matches no file is could-not-run naming it. An entry that is empty, absolute, duplicated, contains `,` `=` `\` `<` `>` `{` `}`, starts with `!`, has a `.`, `..` or empty path segment, ends in the wrong file name, or (for a lockfile) is a glob, an ecosystem with only one of its two lists, and a `REP-002:bun_lock` / `cargo_lock` / `cargo_manifest` / `workspace` input beside the pair it supersedes are all rejected when the config loads; the engine refuses the same values as could-not-run (exit 2) |
 
 ### Registry curation
 
@@ -534,5 +632,5 @@ bun test --coverage     # 100% lines + functions gate (bunfig.toml)
 ```
 
 Tests run real git in temporary repositories under `.scratchpad/test-tmp/`
-(gitignored), exercising the installed stubs end to end. CI:
-`azure-pipelines.yml` (publishing present but disabled).
+(gitignored), exercising the installed stubs end to end. CI runs them through
+the repository's root pipelines under `workflows/pipelines/`.

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

@@ -90,7 +90,7 @@ interface PullRequestList {
   value?: PullRequest[]
 }
 
-export interface PolicyScope {
+interface PolicyScope {
   repositoryId?: string
   refName?: string
   matchKind?: string
@@ -111,12 +111,12 @@ export interface PolicyConfiguration {
   }
 }
 
-export interface PolicyConfigurationList {
+interface PolicyConfigurationList {
   value?: PolicyConfiguration[]
 }
 
-export const MINIMUM_REVIEWER_POLICY_TYPE = 'fa4e907d-c16b-4a4c-9dfa-4906e5d171dd'
-export const BUILD_POLICY_TYPE = '0609b952-1397-4640-95ec-e00a01b2c241'
+const MINIMUM_REVIEWER_POLICY_TYPE = 'fa4e907d-c16b-4a4c-9dfa-4906e5d171dd'
+const BUILD_POLICY_TYPE = '0609b952-1397-4640-95ec-e00a01b2c241'
 
 /** `release: promote <source> to <target>` — derived, never declared. */
 export function promotionTitle(source: string, target: string): string {

package/packages/repo-controls/assets/reconcile-guard.sh

@@ -1,18 +1,17 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# Stage 2 of the CI pipeline for pull requests into `integration` (stage 1
-# bumps the PR branch, stage 3 runs the tests). It forces the PR author,
-# usually an agent, to reconcile with integration before anything merges:
+# Stage 1 of the CI pipeline for pull requests into `integration` (stage 2
+# runs the tests). It forces the PR author, usually an agent, to reconcile with
+# integration before anything merges:
 #
-#   Check A  the PR branch contains integration's tip
-#   Check B  the PR branch's manifest version is integration's + 1 patch
+#   the PR source branch contains integration's tip
+#
+# That is the only check. The version bump is not a PR concern any more: the
+# integration-merge pipeline bumps after the merge (Tarun, 2026-10-01).
 #
 # Read-only: this script only fetches and reads. It never pushes, and the only
 # refs it writes are the two remote-tracking refs it fetches.
-#
-# Run from the package directory (like version-bump.sh); the manifest is
-# resolved repo-relative through `git rev-parse --show-prefix`.
 
 # CI never carries an agent identity. Never set one here, and never inherit
 # one from the caller.
@@ -23,17 +22,11 @@ die() {
   exit 1
 }
 
-version_file=''
 pr_source=''
 base=''
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
-    --file)
-      [[ $# -ge 2 ]] || die '--file requires a path'
-      version_file="$2"
-      shift 2
-      ;;
     --pr-source)
       [[ $# -ge 2 ]] || die '--pr-source requires a branch'
       pr_source="$2"
@@ -50,8 +43,6 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
-[[ -n "$version_file" ]] || die '--file is required'
-[[ "$version_file" == 'package.json' ]] || die 'only --file package.json is supported'
 [[ -n "$pr_source" ]] || die '--pr-source is required'
 [[ -n "$base" ]] || die '--base is required'
 
@@ -66,8 +57,7 @@ case "$branch" in
     ;;
 esac
 
-prefix="$(git rev-parse --show-prefix)" || die 'not inside a git work tree'
-manifest_path="${prefix}${version_file}"
+git rev-parse --show-prefix > /dev/null || die 'not inside a git work tree'
 
 base_ref="refs/remotes/origin/$base"
 branch_ref="refs/remotes/origin/$branch"
@@ -79,35 +69,9 @@ base_short="$(git rev-parse --short "$base_ref")" || die "cannot resolve $base_r
 
 if ! git merge-base --is-ancestor "$base_ref" "$branch_ref"; then
   missing="$(git rev-list --count "$branch_ref..$base_ref")"
-  echo "reconcile-guard: FAIL — $branch does not contain integration's tip ($base_short). Reconcile: git pull origin integration && git push" >&2
+  echo "reconcile-guard: FAIL — $branch does not contain integration's tip ($base_short) — reconcile: git pull origin integration, then push" >&2
   echo "reconcile-guard: $missing integration commit(s) missing from $branch" >&2
   exit 1
 fi
 
-read_version() {
-  local ref="$1" text
-  text="$(git show "$ref:$manifest_path")" || die "cannot read $manifest_path at $ref"
-  printf '%s' "$text" | node -e '
-    const version = JSON.parse(require("node:fs").readFileSync(0, "utf8")).version
-    if (typeof version !== "string") process.exit(1)
-    process.stdout.write(version)
-  ' || die "cannot read a string version from $manifest_path at $ref"
-}
-
-parse_version() {
-  [[ "$1" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]] || die "cannot parse '$1' as a release version x.y.z"
-}
-
-base_version="$(read_version "$base_ref")"
-branch_version="$(read_version "$branch_ref")"
-
-parse_version "$base_version"
-target="${BASH_REMATCH[1]}.${BASH_REMATCH[2]}.$((BASH_REMATCH[3] + 1))"
-parse_version "$branch_version"
-
-if [[ "$branch_version" != "$target" ]]; then
-  echo "reconcile-guard: FAIL — $branch version $branch_version is not integration $base_version + 1 patch ($target). Stage 1 bumps it; re-run the PR build after reconciling." >&2
-  exit 1
-fi
-
-echo "reconcile-guard: PASS — $branch contains integration $base_short and is at $target"
+echo "reconcile-guard: PASS — $branch contains integration $base_short"

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

@@ -1,22 +1,22 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# 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:
+# STAGE 1 of the promote pipeline (push to `integration`): the integration-merge
+# build owns package version allocation (Tarun, 2026-10-01 -- a PR's
+# build-validation policy ignores `[skip ci]`, so a bump pushed from PR CI
+# re-queued itself; a push to a branch honours it). After a merge lands on
+# `integration` this sets the manifest to that commit's version + patch 1:
 #
-#   version-bump.sh --file package.json --pr-source <feature branch> \
-#     --base integration --push
+#   version-bump.sh --file package.json --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.
+# The Azure Pipelines build checks out the detached commit that triggered the
+# run with persisted credentials, so `git push` authenticates as the project
+# build service (which needs Contribute + "Bypass policies when pushing" on
+# `integration`). The bump commit is created on that checkout, carries
+# `[skip ci]` so the push does not trigger this pipeline again, and is pushed
+# with a plain fast-forward -- never forced. If integration moved since the
+# checkout the push is rejected and the script fails loud; the newer merge's
+# own run bumps. No npm query, no PR.
 
 # CI never carries an agent identity: the push below authenticates as the
 # project build service through the checkout's persisted System.AccessToken.
@@ -29,8 +29,7 @@ die() {
 }
 
 version_file=''
-pr_source=''
-base_branch=''
+integration_mode=false
 push_bump=false
 
 while [[ $# -gt 0 ]]; do
@@ -40,15 +39,9 @@ while [[ $# -gt 0 ]]; do
       version_file="$2"
       shift 2
       ;;
-    --pr-source)
-      [[ $# -ge 2 ]] || die '--pr-source requires a branch ref'
-      pr_source="$2"
-      shift 2
-      ;;
-    --base)
-      [[ $# -ge 2 ]] || die '--base requires a branch name'
-      base_branch="$2"
-      shift 2
+    --integration)
+      integration_mode=true
+      shift
       ;;
     --push)
       push_bump=true
@@ -60,52 +53,14 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
+[[ -n "$version_file" ]] || die '--file is required'
 [[ "$version_file" == 'package.json' ]] || die 'only --file package.json is supported'
-[[ -n "$pr_source" ]] || die '--pr-source is required'
-[[ -n "$base_branch" ]] || die '--base is required'
+[[ "$integration_mode" == true ]] || die '--integration is required'
 [[ "$push_bump" == true ]] || die '--push is required'
 
-# 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
-
 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"
 
@@ -113,20 +68,11 @@ 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))"
-
 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
+if [[ ! "$current_version" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
+  die "cannot parse '$current_version' ($version_file) as a release version x.y.z"
 fi
+next_version="${BASH_REMATCH[1]}.${BASH_REMATCH[2]}.$((BASH_REMATCH[3] + 1))"
 
 node -e '
   const fs = require("node:fs")
@@ -142,7 +88,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-pr-source-pre-bump.test.ts).
+# packages/repo-controls/tests/version-bump-integration-pre-bump.test.ts).
 config_path="$repo_root/adl-config.toml"
 pre_bump_list=''
 if [[ -f "$config_path" ]]; then
@@ -226,9 +172,10 @@ fi
 
 git -C "$repo_root" add -A
 git diff --cached --quiet && die "version bump produced no staged change (expected at least $version_file)"
-# 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'
+# `[skip ci]` (Azure DevOps: a push whose commits contain it does not trigger CI
+# pipelines) keeps this push from re-running the promote pipeline that made it.
+git commit -m "chore: bump version $current_version to $next_version [skip ci]"
+if ! git push origin "HEAD:refs/heads/integration"; then
+  die "push to integration rejected: integration moved since checkout, so this bump is stale; the next merge's run bumps"
+fi
+echo "version-bump: bumped integration from $current_version to $next_version; pushed"

package/packages/repo-controls/bunfig.toml

@@ -12,13 +12,12 @@
 # never-unit-tested Azure push code into the report at once, and 100% became
 # unreachable in a single commit.
 #
-# The package's OWN ratchet replaces it -- `coverageRegressions`, the same one
-# consumers are graded by. This repository is now one of its consumers:
-# `[controls.coverage].produce` builds coverage/coverage-summary.json from the
-# lcov below, `pre_push.coverage_ratchet` grades it against the committed copy,
-# and today's untested LINES may shrink but never grow. Counts rather than
-# percentages, for the reason settled for consumer coverage the same day -- a
-# percentage is derived, so it moves whenever a file's size moves.
+# `coverageRegressions` is the shared ratchet primitive used by every controlled
+# repository. This repository's root producer measures all workspace packages,
+# writes coverage/coverage-summary.json, and pre-push grades it against the
+# committed copy. Today's untested lines may shrink but never grow. Counts rather
+# than percentages: a percentage is derived, so it moves whenever a file changes
+# size.
 #
 # Nothing bespoke lives here. An earlier pass wrote a second ratchet and a second
 # record file for this repo alone; that was the package failing to eat its own

package/packages/repo-controls/package/adl-compliance/AGENTS.md

@@ -150,13 +150,12 @@ it. `tests/core/` is the one exception, for the spine (`Check`, `scope`,
 
 ## Status
 
-93 of the registry's 104 rows are ported — counted by importing
+Every row of the registry is implemented — 28 of 28, counted by importing
 `adl_compliance.checks` and measuring `len(CHECKS)` (`checks/__init__.py`'s
-explicit registry tuple), not by re-reading this paragraph.
-
-The remaining 11 are still shell in `compliance_new/`, which is frozen. A row
-with no Python implementation exits 2 with `no check implements <id>` — never
-a silent pass.
+explicit registry tuple), not by re-reading this paragraph. The shell
+`compliance_new/` tree this package ported from is gone, not frozen: a row
+with no Python implementation exits 2 with `no check implements <id>` —
+never a silent pass, and today no row reaches that.
 
 [`docs/operations/adl-compliance-invariants.md`](../../../../docs/operations/adl-compliance-invariants.md)
 records what is not true yet, including two rows that do not