@event4u/agent-config 8.4.1 → 8.5.0

package/src/scripts/_cli/explain_last/assumptions.ts

@@ -1,8 +1,8 @@
 /**
  * Resolve the `assumptions` why-slot for the trace.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/assumptions.py`
- * (ADR-200). Behaviour mirrors the Python original EXACTLY — same string /
+ * Ported from the retired Python `src/scripts/_cli/explain_last/assumptions.py`
+ * (ADR-200). Behaviour pins the historical contract exactly — same string /
  * dict normalisation, same 120-code-point id slice, same `or`-fallback
  * order, same always-array return. No behaviour changes.
  *

package/src/scripts/_cli/explain_last/council.ts

@@ -1,8 +1,8 @@
 /**
  * Resolve the `council` why-slot for the trace.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/council.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same candidate glob,
+ * Ported from the retired Python `src/scripts/_cli/explain_last/council.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same candidate glob,
  * same ±1h run window, same most-recent pick, same member extraction
  * (first stripped line, 200-code-point slice), and the same deliberate
  * omission of cost-metadata fields. No behaviour changes.

package/src/scripts/_cli/explain_last/halt.ts

@@ -1,8 +1,8 @@
 /**
  * Builder for the `trace.halt` slot.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/halt.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same `halts[-1]` pick,
+ * Ported from the retired Python `src/scripts/_cli/explain_last/halt.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same `halts[-1]` pick,
  * same `None` branches, same scrub passes, same `step` empty-string
  * fallback. No behaviour changes.
  *

package/src/scripts/_cli/explain_last/index.ts

@@ -1,8 +1,8 @@
 /**
  * `agent-config explain last` — execution-trace builder.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/__init__.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same subject derivation,
+ * Ported from the retired Python `src/scripts/_cli/explain_last/__init__.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same subject derivation,
  * same run-id derivation (with the UTC-mtime ISO fallback), same slot
  * aggregation order and key shape, same scrub pass on the run id. No
  * behaviour changes.

package/src/scripts/_cli/explain_last/inputs.ts

@@ -1,8 +1,8 @@
 /**
  * Resolve the `inputs` and `pack` why-slots for the trace.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/inputs.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same resolver reuse,
+ * Ported from the retired Python `src/scripts/_cli/explain_last/inputs.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same resolver reuse,
  * same `None`-on-error branches, same per-knob source attribution, same
  * pack-marker discovery order and key shape. No behaviour changes.
  *
@@ -30,9 +30,9 @@ const _SILENCED_LOGGERS: readonly string[] = [
 ];
 
 /**
- * Faithful twin of the Python `_silence_resolver_warnings` context manager.
+ * Port of the retired Python `_silence_resolver_warnings` context manager.
  *
- * The Python original raises the level of the `scripts.config.profiles` /
+ * the retired Python implementation raises the level of the `scripts.config.profiles` /
  * `scripts.config.presets` loggers to ERROR so a profile/preset read
  * failure does not leak an absolute path on stderr. The TypeScript config
  * twins funnel through a single shared `agent_settings.logger` that only

package/src/scripts/_cli/explain_last/memory.ts

@@ -1,8 +1,8 @@
 /**
  * Resolve the `memory` why-slot for the trace.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/memory.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same two sources, same
+ * Ported from the retired Python `src/scripts/_cli/explain_last/memory.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same two sources, same
  * coercion order, same `float()` semantics, same `None`-on-empty branch.
  * No behaviour changes.
  *

package/src/scripts/_cli/explain_last/provider.ts

@@ -1,8 +1,8 @@
 /**
  * Builder for the `trace.provider` slot.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/provider.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same video-only gate,
+ * Ported from the retired Python `src/scripts/_cli/explain_last/provider.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same video-only gate,
  * same `video_provider` / `contract.video_provider` extraction order, same
  * `None` branches, same scrub passes. No behaviour changes.
  *

package/src/scripts/_cli/explain_last/render.ts

@@ -1,8 +1,8 @@
 /**
  * Deterministic Markdown projection of an `ExplainTrace`.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/render.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same fixed section
+ * Ported from the retired Python `src/scripts/_cli/explain_last/render.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same fixed section
  * order, same skip-empty-chunk join, same `rstrip()` + trailing newline,
  * same tip-footer text and `with_footer` gate. No behaviour changes.
  *

package/src/scripts/_cli/explain_last/route.ts

@@ -1,8 +1,8 @@
 /**
  * Resolve the `route` why-slot for the trace.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/route.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same router lookup, same
+ * Ported from the retired Python `src/scripts/_cli/explain_last/route.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same router lookup, same
  * `None`-on-missing-router branch, same scrub passes, same key shape. No
  * behaviour changes.
  *

package/src/scripts/_cli/explain_last/scrubber.ts

@@ -1,8 +1,8 @@
 /**
  * PII / cost-metadata scrubber for the `explain last` trace.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/scrubber.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same regex sources, same
+ * Ported from the retired Python `src/scripts/_cli/explain_last/scrubber.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same regex sources, same
  * resolution order, same idempotence, same long-string threshold and
  * summary text. No behaviour changes — latent bugs are replicated, not
  * fixed.

package/src/scripts/_cli/explain_last/sections/assumptions.ts

@@ -1,9 +1,9 @@
 /**
  * Render the `Assumptions` section.
  *
- * TypeScript twin of
+ * Ported from the retired Python
  * `src/scripts/_cli/explain_last/sections/assumptions.py` (ADR-200).
- * Byte-identical to the Python original — note the DOUBLE space before the
+ * byte-stable — downstream consumers and checksum gates pin these bytes — note the DOUBLE space before the
  * em-dash in the item line (`{ident}  — recorded`). No behaviour changes.
  */
 

package/src/scripts/_cli/explain_last/sections/council.ts

@@ -1,8 +1,8 @@
 /**
  * Render the `Council` section.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/sections/council.py`
- * (ADR-200). Byte-identical to the Python original. No behaviour changes.
+ * Ported from the retired Python `src/scripts/_cli/explain_last/sections/council.py`
+ * (ADR-200). byte-stable — downstream consumers and checksum gates pin these bytes. No behaviour changes.
  */
 
 function _pyTruthy(value: unknown): boolean {

package/src/scripts/_cli/explain_last/sections/halt.ts

@@ -1,8 +1,8 @@
 /**
  * Render the `Why halted?` section.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/sections/halt.py`
- * (ADR-200). Byte-identical to the Python original — note the surface
+ * Ported from the retired Python `src/scripts/_cli/explain_last/sections/halt.py`
+ * (ADR-200). byte-stable — downstream consumers and checksum gates pin these bytes — note the surface
  * lines are indented by exactly two spaces (`f"  {line}"`). No behaviour
  * changes.
  *

package/src/scripts/_cli/explain_last/sections/header.ts

@@ -1,8 +1,8 @@
 /**
  * Render the trace header (title + subject + started-at).
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/sections/header.py`
- * (ADR-200). Byte-identical to the Python original. No behaviour changes.
+ * Ported from the retired Python `src/scripts/_cli/explain_last/sections/header.py`
+ * (ADR-200). byte-stable — downstream consumers and checksum gates pin these bytes. No behaviour changes.
  */
 
 function _pyTruthy(value: unknown): boolean {

package/src/scripts/_cli/explain_last/sections/index.ts

@@ -1,7 +1,7 @@
 /**
  * Section renderers for the `explain last` Markdown projection.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/sections/__init__.py`
+ * Ported from the retired Python `src/scripts/_cli/explain_last/sections/__init__.py`
  * (ADR-200). Re-exports each section module under the same name so the
  * orchestrator (`render.ts`) calls them in fixed order, keeping the
  * Markdown output byte-deterministic for the same input `ExplainTrace`.

package/src/scripts/_cli/explain_last/sections/inputs.ts

@@ -1,8 +1,8 @@
 /**
  * Render the `Why this profile / preset?` knob table.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/sections/inputs.py`
- * (ADR-200). Byte-identical to the Python original. No behaviour changes.
+ * Ported from the retired Python `src/scripts/_cli/explain_last/sections/inputs.py`
+ * (ADR-200). byte-stable — downstream consumers and checksum gates pin these bytes. No behaviour changes.
  */
 
 function _pyTruthy(value: unknown): boolean {

package/src/scripts/_cli/explain_last/sections/memory.ts

@@ -1,8 +1,8 @@
 /**
  * Render the `Memory hits influencing this run` section.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/sections/memory.py`
- * (ADR-200). Byte-identical to the Python original — same `:.2f` score
+ * Ported from the retired Python `src/scripts/_cli/explain_last/sections/memory.py`
+ * (ADR-200). byte-stable — downstream consumers and checksum gates pin these bytes — same `:.2f` score
  * formatting, same `score n/a` fallback for non-numeric scores. No
  * behaviour changes.
  *

package/src/scripts/_cli/explain_last/sections/pack.ts

@@ -1,8 +1,8 @@
 /**
  * Render the `Active pack` section (Phase 4-discovery aware).
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/sections/pack.py`
- * (ADR-200). Byte-identical to the Python original. No behaviour changes.
+ * Ported from the retired Python `src/scripts/_cli/explain_last/sections/pack.py`
+ * (ADR-200). byte-stable — downstream consumers and checksum gates pin these bytes. No behaviour changes.
  */
 
 function _pyTruthy(value: unknown): boolean {

package/src/scripts/_cli/explain_last/sections/provider.ts

@@ -1,8 +1,8 @@
 /**
  * Render the `Why this provider?` section.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/sections/provider.py`
- * (ADR-200). Byte-identical to the Python original. No behaviour changes.
+ * Ported from the retired Python `src/scripts/_cli/explain_last/sections/provider.py`
+ * (ADR-200). byte-stable — downstream consumers and checksum gates pin these bytes. No behaviour changes.
  *
  * Only emitted when `trace.provider` is non-null (the v1 schema bounds this
  * to `subject == "video"` runs where the engine wrote a provider selection

package/src/scripts/_cli/explain_last/sections/route.ts

@@ -1,8 +1,8 @@
 /**
  * Render the `Why this route?` section.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/sections/route.py`
- * (ADR-200). Byte-identical to the Python original. No behaviour changes.
+ * Ported from the retired Python `src/scripts/_cli/explain_last/sections/route.py`
+ * (ADR-200). byte-stable — downstream consumers and checksum gates pin these bytes. No behaviour changes.
  */
 
 function _pyTruthy(value: unknown): boolean {

package/src/scripts/_cli/explain_last/state_loader.ts

@@ -1,8 +1,8 @@
 /**
  * Read and validate the persisted `.work-state.json` envelope.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/state_loader.py`
- * (ADR-200). Behaviour mirrors the Python original EXACTLY — the same
+ * Ported from the retired Python `src/scripts/_cli/explain_last/state_loader.py`
+ * (ADR-200). Behaviour pins the historical contract exactly — the same
  * three raising failure modes, the same exit codes (1 / 2 / 0), and the
  * same byte-identical messages (including the `version={value!r}` Python
  * repr). No behaviour changes.

package/src/scripts/_dispatch.bash

@@ -64,6 +64,19 @@ Tier 0 — daily-driver (init → sync → validate → work):
                              (Option-A loop; called by the /implement-ticket command)
   help                       Show this help (default Tier-0; --tier=1|all expands)
   --version, -V              Print package version
+
+TS-shell native (run via the installed `agent-config` binary):
+  setup                      Open the onboarding wizard in the browser (UI server)
+  install                    Open the install wizard (UI server, Step 1 / AI tools)
+  config                     Open the configuration GUI (global default; --project for the project surface)
+  settings                   Open the local Settings GUI (alias of config)
+  ui:serve                   Start the local UI server (127.0.0.1, auto-picked port)
+  workspaces ls              List workspaces from the discovery manifest
+  packs ls                   List packs from the discovery manifest
+  commands [ls|explain]      List/explain the command surface from the discovery manifest
+  mcp-server                 Turnkey read-only stdio MCP server (no repo clone; ADR-085)
+  doctor-shell               Probe the TS-shell environment
+  eval:record                Record a live trigger-eval result into a corpus manifest
 EOF
 
   if [[ "$tier" == "1" || "$tier" == "all" ]]; then
@@ -110,6 +123,11 @@ Tier 1 — power-user (release shape, audit, migration):
                              user-authored files; persists standing consent
                              (install.auto_converge) on first use.
                              Flags: --dry-run | --yes
+  conformance                Consumer conformance contract: doctor --ci +
+                             installed-and-firing checks. Exits non-zero on
+                             a failed check.
+  use                        Switch the active experience/profile
+                             (writes profile.id). Usage: use <profile-id>
   explain                    Read-only decision-chain trace.
                              Usage: explain config | explain rule <name>
                                   | explain route "<text>"
@@ -206,13 +224,14 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
   telemetry:record           Append one artefact-engagement event (default-off)
   telemetry:status           Print artefact-engagement telemetry status (read-only)
   telemetry:report           Aggregate the engagement log into a quartile report
+  analyze-session            Read-only post-session report from on-disk runtime state
 EOF
   fi
 
   if [[ "$tier" == "0" ]]; then
     cat <<'EOF'
 
-(Hidden: 15 Tier-1 + 24 Tier-2 commands. Run `./agent-config --help --tier=1`
+(Hidden: Tier-1 and Tier-2 commands. Run `./agent-config --help --tier=1`
 or `--tier=all` to see them. Tier criteria: docs/contracts/command-surface-tiers.md.)
 EOF
   fi

package/src/scripts/_lib/agent_settings.ts

@@ -1,7 +1,7 @@
 /**
  * Centralized loader for `.agent-settings.yml` with user-global fallback.
  *
- * TypeScript twin of `src/scripts/_lib/agent_settings.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/_lib/agent_settings.py` (ADR-200,
  * Phase 2 / Wave 2a). Mirrors the Python module's public API exactly —
  * same exported snake_case names, same semantics, same cascade / anchor /
  * whitelist / merge behavior, same YAML load tolerance, same error types.

package/src/scripts/_lib/agent_src.ts

@@ -1,14 +1,14 @@
 /**
  * Locate artefact source roots across the monorepo physical layout.
  *
- * TypeScript twin of `src/scripts/_lib/agent_src.py` (ADR-200, Phase 2
- * Wave 2a). The public API mirrors the Python module EXACTLY — same
+ * Ported from the retired Python `src/scripts/_lib/agent_src.py` (ADR-200, Phase 2
+ * Wave 2a). The public API pins the historical contract exactly — same
  * exported snake_case names, same root ordering, same logical-relpath
  * computation, same first-win precedence when a logical path resolves
  * across multiple roots, and the same error behaviour
  * (`logical_relpath` throws when a path is under no known root; the
  * collision guard in `_root_specs` throws on duplicate non-empty
- * prefixes). No behaviour changes — latent bugs replicated.
+ * prefixes). Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
  * Phase 4 of the monorepo migration (ADR-017) physically moves source
  * artefacts out of the flat `.agent-src.uncondensed/` directory into
@@ -32,10 +32,10 @@
  *   but accepts repo-relative POSIX strings (used by the condenseor's
  *   output-path computation and the LEGACY_SRC_PREFIX logic).
  *
- * Path handling note: the Python original uses `pathlib.Path` objects.
+ * Path handling note: the retired Python implementation uses `pathlib.Path` objects.
  * This twin uses absolute POSIX path strings as the `Path` equivalent
  * (the host filesystem on the supported platforms is POSIX). All public
- * functions that the Python original typed as `Path` accept/return
+ * functions that the retired Python implementation typed as `Path` accept/return
  * strings here; semantics — `.relative_to`, `.as_posix`, `.resolve`,
  * `.rglob`, `.is_dir`, `.is_file`, `.exists` — are reproduced via the
  * helpers below.
@@ -46,7 +46,7 @@ import { fileURLToPath } from 'node:url';
 
 // --- Path-root configuration (mutable to mirror Python module attributes) ----
 //
-// The Python original derives ROOT from `Path(__file__).resolve().parents[3]`
+// the retired Python implementation derives ROOT from `Path(__file__).resolve().parents[3]`
 // and every other root from it as module-level constants. Tests in
 // `tests/test_agent_src_domains.py` reassign `agent_src.SRC_DOMAINS` directly
 // and clear `agent_src._slug_prefix_cache` to point the resolver at a tmp
@@ -474,7 +474,7 @@ export function* iter_all_sources(): Generator<[string, string]> {
             if (!_isFile(p)) {
                 continue;
             }
-            // The Python original guards `relative_to` with try/except
+            // the retired Python implementation guards `relative_to` with try/except
             // ValueError; here `p` is always under `root` by construction, but
             // we mirror the guard for fidelity.
             if (p !== root && !_isUnder(p, root)) {

package/src/scripts/_lib/agents_overlay.ts

@@ -1,7 +1,7 @@
 /**
  * Resolve files under `agents/<kind>/<name>.md` via the cascade.
  *
- * TypeScript twin of `src/scripts/_lib/agents_overlay.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/_lib/agents_overlay.py` (ADR-200,
  * Phase 2 / Wave 2b). Companion to `agent_settings`: where the settings
  * loader merges YAML, this resolves single-file overlays — overrides,
  * contexts, decisions — to a single deepest match across the in-project

package/src/scripts/_lib/bench_ab_cache.ts

@@ -1,7 +1,7 @@
 /**
  * Baseline-cache helpers for the package-impact A/B bench.
  *
- * TypeScript twin of `src/scripts/_lib/bench_ab_cache.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/_lib/bench_ab_cache.py` (ADR-200,
  * Phase 2 Wave 2a). Public API mirrors the Python module exactly — same
  * exported names (deliberately snake_case), same cache-key shape and
  * `to_dict()` / `from_dict()` serialization, same freshness diagnosis.

package/src/scripts/_lib/bench_ab_scoring.ts

@@ -1,7 +1,7 @@
 /**
  * Structural success criteria for Track B.
  *
- * TypeScript twin of `src/scripts/_lib/bench_ab_scoring.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/_lib/bench_ab_scoring.py` (ADR-200,
  * Phase 2 Wave 2a). Public API mirrors the Python module exactly — same
  * exported names (deliberately snake_case), same A/B scoring math, same
  * check ordering, same JSON-identical result shape.

package/src/scripts/_lib/bench_ab_scoring_v2.ts

@@ -1,8 +1,8 @@
 /**
  * Dual-axis deterministic scoring for the bench:ab v2 discipline-axis benchmark.
  *
- * TypeScript twin of `src/scripts/_lib/bench_ab_scoring_v2.py` (ADR-200
- * Python→TS migration). Public API mirrors the Python module EXACTLY — same
+ * Ported from the retired Python `src/scripts/_lib/bench_ab_scoring_v2.py` (ADR-200
+ * Python→TS migration). Public API pins the historical contract exactly — same
  * exported name (`score_task_v2`, deliberately snake_case), same check
  * ordering, same JSON-identical result shape, same scoring math.
  *
@@ -23,7 +23,7 @@
  * The `_diff_line_count` helper replicates CPython `difflib.unified_diff` with
  * default `n=3` context: the SequenceMatcher matching-block algorithm (incl. the
  * `autojunk` popular-element pruning) is ported verbatim so the added+removed
- * line tally is byte-for-byte identical to the Python original.
+ * line tally is byte-for-byte identical to the retired Python implementation.
  */
 import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';

package/src/scripts/_lib/bench_cost.ts

@@ -1,7 +1,7 @@
 /**
  * Cost capture helper for the bench runner.
  *
- * TypeScript twin of `src/scripts/_lib/bench_cost.py` (ADR-200, Phase 2
+ * Ported from the retired Python `src/scripts/_lib/bench_cost.py` (ADR-200, Phase 2
  * Wave 2a). Public API mirrors the Python module exactly — same exported
  * names (deliberately snake_case), same per-tier aggregation, same
  * recompute-from-rates fallback, same 6-decimal rounding, same JSON-identical

package/src/scripts/_lib/bench_quality.ts

@@ -6,7 +6,7 @@
 // assertions against actual output. Without it, we emit `not_collected`
 // per docs/contracts/benchmark-report-schema.md § quality invariants.
 //
-// TypeScript twin of `src/scripts/_lib/bench_quality.py` (ADR-200 py2ts
+// Ported from the retired Python `src/scripts/_lib/bench_quality.py` (ADR-200 py2ts
 // Phase 2 / Wave 2a). Scoring math, rubric/regex semantics, and the
 // `not_collected` shape are mirrored exactly; `quality_score` uses
 // Python's round-half-to-even on `round(passing/total, 4)`.
@@ -194,8 +194,8 @@ function _pyRound(value: number, ndigits: number): number {
 /**
  * Translate a Python `re` pattern + `re.MULTILINE` flag into a JS RegExp.
  * The corpus assertions use simple patterns; we surface a thrown error for
- * patterns JS cannot compile so `_eval_regex` reports `bad_regex` like the
- * Python original (which catches `re.error`).
+ * patterns JS cannot compile so `_eval_regex` reports `bad_regex` — the
+ * historical contract (the retired implementation caught `re.error`).
  */
 function _pyCompile(pattern: string): RegExp {
     // re.MULTILINE → 'm'. Python `.search` is unanchored; RegExp.test is too.

package/src/scripts/_lib/bench_report.ts

@@ -4,9 +4,9 @@
 // docs/contracts/benchmark-report-schema.md. Filename format:
 // `internal/bench/reports/<UTC ISO-8601 with : -> ->-<corpus_id>.{json,md}`.
 //
-// TypeScript twin of `src/scripts/_lib/bench_report.py` (ADR-200 py2ts
-// Phase 2 / Wave 2a). Markdown / JSON rendering is byte-exact with the
-// Python original; the inline `:.2%` formatting replicates Python's
+// Ported from the retired Python `src/scripts/_lib/bench_report.py` (ADR-200 py2ts
+// Phase 2 / Wave 2a). Markdown / JSON rendering is byte-stable (goldens pin
+// it); the inline `:.2%` formatting replicates Python's
 // round-half-to-even semantics.
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -52,7 +52,7 @@ export function write_json(filePath: string, report: unknown): void {
 //
 // Python's f"{x:.2%}" rounds half-to-even on the decimal representation.
 // JS `toFixed` rounds half away from zero, so we reimplement to stay
-// byte-exact with the Python original.
+// byte-exact with the retired Python implementation.
 
 /** Replicate Python `format(x, ".2%")` — value × 100, banker-rounded, '%' suffix. */
 function _fmt_pct2(x: number): string {

package/src/scripts/_lib/bench_telegraph.ts

@@ -11,7 +11,7 @@
 //
 // Cost-touch: 10 prompts × 3 arms × claude-sonnet-4-5 (~$3/M in, ~$15/M out).
 //
-// TypeScript twin of `src/scripts/_lib/bench_telegraph.py` (ADR-200
+// Ported from the retired Python `src/scripts/_lib/bench_telegraph.py` (ADR-200
 // py2ts Phase 2 / Wave 2a). Public API mirrored exactly — snake_case
 // names kept deliberately. Numeric helpers replicate Python's
 // round-half-to-even (banker's rounding) and the `statistics` module

package/src/scripts/_lib/bench_telegraph_report.ts

@@ -5,9 +5,9 @@
 // blocks are disjoint: telegraph has no `selection`/`quality`, and the
 // selection bench has no three-arm condensation metrics.
 //
-// TypeScript twin of `src/scripts/_lib/bench_telegraph_report.py`
+// Ported from the retired Python `src/scripts/_lib/bench_telegraph_report.py`
 // (ADR-200 py2ts Phase 2 / Wave 2a). Markdown rendering is byte-exact
-// with the Python original; the `_fmt_pct` / `:.0f` helpers replicate
+// with the retired Python implementation; the `_fmt_pct` / `:.0f` helpers replicate
 // Python's round-half-to-even formatting.
 import {
     ARMS,
@@ -137,8 +137,8 @@ function _prompt_block(r: PromptResult): PromptBlock {
 //
 // Python's f"{x:.2%}" and f"{m:.0f}" both round half-to-even (banker's
 // rounding) on the decimal representation. JS `toFixed` rounds half away
-// from zero, so we reimplement the formatting to stay byte-exact with the
-// Python original.
+// from zero, so we reimplement the formatting to keep the report bytes
+// stable (goldens pin them).
 
 /** Replicate Python `format(x, f".{ndigits}%")` — value × 100, banker-rounded, '%' suffix. */
 function _py_format_pct(x: number, ndigits: number): string {

package/src/scripts/_lib/changelog_eras.ts

@@ -1,7 +1,7 @@
 /**
  * Shared constants + helpers for CHANGELOG.md era discipline.
  *
- * TypeScript twin of `src/scripts/_lib/changelog_eras.py` (ADR-200
+ * Ported from the retired Python `src/scripts/_lib/changelog_eras.py` (ADR-200
  * py2ts Phase 2 / Wave 1). The drift gate (`tests/test_changelog_eras.py`
  * / `tests/lib/changelog_eras.test.ts`) and the release automation
  * (`scripts/release.py`) both reason about the same era shape: a single

package/src/scripts/_lib/claude_desktop_bundler.ts

@@ -1,7 +1,7 @@
 /**
  * Claude Desktop skill ZIP bundler (Phase 4 of event4u-namespace roadmap).
  *
- * TypeScript twin of `src/scripts/_lib/claude_desktop_bundler.py`
+ * Ported from the retired Python `src/scripts/_lib/claude_desktop_bundler.py`
  * (ADR-200 py2ts Phase 2 / Wave 1).
  *
  * Claude Desktop has no filesystem convention for skills; the Customize →

package/src/scripts/_lib/cli_wrapper.ts

@@ -1,7 +1,7 @@
 /**
  * Install / refresh the consumer-facing `./agent-config` wrapper.
  *
- * TypeScript twin of `src/scripts/_lib/cli_wrapper.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/_lib/cli_wrapper.py` (ADR-200 —
  * Python→TS migration, Phase 2 / Wave 1). Public API mirrors the
  * Python module exactly (snake_case kept deliberately).
  *

package/src/scripts/_lib/fs_atomic.ts

@@ -1,7 +1,7 @@
 /**
  * Atomic file-write primitive shared by lockfile-schema-v2 writers.
  *
- * TypeScript twin of `src/scripts/_lib/fs_atomic.py` (ADR-200 — Python→TS
+ * Ported from the retired Python `src/scripts/_lib/fs_atomic.py` (ADR-200 — Python→TS
  * migration, Phase 2 / Wave 1). Public API mirrors the Python module
  * exactly (snake_case kept deliberately — fidelity over TS idiom).
  *

package/src/scripts/_lib/global_deploy_inventory.ts

@@ -1,7 +1,7 @@
 /**
  * Per-tool inventory of files written by global deploys — and stale reaping.
  *
- * TypeScript twin of `src/scripts/_lib/global_deploy_inventory.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/_lib/global_deploy_inventory.py` (ADR-200 —
  * Python→TS migration, Phase 2 / Wave 2a). Public API mirrors the Python
  * module exactly (snake_case kept deliberately), including the JSON
  * serialization shape (`indent=2, sort_keys=True` + trailing newline) and the

package/src/scripts/_lib/install_layout.ts

@@ -1,7 +1,7 @@
 /**
  * Install-layout ABI version.
  *
- * TypeScript twin of `src/scripts/_lib/install_layout.py` (ADR-200 — Python→TS
+ * Ported from the retired Python `src/scripts/_lib/install_layout.py` (ADR-200 — Python→TS
  * migration). Public API mirrors the Python module exactly (snake_case kept
  * deliberately — fidelity over TS idiom): the two version constants and the
  * `coerce_layout_version` / `needs_migration` helpers, with Python `int()`

package/src/scripts/_lib/install_regenerator.ts

@@ -1,7 +1,7 @@
 /**
  * Provision the roadmap-progress regenerator into a consumer.
  *
- * TypeScript twin of `src/scripts/_lib/install_regenerator.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/_lib/install_regenerator.py` (ADR-200 —
  * Python→TS migration, Phase 2 / Wave 2a). Public API mirrors the Python
  * module exactly (snake_case kept deliberately).
  *

package/src/scripts/_lib/installed_lock.ts

@@ -1,7 +1,7 @@
 /**
  * Global-install lockfile at `~/.event4u/agent-config/installed.lock`.
  *
- * TypeScript twin of `src/scripts/_lib/installed_lock.py` (ADR-200 — Python→TS
+ * Ported from the retired Python `src/scripts/_lib/installed_lock.py` (ADR-200 — Python→TS
  * migration, Phase 2 / Wave 2a). Public API mirrors the Python module exactly
  * (snake_case kept deliberately — fidelity over TS idiom), including the
  * byte-exact lockfile wire format and the tempfile + rename atomic write.

package/src/scripts/_lib/installed_tools.ts

@@ -1,7 +1,7 @@
 /**
  * Project-scope installed-tools manifest at `agents/installed-tools.lock`.
  *
- * TypeScript twin of `src/scripts/_lib/installed_tools.py` (ADR-200 — Python→TS
+ * Ported from the retired Python `src/scripts/_lib/installed_tools.py` (ADR-200 — Python→TS
  * migration, Phase 2 / Wave 2a). Public API mirrors the Python module exactly
  * (snake_case kept deliberately — fidelity over TS idiom), including the
  * byte-exact YAML wire format the `_render` golden tests pin.