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

package/packages/agent-settings/assets/TARUN-GLOBAL-AGENTS-INSTRUCTIONS.md

@@ -0,0 +1,40 @@
+# Tarun's global agent instructions
+
+My personal preferences, for every agent on every machine I own, for coding and non-coding work alike.
+Where a repository has its own AGENTS.md, that file and the files it links add the repository's rules. They never relax Truthfulness, Verification before claiming done or Scope discipline here; on any other conflict, ask.
+
+## Communication
+- Address me as **Tarun**.
+- **Answer first.** No greeting, no "let me", no recap of what was just done, no closers.
+- One idea per sentence. Short beats polite. Articles can go; not, never, no, only never do. Numbers, paths, commands exact.
+- Bullet points over prose.
+- **Open points:** one numbered list of open decisions per conversation. Show it only when it changes — item added or resolved. After a long gap or compaction, restate the full list. That is when it gets lost.
+- **Questions:** one at a time, one or two sentences. Options inline: `A) … B) …`. A long multi-part question means split the work, not more prose.
+- Full sentences for security warnings, irreversible actions, step-by-step orders, and when I'm confused. Then short resumes.
+- No performance. If short phrasing isn't shorter, plain English wins. Never rewrite my prompts.
+
+## Truthfulness (non-negotiable)
+- Never present something as done, working or checked when it is not. A failure reported plainly is worth more than a success that is not real.
+- **No silent fallback or degrade** — if the real path fails, say so loudly and stop.
+- **No silent drops** — no skipped steps, ignored errors or quietly narrowed scope.
+- **No fakes** — no placeholders, stand-ins or TODOs passed off as finished.
+- Unverified claims never enter anything that lasts: documents, messages, notes, memory.
+- Never read secret stores or credential files, never pass a token or password in a command or message, and never claim to be me or set anything that marks the session as human (drafting in my name when I ask is fine).
+
+## Verification before claiming done
+- **Evidence over assertions:** show what you ran or read, and make the check falsifiable ("did you search the source?" has an answer; "did you verify?" does not).
+- **A search shows what was returned, not what exists.** Before saying something is absent, say how you looked, and run a control search the same way for something you know is there. Search wide first, then narrow. No hits for both means you searched the wrong place.
+- **Ask the authoritative source, not the one in front of you:** the original over a copy, the live system over a description of it.
+- **Re-check before reporting.** Cite the check you are reporting, not one you remember. Never claim "checked everything" without checking every case.
+- A requirement you are about to not meet is a **stop**: tell me; never quietly decide to skip it.
+
+## Scope discipline
+- Work in your own working directory. Touch only what is in scope: the files, accounts, people and systems the task names.
+- Anything outside scope is raised as an open point for me (or recorded where that work is tracked): never silently done, never silently dropped.
+
+## Delegation & parallelism
+- Where the surface supports helper agents, the main agent orchestrates and verifies and helpers do the hands-on work; small tasks may be done directly.
+- Split independent work into **concurrent agents** launched together — never sequential when it can fan out.
+- Match the model to the task: strongest for deep analysis and judgment, fastest for quick lookups.
+- Author and reviewer are **distinct passes in separate contexts**. Never self-approve.
+- Prefer speed through parallel runs and fast models; never skip verification for speed.

package/packages/agent-settings/src/global-agents.ts

@@ -1,16 +1,16 @@
 /**
- * Deploy the canonical `packages/agent-settings/assets/GLOBAL-AGENTS.md` out
+ * Deploy the canonical `packages/agent-settings/assets/TARUN-GLOBAL-AGENTS-INSTRUCTIONS.md` out
  * to every AI-agent host's own global instruction file, so each host reads
  * the same content: `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`,
  * `~/.cursor/AGENTS.md`, `~/.kimi-code/AGENTS.md`,
  * `~/.config/opencode/AGENTS.md`.
  *
- * The canonical source is committed in this repo (`../assets/GLOBAL-AGENTS.md`
+ * The canonical source is committed in this repo (`../assets/TARUN-GLOBAL-AGENTS-INSTRUCTIONS.md`
  * relative to this file), not read from any other repo's checkout at
  * runtime — two different repos fighting over the same global target file is
  * exactly the collision this replaces.
  *
- * Ownership model: GLOBAL-AGENTS.md is the single source of truth for every
+ * Ownership model: TARUN-GLOBAL-AGENTS-INSTRUCTIONS.md is the single source of truth for every
  * target. Deploy is always forced — there is no opt-out flag:
  *   - missing target        -> created from the source.
  *   - content === source    -> untouched (true no-op).
@@ -18,7 +18,7 @@
  *                              stale, both are drift). These exact files are
  *                              authoritative adl roots: replacement does
  *                              not retain a displaced copy.
- * Any change to a host's global instructions must go through GLOBAL-AGENTS.md.
+ * Any change to a host's global instructions must go through TARUN-GLOBAL-AGENTS-INSTRUCTIONS.md.
  * Uninstall removes those same owned files regardless of their current bytes.
  */
 
@@ -31,6 +31,7 @@ import {
   rmSync,
   writeFileSync,
 } from 'node:fs'
+import { hostname as osHostname } from 'node:os'
 import { dirname, isAbsolute, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -47,7 +48,29 @@ export const AGENT_TARGETS: readonly AgentTarget[] = [
   { relativeDir: '.config/opencode', file: 'AGENTS.md' },
 ]
 
-export const DEFAULT_SOURCE_PATH = fileURLToPath(new URL('../assets/GLOBAL-AGENTS.md', import.meta.url))
+export const DEFAULT_SOURCE_PATH = fileURLToPath(new URL('../assets/TARUN-GLOBAL-AGENTS-INSTRUCTIONS.md', import.meta.url))
+
+export const DEFAULT_MANIFEST_PATH = fileURLToPath(new URL('../../fleet/manifest.json', import.meta.url))
+
+export type FleetScope = { readonly inFleet: true; readonly device: string } | { readonly inFleet: false; readonly note: string }
+
+export function deviceNameOf(hostname: string): string {
+  return hostname.split('.')[0] ?? hostname
+}
+
+// Fleet-only deploy rule and its rationale: README "Global agent instructions".
+export function resolveFleetScope(hostname: string, manifestPath: string): FleetScope {
+  let manifest: { mac?: { devices?: object }; linux?: { devices?: object } }
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+  } catch (cause) {
+    throw new Error(`cannot read fleet manifest ${manifestPath}: ${messageOf(cause)}`)
+  }
+  const device = deviceNameOf(hostname)
+  const names = [...Object.keys(manifest.mac?.devices ?? {}), ...Object.keys(manifest.linux?.devices ?? {})]
+  if (names.includes(device)) return { inFleet: true, device }
+  return { inFleet: false, note: `skipped: '${device}' is not a device in packages/fleet/manifest.json, so no global file is written` }
+}
 
 export type TargetState = 'missing' | 'matches' | 'drifted'
 
@@ -181,23 +204,35 @@ function readSource(sourcePath: string): string {
 }
 
 function usage(): never {
-  throw new Error('usage: global-agents --home ABSOLUTE_PATH --mode deploy|status|uninstall')
+  throw new Error('usage: global-agents --home ABSOLUTE_PATH --mode deploy|status|uninstall [--host NAME] [--manifest PATH]')
 }
 
-export function main(argv: readonly string[]): void {
+export function main(argv: readonly string[], hostname: string = osHostname()): void {
   let home = ''
   let mode = 'status'
+  let host = hostname
+  let manifest = DEFAULT_MANIFEST_PATH
 
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index]
     if (argument === '--home') home = argv[++index] ?? ''
     else if (argument === '--mode') mode = argv[++index] ?? ''
+    else if (argument === '--host') host = argv[++index] ?? ''
+    else if (argument === '--manifest') manifest = argv[++index] ?? ''
     else usage()
   }
-  if (home.length === 0 || !['deploy', 'status', 'uninstall'].includes(mode)) usage()
+  if (home.length === 0 || host.length === 0 || manifest.length === 0 || !['deploy', 'status', 'uninstall'].includes(mode)) usage()
 
   const sourceContent = readSource(DEFAULT_SOURCE_PATH)
 
+  if (mode !== 'uninstall') {
+    const scope = resolveFleetScope(host, manifest)
+    if (!scope.inFleet) {
+      console.log(`global-agents: ${scope.note}`)
+      return
+    }
+  }
+
   if (mode === 'status') {
     const statuses = inspectGlobalAgents(home, sourceContent)
     for (const status of statuses) console.log(`${status.state}: ${status.path}`)

package/packages/agent-skills/assets/adl-mechanics/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: adl-mechanics
+description: How agents reach Azure DevOps in an adl-controlled repository — agent identity, the git front controller, the adl MCP tools and their CLI fallback, repository-control hooks, and when `adl run` may start a sub-agent.
+---
+
+# adl mechanics
+
+How adl behaves on every machine and in every repository it controls.
+
+## Use When
+
+- You are about to run a git network command, open or update a PR, read or write a work item, or start a build.
+- A command is refused for identity, credentials or hooks, and you need to know why.
+- The operator asks you to start a sub-agent session with `adl run`.
+
+## Agent identity
+
+- Every Azure DevOps access (git, PRs, work items, builds, reads included) runs as an agent identity, never as the human. The default is the machine's default agent, set by fleet reconcile; it can always be overridden.
+- **Override:** prefix a command with `ADL_AGENT_ID_AGENT=<agent-id>`. An MCP tool call can't carry a prefix, so it uses the session environment or the machine default; the CLI fallback (`adl mcp cli <command>`) takes the prefix like any command.
+- Never read vault files. Never pass a token.
+- **Never set `ADL_HUMAN_AZDO`.** It is the owner's human-terminal marker for `git-ado`'s and `adl id whoami`'s fail-closed human pass-through (stdin is a TTY and `ADL_HUMAN_AZDO=1`, exactly). An agent carrying it would let a child process forge that pass-through.
+
+## Git and Azure DevOps operations
+
+- Use ordinary `git` for every Git operation. The managed `/usr/local/bin/git` front controller hands local and non-Azure DevOps work to the system Git, and routes HTTPS Azure DevOps network commands through `adl-agent-id exec --agent "$ADL_AGENT_ID_AGENT"`. `git-ado` handles the credential boundary; there is no second account or secret location.
+- PRs, work items and builds go through the `adl` MCP server (`adl mcp serve`): `pr_list_or_get`, `pr_create_or_update`, `pr_review`, `build_list_or_get`, `build_run`, `workitem_list_or_get`, `workitem_create_or_update`. If the server is not working, fall back to `adl mcp cli <command>`.
+
+## Repository controls
+
+- Run via `adl repo controls`. Git hooks run pre-commit (local checks) and pre-push (Azure DevOps governance).
+- Each repository is reconciled on its own, with its `.agents/`, `.claude/`, `.codex/`, `.cursor/`, `.kimi-code/` and `.opencode/` projections.
+
+## Sub-agent sessions (`adl run`)
+
+- Only on the operator's explicit request; an agent never starts one on its own. It is not an identity route and not a fallback for anything.
+- **Headless:** `adl run <surface> --headless "<prompt>"`, surface one of `claude`, `codex`, `opencode`, `kimi`, `cursor`.
+- **Identity:** add `--as <agent>`.
+- **Model:** add `--model <model>`. adl passes each surface's own flag (claude and cursor `--model`; codex, opencode and kimi `-m`); a surface without one refuses it (exit 2). `--model` cannot be combined with `adl run -- <cmd>`.

package/packages/agent-skills/assets/agent-search-tool-audit/scripts/audit.sh

@@ -92,7 +92,7 @@ run_ts = sys.argv[2]
 today = sys.argv[3]
 log_files = sys.argv[4:]
 
-cutoff = datetime.datetime.fromisoformat(today + "T00:00:00Z") - datetime.timedelta(days=days-1)
+cutoff = datetime.datetime.fromisoformat(today + "T00:00:00+00:00") - datetime.timedelta(days=days-1)
 
 # Per (host, day), tally. Dedupe by (ts, command, rule) within each log.
 per_host_day = collections.defaultdict(lambda: collections.Counter())

package/packages/agent-skills/assets/to-feature/SKILL.md

@@ -8,7 +8,7 @@ disable-model-invocation: true
 
 Open a **Feature** on the board and give it a plan folder to live in.
 
-**A plan is a Feature, and a Feature is a directory** — `plans/features/az<id>-<slug>/spec.md`, named for the work item it is. This skill creates that Feature and that directory; `to-workitems` later fills its `items/` with PBIs and Bugs parented under it. Where the repo carries a `plans/AGENTS.md`, it governs; otherwise follow the global `## Plans and work items` contract in your host's agent instructions.
+**A plan is a Feature, and a Feature is a directory** — `plans/features/az<id>-<slug>/spec.md`, named for the work item it is. This skill creates that Feature and that directory; `to-workitems` later fills its `items/` with PBIs and Bugs parented under it. Where the repo carries a `plans/AGENTS.md`, it governs; otherwise follow `## Plans and work items` in the repository's `CONTRIBUTING.md`.
 
 Do NOT interview the user — synthesize what you already know from the conversation and the codebase.
 

package/packages/agent-skills/assets/to-workitems/SKILL.md

@@ -8,7 +8,7 @@ disable-model-invocation: true
 
 Put a plan's **backlog items** on the board.
 
-**A plan is a Feature. An item file is a PBI or a Bug.** One file each. The plan and its `## Items` table are written before this skill runs; the item files are not, because each is named for an id only this skill allocates. Where the repo carries a `plans/AGENTS.md`, it governs the layout; otherwise follow the global `## Plans and work items` contract in your host's agent instructions. [references/AZURE-DEVOPS-HIERARCHY.md](references/AZURE-DEVOPS-HIERARCHY.md) carries the board rules both depend on.
+**A plan is a Feature. An item file is a PBI or a Bug.** One file each. The plan and its `## Items` table are written before this skill runs; the item files are not, because each is named for an id only this skill allocates. Where the repo carries a `plans/AGENTS.md`, it governs the layout; otherwise follow `## Plans and work items` in the repository's `CONTRIBUTING.md`. [references/AZURE-DEVOPS-HIERARCHY.md](references/AZURE-DEVOPS-HIERARCHY.md) carries the board rules both depend on.
 
 ## Use When
 

package/packages/agent-skills/assets/to-workitems/references/AZURE-DEVOPS-HIERARCHY.md

@@ -47,6 +47,9 @@ expressed by parenting; they need `System.LinkTypes.Dependency-Reverse` links,
 which `workitem_create_or_update`'s `predecessors` argument creates — one link
 per id, in the order given.
 
+Supplying `parentId` on an **update** moves the item: the old parent link is
+removed, never kept alongside the new one.
+
 `predecessors` is the only argument that creates them. It has no alias at the
 tool level: `blockedBy` is not read.
 

package/packages/azdo/src/lib/agent-identity.ts

@@ -147,7 +147,7 @@ export interface AgentIdentityResolution {
  *  - `env.ADL_HUMAN_AZDO === '1'`: the EXACT string `"1"`, not `"true"`,
  *    not `"yes"`, not trimmed whitespace -- Tarun exports it from his own
  *    `.zshrc`. An agent must never set it (packages/agent-settings'
- *    GLOBAL-AGENTS.md, "Agent identity"; the hook's denial of an agent
+ *    TARUN-GLOBAL-AGENTS-INSTRUCTIONS.md, "Agent identity"; the hook's denial of an agent
  *    setting it is packages/agent-hooks work, not this module's).
  *
  * No fallback, no trimming, no case-insensitivity: a near-miss value is

package/packages/repo-controls/README.md

@@ -359,7 +359,7 @@ guidance (see [Compliance seeding](#compliance-seeding) below). The decisions
 and the gate list live in
 [`docs/architecture/compliance-controls.md`](../../docs/architecture/compliance-controls.md#strict-activation-and-switching-a-gate-off).
 `install --rewire` (what fleet reconcile runs on every enrolled repo) seeds nothing,
-scaffolds nothing and does not grade: it only re-deploys the hook stubs, `.workflows`
+scaffolds nothing (no root template either) and does not grade: it only re-deploys the hook stubs, `.workflows`
 and the lock, and leaves adl-config.toml byte-identical. Without `uv`, the `adl install`
 wrapper prints a one-line warning that grading is skipped, finishes deploying and exits 0;
 pre-commit still fails loudly without `uv`. See
@@ -551,12 +551,17 @@ doctor report and never repairs or stages the managed surface: run
 An existing `[controls.compliance]` with no `trees` table gets it appended; one
 that already has a `trees` table (any keys) is left byte-identical.
 
-Install also scaffolds the repository entry files `AGENTS.md` and `CLAUDE.md`
-(`@AGENTS.md`) at the root when absent (never overwritten) — `SCAFFOLD_ROOT_FILES` in
-`src/constants.ts` is the list. `INVARIANTS.md` is deployed from
-`assets/GLOBAL-INVARIANTS.md`, the invariants that apply to ALL repositories, only when
-the target has none (never overwritten); the engine's root gate still requires
-`INVARIANTS.md`. See Scaffolding below
+### Root templates
+
+The root templates `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md` and `INVARIANTS.md`
+(`SCAFFOLD_ROOT_FILES` in `src/constants.ts`, sources in `assets/scaffold/root/`) are
+written, when absent, only by a run that creates `adl-config.toml` (`adl install` on a
+repository without one, or `adl migrate`; the internal `install --config-created` flag, set by `adl install`,
+says so and is deliberately absent from help). `--rewire`, fleet reconcile and any later install never write them, even when a
+file is missing. The only overwrite is `install --force-templates[=<file,...>]`: bare means
+all four, a comma list picks files, an unknown name exits 2 listing the valid ones, and it
+cannot be combined with `--rewire`. Each overwrite is an `update` action, also in `--json`; a forced template whose bytes already match is left unchanged and reported as no action.
+The engine's root gate still requires `INVARIANTS.md`. See Scaffolding below
 for which folders it creates.
 
 #### Grading

package/packages/repo-controls/assets/scaffold/root/AGENTS.md

@@ -1,22 +1,71 @@
 # Agent entry point
 
-This is the first file a human or agent should read on arriving at this
-repository. Edit it to describe what this repository is; the sections below
-describe the layout the adl repo controls enforce.
+First file a human or agent reads here. Keep it short.
 
-## Layout
+## What this repository is
+- <!-- Owner: one or two lines on what this repo is and who uses it. -->
+
+## Layout (paths as declared in `[controls.compliance.trees]`)
 
 | Path | What lives there |
 | --- | --- |
 | `docs/` | reference documentation, see `docs/AGENTS.md` |
 | `plans/` | Features and the PBIs/Bugs under them, see `plans/AGENTS.md` |
 | `workflows/` | CI pipelines and build/release scripts, see `workflows/AGENTS.md` |
-| `.workflows/` | managed hook stubs and lock, rebuilt by `adl repo controls install`; never hand-edit |
-
-## Rules
+| `.workflows/` | managed hook stubs and lock; rebuilt by `adl repo controls install`, never hand-edit |
 
-- This repository is graded by `adl-compliance` on every commit; the enabled
-  gates are `[controls.compliance].enabled` in `adl-config.toml`. A failing
-  gate is fixed, not skipped.
-- `INVARIANTS.md` lists what this repository must never regress.
+## Where to look next
+- `CONTRIBUTING.md`: plans and work items, commits and PRs, release flow, tasks ledger.
+- `INVARIANTS.md`: what must never regress, how each is verified, protected paths.
+- Graded on every commit by `adl repo controls compliance run`; enabled gates are `[controls.compliance].enabled` in `adl-config.toml`. A failing gate is fixed, not skipped.
 - Work-item status lives on the board, never in a file.
+
+## Keep this guidance alive
+- **When:** you were corrected by the owner, a gate or test failed for a reason not written here, or you learned a rule the hard way.
+- **Where (one place only):**
+  - convention or workflow → `CONTRIBUTING.md`
+  - must-never-regress rule → `INVARIANTS.md`, only with its verifying gate/test/command; no check, no invariant
+  - orientation (what lives where) → `AGENTS.md`
+  - folder-specific → that folder's `AGENTS.md`
+  - applies to every repository → tell the owner; never edit global files
+- **How:** put the edit in the same commit/PR that taught you it; edit the existing bullet instead of adding a near-duplicate; one bullet, at most 2 lines.
+- **Never record:** secrets, ids/URLs of one-off items, session or progress state, unverified claims, rules a gate already enforces and explains in its own message.
+
+## Working defaults for code
+Tarun's global instructions cover communication, truthfulness, verification, scope and delegation. These are the coding defaults. Edit them for this repository, except "Truthfulness and verification in code", which a repository may add to but never relax.
+
+### Truthfulness and verification in code
+- No `|| true`, no swallowed errors, no skipped gates.
+- Negative claims need source-level proof: grep the implementation, not a tool listing. Search the whole package first, then narrow.
+- Before reporting what the repository contains, ask the remote (`git show origin/<branch>:<path>`); before reporting a shipped tool's behaviour, ask the installed binary.
+- Name the ref. Where a change is in flight, two branches answer differently and both are right about themselves; say which one you asked.
+- Deployed is not running: a long-lived server or daemon keeps the code it started with. When a fix is installed and behaviour has not changed, restart the process first.
+
+### Checkouts
+- Commit rules: `CONTRIBUTING.md`.
+- At most 3 checkouts per repository, including the main folder; git refuses the 4th and names the command to use. Reconcile old worktrees first (merge, then `git worktree remove <path>`).
+- Prefer the one checkout; parallel subagents share it, each with its own write scope. Only the orchestrator commits.
+
+### Tests
+- For features, bugfixes and non-trivial refactors: tests first, confirmed failing for the right reason; then minimal code to pass; then a separate review pass.
+- Every code change ships a new test. Exempt: pure config, docs, trivial one-liners.
+- A test changes only when the intended behaviour changes. Don't loosen, skip or delete an assertion, or set an expectation to whatever the code returns, to hide a failure. Red is honest.
+- When a change deliberately alters behaviour, rework the tests that assert the old behaviour in the same change; name each one and the decision that changed it.
+
+### Fixing things
+- Fix at the source — the primitive, token or shared layer — so it propagates everywhere, not a narrow downstream patch.
+- Consult official docs before coding against an unfamiliar SDK, framework or API.
+
+### Context tooling
+- Match the tool to the question (when installed; otherwise `rg`):
+  - Orient in unfamiliar code → `crg architecture`, `crg communities`.
+  - Symbols and semantic code queries → `crg search "<text>"`.
+  - Callers, callees, blast radius → `crg query callers_of|callees_of|tests_for|importers_of <target>`, `crg impact`.
+  - Unreferenced code → `crg dead-code`.
+  - A code shape rather than a string → `ast-grep`.
+  - Prose in documentation folders (`docs/`, `plans/`) → `search <text>` (hybrid semantic + keyword).
+  - Literal text or regex → `rg`. Never `grep`; never `find | grep`, which filters file names and misses the file whose contents match.
+  - Files by name or tree → the host's native file-listing tools.
+
+### Temporary files
+- Scratch and throwaway work goes in `.scratchpad/` at the repository root, never `/tmp` or `/private/tmp`. Create it if missing; it is gitignored. Real deliverables go to their proper home.

package/packages/repo-controls/assets/scaffold/root/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing
+
+How to contribute to THIS repository. Orientation is in `AGENTS.md`; what must never regress, and the protected paths, are in `INVARIANTS.md`. Tree paths are those declared in `[controls.compliance.trees]`; `plans/` is the default.
+
+## Plans and work items
+- A plan is a Feature; a backlog item is a PBI or a Bug. One file each; the board is the only place their state lives.
+- Layout: `plans/features/az<feature id>-<slug>/spec.md`, items under `items/az<id>-<slug>.md`.
+- The id is the identity: allocate the item on the board first, then name the file. Until then it is a row in the plan's `## Items` table.
+- Nothing moves between directories; the spec text is the item's fields.
+- A gap found along the way goes in `plans/GAPS-AND-FINDINGS.md` and becomes a Bug under the same Feature.
+
+## Commits and PRs
+- Each commit is independently green and on one topic. Never `git stash`. Green wins over one topic, and say so.
+- Subject: `<type>(<scope>): <lowercase subject>`; types `feat|fix|docs|refactor|perf|chore`; no `!`.
+- Branch: `<type>/<kebab>`, same types, not configurable.
+- `release:` is reserved for the promotion PR the pipeline raises; never write one by hand.
+- A PR body needs non-empty `## Summary`, `## Why` and `## Changes`; the title follows the subject grammar.
+
+## Release flow
+- `<type>/<kebab>` branch → PR → `integration` (auto-completes when green) → pipeline opens `integration → main` → owner approves. No agent opens that PR.
+- A repository that differs states it under "Release flow of this repository".
+
+## Tasks ledger
+- At the start and the end of a task, append one line to `docs/notes.md` (create it if missing, with YAML frontmatter and a `## Lines` section).
+- Format `YYYY-MM-DD HH:MM <surface> <note>`, whole line ≤100 characters. Append-only, newest last, never rewrite earlier lines. One ledger per repository.
+
+## Release flow of this repository
+- <!-- Owner: state any difference from the flow above; delete this section if none. -->

package/packages/repo-controls/assets/scaffold/root/INVARIANTS.md

@@ -0,0 +1,17 @@
+# Invariants
+
+Must-never-regress rules. One bullet each: `rule` — verified by `gate/test/command`. No check, no invariant. Add yours under "This repository".
+
+## Estate-wide
+- The compliance gates enabled in `adl-config.toml` pass before every commit — verified by `adl repo controls` pre-commit and CI. A gate is switched off only by the owner, by removing it from `[controls.compliance] enabled`.
+- A compliance exemption list only shrinks: remove a file once it passes; never add one — verified by the gate that reads the register.
+- No multi-line comments in code; the explanation lives in `docs/` — verified by `repository.no-multiline-comments`.
+- The standard trees `docs`, `plans`, `workflows` and `compliance` are those declared in `[controls.compliance.trees]`, matching the layout in `AGENTS.md` — verified by the layout and docs gates.
+
+## Protected paths
+- Landed only by the owner; an agent leaves them uncommitted and asks — verified by the pre-commit integrity gate.
+- `adl-config.toml`, `compliance/` (or the compliance tree declared in `[controls.compliance.trees]`) and `workflows/`, plus any pattern this repository adds under `[controls.integrity].watched`.
+- No dot folder is protected as a whole: `.workflows/` and the agent surface folders hold the repository's own hooks and skills.
+
+## This repository
+- <!-- Owner: `rule` — verified by `gate/test/command`. -->

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

@@ -1,4 +1,4 @@
-import { HOOK_NAMES, TOOL, VERSION } from './constants.ts'
+import { HOOK_NAMES, SCAFFOLD_ROOT_FILES, TOOL, VERSION } from './constants.ts'
 import { doctor } from './doctor.ts'
 import { azdoPush } from './azdo-push.ts'
 import { ensurePromotionPullRequest } from './promote.ts'
@@ -18,7 +18,8 @@ export interface Io {
 }
 
 const USAGE = `usage:
-  ${TOOL} install [--repo <path>] [--dry-run] [--json] [--no-grade] [--rewire]
+  ${TOOL} install [--repo <path>] [--dry-run] [--json] [--no-grade] [--rewire] [--force-templates[=<file,...>]]
+  (--force-templates: overwrite the root templates; bare = all of ${SCAFFOLD_ROOT_FILES.join(', ')}, or a comma list)
   ${TOOL} grade [--repo <path>]   (prints the compliance verdict as JSON; exit 0 whatever the verdict)
   ${TOOL} uninstall [--repo <path>] [--dry-run]
   ${TOOL} doctor [--repo <path>] [--json]
@@ -40,6 +41,8 @@ interface Parsed {
   flags: Set<string>
   positional: string[]
   rest: string[]
+  /** The raw `--force-templates=<list>` value; undefined for the bare flag. */
+  forced?: string
 }
 
 function parse(command: string, argv: string[], allowed: string[]): Parsed {
@@ -50,7 +53,11 @@ function parse(command: string, argv: string[], allowed: string[]): Parsed {
       parsed.rest = argv.slice(index + 1)
       break
     }
-    if (arg === '--repo') {
+    if (arg === '--force-templates' || arg.startsWith('--force-templates=')) {
+      if (!allowed.includes('--force-templates')) throw new UsageError(`unknown option for ${command}: ${arg}`)
+      parsed.flags.add('--force-templates')
+      if (arg.includes('=')) parsed.forced = arg.slice(arg.indexOf('=') + 1)
+    } else if (arg === '--repo') {
       parsed.repo = argv[++index] ?? ''
     } else if (arg.startsWith('--')) {
       if (!allowed.includes(arg)) throw new UsageError(`unknown option for ${command}: ${arg}`)
@@ -66,6 +73,15 @@ function parse(command: string, argv: string[], allowed: string[]): Parsed {
   return parsed
 }
 
+/** The root templates named by `--force-templates[=<list>]`; the bare flag means all, an unknown or empty name is refused. */
+function forcedTemplates(value: string | undefined): string[] {
+  if (value === undefined) return [...SCAFFOLD_ROOT_FILES]
+  const names = value.split(',')
+  const unknown = names.filter((name) => !(SCAFFOLD_ROOT_FILES as readonly string[]).includes(name))
+  if (unknown.length > 0) throw new UsageError(`unknown root template for --force-templates: ${unknown.map((n) => `'${n}'`).join(', ')} (valid: ${SCAFFOLD_ROOT_FILES.join(', ')})`)
+  return names
+}
+
 function printActions(io: Io, actions: Action[], dryRun: boolean): void {
   const tag = dryRun ? '[dry-run] ' : ''
   for (const action of actions) io.out(`${tag}${action.kind} ${action.target} (${action.reason})`)
@@ -84,10 +100,12 @@ async function dispatch(argv: string[], io: Io): Promise<number> {
       io.out(USAGE)
       return 0
     case 'install': {
-      const parsed = parse(command, args, ['--dry-run', '--json', '--no-grade', '--rewire'])
+      const parsed = parse(command, args, ['--dry-run', '--json', '--no-grade', '--rewire', '--config-created', '--force-templates'])
       const rewire = parsed.flags.has('--rewire')
+      const forceTemplates = parsed.flags.has('--force-templates') ? forcedTemplates(parsed.forced) : []
+      if (rewire && forceTemplates.length > 0) throw new UsageError('--force-templates cannot be combined with --rewire (a re-wire never writes root templates)')
       const grade = parsed.flags.has('--no-grade') || rewire ? {} : { grade: { env: io.env } }
-      const result = install(parsed.repo, { dryRun: parsed.flags.has('--dry-run'), rewire, ...grade })
+      const result = install(parsed.repo, { dryRun: parsed.flags.has('--dry-run'), rewire, configCreated: parsed.flags.has('--config-created'), forceTemplates, ...grade })
       if (parsed.flags.has('--json')) {
         io.out(JSON.stringify(result))
         return 0

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

@@ -2,16 +2,6 @@ import { readFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 
 export const TOOL = 'adl-repo-controls'
-/**
- * Never published (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).
- */
-const PACKAGE_NAME = '@amsterdamdatalabs/adl-repo-controls'
-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`
@@ -72,11 +62,8 @@ export const RECONCILE_GUARD_REL = '.workflows/reconcile-guard.sh'
 /** The folder skeleton `install` bootstraps for the adl standard trees; see README, "Scaffolding". */
 export const SCAFFOLD_ROOT = join(PACKAGE_ROOT, 'assets', 'scaffold')
 export const SCAFFOLD_TREES = ['docs', 'plans', 'workflows'] as const
-/** Repository-root entry files, scaffolded from `assets/scaffold/root/` when absent (never overwritten). */
-export const SCAFFOLD_ROOT_FILES = ['AGENTS.md', 'CLAUDE.md'] as const
-/** The invariants that apply to ALL repositories; install deploys it as `INVARIANTS.md` only when the target has none. */
-export const GLOBAL_INVARIANTS_SOURCE = join(PACKAGE_ROOT, 'assets', 'GLOBAL-INVARIANTS.md')
-export const GLOBAL_INVARIANTS_TARGET = 'INVARIANTS.md'
+/** Repository-root templates in `assets/scaffold/root/`: written only by a run that creates adl-config.toml, overwritten only by `--force-templates`. */
+export const SCAFFOLD_ROOT_FILES = ['AGENTS.md', 'CLAUDE.md', 'CONTRIBUTING.md', 'INVARIANTS.md'] as const
 
 export const MANAGED_ASSETS = [
   { rel: PROMOTE_REL, source: join(PACKAGE_ROOT, 'assets', 'promote.ts'), mode: 0o755, doctorId: 'promote' },

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

@@ -24,8 +24,6 @@ import {
   ADL_NPM_INSTALL,
   CONFIG_REL,
   GITIGNORE_REL,
-  GLOBAL_INVARIANTS_SOURCE,
-  GLOBAL_INVARIANTS_TARGET,
   HOOK_NAMES,
   HOOKS_PATH,
   LOCK_REL,
@@ -234,6 +232,10 @@ export interface InstallOptions {
   grade?: { env: Env }
   /** Re-wire only: no config seeding, no scaffolding, no grading (fleet reconcile; see README, "Re-wiring"). */
   rewire?: boolean
+  /** This run created adl-config.toml, so the root templates are written when absent; see README, "Root templates". */
+  configCreated?: boolean
+  /** Root templates to overwrite (`--force-templates`); the only way an existing template is replaced. */
+  forceTemplates?: readonly string[]
 }
 
 export interface InstallResult {
@@ -266,6 +268,7 @@ function readCentralMarker(repo: string, dryRun: boolean): string {
 export function install(repoArg: string, options: InstallOptions): InstallResult {
   const repo = resolveRepo(repoArg)
   const dryRun = options.dryRun === true
+  const configMissing = !existsSync(join(repo, CONFIG_REL))
   const initialConfigText = readCentralMarker(repo, dryRun)
   // Validate only repo-controls' declared tables before deleting its root.
   // Other owners' tables remain deliberately opaque.
@@ -336,6 +339,7 @@ export function install(repoArg: string, options: InstallOptions): InstallResult
       created: complianceResult.created,
       sha256: sha256(extractTableSpan(finalConfigText, 'controls.compliance') as string),
     }
+    scaffoldRootTemplates(ops, options.configCreated === true || (dryRun && configMissing), options.forceTemplates ?? [])
     scaffoldStandardTrees(finalConfigText, ops)
   }
 
@@ -507,10 +511,6 @@ function assertComplianceTree(value: unknown): void {
 /** Bootstrap the standard trees at their declared paths, only where the folder is missing; see README, "Scaffolding". */
 function scaffoldStandardTrees(configText: string, ops: Ops): void {
   const missing = declaredScaffoldTrees(configText).filter(({ base }) => !ops.occupied(base))
-  for (const rel of SCAFFOLD_ROOT_FILES) {
-    ops.create(rel, readFileSync(join(SCAFFOLD_ROOT, 'root', rel)), 'scaffold the repository entry files (user-owned after install)')
-  }
-  ops.create(GLOBAL_INVARIANTS_TARGET, readFileSync(GLOBAL_INVARIANTS_SOURCE), 'deploy the global invariants (user-owned after install)')
   for (const { name, base } of missing) {
     for (const rel of scaffoldFiles(join(SCAFFOLD_ROOT, name), '')) {
       ops.create(`${base}/${rel}`, readFileSync(join(SCAFFOLD_ROOT, name, rel)), `scaffold the ${name} tree (user-owned after install)`)
@@ -518,6 +518,15 @@ function scaffoldStandardTrees(configText: string, ops: Ops): void {
   }
 }
 
+/** Root templates: created when absent on a run that created adl-config.toml, overwritten only for the forced names; see README, "Root templates". */
+function scaffoldRootTemplates(ops: Ops, created: boolean, forced: readonly string[]): void {
+  for (const rel of SCAFFOLD_ROOT_FILES) {
+    const bytes = readFileSync(join(SCAFFOLD_ROOT, 'root', rel))
+    if (forced.includes(rel)) ops.write(rel, bytes, 'overwrite the root template (--force-templates)')
+    else if (created) ops.create(rel, bytes, 'scaffold the repository root template (user-owned after install)')
+  }
+}
+
 /** Every file under `dir`, relative to it, sorted, depth-first. */
 function scaffoldFiles(dir: string, prefix: string): string[] {
   return readdirSync(join(dir, prefix), { withFileTypes: true })