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

package/packages/agent-settings/src/deploy/lean-ctx-merge.ts

@@ -1,580 +0,0 @@
-/**
- * The merge contract for a repo-local lean-ctx file, corrected by a
- * SECOND independent review (2026-09-29) after the marker-region design
- * itself shipped. Three real bugs found there:
- *
- *  3. HIGH — `shell_allowlist_extra` lived INSIDE the managed block, so a
- *     real `lean-ctx allow <cmd>` writing an entry into it was wiped by
- *     the very next deploy's self-heal (a whole-block replace). DECISION:
- *     the array leaves the managed block and becomes a UNION key —
- *     resolved by a narrow text scan (string literals only), adl's
- *     required entries inserted before `]` if missing, nothing ever
- *     removed or reordered.
- *  4. HIGH — migration required the asset's CURRENT text to be found
- *     verbatim in the existing file. The asset changing at all (as it
- *     legitimately does, e.g. this same fix) broke migration for every
- *     already-enrolled repo, including this one. DECISION: migration now
- *     classifies the existing (markerless) file LINE BY LINE — a line
- *     matching a KNOWN adl key (`minimal_overhead`, ..., `mode`) is adl's
- *     own, replaced by the canonical value regardless of what it used to
- *     say; a blank line is dropped (formatting only); anything else —
- *     an unrecognized key, a table header, OR A COMMENT (finding 4-minor,
- *     independent review 2026-09-30, superseding this bullet's original
- *     "comments are dropped too" — see `migrateByKnownKeys`'s own doc
- *     comment for why) — is the user's, kept verbatim, in place, after
- *     the canonical block. This never depends on the asset's exact prior
- *     text, so a template change cannot break migration again.
- *  5. MED — two blind spots: a quoted duplicate key AFTER the block, and
- *     a user table header BEFORE it (which silently turns adl's own keys
- *     into `<table>.<key>`), both passed as "unchanged" under pure
- *     text/region matching. DECISION: after composing (never
- *     re-serializing — this validates the ACTUAL COMPOSED TEXT, whether
- *     that text turned out unchanged, self-healed, or migrated), the
- *     WHOLE file is parsed with a real TOML parser (`Bun.TOML`, not
- *     `@iarna/toml` — TOML 0.5, rejects valid TOML 1.0) and every adl key
- *     must resolve AT THE TOP LEVEL to adl's own value; any parse
- *     failure or mismatch is a conflict, never a silent "unchanged".
- *     Independent review, 2026-09-30, finding 5-rest: this validation is
- *     only as good as `scalarValuesOf`'s own coverage — a version that
- *     recognized only `true`/`false` left layout.toml's own `mode = "xdg"`
- *     (a string) OUT of `expectedScalars` entirely, so a table header
- *     before ITS block passed silently. `scalarValuesOf` now parses every
- *     scalar shape a managed block can carry (bool, number, quoted
- *     string, simple string array), closing that gap for every target,
- *     not just config.toml's boolean keys.
- *
- * Marker-region mechanics (BEGIN/END, malformed markers, migration) are
- * shared by every target — config.toml's scalar keys, layout.toml's
- * whole content, and (with an append-not-migrate variant — see finding 6,
- * `resolveGitignoreWrite`) the `.agents/.gitignore` block. config.toml
- * additionally carries the union-key array outside its own block
- * (`resolveConfigTomlWrite`).
- */
-
-export const LEAN_CTX_MARKER_START = '# >>> adl managed (do not edit within this block) >>>';
-export const LEAN_CTX_MARKER_END = '# <<< adl managed <<<';
-export const SHELL_ALLOWLIST_KEY = 'shell_allowlist_extra';
-
-interface Region {
-  readonly start: number;
-  /** Exclusive — the index immediately after the closing marker's own text. */
-  readonly end: number;
-}
-type RegionResult = Region | 'missing' | 'malformed';
-
-function findRegion(content: string): RegionResult {
-  const start = content.indexOf(LEAN_CTX_MARKER_START);
-  const stop = content.indexOf(LEAN_CTX_MARKER_END);
-  if (start < 0 && stop < 0) return 'missing';
-  if (start < 0 || stop < 0 || stop < start) return 'malformed';
-  return { start, end: stop + LEAN_CTX_MARKER_END.length };
-}
-
-/** The block's own content between (and including) its markers, no trailing newline. */
-function canonicalBlockOf(assetText: string): string {
-  return assetText.replace(/\n+$/, '');
-}
-
-function spliceRegion(content: string, region: Region, canonicalBlock: string): string {
-  return `${content.slice(0, region.start)}${canonicalBlock}${content.slice(region.end)}`;
-}
-
-/** `key = ...` names declared directly inside `canonicalBlock` — a plain line scan, not a TOML parse (this module never parses to decide what to write; only to VALIDATE the result — see `validateComposedToml`). */
-function declaredKeyNames(canonicalBlock: string): readonly string[] {
-  const names: string[] = [];
-  for (const line of canonicalBlock.split('\n')) {
-    const match = /^([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line);
-    if (match) names.push(match[1] as string);
-  }
-  return names;
-}
-
-function duplicateKeyOutsideRegion(content: string, region: Region, canonicalBlock: string): string | undefined {
-  const outside = content.slice(0, region.start) + content.slice(region.end);
-  for (const name of declaredKeyNames(canonicalBlock)) {
-    if (new RegExp(`^\\s*${name}\\s*=`, 'm').test(outside)) return name;
-  }
-  return undefined;
-}
-
-/**
- * Migration (finding 4): classifies a markerless file the lock already
- * says adl wrote, line by line, against `knownKeys` for THIS target.
- * Never depends on the asset's own exact prior text — a `key = value`
- * line naming a known key is adl's own (dropped; the canonical block
- * replaces it outright, whatever it used to say); a blank line is
- * dropped (formatting only); anything else — including a full-line
- * comment — is kept verbatim, IN ORDER, as the user's.
- *
- * A comment is deliberately NOT dropped (independent review, 2026-09-30,
- * finding 4-minor — this superseded an earlier version that dropped
- * every comment line as "adl's own old commentary, not reliably told
- * apart from a user's by text alone"): dropping a genuine user comment
- * is permanent, silent data loss; keeping an old adl comment as harmless
- * extra text next to the canonical block (which carries its own fresh
- * comments regardless) costs nothing. When in doubt, keep it — the same
- * rule this module already applies to every OTHER unrecognized line.
- *
- * `recognizedCount` is how many lines matched a known key — the signal
- * that decides whether migration is safe AT ALL (`resolveLeanCtxWrite`'s
- * own caller): a file with at least one recognizable adl key is
- * plausibly adl's own prior content, whatever else is wrong with it; a
- * file with NONE (a whole-file clobber — `"tampered\n"`, Tarun 2026-09-29,
- * D.b: this exact scenario is a conflict, not a guess) has no evidence
- * left to migrate from at all.
- */
-function migrateByKnownKeys(content: string, knownKeys: ReadonlySet<string>): { readonly kept: readonly string[]; readonly recognizedCount: number } {
-  const kept: string[] = [];
-  let recognizedCount = 0;
-  for (const line of content.split('\n')) {
-    const trimmed = line.trim();
-    if (trimmed.length === 0) continue;
-    const match = /^([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(trimmed);
-    if (match && knownKeys.has(match[1] as string)) {
-      recognizedCount += 1;
-      continue;
-    }
-    kept.push(line);
-  }
-  return { kept, recognizedCount };
-}
-
-/** One adl-owned scalar whose value differed and was restored to adl's own (2026-09-30, Tarun's merge-contract correction: "adl-owned entries SELF-HEAL" — a differing value is drift, never a conflict). Named on the write outcome so deploy/doctor can report it explicitly, the same way a healed hook is named. */
-export interface RestoredScalar {
-  readonly key: string;
-  readonly value: unknown;
-  readonly previous: unknown;
-}
-
-export type LeanCtxWriteOutcome =
-  | { readonly action: 'unchanged' }
-  | { readonly action: 'write'; readonly text: string; readonly restoredScalars?: readonly RestoredScalar[] }
-  | { readonly action: 'conflict'; readonly reason: string };
-
-/** Real TOML 1.0 parse (Bun's built-in, not `@iarna/toml` — TOML 0.5) — read-only validation, never used to decide what to write. */
-function parseToml(text: string): Record<string, unknown> | 'invalid' {
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Bun global, no @types/bun in this package's own deps
-    const doc = (globalThis as any).Bun.TOML.parse(text);
-    return typeof doc === 'object' && doc !== null && !Array.isArray(doc) ? (doc as Record<string, unknown>) : 'invalid';
-  } catch {
-    return 'invalid';
-  }
-}
-
-/** True iff `actual` matches `expected`, where `expected` may be a scalar (compared by `===`) or an array (compared element-by-element, same length and order). */
-function tomlValueMatches(actual: unknown, expected: unknown): boolean {
-  if (Array.isArray(expected)) {
-    return Array.isArray(actual) && actual.length === expected.length && expected.every((entry, i) => actual[i] === entry);
-  }
-  return actual === expected;
-}
-
-/**
- * Finding 5's safety net: parses the COMPOSED text (whatever this module
- * is about to call "unchanged" or "write") and confirms every one of
- * `expectedScalars` resolves at the TOP LEVEL to its expected value, and
- * (when `expectedArrayEntries` is given) `arrayKey` resolves to an array
- * containing every one of them. A duplicate key elsewhere in the file, or
- * a table header before the managed block turning adl's own keys into
- * `<table>.<key>`, fails this — a conflict, never a silent pass.
- */
-function validateComposedToml(
-  text: string,
-  expectedScalars: Readonly<Record<string, unknown>>,
-  arrayKey?: string,
-  expectedArrayEntries?: readonly string[],
-): string | undefined {
-  const doc = parseToml(text);
-  if (doc === 'invalid') return 'the composed file is not valid TOML';
-  for (const [key, value] of Object.entries(expectedScalars)) {
-    if (!tomlValueMatches(doc[key], value)) return `"${key}" does not resolve to adl's value at the top level (a table header before the managed block, or a duplicate key, is shadowing it)`;
-  }
-  if (arrayKey !== undefined && expectedArrayEntries !== undefined) {
-    const actual = doc[arrayKey];
-    if (!Array.isArray(actual)) return `"${arrayKey}" does not resolve to an array at the top level`;
-    const missing = expectedArrayEntries.filter((entry) => !actual.includes(entry));
-    if (missing.length > 0) return `"${arrayKey}" is missing adl-required entries: ${missing.join(', ')}`;
-  }
-  return undefined;
-}
-
-/**
- * Parses a single-line TOML scalar value — bool, integer/float, quoted
- * string, or a simple (string-literals-only) inline array — or returns
- * `undefined` for anything else (a multi-line value, a table, etc.),
- * which `scalarValuesOf` then simply skips rather than guessing.
- */
-function parseTomlScalarValue(raw: string): unknown {
-  const trimmed = raw.trim();
-  if (trimmed === 'true') return true;
-  if (trimmed === 'false') return false;
-  if (/^-?\d+(\.\d+)?$/.test(trimmed)) return Number(trimmed);
-  const stringMatch = /^"((?:[^"\\]|\\.)*)"$/.exec(trimmed);
-  if (stringMatch) return (stringMatch[1] as string).replace(/\\(.)/g, '$1');
-  const arrayMatch = /^\[(.*)\]$/.exec(trimmed);
-  if (arrayMatch) {
-    const entries = parseSimpleStringArrayBody(arrayMatch[1] as string);
-    if (entries !== 'malformed') return entries;
-  }
-  return undefined;
-}
-
-/**
- * Every `key = value` line's value, parsed generically (finding 5-rest,
- * independent review 2026-09-30 — this used to recognize `true`/`false`
- * only, so a STRING-valued key like layout.toml's own `mode = "xdg"` was
- * silently excluded from `validateComposedToml`'s `expectedScalars`
- * entirely, leaving that target's own table-header-before-block blind
- * spot uncaught; see this file's header for the full history). A value
- * this module cannot parse (a multi-line construct) is simply skipped,
- * never guessed at.
- */
-function scalarValuesOf(canonicalBlock: string): Record<string, unknown> {
-  const values: Record<string, unknown> = {};
-  for (const line of canonicalBlock.split('\n')) {
-    const match = /^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.+)$/.exec(line.trim());
-    if (!match) continue;
-    const value = parseTomlScalarValue(match[2] as string);
-    if (value !== undefined) values[match[1] as string] = value;
-  }
-  return values;
-}
-
-/**
- * Marker-region-only target (layout.toml): the whole file's meaningful
- * content is inside the block. Callers only reach this once
- * `currentText !== assetText` — an exact match is always `unchanged`.
- */
-export function resolveLeanCtxWrite(assetText: string, currentText: string, wasWrittenByUs: boolean): LeanCtxWriteOutcome {
-  const canonicalBlock = canonicalBlockOf(assetText);
-  const region = findRegion(currentText);
-
-  if (region === 'malformed') {
-    return { action: 'conflict', reason: 'managed block markers are malformed (BEGIN/END unpaired or out of order); left untouched' };
-  }
-
-  if (region === 'missing') {
-    if (!wasWrittenByUs) {
-      return { action: 'conflict', reason: 'no adl-managed block found in this file, and it is not recorded as adl-written; left untouched' };
-    }
-    const knownKeys = new Set(declaredKeyNames(canonicalBlock));
-    const { kept, recognizedCount } = migrateByKnownKeys(currentText, knownKeys);
-    if (recognizedCount === 0) {
-      return { action: 'conflict', reason: 'no recognizable adl-owned content found to migrate; left untouched' };
-    }
-    const composed = kept.length > 0 ? `${canonicalBlock}\n\n${kept.join('\n').replace(/\n+$/, '')}\n` : `${canonicalBlock}\n`;
-    const invalid = validateComposedToml(composed, scalarValuesOf(canonicalBlock));
-    if (invalid !== undefined) return { action: 'conflict', reason: `cannot migrate safely: ${invalid}` };
-    return { action: 'write', text: composed };
-  }
-
-  const duplicate = duplicateKeyOutsideRegion(currentText, region, canonicalBlock);
-  if (duplicate !== undefined) {
-    return { action: 'conflict', reason: `"${duplicate}" is declared both inside and outside the adl-managed block; left untouched` };
-  }
-
-  const installed = currentText.slice(region.start, region.end);
-  const composed = installed === canonicalBlock ? currentText : spliceRegion(currentText, region, canonicalBlock);
-  const invalid = validateComposedToml(composed, scalarValuesOf(canonicalBlock));
-  if (invalid !== undefined) return { action: 'conflict', reason: invalid };
-  return installed === canonicalBlock ? { action: 'unchanged' } : { action: 'write', text: composed };
-}
-
-/** A simple (string-literals-only) array's parsed entries, or 'malformed' if it contains anything else (a number, a nested array, a bare identifier). */
-function parseSimpleStringArrayBody(body: string): readonly string[] | 'malformed' {
-  const trimmed = body.trim();
-  if (trimmed.length === 0) return [];
-  const entries: string[] = [];
-  for (const piece of trimmed.split(',').map((p) => p.trim())) {
-    if (piece.length === 0) continue;
-    const match = /^"((?:[^"\\]|\\.)*)"$/.exec(piece);
-    if (!match) return 'malformed';
-    entries.push(match[1] as string);
-  }
-  return entries;
-}
-
-interface ArraySpan {
-  readonly start: number;
-  readonly end: number;
-  readonly body: string;
-}
-function findArray(text: string, key: string): ArraySpan | 'missing' | 'malformed' {
-  const startMatch = new RegExp(`^${key}\\s*=\\s*\\[`, 'm').exec(text);
-  if (!startMatch) return 'missing';
-  const openBracket = startMatch.index + startMatch[0].length - 1;
-  const closeBracket = text.indexOf(']', openBracket);
-  if (closeBracket === -1) return 'malformed';
-  const body = text.slice(openBracket + 1, closeBracket);
-  if (body.includes('[')) return 'malformed'; // a nested array -- not "a simple string array"
-  return { start: startMatch.index, end: closeBracket + 1, body };
-}
-
-/** Text-splices `missingEntries` into an existing simple array's body, right before its closing `]`, never touching what is already there. */
-function insertMissingEntries(text: string, array: ArraySpan, missingEntries: readonly string[]): string {
-  const closeBracketIndex = array.end - 1; // position of ']'
-  const bodyTrimmedEnd = text.slice(array.start, closeBracketIndex).replace(/\s+$/, '');
-  const needsLeadingComma = /[^\s[]$/.test(bodyTrimmedEnd) && !bodyTrimmedEnd.endsWith(',');
-  const insertion = `${needsLeadingComma ? ',' : ''}\n${missingEntries.map((e) => `    "${e}",`).join('\n')}\n`;
-  return `${text.slice(0, closeBracketIndex)}${insertion}${text.slice(closeBracketIndex)}`;
-}
-
-/**
- * The portion of `text` that TOML grammar guarantees is ALL bare
- * (top-level) key/value pairs — everything up to (not including) the
- * first `[table]` or `[[array-of-tables]]` header. A key/value LINE
- * found inside this prefix is unambiguously top-level; the same key name
- * appearing after a table header belongs to that table instead
- * (`table.key`, a completely different key), which a pure line/regex
- * scan cannot tell apart from a top-level line on its own — this keeps
- * that distinction correct without needing to track table context.
- */
-function topLevelPrefixEnd(text: string): number {
-  const match = /^\[/m.exec(text);
-  return match ? match.index : text.length;
-}
-
-/**
- * Removes the (top-level-only, see `topLevelPrefixEnd`) `key = value`
- * line for each key in `keys` from `text` — used for every adl-owned
- * scalar key the current file ALREADY declares at the top level, whether
- * its value matches adl's canonical one or not: the FULL canonical block
- * (always inserted whole, never partial — every other reader of this
- * module assumes the managed block IS the complete canonical text) is
- * about to declare it again, and TOML forbids a duplicate top-level key
- * regardless of whether the two values agree. This is not "deleting a
- * user's line" in the sense the merge decision forbids — a matching
- * value is unchanged and un-lost, merely consolidated into the block
- * exactly where an ordinary deploy would have put it; a DIFFERING value
- * is adl-owned drift, and adl's own merge contract ("adl-owned entries
- * SELF-HEAL") already says adl's value wins — the caller names the
- * restore (`RestoredScalar`) so it is never silent.
- */
-function removeTopLevelScalarLines(text: string, keys: ReadonlySet<string>): string {
-  if (keys.size === 0) return text;
-  const prefixEnd = topLevelPrefixEnd(text);
-  const prefix = text.slice(0, prefixEnd);
-  const rest = text.slice(prefixEnd);
-  const keptPrefixLines = prefix.split('\n').filter((line) => {
-    const match = /^([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line.trim());
-    return match === null || !keys.has(match[1] as string);
-  });
-  return `${keptPrefixLines.join('\n')}${rest}`;
-}
-
-/**
- * config.toml specifically (finding 3 + 4 + 5, and MERGED entirely,
- * Tarun 2026-09-30 — see this function's own migration branch, below,
- * and the describe block in lean-ctx-merge-contract.test.ts headed
- * "config.toml's allow list is MERGED entry-by-entry" for the full
- * decision): its own scalar keys live in the marker-region block exactly
- * like `resolveLeanCtxWrite`, but `shell_allowlist_extra` lives OUTSIDE
- * the markers as a UNION key — located anywhere in the file by a narrow
- * text scan, adl's required entries inserted before `]` if missing,
- * nothing ever removed/reordered. A non-simple array (anything but
- * string literals) is a conflict.
- */
-export function resolveConfigTomlWrite(assetText: string, currentText: string, wasWrittenByUs: boolean): LeanCtxWriteOutcome {
-  const assetArray = findArray(assetText, SHELL_ALLOWLIST_KEY);
-  if (assetArray === 'missing' || assetArray === 'malformed') {
-    throw new Error(`agent-settings lean-ctx config.toml asset itself has no valid "${SHELL_ALLOWLIST_KEY}" array — this is a packaging bug, not a target-repo conflict`);
-  }
-  const requiredEntries = parseSimpleStringArrayBody(assetArray.body);
-  if (requiredEntries === 'malformed') {
-    throw new Error(`agent-settings lean-ctx config.toml asset's own "${SHELL_ALLOWLIST_KEY}" array is not a simple string array — this is a packaging bug, not a target-repo conflict`);
-  }
-  const canonicalBlock = canonicalBlockOf(assetText.slice(0, assetArray.start));
-  const scalarValues = scalarValuesOf(canonicalBlock);
-
-  let working = currentText;
-  const region = findRegion(working);
-  if (region === 'malformed') return { action: 'conflict', reason: 'managed block markers are malformed (BEGIN/END unpaired or out of order); left untouched' };
-
-  if (region === 'missing') {
-    if (!wasWrittenByUs) return { action: 'conflict', reason: 'no adl-managed block found in this file, and it is not recorded as adl-written; left untouched' };
-
-    // Tarun, 2026-09-30 (corrected the same day — Tarun's merge contract
-    // is "adl-owned entries SELF-HEAL; user additions are kept"): "Merge
-    // the allow list in config.toml, the standard allow list must be
-    // checked entry by entry, missing should be added, user entries must
-    // not be removed." A markerless file is a MERGE target whenever it
-    // is valid TOML at all — even a WHOLE-FILE overwrite with the user's
-    // own unrelated content — never a conflict. An adl-owned scalar
-    // already present at the top level ALWAYS self-heals to adl's own
-    // value (an older asset default, or a user edit, is drift, not a
-    // conflict — otherwise every already-enrolled repo carrying an older
-    // adl default would conflict on upgrade); the restore is named
-    // (`restoredScalars`, below) so it is never silent. Conflict remains
-    // ONLY where merging is genuinely unsafe: invalid TOML (nowhere to
-    // safely place a block), or an allow-list value that isn't a simple
-    // string array. Nothing of the user's is ever deleted or reordered.
-    const parsedCurrent = parseToml(currentText);
-    if (parsedCurrent === 'invalid') {
-      return { action: 'conflict', reason: 'current file is not valid TOML; cannot place the managed block safely' };
-    }
-    if (Object.prototype.hasOwnProperty.call(parsedCurrent, SHELL_ALLOWLIST_KEY) && !Array.isArray(parsedCurrent[SHELL_ALLOWLIST_KEY])) {
-      return { action: 'conflict', reason: `"${SHELL_ALLOWLIST_KEY}" is not a simple string array; cannot merge safely` };
-    }
-
-    // Every adl-owned scalar key the current file ALREADY declares at
-    // the top level — matching value or not — is removed from its
-    // original line: the FULL canonical block (always inserted whole; a
-    // "partial" block would make the managed-region invariant every
-    // other code path relies on unstable across repeated runs) is about
-    // to declare it again, and TOML forbids a duplicate top-level key
-    // regardless of whether the two values agree. A DIFFERING value is
-    // named in `restoredScalars` — adl's own value always wins.
-    const presentKeys = new Set(Object.keys(scalarValues).filter((key) => Object.prototype.hasOwnProperty.call(parsedCurrent, key)));
-    const restoredScalars: RestoredScalar[] = [...presentKeys]
-      .filter((key) => !tomlValueMatches(parsedCurrent[key], scalarValues[key]))
-      .map((key) => ({ key, value: scalarValues[key], previous: parsedCurrent[key] }));
-    const restOfFile = removeTopLevelScalarLines(currentText, presentKeys).replace(/^\n+/, '');
-
-    // Insert AT THE TOP, before any table header — always syntactically
-    // safe for valid TOML (bare key/value pairs may appear anywhere
-    // before the first table), and scalar collisions are already ruled
-    // out above.
-    let composed = restOfFile.length > 0 ? `${canonicalBlock}\n\n${restOfFile}` : `${canonicalBlock}\n`;
-
-    const arraySpan = findArray(composed, SHELL_ALLOWLIST_KEY);
-    if (arraySpan === 'malformed') {
-      return { action: 'conflict', reason: `"${SHELL_ALLOWLIST_KEY}" is not a simple string array; cannot merge safely` };
-    }
-    if (arraySpan === 'missing') {
-      // The user has no such array at all -- create it, with just the
-      // standard entries, right after the inserted block.
-      const arrayText = `${SHELL_ALLOWLIST_KEY} = [\n${requiredEntries.map((e) => `    "${e}",`).join('\n')}\n]\n`;
-      composed = `${canonicalBlock}\n${arrayText}\n${restOfFile}`;
-    } else {
-      const currentEntries = parseSimpleStringArrayBody(arraySpan.body);
-      if (currentEntries === 'malformed') {
-        return { action: 'conflict', reason: `"${SHELL_ALLOWLIST_KEY}" is not a simple string array; cannot merge safely` };
-      }
-      // Entry by entry: only the STANDARD entries missing from the
-      // user's OWN array are appended, at the end, byte-for-byte -- the
-      // user's own entries, and their order, are never touched.
-      const missingEntries = requiredEntries.filter((entry) => !currentEntries.includes(entry));
-      if (missingEntries.length > 0) composed = insertMissingEntries(composed, arraySpan, missingEntries);
-    }
-
-    const invalid = validateComposedToml(composed, scalarValues, SHELL_ALLOWLIST_KEY, requiredEntries);
-    if (invalid !== undefined) return { action: 'conflict', reason: `cannot merge safely: ${invalid}` };
-    return restoredScalars.length > 0 ? { action: 'write', text: composed, restoredScalars } : { action: 'write', text: composed };
-  }
-
-  const duplicate = duplicateKeyOutsideRegion(working, region, canonicalBlock);
-  if (duplicate !== undefined) return { action: 'conflict', reason: `"${duplicate}" is declared both inside and outside the adl-managed block; left untouched` };
-
-  const installedBlock = working.slice(region.start, region.end);
-  if (installedBlock !== canonicalBlock) working = spliceRegion(working, region, canonicalBlock);
-
-  // Step 2: the union array, resolved fresh against the (possibly just-healed) text.
-  const currentArray = findArray(working, SHELL_ALLOWLIST_KEY);
-  if (currentArray === 'missing') return { action: 'conflict', reason: `expected "${SHELL_ALLOWLIST_KEY}" array not found` };
-  if (currentArray === 'malformed') return { action: 'conflict', reason: `"${SHELL_ALLOWLIST_KEY}" is not a simple string array (contains something other than string literals)` };
-  const currentEntries = parseSimpleStringArrayBody(currentArray.body);
-  if (currentEntries === 'malformed') return { action: 'conflict', reason: `"${SHELL_ALLOWLIST_KEY}" is not a simple string array (contains something other than string literals)` };
-  const missing = requiredEntries.filter((entry) => !currentEntries.includes(entry));
-  if (missing.length > 0) working = insertMissingEntries(working, currentArray, missing);
-
-  if (working === currentText) {
-    const invalid = validateComposedToml(working, scalarValues, SHELL_ALLOWLIST_KEY, requiredEntries);
-    if (invalid !== undefined) return { action: 'conflict', reason: invalid };
-    return { action: 'unchanged' };
-  }
-  const invalid = validateComposedToml(working, scalarValues, SHELL_ALLOWLIST_KEY, requiredEntries);
-  if (invalid !== undefined) return { action: 'conflict', reason: invalid };
-  return { action: 'write', text: working };
-}
-
-/** The block's own ignore-pattern lines (no markers, no comments) — what "already present" is checked against: a negation of one of these BEFORE an existing block is a conflict (round 5), and a bare duplicate of one of these OUTSIDE an existing block is ambiguous and stays a conflict too. Round 5 (Tarun, 2026-09-30) stopped using this to DROP lines during migration — see `resolveGitignoreWrite`'s own header for why. */
-function gitignorePatternLines(canonicalBlock: string): readonly string[] {
-  return canonicalBlock
-    .split('\n')
-    .map((l) => l.trim())
-    .filter((l) => l.length > 0 && l !== LEAN_CTX_MARKER_START && l !== LEAN_CTX_MARKER_END && !l.startsWith('#'));
-}
-
-/**
- * `.agents/.gitignore` (finding 6, REDECIDED 2026-09-30 — a real repro
- * showed the round-3 fix never actually ran: `lean-ctx-deploy.ts`'s own
- * top-level `exists && !managedByUs` guard short-circuited to a hard
- * conflict before this function was even called, and this function's
- * OWN `!wasWrittenByUs` check would have refused it too). A markerless
- * `.gitignore` is no longer a hard conflict EITHER WAY — written by adl
- * before, or a plain user file that has simply never been touched.
- *
- * ROUND 5 (fourth independent review, same day) found the FIRST fix's
- * own ordering bug: it deleted any existing line that happened to match
- * one of adl's own patterns, then appended the canonical block at the
- * END. A user's `*.bak` (redundant with adl's own pattern) followed by
- * their OWN deliberate `!keep.bak` override got the `*.bak` line
- * deleted, and adl's later copy of it (inside the appended block) then
- * silently outranked `!keep.bak` — gitignore's last-match-wins rule
- * turned the user's override backwards.
- *
- * DECISION (Tarun, 2026-09-30): never delete or reorder a user's own
- * line, full stop — not even one that looks exactly like adl's own
- * pattern (the cosmetic cost of a harmless duplicate line is strictly
- * better than ever risking a real one). For a markerless file, the
- * canonical block is PREPENDED instead of appended: every existing line
- * (all of them, unmodified, in their original order) then comes AFTER
- * the block and keeps winning, including any negation — exactly
- * gitignore's own "last match wins" semantics, by construction, with no
- * special-casing needed for negations in this branch at all (a
- * pre-existing negation is now IMPOSSIBLE to place before the block,
- * since the block is always first).
- *
- * For an EXISTING marked file, the block never moves from wherever it
- * already sits — but a NEW negation added BEFORE it (which the block's
- * own later copy of that pattern would silently override) is its own
- * conflict, reported rather than silently accepted. A negation added
- * AFTER the block already wins correctly and is not a conflict.
- *
- * The "bare duplicate outside the block" check (below) is scoped to
- * BEFORE the block only — found while verifying this very fix against
- * this repo's own REAL data, not asked for by name: a markerless
- * migration keeps every existing line, including ones that happen to be
- * adl's own canonical patterns (this repo's own actual pre-marker
- * `.agents/.gitignore` is exactly that shape), and those necessarily end
- * up AFTER the newly-prepended block. A duplicate AFTER the block is
- * provably inert (gitignore's last-match-wins rule makes a trailing
- * repeat of the same pattern a no-op), so checking it unscoped turned
- * every such migration into a conflict on EVERY subsequent deploy
- * forever. A duplicate BEFORE the block is the one that still matters:
- * it is exactly the negation risk above, generalized to a bare
- * (non-negated) repeat that could still be reordered or edited later in
- * a way the block's own later copy would silently shadow.
- */
-export function resolveGitignoreWrite(assetText: string, currentText: string, _wasWrittenByUs: boolean): LeanCtxWriteOutcome {
-  const canonicalBlock = canonicalBlockOf(assetText);
-  const region = findRegion(currentText);
-  if (region === 'malformed') return { action: 'conflict', reason: 'managed block markers are malformed (BEGIN/END unpaired or out of order); left untouched' };
-
-  const patternLines = new Set(gitignorePatternLines(canonicalBlock));
-
-  if (region === 'missing') {
-    const trimmed = currentText.replace(/\n+$/, '');
-    return { action: 'write', text: trimmed.length > 0 ? `${canonicalBlock}\n\n${trimmed}\n` : `${canonicalBlock}\n` };
-  }
-
-  const beforeLines = new Set(
-    currentText
-      .slice(0, region.start)
-      .split('\n')
-      .map((l) => l.trim()),
-  );
-  for (const pattern of patternLines) {
-    if (beforeLines.has(`!${pattern}`)) {
-      return { action: 'conflict', reason: `"!${pattern}" appears before the managed block and would be silently overridden by the block's own later "${pattern}"; left untouched` };
-    }
-    if (beforeLines.has(pattern)) {
-      return { action: 'conflict', reason: `"${pattern}" already appears before the managed block; left untouched` };
-    }
-  }
-
-  const installed = currentText.slice(region.start, region.end);
-  if (installed === canonicalBlock) return { action: 'unchanged' };
-  return { action: 'write', text: spliceRegion(currentText, region, canonicalBlock) };
-}

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

@@ -1,38 +0,0 @@
----
-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>`.