@event4u/agent-config 8.4.0 → 8.5.0

package/src/scripts/install.ts

@@ -2,8 +2,8 @@
 /**
  * Agent Config — Project Bridge Installer (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/install.py` (ADR-200, py2ts migration).
- * The CLI contract mirrors the Python original EXACTLY — same flags, same
+ * Ported from the retired Python `src/scripts/install.py` (ADR-200).
+ * The CLI contract pins the historical contract exactly — same flags, same
  * exit codes, same stdout/stderr split, byte-identical emitted output,
  * same filesystem effects, same subprocess argv/cwd/env. No behaviour
  * changes — latent quirks are replicated and flagged inline, not fixed.
@@ -51,7 +51,7 @@
  *   import-resolution detail with no observable effect.
  * - `scripts._cli.cmd_migrate` now has a `.ts` twin, so `_run_migrate_to_global`
  *   calls `cmd_migrate.main([], { cwd })` directly in-process — exactly as the
- *   Python original ran it via `sys.stdout`. The migrator's `out`/`err` sinks
+ *   retired Python implementation ran it via `sys.stdout`. The migrator's `out`/`err` sinks
  *   default to `process.stdout`/`process.stderr`, preserving the prior
  *   `stdio:['ignore','inherit','pipe']` observable contract (stdout text + exit
  *   code). Inline reason at the call site.
@@ -80,6 +80,9 @@ import * as user_global_paths from './_lib/user_global_paths.js';
 import * as claude_desktop_bundler from './_lib/claude_desktop_bundler.js';
 import * as claude_settings_hooks from './_lib/claude_settings_hooks.js';
 import { find_project_root_with_anchor, load_agent_settings } from './_lib/agent_settings.js';
+import { flattenSurface, computeSurfaceDelta, type SettingsSurface } from '../shared/settingsSurface.js';
+import { settingsSchema } from '../server/schemas/settings.js';
+import { zodToJsonSchema } from 'zod-to-json-schema';
 import { detect_module_roots } from './_lib/module_detection.js';
 import {
     TIER_TO_CLAUDE_MODEL,
@@ -2832,6 +2835,66 @@ function _deploy_claude_desktop(
     return [bundle_count, 0, 'deployed', [bundles_dir, ...marker_paths]];
 }
 
+/**
+ * Claude Code flat-command mitigation (council 2026-07-08,
+ * cc-user-command-discovery). Claude Code ≤ 2.1.204 does not register FLAT
+ * user-scope command files (`~/.claude/commands/<name>.md`) — probed and
+ * confirmed: nested commands (`/cluster:sub`) and user-scope skills DO
+ * register. Until upstream fixes discovery, tier-0/1 VISIBLE flat commands
+ * are re-projected as skill wrappers (`~/.claude/skills/<name>/SKILL.md`)
+ * and their flat command file is dropped from the claude-code anchor —
+ * single source, so no duplicate `/name` appears once upstream fixes flat
+ * discovery (revert = one package release, no per-machine gating).
+ * Tier-2/internal flat commands stay command files. A command whose name
+ * collides with a real skill is skipped (the skill already owns `/name`).
+ */
+const _CLAUDE_FLAT_WRAPPER_EXTRA = new Set(['commit']); // essential; absent from the manifest
+export function _apply_claude_flat_command_wrappers(
+    anchor: string,
+    package_root: string,
+    current_files: Set<string>,
+): { wrapped: string[]; collisions: string[] } {
+    const wrapped: string[] = [];
+    const collisions: string[] = [];
+    // Tier-0/1 visible command slugs from the locked discovery manifest.
+    const eligible = new Set<string>(_CLAUDE_FLAT_WRAPPER_EXTRA);
+    try {
+        const manifest = JSON.parse(
+            fs.readFileSync(path.join(package_root, 'dist', 'discovery', 'discovery-manifest.json'), 'utf8'),
+        ) as { artefacts?: Array<{ category?: string; slug?: string; tier?: number; visibility?: string }> };
+        for (const a of manifest.artefacts ?? []) {
+            if (a.category !== 'command' || typeof a.slug !== 'string') continue;
+            if ((a.tier ?? 2) <= 1 && a.visibility !== 'internal') eligible.add(a.slug);
+        }
+    } catch {
+        // No manifest → wrap only the hardcoded essentials.
+    }
+    for (const slug of [...eligible].sort()) {
+        const flat_rel = `commands/${slug}.md`;
+        const flat_abs = path.join(anchor, 'commands', `${slug}.md`);
+        if (!fs.existsSync(flat_abs)) continue;
+        const skill_dir = path.join(anchor, 'skills', slug);
+        if (fs.existsSync(skill_dir)) {
+            // A real skill owns /<slug> — never overwrite it.
+            collisions.push(slug);
+            continue;
+        }
+        let body = fs.readFileSync(flat_abs, 'utf8');
+        // SKILL.md requires a `name:` — inject it into the existing
+        // frontmatter when absent (command frontmatter carries description).
+        if (body.startsWith('---\n') && !/^name:/m.test(body.split('\n---')[0] ?? '')) {
+            body = body.replace('---\n', `---\nname: ${slug}\n`);
+        }
+        fs.mkdirSync(skill_dir, { recursive: true });
+        fs.writeFileSync(path.join(skill_dir, 'SKILL.md'), body, 'utf8');
+        fs.rmSync(flat_abs, { force: true });
+        current_files.delete(flat_rel);
+        current_files.add(`skills/${slug}/SKILL.md`);
+        wrapped.push(slug);
+    }
+    return { wrapped, collisions };
+}
+
 function _deploy_global_content(
     tools: Set<string>,
     force: boolean,
@@ -2874,6 +2937,20 @@ function _deploy_global_content(
                 global_deploy_inventory.expected_deploy_files(src, dest_sub ? dest_sub : ''),
             );
         }
+        // Flat-command → skill-wrapper re-projection for Claude Code
+        // (discovery regression mitigation; see the helper's doc block).
+        // Runs before the postcheck + inventory record so `current_files`
+        // reflects the transformed tree and reaping stays consistent.
+        if (tool_id === 'claude-code') {
+            const res = _apply_claude_flat_command_wrappers(anchor, package_root, current_files);
+            if (res.wrapped.length > 0 && !state.QUIET) {
+                info(
+                    `  claude-code: ${res.wrapped.length} visible flat command(s) projected as ` +
+                        'skill wrappers (Claude Code flat-command discovery workaround)',
+                );
+            }
+        }
+
         const missing_targets = _verify_deploy_targets(anchor, plan);
         if (missing_targets.length > 0) {
             if (!state.QUIET) {
@@ -3275,6 +3352,20 @@ function install_global(
         }
     }
 
+    // Settings-surface snapshot + upgrade delta (road-to-settings-change-
+    // review; council 2026-07-08, 2/2 converged on snapshot-at-install).
+    // Every global install persists the flattened settings surface; when a
+    // PREVIOUS snapshot from a different version exists, the semantic delta
+    // (added / default_changed / enum_added / enum_removed / type_changed)
+    // is written to state/settings-delta.json — the pending-review flag the
+    // GUI banner, the review page, and doctor consume. Never fatal: a
+    // snapshot failure must not sink the install.
+    try {
+        _write_settings_surface_snapshot(installed_version);
+    } catch (e) {
+        if (!state.QUIET) warn(`settings-surface snapshot failed — ${String(e)}`);
+    }
+
     if (!state.QUIET) {
         process.stdout.write('\n');
         success(`Global install completed (v${installed_version}).`);
@@ -3283,6 +3374,55 @@ function install_global(
     return 0;
 }
 
+const SETTINGS_SURFACE_REL = path.join('state', 'settings-surface.json');
+const SETTINGS_DELTA_REL = path.join('state', 'settings-delta.json');
+
+function _current_settings_surface(version: string): SettingsSurface {
+    const jsonSchema = zodToJsonSchema(settingsSchema, {
+        name: 'AgentSettings',
+        $refStrategy: 'none',
+        target: 'jsonSchema7',
+    }) as Parameters<typeof flattenSurface>[0];
+    return flattenSurface(jsonSchema, version);
+}
+
+function _write_settings_surface_snapshot(installed_version: string): void {
+    const root = user_global_paths.event4u_root();
+    const surface_path = path.join(root, SETTINGS_SURFACE_REL);
+    const delta_path = path.join(root, SETTINGS_DELTA_REL);
+    const next = _current_settings_surface(installed_version);
+
+    let previous: SettingsSurface | null = null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(surface_path, 'utf8')) as SettingsSurface;
+        if (parsed !== null && typeof parsed === 'object' && parsed.entries !== undefined) previous = parsed;
+    } catch {
+        // First run after this feature ships — seed-only (council Q1:
+        // no template fallback; the transition cost is paid once).
+    }
+
+    if (previous !== null && previous.version !== next.version) {
+        const delta = computeSurfaceDelta(previous, next);
+        if (delta.changes.length > 0) {
+            fs.mkdirSync(path.dirname(delta_path), { recursive: true, mode: 0o700 });
+            fs.writeFileSync(delta_path, `${JSON.stringify(delta, null, 2)}\n`, { mode: 0o600 });
+            if (!state.QUIET) {
+                const counts: Record<string, number> = {};
+                for (const c of delta.changes) counts[c.kind] = (counts[c.kind] ?? 0) + 1;
+                const parts = Object.entries(counts).map(([k, v]) => `${v} ${k.replace('_', ' ')}`);
+                info(
+                    `Settings surface changed ${delta.oldVersion} → ${delta.newVersion}: ` +
+                        `${parts.join(', ')}. Review with \`agent-config config\` ` +
+                        '(Settings → banner) — nothing was changed automatically.',
+                );
+            }
+        }
+    }
+
+    fs.mkdirSync(path.dirname(surface_path), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(surface_path, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+}
+
 function arrayStrEqual(a: string[], b: string[]): boolean {
     return a.length === b.length && a.every((v, i) => v === b[i]);
 }
@@ -4531,6 +4671,8 @@ export {
     _wizard_should_launch,
     _dry_run_summary,
     _apply_payload_preview,
+    _write_settings_surface_snapshot,
+    _current_settings_surface,
     jsonDumpsIndent,
     jsonDumpsCompact,
     _canonical_settings_target,

package/src/scripts/inventory_abstraction_budget.ts

@@ -2,7 +2,7 @@
 /**
  * Abstraction-budget inventory — read-only discovery pass.
  *
- * TypeScript twin of `src/scripts/inventory_abstraction_budget.py`
+ * Ported from the retired Python `src/scripts/inventory_abstraction_budget.py`
  * (ADR-200 — Python→TS migration, Phase 8 / Wave 8c). Mirrors the
  * Python CLI contract EXACTLY — the `--quiet` flag, exit code (always
  * 0), the stdout/stderr split routed through the `script_output` twin,
@@ -11,9 +11,9 @@
  * quoting).
  *
  * Imports the `_lib/agent_src` + `_lib/script_output` twins (the SAME
- * surfaces the Python original imports). Reference counts are grep-backed
+ * surfaces the retired Python implementation imports). Reference counts are grep-backed
  * (ripgrep with python-walk fallback) — `rg` is invoked as a subprocess
- * exactly like the Python original, so the counts agree.
+ * exactly like the retired Python implementation, so the counts agree.
  *
  * Read-only. Touches no abstraction file. No behaviour changes — latent
  * Python quirks replicated.
@@ -127,7 +127,7 @@ function newStats(): Stats {
 }
 
 function _log(level: 'info' | 'success' | 'warn' | 'error', msg: string): void {
-    // script_output twin is always present here (unlike the Python original's
+    // script_output twin is always present here (unlike the retired Python implementation's
     // graceful-degradation guard, which exists only for the rare run outside the
     // repo). Mirror the Python branch: when script_output is None it would print
     // only on error to stderr — but in this twin the module is always imported.
@@ -466,7 +466,7 @@ export function inventory_packs(stats: Stats): void {
     // FileNotFoundError when the directory does not exist (it is NOT guarded
     // by an is_dir() check, unlike the other inventory passes). Replicate that
     // latent crash faithfully: on the current src/-based layout (no packages/
-    // dir) the Python original aborts with a FileNotFoundError traceback and
+    // dir) the retired Python implementation aborts with a FileNotFoundError traceback and
     // exit 1. See the divergence note in the wave report — this is a real
     // latent Python bug being mirrored, not a TS choice.
     for (const child of _iterdirSortedStrict(packs_dir)) {

package/src/scripts/inventory_frontmatter.ts

@@ -2,7 +2,7 @@
 /**
  * Inventory frontmatter keys across all agent artefacts.
  *
- * TypeScript twin of `src/scripts/inventory_frontmatter.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/inventory_frontmatter.py` (ADR-200 —
  * Python→TS migration, Phase 8 / Wave 8c). Mirrors the CLI contract
  * EXACTLY: no flags, exit code 0, byte-identical Markdown stdout. No
  * behaviour changes — latent bugs (line-based frontmatter parse, the

package/src/scripts/inventory_meta_layers.ts

@@ -2,7 +2,7 @@
 /**
  * Meta-layer / concept-surface inventory — read-only discovery pass.
  *
- * TypeScript twin of `src/scripts/inventory_meta_layers.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/inventory_meta_layers.py` (ADR-200 —
  * Python→TS migration, Phase 8 / Wave 8c). Mirrors the CLI contract EXACTLY:
  * flag (`--quiet`), exit code 0, byte-identical stdout, and the byte-identical
  * written `meta-layer-inventory.md` (`\n`-joined) + `meta-layer-inventory.csv`

package/src/scripts/iron_law_sha.ts

@@ -2,7 +2,7 @@
 /**
  * SHA-256 of every triple-fence block in a rule file (Iron Law preservation).
  *
- * TypeScript twin of `iron_law_sha.py` (Phase 8 / Wave 8e). Mirrors the
+ * Ported from the retired Python `iron_law_sha.py` (Phase 8 / Wave 8e). Mirrors the
  * Python CLI contract byte-for-byte: flags, exit codes, stdout layout.
  *
  * Usage:

package/src/scripts/knowledge_global_cli.ts

@@ -2,8 +2,8 @@
 /**
  * Command surface for the file-first global knowledge-card store (ADR-100).
  *
- * TypeScript twin of `src/scripts/knowledge_global_cli.py` (ADR-200). The CLI
- * contract mirrors the Python original EXACTLY — same subcommands, flags,
+ * Ported from the retired Python `src/scripts/knowledge_global_cli.py` (ADR-200). The CLI
+ * contract pins the historical contract exactly — same subcommands, flags,
  * exit codes, stdout/stderr split, byte-identical messages, table layout,
  * provenance write, and kill-switch no-op behavior. No behaviour changes.
  *
@@ -392,7 +392,7 @@ function cmd_validate(args: { check_urls: boolean }): number {
         return 0;
     }
 
-    // The Python original spawns `python3 check_knowledge_cards.py --global
+    // the retired Python implementation spawns `python3 check_knowledge_cards.py --global
     // --strict`. The TS twin spawns the sibling `check_knowledge_cards.ts`
     // via the same tsx runtime (process spawn, not an import).
     const tsxBin = path.join(

package/src/scripts/linked_projects_list.ts

@@ -2,7 +2,7 @@
 /**
  * `agent-config linked-projects:list` — list opted-in IDE-attached siblings.
  *
- * TypeScript twin of `linked_projects_list.py` (Phase 8 / Wave 8e).
+ * Ported from the retired Python `linked_projects_list.py` (Phase 8 / Wave 8e).
  *
  * Phase 4 of `road-to-leaner-core-and-discovery`; closes the ADR-032 follow-up
  * "expose the detector as a CLI subcommand for consumer reach". Pure wrapper over

package/src/scripts/lint_agent_security.ts

@@ -2,7 +2,7 @@
 /**
  * P1.6 — umbrella runner for the agent-security self-audit linters.
  *
- * TypeScript twin of `src/scripts/lint_agent_security.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/lint_agent_security.py` (ADR-200 —
  * Python→TS migration). Mirrors the CLI contract EXACTLY: the `--sarif PATH`
  * / `--quiet` flags, the per-linter glyph lines, the aggregated summary, the
  * byte-identical SARIF report (`json.dumps(indent=2)` parity), and the exit
@@ -15,9 +15,9 @@
  * (road-to-security-pillar.md P1).
  *
  * The four child linters now have TypeScript twins, so this runner spawns each
- * `<child>.ts --json` via the repo-local `tsx` binary (the Python originals
+ * `<child>.ts --json` via the repo-local `tsx` binary (the retired Python implementations
  * were deleted in the ADR-200 migration). Each child is a separate process so
- * its JSON findings are aggregated here exactly as the Python original
+ * its JSON findings are aggregated here exactly as the retired Python implementation
  * aggregated `subprocess.run` output.
  *
  * Usage:
@@ -51,7 +51,7 @@ const LINTERS: ReadonlyArray<[string, string]> = [
 
 function _run(script: string): [number, Finding[]] {
   // Spawn the child linter's `.ts` twin via the repo-local tsx binary
-  // (capture_output=True, text=True equivalent). Mirrors the Python original's
+  // (capture_output=True, text=True equivalent). Mirrors the retired Python implementation's
   // `subprocess.run([sys.executable, HERE/<child>.py, "--json"])`, now that the
   // children are TypeScript and the `.py` originals are deleted.
   const proc = spawnSync(tsxBin, [path.join(_HERE, script), "--json"], {

package/src/scripts/lint_agent_skill_names.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env tsx
 // Agent-Skills name-compliance linter (2026-06 Zed fix).
 //
-// TypeScript twin of src/scripts/lint_agent_skill_names.py — same two
+// TypeScript port of the retired Python src/scripts/lint_agent_skill_names.py — same two
 // blocking checks (command name == path-derived slug; skill name == dir),
 // same Agent-Skills name pattern, same stdout/stderr split, same exit codes
 // (0 clean / 1 violations / 3 internal error), same `--quiet` flag.

package/src/scripts/lint_agents_layout.ts

@@ -2,8 +2,8 @@
 /**
  * CI guard for the `agents/` top-level layout.
  *
- * TypeScript twin of `src/scripts/lint_agents_layout.py` (ADR-200,
- * Phase 4 / Wave 4b). The CLI contract is mirrored EXACTLY — `--quiet`
+ * Ported from the retired Python `src/scripts/lint_agents_layout.py` (ADR-200,
+ * Phase 4 / Wave 4b). The CLI contract is pinned — `--quiet`
  * / `--strict` flags (parsed by membership test, like the Python which
  * scans `sys.argv[1:]`), exit codes (0 clean / warnings, 1 unknown
  * flat-file violation), stdout/stderr split (everything goes to stdout),

package/src/scripts/lint_agents_md.ts

@@ -2,11 +2,11 @@
 /**
  * Thin-Root contract linter for AGENTS.md files (Phase 7).
  *
- * TypeScript twin of `src/scripts/lint_agents_md.py` (ADR-200, Phase 4 /
- * Wave 4b). The CLI contract is mirrored EXACTLY — `--quiet` detected by
+ * Ported from the retired Python `src/scripts/lint_agents_md.py` (ADR-200, Phase 4 /
+ * Wave 4b). The CLI contract is pinned — `--quiet` detected by
  * argv membership (no argparse), exit codes (0 / 1), stdout-only output,
  * byte-identical messages, same target order. No behaviour changes —
- * latent bugs replicated.
+ * historical quirks preserved (consumers pin the exact behaviour).
  *
  * Enforces caps + pointer-ratio + pointer-anatomy + emergency-triage
  * contract from `.agent-src.uncondensed/skills/agents-md-thin-root/SKILL.md`.

package/src/scripts/lint_archived_skills.ts

@@ -2,8 +2,8 @@
 /**
  * Lint archive notes under agents/evidence/archived-skills/.
  *
- * TypeScript twin of `src/scripts/lint_archived_skills.py` (ADR-200, Phase 4
- * / Wave 4b). The CLI contract is mirrored EXACTLY — `--quiet` flag, exit
+ * Ported from the retired Python `src/scripts/lint_archived_skills.py` (ADR-200, Phase 4
+ * / Wave 4b). The CLI contract is pinned — `--quiet` flag, exit
  * codes (0 contract holds, 1 violations), stdout/stderr split,
  * byte-identical finding messages, same scan trees and order, same
  * frontmatter parser, same `artefact_roots()` skill-root discovery.

package/src/scripts/lint_artefact_frontmatter.ts

@@ -2,8 +2,8 @@
 /**
  * Lint Phase-4 discovery frontmatter on every artefact.
  *
- * TypeScript twin of `src/scripts/lint_artefact_frontmatter.py` (ADR-200,
- * Phase 4 / Wave 4b). The CLI contract is mirrored EXACTLY — `--quiet`
+ * Ported from the retired Python `src/scripts/lint_artefact_frontmatter.py` (ADR-200,
+ * Phase 4 / Wave 4b). The CLI contract is pinned — `--quiet`
  * flag, exit codes (0 clean, 1 violation), stdout/stderr split,
  * byte-identical finding messages (including Python-shaped list repr),
  * same scan trees and order, same `validate_frontmatter.parse_frontmatter`

package/src/scripts/lint_bench_ab.ts

@@ -2,8 +2,8 @@
 /**
  * Validate the A/B bench corpora + `docs/benchmark.md` shape.
  *
- * TypeScript twin of `src/scripts/lint_bench_ab.py` (ADR-200, Phase 4 /
- * Wave 4b). The CLI contract is mirrored EXACTLY — `--quiet` flag, exit
+ * Ported from the retired Python `src/scripts/lint_bench_ab.py` (ADR-200, Phase 4 /
+ * Wave 4b). The CLI contract is pinned — `--quiet` flag, exit
  * codes (0 success, 1 first violation), stdout/stderr split, byte-identical
  * finding messages (including the `lint_bench_ab: <relpath>: <msg>` prefix
  * and the Python `repr()`-shaped value formatting), same check order, same

package/src/scripts/lint_bench_corpus.ts

@@ -2,7 +2,7 @@
 /**
  * Lint benchmark corpora under tests/eval/corpus-*.yaml.
  *
- * TypeScript twin of `src/scripts/lint_bench_corpus.py` (ADR-200, Phase 4 /
+ * Ported from the retired Python `src/scripts/lint_bench_corpus.py` (ADR-200, Phase 4 /
  * Wave 4b). Mirrors the Python CLI contract exactly: same scan scope + glob
  * ordering, finding messages (including Python-repr rendering of bad values),
  * stdout/stderr split, and exit codes.

package/src/scripts/lint_command_flow_coverage.ts

@@ -2,7 +2,7 @@
 /**
  * Command → flow coverage lint (the Flows primary view).
  *
- * TypeScript twin of `src/scripts/lint_command_flow_coverage.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/lint_command_flow_coverage.py` (ADR-200,
  * Phase 4 / Wave 4b). Mirrors the CLI contract EXACTLY — the `--quiet`
  * argparse flag, exit codes (0 clean, 1 violations, 3 internal error),
  * byte-identical stdout/stderr lines, the same violation ordering

package/src/scripts/lint_command_routing.ts

@@ -2,12 +2,12 @@
 /**
  * Routing-metadata + routing-eval linter for visible commands.
  *
- * TypeScript twin of `src/scripts/lint_command_routing.py` (ADR-200, Phase 4 /
+ * Ported from the retired Python `src/scripts/lint_command_routing.py` (ADR-200, Phase 4 /
  * Wave 4b). Mirrors the Python CLI contract exactly: same `--quiet` flag,
  * scan scope (src/domains/**\/command.md, legacy packages fallback), file
  * ordering, frontmatter parsing, finding messages, stdout/stderr split, and
  * exit codes (0 clean, 1 violations, 3 internal error). No behaviour changes —
- * latent bugs replicated.
+ * historical quirks preserved (consumers pin the exact behaviour).
  *
  * Every VISIBLE command (tier 0/1) must carry:
  *   - `intent`     — non-empty one-line existence justification

package/src/scripts/lint_command_tiers.ts

@@ -2,7 +2,7 @@
 /**
  * Lint slash-command frontmatter for the `tier:` key.
  *
- * TypeScript twin of `src/scripts/lint_command_tiers.py` (ADR-200, Phase 4 /
+ * Ported from the retired Python `src/scripts/lint_command_tiers.py` (ADR-200, Phase 4 /
  * Wave 4b). Mirrors the Python CLI contract exactly: same scan scope, file
  * ordering, finding messages, stdout/stderr split, and exit codes
  * (return-code bitwise-OR accumulation across the domain + per-root +

package/src/scripts/lint_command_verbs.ts

@@ -2,13 +2,13 @@
 /**
  * Controlled-verb linter for visible commands.
  *
- * TypeScript twin of `src/scripts/lint_command_verbs.py` (ADR-200,
- * Phase 4 / Wave 4b). The CLI contract is mirrored EXACTLY — `--baseline`
+ * Ported from the retired Python `src/scripts/lint_command_verbs.py` (ADR-200,
+ * Phase 4 / Wave 4b). The CLI contract is pinned — `--baseline`
  * / `--all` / `--quiet` flags, exit codes (0 clean, 1 violations, 3
  * internal error), stdout/stderr split, byte-identical finding messages,
  * same scan scope (forward-only git diff + working-tree status, or every
  * visible command under `--all`), and the same sorted iteration order.
- * snake_case kept. No behaviour changes — latent bugs replicated.
+ * snake_case kept. Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
  * A VISIBLE command (tier 0/1) must have a leading token drawn from the
  * approved verb allowlist in `src/config/discovery/command-verbs.yml`.
@@ -312,7 +312,7 @@ function parse_args(argv: readonly string[]): ParsedArgs {
 
 function _argparse_error(message: string): never {
     // Mirror Python argparse: usage line + program error, both on stderr,
-    // exit code 2. The prog name is the basename of the Python original.
+    // exit code 2. The prog name is the basename of the retired Python implementation.
     process.stderr.write(
         'usage: lint_command_verbs.py [-h] [--baseline BASELINE] [--all] [--quiet]\n',
     );

package/src/scripts/lint_commit_subjects.ts

@@ -2,8 +2,8 @@
 /**
  * Commit-subject linter.
  *
- * TypeScript twin of `src/scripts/lint_commit_subjects.py` (ADR-200,
- * Phase 4 / Wave 4b). The CLI contract is mirrored EXACTLY — `--base`
+ * Ported from the retired Python `src/scripts/lint_commit_subjects.py` (ADR-200,
+ * Phase 4 / Wave 4b). The CLI contract is pinned — `--base`
  * / `--head` / `--quiet` flags, exit codes (0 clean / advisory, 1
  * violations), stdout/stderr split, byte-identical finding messages
  * (the issue strings are grepped by tests), and the same git invocation

package/src/scripts/lint_context_spine_usage.ts

@@ -2,11 +2,11 @@
 /**
  * Context-spine usage linter.
  *
- * TypeScript twin of `src/scripts/lint_context_spine_usage.py` (ADR-200,
- * Phase 4 / Wave 4b). The CLI contract is mirrored EXACTLY — `--quiet`
+ * Ported from the retired Python `src/scripts/lint_context_spine_usage.py` (ADR-200,
+ * Phase 4 / Wave 4b). The CLI contract is pinned — `--quiet`
  * detected by argv membership (no argparse), exit codes (0 clean,
  * 1 violations / no files), stdout/stderr split, byte-identical messages,
- * same glob scan order. No behaviour changes — latent bugs replicated.
+ * same glob scan order. Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
  * For every slot declared in frontmatter (`context_spine: [...]`), the skill
  * body MUST cite the slot at least once (link, bold, or inline-code form).

package/src/scripts/lint_discovery_manifest.ts

@@ -2,15 +2,15 @@
 /**
  * Lint a generated discovery-manifest.json against schema + checksum.
  *
- * TypeScript twin of `src/scripts/lint_discovery_manifest.py` (ADR-200,
- * Phase 4 / Wave 4b). The CLI contract is mirrored EXACTLY — `--manifest`
+ * Ported from the retired Python `src/scripts/lint_discovery_manifest.py` (ADR-200,
+ * Phase 4 / Wave 4b). The CLI contract is pinned — `--manifest`
  * / `--quiet` flags, exit codes (0 / 1), stdout/stderr split, byte-identical
  * SUCCESS + vocab + determinism + checksum messages, same check order, and
  * a byte-identical checksum recomputation (recursive key-sort + indent-2,
- * `ensure_ascii=False`). No behaviour changes — latent bugs replicated.
+ * `ensure_ascii=False`). Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
  * DIVERGENCE CANDIDATES:
- *  1. The Python original imports `jsonschema` and exits 1 with the message
+ *  1. the retired Python implementation imports `jsonschema` and exits 1 with the message
  *     `error: jsonschema not installed (...)` when it is absent. The TS twin
  *     has no such dependency, so that exit-1 path never fires — the schema
  *     check always runs.

package/src/scripts/lint_discovery_vocabulary.ts

@@ -2,12 +2,12 @@
 /**
  * Vocabulary linter for `src/config/discovery/{workspaces,packs}.yml`.
  *
- * TypeScript twin of `src/scripts/lint_discovery_vocabulary.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/lint_discovery_vocabulary.py` (ADR-200,
  * Phase 4 / Wave 4b). Mirrors the Python CLI contract exactly: `--quiet`
  * flag, same scan scope, finding messages, stdout/stderr split (errors to
  * stderr, OK line to stdout), and exit codes (0 clean, 1 on failure, 2 if
  * YAML loader is unavailable — N/A here, `yaml` is bundled). No behaviour
- * changes — latent quirks replicated.
+ * changes — historical quirks preserved (consumers pin the exact behaviour).
  *
  * Source-of-truth check: the YAML files MUST mirror the closed vocabulary in
  * ADR-013 exactly. Cross-reference + bidirectional integrity + non-overlap

package/src/scripts/lint_empty_roadmaps.ts

@@ -2,10 +2,10 @@
 /**
  * Hard-Gate linter: no empty roadmap files under `agents/roadmaps/`.
  *
- * TypeScript twin of `src/scripts/lint_empty_roadmaps.py` (ADR-200 migration).
+ * Ported from the retired Python `src/scripts/lint_empty_roadmaps.py` (ADR-200).
  * Byte-identical CLI contract: same stdout, same exit codes (0 = clean,
  * 1 = at least one empty roadmap). `--quiet` is a bare argv membership check
- * (computed at import, NOT argparse), mirroring the Python original.
+ * (computed at import, NOT argparse), mirroring the retired Python implementation.
  *
  * A roadmap `.md` that is 0 bytes (or only whitespace) is never valid — it
  * carries no goal, no phases, no content. Scope: every `*.md` under
@@ -85,7 +85,7 @@ function _rglobMdSorted(base: string): string[] {
 // Python `str.strip()` (no args) strips every character for which
 // `str.isspace()` is true: ASCII whitespace + the C0 separators \x1c-\x1f +
 // NEL \x85 + the Unicode whitespace set. Match that exact class so a
-// "whitespace-only" file is detected identically to the Python original.
+// "whitespace-only" file is detected identically to the retired Python implementation.
 const _PY_WS = /[\t\n\v\f\r \u001c\u001d\u001e\u001f\u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]/g;
 
 function _toPosix(target: string, root: string): string {

package/src/scripts/lint_eval_freshness.ts

@@ -4,8 +4,8 @@
  * `upstream.last_eval` (the corpus-refresh DoD, ADR-061 §6 + road-to-image-brand-
  * typography Phase D).
  *
- * TypeScript twin of `src/scripts/lint_eval_freshness.py` (ADR-200,
- * Python→TypeScript migration). The CLI contract is mirrored EXACTLY — the
+ * Ported from the retired Python `src/scripts/lint_eval_freshness.py` (ADR-200,
+ * Python→TypeScript migration). The CLI contract is pinned — the
  * `--quiet` flag, the `argparse` usage / error text (`-h`/`--help` → exit 0,
  * unknown arg → exit 2), the scan order (`sorted(SKILLS_DIR.glob(
  * "<skill>/data/manifest.json"))` — pathlib component-wise sort), byte-identical

package/src/scripts/lint_examples.ts

@@ -2,13 +2,13 @@
 /**
  * Phase 3.4 demo-shape linter — wrong / right / why per demo.
  *
- * TypeScript twin of `src/scripts/lint_examples.py` (ADR-200, Phase 4 /
+ * Ported from the retired Python `src/scripts/lint_examples.py` (ADR-200, Phase 4 /
  * Wave 4b). Mirrors the CLI contract EXACTLY — the `--quiet` flag is a
  * bare `sys.argv` membership check (NOT argparse, so there is no real
  * `-h`/`--help`), the same `glob` (non-recursive) over
  * `docs/guidelines/agent-infra/*-demos.md`, byte-identical finding
  * messages, stdout/stderr split, exit codes, and file ordering
- * (sorted glob). No behaviour changes — latent quirks replicated.
+ * (sorted glob). Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
  * Validates every `docs/guidelines/agent-infra/*-demos.md`: frontmatter
  * keys (`demo_for:`, `layer: pattern-memory`, `prose_delta:` with

package/src/scripts/lint_explain_trace.ts

@@ -2,7 +2,7 @@
 /**
  * Lint an ExplainTrace v1 JSON payload against the schema.
  *
- * TypeScript twin of `src/scripts/lint_explain_trace.py` (ADR-200, Phase 4 /
+ * Ported from the retired Python `src/scripts/lint_explain_trace.py` (ADR-200, Phase 4 /
  * Wave 4b). Reads a JSON file (or stdin via `--stdin`) and validates it
  * against `docs/contracts/explain-trace.schema.json`.
  *
@@ -14,7 +14,7 @@
  *   - error lines ordered by `sorted(absolute_path)`.
  *
  * DOCUMENTED DIVERGENCE (validation-failure message text):
- *   The Python original uses `jsonschema.Draft202012Validator`; its
+ *   the retired Python implementation uses `jsonschema.Draft202012Validator`; its
  *   `ValidationError.message` wording is library-specific. This twin
  *   implements a faithful Draft-2020-12 *subset* validator covering only the
  *   keywords the explain-trace schema uses (type / const / enum / required /