@event4u/agent-config 9.8.0 → 9.9.0

package/src/scripts/memory_status.ts

@@ -176,7 +176,13 @@ export function main(): number {
     return 0;
 }
 
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
 function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
     if (process.argv[1] === undefined) {
         return false;
     }

package/src/scripts/minimal_safe_diff_hook.ts

@@ -36,6 +36,7 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { atomic_write_json } from "./hooks/state_io.js";
+import { readHookStdin } from "./hooks/hook_stdin.js";
 
 // NOTE: the Python docstring says `agents/runtime/state/`, but the code
 // constant is `agents/state/`. Replicated verbatim — latent docstring/code
@@ -335,11 +336,7 @@ function parse_args(argv: string[]): ParsedArgs {
 }
 
 function _readStdin(): string {
-  try {
-    return fs.readFileSync(0, "utf-8");
-  } catch {
-    return "";
-  }
+  return readHookStdin();
 }
 
 export function main(argv?: string[]): number {
@@ -347,7 +344,13 @@ export function main(argv?: string[]): number {
   return run(_readStdin(), { consumer_root: process.cwd(), verbose: args.verbose });
 }
 
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
 function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
     if (process.argv[1] === undefined) {
         return false;
     }

package/src/scripts/onboarding_gate_hook.ts

@@ -36,6 +36,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 // `agents/runtime/state/.dispatcher.lock` discipline (hook-architecture-v1.md
 // § Concurrency, Phase 7.4).
 import { atomic_write_json } from "./hooks/state_io.js";
+import { readHookStdin } from "./hooks/hook_stdin.js";
 
 export const SETTINGS_FILE = ".agent-settings.yml";
 // NOTE: the Python docstring says `agents/runtime/state/`, but the code
@@ -201,11 +202,7 @@ function parse_args(argv: string[]): ParsedArgs {
 }
 
 function _readStdin(): void {
-  try {
-    fs.readFileSync(0, "utf-8");
-  } catch {
-    /* ignore */
-  }
+  readHookStdin();
 }
 
 export function main(argv?: string[]): number {
@@ -216,7 +213,13 @@ export function main(argv?: string[]): number {
   return run({ consumer_root: process.cwd(), verbose: args.verbose });
 }
 
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
 function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
     if (process.argv[1] === undefined) {
         return false;
     }

package/src/scripts/orchestration_record.ts

@@ -12,6 +12,10 @@
  *     --tier-chosen lite --tier-source inferred --task-class read-only-fanout \
  *     [--tiers sonnet,opus] [--agent-combo implementer,judge] [--wall-clock-ms 18500] [--dispatch-outcome DONE] \
  *     [--first-pass-success true|false] [--escalated true|false] \
+ *     [--init-tokens 1200] [--payload-hash <hex8-64>] [--lookup-class definition|references|string-existence|report-run] \
+ *     [--route-taken primitive|subagent] [--budget-hit true|false] [--correctness-match true|false] \
+ *     [--cache-hit true|false] [--origin lean-init-2026] \
+ *     [--rules-carried 32] [--rules-used 5] \
  *     [--dir <audit-dir>] [--dry-run]
  *
  * Read by `src/scripts/orchestration_savings_report.ts`.
@@ -22,6 +26,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { pathToFileURL } from 'node:url';
 
+import type { LookupClass } from './_lib/auto_dispatch.js';
 import {
     buildOrchestrationLine,
     type Provenance,
@@ -33,6 +38,7 @@ import {
     type LinePhase,
     type LineOutcome,
     type RecordInput,
+    type RouteTaken,
 } from './_lib/orchestration_record.js';
 
 const DEFAULT_DIR = 'agents/runtime/state/audit';
@@ -122,6 +128,16 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         verify_mode: str(flags, 'verify-mode') as VerifyMode | undefined,
         first_pass_success: bool(flags, 'first-pass-success'),
         escalated: bool(flags, 'escalated'),
+        init_tokens: int(flags, 'init-tokens'),
+        payload_hash: str(flags, 'payload-hash'),
+        lookup_class: str(flags, 'lookup-class') as LookupClass | undefined,
+        route_taken: str(flags, 'route-taken') as RouteTaken | undefined,
+        budget_hit: bool(flags, 'budget-hit'),
+        correctness_match: bool(flags, 'correctness-match'),
+        cache_hit: bool(flags, 'cache-hit'),
+        origin: str(flags, 'origin'),
+        rules_carried: int(flags, 'rules-carried'),
+        rules_used: int(flags, 'rules-used'),
         phase: str(flags, 'phase') as LinePhase | undefined,
         outcome: str(flags, 'outcome') as LineOutcome | undefined,
         confidence_band: str(flags, 'confidence-band') as Band | undefined,

package/src/scripts/pr_url_reminder_hook.ts

@@ -28,6 +28,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { readHookStdin } from "./hooks/hook_stdin.js";
 
 const EXIT_ALLOW = 0;
 const EXIT_WARN = 2;
@@ -150,10 +151,16 @@ export function main(): number {
 }
 
 function _readStdin(): string {
-  return fs.readFileSync(0, "utf-8");
+  return readHookStdin();
 }
 
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
 function _isCliEntry(): boolean {
+  if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+    return false;
+  }
   if (process.argv[1] === undefined) {
     return false;
   }

package/src/scripts/prepack-check.mjs

@@ -159,6 +159,23 @@ process.stderr.write(
     `prepack-check: import-completeness OK (${scanRoots.length} shipped src tree(s) scanned)\n`,
 );
 
+// ---------------------------------------------------------------------------
+// Lifecycle-target guard (gate 3): every consumer-side lifecycle script
+// (preinstall/install/postinstall/prepare) must reference only targets that
+// exist and ship. Structural fix for the 9.8.0 dead-postinstall class.
+// ---------------------------------------------------------------------------
+import { existsSync } from 'node:fs';
+import { checkLifecycleTargets } from './prepack_lifecycle_check.mjs';
+
+const lifecycleErrors = checkLifecycleTargets(pkg, (p) => existsSync(resolve(p)));
+if (lifecycleErrors.length > 0) {
+    for (const e of lifecycleErrors) {
+        process.stderr.write(`prepack-check: ${e}\n`);
+    }
+    die(`${lifecycleErrors.length} lifecycle script target(s) missing or unshipped.`);
+}
+process.stderr.write('prepack-check: lifecycle script targets OK\n');
+
 // Optional: invoked with --verbose dumps the size for tarball-budget bookkeeping.
 if (argv.includes('--verbose')) {
     process.stderr.write(`prepack-check: size=${st.size} bytes\n`);

package/src/scripts/prepack_lifecycle_check.d.mts

@@ -0,0 +1,8 @@
+/** Type declarations for prepack_lifecycle_check.mjs (plain-JS prepack gate). */
+export declare const CONSUMER_LIFECYCLE_SCRIPTS: string[];
+export declare function extractScriptTargets(command: string): string[];
+export declare function isShippedPath(relPath: string, files: string[]): boolean;
+export declare function checkLifecycleTargets(
+    pkg: { scripts?: Record<string, string>; files?: string[] },
+    existsFn: (relPath: string) => boolean,
+): string[];

package/src/scripts/prepack_lifecycle_check.mjs

@@ -0,0 +1,82 @@
+/**
+ * prepack_lifecycle_check.mjs — gate 3 of the prepack guard.
+ *
+ * Every `package.json` lifecycle script that runs on the CONSUMER side
+ * (preinstall / install / postinstall / prepare) must only reference file
+ * targets that exist AND are covered by the `files` pack whitelist. This is
+ * the structural fix for the 9.8.0 dead-postinstall class: a hook pointing at
+ * `dist/scripts/postinstall_gui.js` that nothing built failed silently on
+ * every install for months because the check was one-time, not standing.
+ *
+ * Pure module (no top-level side effects) so the red/green test can exercise
+ * it with a fabricated package.json — prepack-check.mjs is the CLI caller.
+ */
+
+/** Lifecycle scripts npm executes in a CONSUMER install of the tarball. */
+export const CONSUMER_LIFECYCLE_SCRIPTS = ['preinstall', 'install', 'postinstall', 'prepare'];
+
+/**
+ * Extract file-path targets from a shell command line: arguments following
+ * `node` / `bash` / `sh` interpreters. Flags and shell operators are skipped.
+ */
+export function extractScriptTargets(command) {
+    const targets = [];
+    // Split on shell connectors so each simple command is scanned on its own.
+    for (const segment of command.split(/&&|\|\||;|\|/)) {
+        const tokens = segment.trim().split(/\s+/);
+        for (let i = 0; i < tokens.length - 1; i += 1) {
+            if (!/^(node|bash|sh)$/.test(tokens[i])) continue;
+            for (let j = i + 1; j < tokens.length; j += 1) {
+                const tok = tokens[j];
+                if (tok.startsWith('-')) continue; // interpreter flag
+                // Shell noise (redirections, subshell tokens) ends the scan.
+                if (/[<>()[\]]/.test(tok)) break;
+                targets.push(tok);
+                break;
+            }
+        }
+    }
+    return targets;
+}
+
+/** Whitelist membership — same semantics as prepack-check's isShipped(). */
+export function isShippedPath(relPath, files) {
+    const posix = relPath.split('\\').join('/');
+    const prefixes = files.filter((f) => f.endsWith('/')).map((f) => f.replace(/\/+$/, '') + '/');
+    const exact = new Set(files.filter((f) => !f.endsWith('/')));
+    if (exact.has(posix)) return true;
+    return prefixes.some((p) => posix.startsWith(p));
+}
+
+/**
+ * Check every consumer-side lifecycle script of `pkg`.
+ *
+ * @param pkg parsed package.json ({ scripts, files })
+ * @param existsFn (relPath: string) => boolean — injectable for tests
+ * @returns string[] — human-readable errors; empty = green
+ */
+export function checkLifecycleTargets(pkg, existsFn) {
+    const errors = [];
+    const scripts = pkg.scripts ?? {};
+    const files = pkg.files ?? [];
+    for (const name of CONSUMER_LIFECYCLE_SCRIPTS) {
+        const command = scripts[name];
+        if (typeof command !== 'string' || command.length === 0) continue;
+        for (const target of extractScriptTargets(command)) {
+            if (!existsFn(target)) {
+                errors.push(
+                    `scripts.${name} references '${target}', which does not exist ` +
+                        '(dead lifecycle script — fails silently on every consumer install)',
+                );
+                continue;
+            }
+            if (!isShippedPath(target, files)) {
+                errors.push(
+                    `scripts.${name} references '${target}', which is not covered by the ` +
+                        'package.json `files` whitelist (missing from the published tarball)',
+                );
+            }
+        }
+    }
+    return errors;
+}

package/src/scripts/profile_staleness_hook.ts

@@ -36,6 +36,7 @@ import {
   LOCAL_PROJECT_FILE,
   LOCAL_PROJECT_SUBDIR,
 } from "./_lib/agent_settings.js";
+import { readHookStdin } from "./hooks/hook_stdin.js";
 
 // --- inlined session_profiles.stale_notice slice (unported dep) ----------
 
@@ -118,13 +119,7 @@ function _project_root(): string {
 }
 
 function _readStdinIfNotTty(): void {
-  try {
-    if (!process.stdin.isTTY) {
-      fs.readFileSync(0, "utf-8");
-    }
-  } catch {
-    /* ignore */
-  }
+  readHookStdin();
 }
 
 function _parseRoot(argv: string[]): string | null {
@@ -161,7 +156,13 @@ export function main(argv?: string[]): number {
   return 0;
 }
 
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
 function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
     if (process.argv[1] === undefined) {
         return false;
     }

package/src/scripts/report_install_drift.ts

@@ -0,0 +1,109 @@
+#!/usr/bin/env tsx
+/**
+ * Installer drift report — measures, never gates.
+ *
+ * Compares the sha256 hashes recorded in `agents/installed-tools.lock`
+ * (`kind: 'deployed'` entries) against the current on-disk content of those
+ * same files and reports anything locally modified or deleted since the
+ * last install/upgrade. This is telemetry for the "do consumers edit
+ * framework-authoritative files" premise — it is NEVER a gate. The drift
+ * report itself always exits 0 regardless of what it finds; only a usage
+ * error (unknown flag, missing value) exits non-zero, matching the rest of
+ * this package's CLI scripts.
+ *
+ * `install.ts`'s global-install upgrade path calls the same
+ * `_lib/install_drift.ts` library directly (not this CLI) and always
+ * proceeds with the redeploy regardless of what the report finds.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/report_install_drift
+ *   ./scripts-run src/scripts/report_install_drift --project <path>
+ *   ./scripts-run src/scripts/report_install_drift --format json
+ *
+ * Exit codes: 0 report emitted (clean or drifted) · 2 usage error.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { collect_drift, format_drift_report } from "./_lib/install_drift.js";
+
+interface Options {
+  project: string;
+  format: "text" | "json";
+}
+
+function fail(message: string): never {
+  process.stderr.write(`❌  report_install_drift: ${message}\n`);
+  process.exit(2);
+}
+
+function _parse(argv: string[]): Options {
+  const opts: Options = { project: process.cwd(), format: "text" };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") {
+      process.stdout.write(
+        "usage: report_install_drift [--project <path>] [--format text|json]\n",
+      );
+      process.exit(0);
+    } else if (arg === "--project") {
+      const value = argv[i + 1];
+      if (value === undefined) fail("--project requires a value");
+      opts.project = path.resolve(value);
+      i += 1;
+    } else if (arg === "--format") {
+      const value = argv[i + 1];
+      if (value !== "text" && value !== "json") {
+        fail(`--format must be 'text' or 'json' (got ${JSON.stringify(value ?? null)})`);
+      }
+      opts.format = value;
+      i += 1;
+    } else {
+      fail(`unknown argument: ${arg}`);
+    }
+  }
+  return opts;
+}
+
+/**
+ * Run the report and print it. Always returns 0 — the finding is telemetry,
+ * never a build/CI failure signal.
+ */
+export function main(argv: string[] = process.argv.slice(2)): number {
+  const opts = _parse(argv);
+  const entries = collect_drift(opts.project);
+
+  if (opts.format === "json") {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          project_root: opts.project,
+          manifest_found: entries !== null,
+          drift: entries ?? [],
+        },
+        null,
+        2,
+      )}\n`,
+    );
+  } else {
+    process.stdout.write(format_drift_report(entries));
+  }
+  return 0;
+}
+
+// Main-guard (realpath-compared, mirrors the repo convention).
+if (process.argv[1] !== undefined) {
+  try {
+    const here = fs.realpathSync(fileURLToPath(import.meta.url));
+    const argv1 = fs.realpathSync(path.resolve(process.argv[1]));
+    if (here === argv1) {
+      process.exit(main(process.argv.slice(2)));
+    }
+  } catch {
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+      process.exit(main(process.argv.slice(2)));
+    }
+  }
+}

package/src/scripts/roadmap_progress_hook.ts

@@ -40,6 +40,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { hardenedSpawnEnv } from "./_lib/spawn_env.js";
 import { log_dispatch_issue } from "./hooks/dispatch_issues.js";
+import { readHookStdin } from "./hooks/hook_stdin.js";
 
 export const REPLAY_ENV_VAR = "AGENT_CONFIG_REPLAY";
 
@@ -458,11 +459,7 @@ function parse_args(argv: string[]): ParsedArgs {
 }
 
 function _readStdin(): string {
-  try {
-    return fs.readFileSync(0, "utf-8");
-  } catch {
-    return "";
-  }
+  return readHookStdin();
 }
 
 export function main(argv?: string[]): number {
@@ -471,7 +468,13 @@ export function main(argv?: string[]): number {
   return run(_readStdin(), { consumer_root: root, verbose: args.verbose });
 }
 
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
 function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
     if (process.argv[1] === undefined) {
         return false;
     }

package/src/scripts/schemas/license-policy.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "license-policy.schema.json",
+  "title": "license-policy.yaml — derived borrow-compatibility policy",
+  "description": "Contract for the S1.2 override surface (road-to-provenance-and-license-governance). `policy.{allow,conditional,deny}` are the closed compatibility-matrix source classes; the top-level `deny` array is a flattened, concrete-SPDX-id view of `policy.deny` — it is the shape `src/scripts/lint_provenance.ts`'s `resolveDenyPolicy()` already reads directly, so this file works as its override surface without any change on that side. `derived_from: manual` marks the file as a consumer override the detector must never silently overwrite (loosening any class below the derived verdict is rejected unless this is set). Enforced by the hand-rolled Draft-07 subset validator in validate_frontmatter.ts (`validate()`/`load_schema()`) — keep to its supported keyword set: type, required, properties, additionalProperties, items, minItems, pattern, minLength, maxLength, enum. No oneOf/const/patternProperties.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "derived_from", "detection", "target_class", "workspace_scope", "policy", "deny", "warnings", "derived_at"],
+  "properties": {
+    "schema_version": {
+      "type": "integer",
+      "enum": [1]
+    },
+    "derived_from": {
+      "type": "string",
+      "enum": [
+        "MIT", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause", "ISC", "0BSD",
+        "MPL-2.0", "LGPL-2.1", "LGPL-3.0", "GPL-2.0", "GPL-3.0", "AGPL-3.0",
+        "SSPL-1.0", "Unlicense", "CC0-1.0",
+        "none-detected", "manual"
+      ],
+      "description": "The SPDX id the policy was derived from; 'none-detected' when no license source resolved; 'manual' when a consumer authored this file directly (never auto-overwritten, and the only value allowed to loosen policy below the derived verdict)."
+    },
+    "detection": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "license_sha256"],
+      "properties": {
+        "source": {
+          "type": "string",
+          "enum": ["license-file", "package-json", "composer-json", "none", "manual"]
+        },
+        "license_sha256": {
+          "pattern": "^[a-f0-9]{64}$",
+          "description": "SHA-256 hex digest of the detected LICENSE/LICENSE.md/COPYING file content; null when no such file exists. A later change to that file's content changes this hash, which is the invalidation trigger (re-derive on mismatch, escalate on downgrade)."
+        }
+      }
+    },
+    "target_class": {
+      "type": "string",
+      "enum": ["permissive", "weak-copyleft", "gpl-2.0", "gpl-3.0", "agpl", "none"]
+    },
+    "workspace_scope": {
+      "type": "string",
+      "enum": ["single", "homogeneous-multi"],
+      "description": "'single' when the repo declares no workspaces; 'homogeneous-multi' when workspaces are declared and none diverge from the root SPDX id. A divergent workspace escalates instead of writing this file at all (v1 scope-limiter — full per-workspace derivation is parked, see agents/roadmaps/later/road-to-per-workspace-license-policy.md)."
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["allow", "conditional", "deny"],
+      "description": "The closed compatibility-matrix verdict, keyed by SOURCE license class (not concrete SPDX id) — this is the roadmap S1.2 matrix output. The three arrays repeat the same item schema inline (not $ref — the hand-rolled Draft-07 subset validator this file is checked against does not resolve $ref).",
+      "properties": {
+        "allow": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["permissive", "public-domain", "weak-copyleft", "gpl-2.0", "gpl-3.0", "agpl", "sspl", "unknown"] }
+        },
+        "conditional": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["permissive", "public-domain", "weak-copyleft", "gpl-2.0", "gpl-3.0", "agpl", "sspl", "unknown"] }
+        },
+        "deny": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["permissive", "public-domain", "weak-copyleft", "gpl-2.0", "gpl-3.0", "agpl", "sspl", "unknown"] }
+        }
+      }
+    },
+    "deny": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "MIT", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause", "ISC", "0BSD",
+          "MPL-2.0", "LGPL-2.1", "LGPL-3.0", "GPL-2.0", "GPL-3.0", "AGPL-3.0",
+          "SSPL-1.0", "Unlicense", "CC0-1.0"
+        ]
+      },
+      "description": "Flattened concrete-SPDX-id expansion of policy.deny — the shape lint_provenance.ts's resolveDenyPolicy() reads directly (top-level `deny: [<SPDX id>, ...]`). Never hand-edit; loosening this array without derived_from: manual is rejected by the merge step."
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "derived_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}"
+    }
+  }
+}

package/src/scripts/schemas/provenance-borrow.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "provenance-borrow.schema.json",
+  "title": "Provenance ledger borrow record",
+  "description": "One line of provenance/borrows.jsonl — a single conscious external-code borrow. Contract: provenance/README.md. Enforced by src/scripts/lint_provenance.ts (hand-rolled validator, following the ticket.schema.json / ticket-manifest.schema.json precedent — this file documents the contract; it is not loaded at runtime).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["source_url", "license", "source_sha", "borrowed_at", "files", "transformation_note", "cleared_by"],
+  "properties": {
+    "source_url": {
+      "type": "string",
+      "pattern": "^(https?://\\S+|git@\\S+)$",
+      "description": "Where the borrowed code came from."
+    },
+    "license": {
+      "type": "string",
+      "description": "SPDX identifier of the source's license, or the literal 'unknown'. 'unknown' and any deny-class SPDX id (GPL/AGPL/SSPL family, under the default conservative policy) fail the linter — an unresolved license must never land in the ledger (principle #1: unknown escalates, never down-guessed)."
+    },
+    "source_sha": {
+      "type": "string",
+      "pattern": "^[0-9a-fA-F]{7,64}$",
+      "description": "Commit or blob SHA the borrow was taken from."
+    },
+    "borrowed_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ISO-8601 date (YYYY-MM-DD) the borrow landed."
+    },
+    "files": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" },
+      "description": "Repo-relative paths touched by the borrow. Every path must exist and must not escape the repo root."
+    },
+    "transformation_note": {
+      "type": "string",
+      "minLength": 20,
+      "description": "What structurally changed. Rename-only phrasing is rejected — per principle #6, rename-only is not transformation; clearing requires structural re-derivation (the hit disappears on rescan) or an attributed ledger entry describing an actual structural change."
+    },
+    "cleared_by": {
+      "type": "string",
+      "enum": ["rescan", "ledger", "human"],
+      "description": "How the borrow was cleared: an automated rescan found the hit gone after rewrite, this ledger entry itself is the clearance, or a human reviewed and cleared it."
+    }
+  }
+}

package/src/scripts/schemas/rule.schema.json

@@ -115,6 +115,16 @@
       "items": {"type": "string", "pattern": "^[a-z][a-z0-9-]*$"},
       "description": "ADR-013 pack ids (additive discovery axis). Closed vocabulary enforced by scripts/lint_artefact_frontmatter.py against config/discovery/packs.yml."
     },
+    "roles": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "enum": ["developer", "reviewer", "tester", "po", "incident", "planner"]
+      },
+      "description": "Subagent role-mode scoping axis (road-to-lean-agent-init Phase 4), parallel to `workspaces`/`packs`. Closed vocabulary — the six RoleMode ids from src/scripts/_lib/subagent_spawn.ts. Absent/empty = untagged, fails safe (ships to every role). Kernel rules (type: always) always ship regardless of this field. Enforced via this schema's `enum` (not a src/config/discovery/*.yml + lint_artefact_frontmatter.ts cross-check like workspaces/packs) because lint_artefact_frontmatter.ts still scans the retired legacy rules tree (0 artefacts post-ADR-051 src/ migration) and is a no-op for src/rules/*.md today; validate_frontmatter.ts (the active src/rules linter) enforces this enum instead."
+    },
     "lifecycle": {
       "type": "string",
       "enum": ["active", "deprecated", "experimental", "archived"],