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

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

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

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

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

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

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

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

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

package/packages/repo-controls/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 })