@event4u/agent-config 9.8.0 → 9.10.0

package/docs/mcp.md

@@ -1,147 +0,0 @@
-# MCP config generation
-
-One `mcp.json` at your repo root, one `task mcp:render`, three tools configured.
-No hand-editing Claude Desktop, Cursor, and Windsurf files in parallel. No
-secrets committed.
-
-## What this solves
-
-MCP servers are configured per tool today: `.cursor/mcp.json`, a Windsurf
-equivalent, and `~/.config/claude-desktop/claude_desktop_config.json`. Each
-file has the same server list, duplicated. Secrets land in plaintext if you
-commit them, out of reach if you don't.
-
-The renderer fixes both:
-
-- One source of truth (`mcp.json`) → three target files.
-- `${env:VAR}` placeholders resolved at render time from the environment.
-- Missing `${env:VAR}` → non-zero exit, no partial files written.
-
-## Schema
-
-`mcp.json` at the repo root:
-
-```json
-{
-  "servers": {
-    "<server-name>": {
-      "command": "string",
-      "args":    ["string", "..."],
-      "env":     { "KEY": "string" },
-      "cwd":     "string"
-    }
-  }
-}
-```
-
-- `command` and `args` are required per server.
-- `env` and `cwd` are optional.
-- Every string value accepts `${env:VAR_NAME}` placeholders. The renderer
-  replaces them with the value of `VAR_NAME` from the process environment.
-- `${env:VAR}` may appear anywhere in a string; multiple placeholders per
-  string are supported.
-- The source file uses `servers` as the top-level key; the renderer emits
-  `mcpServers` because that is what all three targets expect.
-
-Internal references like `${ref:path.to.value}` are **not** supported. Keep
-values literal, or resolve them from the environment.
-
-## Usage
-
-**Consumer projects** — use the `./agent-config` CLI installed into the
-project root:
-
-```bash
-./agent-config mcp:render                    # write in-project targets
-./agent-config mcp:render --claude-desktop   # also write user-scope Claude Desktop
-./agent-config mcp:check                     # dry-run; exit 1 if targets are stale
-```
-
-**Package maintainers** — the same commands are available through Taskfile:
-
-```bash
-task mcp:render
-task mcp:render -- --claude-desktop
-task mcp:check
-```
-
-Or invoke the script directly (maintainer workflow, inside the package repo):
-
-```bash
-./scripts-run src/scripts/mcp_render [--source PATH] [--claude-desktop] [--check]
-```
-
-Default output paths:
-
-| Target          | Path                                                      | Scope          |
-|-----------------|-----------------------------------------------------------|----------------|
-| Cursor          | `.cursor/mcp.json`                                        | repo, commit it |
-| Windsurf        | `.windsurf/mcp.json`                                      | repo, commit it |
-| Claude Desktop  | `~/.config/claude-desktop/claude_desktop_config.json`     | user, opt-in    |
-
-## Worked example
-
-`mcp.json`:
-
-```json
-{
-  "servers": {
-    "github": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-github"],
-      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GH_TOKEN}" }
-    },
-    "jira": {
-      "command": "docker",
-      "args": ["run", "--rm", "-i", "mcp/jira:latest"],
-      "env": {
-        "JIRA_TOKEN": "${env:JIRA_TOKEN}",
-        "JIRA_HOST":  "example.atlassian.net"
-      }
-    }
-  }
-}
-```
-
-Then:
-
-```bash
-export GH_TOKEN=ghp_xxx
-export JIRA_TOKEN=jira_yyy
-task mcp:render
-```
-
-Produces `.cursor/mcp.json` and `.windsurf/mcp.json` with the secrets
-substituted inline and the root key renamed to `mcpServers`.
-
-## Failure modes
-
-- **Missing `mcp.json`** — exit 1, message naming the expected path.
-- **Invalid JSON** — exit 1, message with the parser error.
-- **Missing `servers` key** — exit 1, shape rejected at load time.
-- **Unresolved `${env:VAR}`** — exit 1, grouped report listing every missing
-  variable and every path in the config where it is used. **No target file
-  is written**, not even a partial one. Set the variable(s) and re-run.
-- **`task mcp:check` disagrees with on-disk targets** — exit 1; run
-  `task mcp:render` to regenerate.
-
-## What this is not
-
-The renderer is one-way: `mcp.json` → tool configs. It does not read or diff
-pre-existing tool configs. Remove stale entries from your source file and
-re-render.
-
-Keychain backends (`security`, `secret-tool`, Bitwarden CLI) are **out of
-scope**. The environment is the only secret surface. Pipe from whatever
-secret tool you already use into the process environment before you run
-`task mcp:render`.
-
-## Related
-
-- [`docs/mcp-registries.md`](mcp-registries.md) — where to *discover* MCP servers
-  (official registry / Glama / Smithery) and how to install one per agent, incl.
-  Augment's manual Import-from-JSON path.
-- [`src/skills/mcp/SKILL.md`](../src/skills/mcp/SKILL.md) — MCP server
-  selection and usage patterns.
-- [`agents/roadmaps/archive/road-to-mcp.md`](../agents/roadmaps/archive/road-to-mcp.md) — archived roadmap that produced this feature.
-- Reference substitution implementation: an external reference.

package/docs/media/proof-demo.cast

@@ -1,14 +0,0 @@
-{"version":3,"term":{"cols":80,"rows":24},"timestamp":1783261474,"command":"bash internal/demo/proof-demo-commands.sh","env":{"SHELL":"/bin/zsh"}}
-[0.007, "o", "\r\n\u001b[1;36m$ task check-claims       # every public claim binds to resolvable evidence\u001b[0m\r\n"]
-[0.360, "o", "\u001b[32m   ✓ pass\u001b[0m\r\n\r\n"]
-[0.000, "o", "\u001b[1;36m$ task check-refs         # no broken internal references\u001b[0m\r\n"]
-[0.445, "o", "\u001b[32m   ✓ pass\u001b[0m\r\n"]
-[0.000, "o", "\r\n\u001b[1;36m$ task check-skill-gaps   # every known-limit cites a real witness test\u001b[0m\r\n"]
-[0.399, "o", "\u001b[32m   ✓ pass\u001b[0m\r\n"]
-[0.000, "o", "\r\n\u001b[1;36m$ task check-comparison   # every comparison-table pointer resolves\u001b[0m\r\n"]
-[0.359, "o", "\u001b[32m   ✓ pass\u001b[0m\r\n"]
-[0.001, "o", "\r\n\u001b[1;36m$ task build-proof-check  # the proof page is in sync with its sources\u001b[0m\r\n"]
-[0.399, "o", "\u001b[32m   ✓ pass\u001b[0m\r\n"]
-[0.000, "o", "\r\n"]
-[0.000, "o", "\u001b[1;32m✓ trust surface verified — reproduce any line on a fresh checkout.\u001b[0m\r\n"]
-[0.000, "x", "0"]

package/docs/migration/consumer-template-consumption-model.md

@@ -1,145 +0,0 @@
-# Consumer Template Consumption Model
-
-> Phase 1 Step 11 of `agents/roadmaps/archive/road-to-typescript-only-scripts.md`.
-> Question: how does `dist/agent-src/templates/scripts/` content reach a consumer
-> project — copied, referenced in place, or symlinked — and what does that mean
-> for the Phase 9 TS migration of the consumer-shipped scripts?
-
-## Verdict: hybrid — in-place execution is primary, copies are secondary
-
-The template scripts are **executed in place from the installed package root**
-as the primary channel, with **two copy channels** layered on top (one
-installer-driven, one manual). Nothing is ever symlinked into a consumer tree —
-the installer explicitly dereferences symlinks on copy
-(`src/scripts/install.py:3201-3264`, rationale at `install.py:1950-1953`:
-"Council Round 3 Q1 rejected cross-scope symlinks").
-
-### Channel 1 — in-place from the package root (primary)
-
-The consumer CLI (`agent-config`, master entrypoint
-`src/scripts/_dispatch.bash`) derives `PACKAGE_ROOT` from its own location —
-`node_modules/@event4u/agent-config/` or the global npm install — and resolves
-symlinks first (`_dispatch.bash:24-32`).
-
-- The work engine (`/work`, `/implement-ticket`) runs **exclusively** in place:
-  `cmd_implement_ticket` and `cmd_work` hard-code
-  `engine_root="$PACKAGE_ROOT/dist/agent-src/templates/scripts"` and exec
-  `python3 -m work_engine` with `PYTHONPATH=$engine_root`
-  (`_dispatch.bash:393-420`). There is **no consumer-override tier** for the
-  engine.
-- The memory/telemetry CLI surface (`memory:lookup`, `memory:signal`,
-  `memory:hash`, `telemetry:record|status|report`, `check_memory`,
-  `check_memory_proposal`) resolves through `resolve_template_script`
-  (`_dispatch.bash:318-337`, call sites `:422-478`) with a three-tier chain:
-
-  1. `$CONSUMER_ROOT/scripts/<name>` — local copy / customization (wins)
-  2. `$CONSUMER_ROOT/.augment/templates/scripts/<name>` — installer-shipped
-     (legacy project-scope projection)
-  3. `$PACKAGE_ROOT/dist/agent-src/templates/scripts/<name>` — package-internal
-     fallback (the path every fresh consumer actually hits)
-
-### Channel 2 — installer-driven copies (user scope, Augment only)
-
-Consumer installs are **global-only** per ADR-020: both front doors gate
-`--scope=project` behind `AGENT_CONFIG_DEV_MODE=1`
-(`src/scripts/install:188-196` and `install.py:2142-2163`,
-`_enforce_consumer_global_only` called from `main()` at `install.py:4745`).
-
-In global scope, only the **Augment** deploy plan copies the templates tree:
-`("dist/agent-src/templates", "templates")` in `GLOBAL_DEPLOY_SOURCES`
-(`install.py:1993-2002`) lands `templates/scripts/` under `~/.augment/templates/`
-(anchor `install.py:1841`). The Claude Code skill bundle
-(`_CLAUDE_SKILL_BUNDLE`, `install.py:1977-1992`) ships rules/skills/commands/
-personas but **not** templates. Source paths always reference `dist/agent-src/`
-because that is the only asset tree in the npm tarball
-(`install.py:1973-1976`, `package.json#files`).
-
-Note the asymmetry: the dispatcher's tier-2 lookup reads the **project-local**
-`.augment/templates/scripts/` (written only by the legacy/maintainer
-project-scope install), not the global `~/.augment/templates/`. The global
-Augment copy exists for the Augment tool surface itself, not for the
-dispatcher.
-
-The wizard is the same engine, not a separate one: `src/server/routes/wizard.ts`
-spawns `scripts/install.py --apply-payload` (`wizard.ts:325`, `:371`, `:953`),
-so all GUI installs converge on the copy semantics above.
-
-### Channel 3 — documented manual copies (opt-in features)
-
-`src/agent-src/templates/scripts/README.md:21-36` and `:171-178` instruct
-consumers to `cp` selected scripts into their own tree: `pr_risk_review.py`,
-`pr_review_routing.py` → consumer `scripts/`; YAML examples → `.github/`. The
-shipped GitHub workflow templates depend on those copies
-(`src/agent-src/templates/github-workflows/memory-hygiene.yml:14`,
-`pr-risk-review.yml:9`). These copies are consumer-owned the moment they are
-made.
-
-## (b) Can consumers modify the scripts locally? Do re-installs overwrite?
-
-- **Installer-deployed copies are always overwritten.** `_resolve_file_conflict`
-  (`install.py:229-243`) unconditionally returns `"write"` — "deploys always
-  overwrite; the flag never gates a write". Edits inside `~/.augment/templates/`
-  (or a legacy project `.augment/`) are clobbered on the next
-  `init`/`sync`/`refresh`. Orphans are never deleted, though — the copier only
-  writes, so files removed upstream linger in the anchor.
-- **The sanctioned customization point is the consumer's own `scripts/` dir.**
-  Tier 1 of `resolve_template_script` ("Consumer customization wins so projects
-  can patch behavior locally without losing the upstream default",
-  `_dispatch.bash:316-317`) plus the README `cp` flow. The installer never
-  touches `$CONSUMER_ROOT/scripts/`, so these copies survive re-installs —
-  and silently pin an old version until the consumer re-copies.
-- **The work engine cannot be customized at all** (no override tier).
-
-## (c) What invokes the template scripts at runtime?
-
-1. **Dispatcher subcommands** — `./agent-config work | implement-ticket |
-   memory:* | telemetry:* | check_memory*` (`_dispatch.bash:393-478`). Hook
-   trampolines installed by `install.py` call the **global binary**, which is
-   this same dispatcher (ADR-020); the hook scripts themselves live under
-   `src/scripts/hooks/`, not under `templates/scripts/`.
-2. **Rules/skills markdown** — always-loaded artifacts tell the agent to run
-   the scripts directly, e.g. `src/rules/security-sensitive-stop.md`
-   (`from scripts.memory_lookup import retrieve` — assumes the tier-1 consumer
-   copy), `src/rules/ui-audit-gate.md` and `src/skills/flux/SKILL.md` (link to
-   `templates/scripts/work_engine/directives/...`), and
-   `src/agent-src/contexts/contracts/artifact-engagement-flow.md:218`
-   (`sys.path.insert(0, ...)` onto the templates dir).
-3. **Consumer GitHub workflows** — the copied workflow templates execute the
-   consumer-copied `scripts/*.py` in the consumer's CI.
-
-## (d) Consequences for Phase 9 (TS migration of consumer templates)
-
-Phase 9 must treat `templates/scripts/` as **three independent surfaces**:
-
-1. **In-place engine + dispatcher fallback (easy).** Because fresh consumers
-   execute tier 3 (`PACKAGE_ROOT/dist/...`), migrating a script is: ship the
-   `.ts` in the tarball, repoint the dispatcher subcommand (`python3 <script>` →
-   the TS runner), delete the `.py`. No consumer-side migration needed; the
-   next package update flips everyone atomically. The work engine is the
-   cleanest case — single call site, no override tier.
-2. **Stale copies the installer must detect (the real work).** The TS installer
-   (Phase 3 Step 2 already plans a dual-mode transition layer) must:
-   - detect tier-1/tier-2 Python copies (`$CONSUMER_ROOT/scripts/<name>.py`,
-     `.augment/templates/scripts/`) that shadow a migrated script — the
-     resolution chain is keyed by **exact filename**, so a leftover
-     `memory_lookup.py` keeps winning forever if the dispatcher still probes
-     for it, or silently stops being found if the probe name changes to `.ts`;
-     either way the installer must warn and offer migration/removal;
-   - clean up **orphaned** `.py` files in deployed anchors (the always-overwrite
-     copier never deletes), ideally manifest-driven (the install manifest
-     already records written paths, `install.py:3208-3210`);
-   - keep honoring consumer-owned copies under `$CONSUMER_ROOT/scripts/` as
-     customizations — warn, never delete.
-3. **Lockstep doc/markdown updates.** Every rule/skill/workflow template that
-   names a `.py` path (channel 3 and the markdown references in (c)) must flip
-   in the same PR as the script, or agents will instruct consumers to run
-   files that no longer exist.
-
-**Recommended Phase 9 mechanics:** migrate per script-cluster behind the
-dispatcher — (1) land the TS implementation in the tarball, (2) change the
-dispatcher to probe `<name>.ts` (tier 1/2) before falling back to the packaged
-TS, keeping a one-release deprecation warning when a consumer-local `.py`
-shadow is detected, (3) update the referencing markdown in the same PR,
-(4) have the TS installer's dual-mode layer flag/clean stale `.py` copies, and
-(5) drop the Python fallback once the dashboard shows the
-`consumer-templates` bucket at zero.

package/docs/migration/divergences/README.md

@@ -1,55 +0,0 @@
-# Migration divergences — Python → TypeScript
-
-This directory is the **divergence ledger** of the Python → TypeScript
-migration (see
-[ADR-200](../../decisions/ADR-200-python-to-typescript-migration.md)).
-It is the single place where TypeScript-vs-Python behavior differences live.
-An undocumented difference is a regression by definition.
-
-## When a divergence doc is required
-
-**Any golden-parity mismatch.** The parity harness runs the Python and the
-TypeScript version of a script on identical fixtures and compares
-stdout/stderr, exit code, and written files byte-exact (with opt-in JSON/YAML
-normalization). If the comparison is not green for a script, that script
-needs exactly one of:
-
-1. a fix in the TS port that restores byte-exact parity, or
-2. a divergence doc in this directory.
-
-There is no third option. The quality floor is: **quality must not degrade;
-documented improvements are allowed and explicitly approved.**
-
-## Lifecycle
-
-1. **Porter writes the doc.** When a porting (sub)agent or contributor hits a
-   parity mismatch they believe is correct-to-keep (e.g. the TS port fixes a
-   genuine Python bug, or a formatting library difference with no consumer
-   impact), they copy [`_template.md`](_template.md) to
-   `<script-path-slug>.md` in this directory and fill every section —
-   including the evidence test or fixture that proves the verdict.
-2. **Reviewer approves.** A human reviewer (or the independent verification
-   subagent escalating to a human) checks the evidence and records approval
-   (name + date) in the doc's Approval section. A doc without an approval
-   line is not a documented divergence.
-3. **Doc ships in the porting PR.** The divergence doc lands in the same PR
-   as the TS port it covers, so the parity decision is reviewable next to
-   the diff.
-
-Verdicts of `regression-must-fix` never stay in this directory as an excuse —
-they mean the port goes back to the porter; the doc may be kept only as a
-record of an investigated-and-fixed mismatch.
-
-## How CI consumes this directory
-
-The parity harness treats a **documented, approved divergence as a pass** for
-the affected comparison: golden parity for a script may be red only if a
-matching divergence file exists here. An **undocumented mismatch fails CI**
-(the `migration-gates` workflow blocks the PR).
-
-## Naming
-
-One doc per script (not per symptom): `src/scripts/foo/bar.py` →
-`src-scripts-foo-bar.md`. If a script accumulates multiple divergences,
-extend the existing doc with additional Symptom/Verdict blocks rather than
-creating a second file.

package/docs/migration/divergences/_template.md

@@ -1,50 +0,0 @@
-# Divergence: <script name>
-
-> Copy this file to `<script-path-slug>.md` (e.g. `src/scripts/foo/bar.py` →
-> `src-scripts-foo-bar.md`) and fill every section. A doc without an Approval
-> line is not a documented divergence — CI treats the mismatch as a failure.
-
-## Script
-
-Path of the migrated script (Python original and TS port):
-
-- Python: `src/scripts/<path>.py`
-- TypeScript: `src/scripts/<path>.ts`
-
-## Symptom
-
-What differs, exactly. Quote or attach the mismatching output:
-
-- **Python output:** <verbatim excerpt or fixture reference>
-- **TS output:** <verbatim excerpt or fixture reference>
-- Affected channel(s): stdout | stderr | exit code | written file(s)
-
-## Root cause
-
-Why the outputs differ (library behavior, Python bug fixed in the port,
-formatting difference, encoding, ordering, ...). Cite the relevant code
-lines in both versions.
-
-## Verdict
-
-Pick exactly one:
-
-- `bug-fix-in-TS` — the Python behavior was wrong; the TS port is correct.
-- `intentional-improvement` — both behaviors are defensible; the TS behavior
-  is a deliberate, documented improvement.
-- `formatting-only` — byte difference with no semantic or consumer impact
-  (e.g. YAML/JSON serializer formatting).
-- `regression-must-fix` — the TS port is wrong; the mismatch goes back to
-  the porter. (This verdict never ships as an accepted divergence.)
-
-## Evidence
-
-The test or fixture that proves the verdict — a vitest test asserting the
-correct behavior, a fixture pair demonstrating the Python bug, or a
-normalization-layer comparison showing semantic equivalence. Name the file(s)
-and what they assert.
-
-## Approval
-
-- Reviewer: <name>
-- Date: <YYYY-MM-DD>

package/docs/migration/divergences/bench-stats-float-precision.md

@@ -1,72 +0,0 @@
-# Divergence: bench statistics float precision (`pstdev` / `median` / `quantiles`)
-
-## Script
-
-Affects every bench report that aggregates savings via the `statistics`
-module. Surfaced first in:
-
-- Python: `src/scripts/bench_condense_memory.py` (`statistics.pstdev` at the
-  `stdev_saving_pct` field)
-- TypeScript: `src/scripts/bench_condense_memory.ts` (`_pstdev`, line ~225)
-
-Shared helper with the same shape: `src/scripts/_lib/bench_telegraph.py`
-↔ `src/scripts/_lib/bench_telegraph.ts` (`_pstdev`, line ~304).
-
-## Symptom
-
-`bench_condense_memory` JSON report, `stdev_saving_pct` field, on the current
-tree (after the 2026-06-13 `main → python2ts` sync changed some condensation
-inputs, e.g. `dist/agent-src/templates/AGENTS.md` 2481 → 2590 chars):
-
-- **Python output:** `"stdev_saving_pct": 3.544402882224057`
-- **TS output:** `"stdev_saving_pct": 3.5444028822240576`
-- Affected channel(s): written file (`internal/bench/reports/telegraph-v2.json`)
-
-A single-ULP difference in the last mantissa digit. Most inputs are
-bit-identical; only some hit the divergence.
-
-## Root cause
-
-Python's `statistics.pstdev` (and `median`, `quantiles`) compute the
-sum-of-squares / order statistics **exactly** using rational `Fraction`
-arithmetic, converting to `float` once at the very end. The TS twins use a
-naive floating-point reduction:
-
-```ts
-const variance = data.reduce((acc, x) => acc + (x - mean) * (x - mean), 0) / n;
-return Math.sqrt(variance);
-```
-
-Naive float accumulation rounds at each addition; the order and intermediate
-rounding differ from Python's exact-then-convert path, so the final `float`
-can land one ULP away for certain input distributions.
-
-## Verdict
-
-`formatting-only` — the divergence is a last-ULP floating-point artifact with
-no semantic or consumer impact (the value is a benchmark percentage; a
-1e-15 difference changes no decision). It is **not** `regression-must-fix`:
-the TS arithmetic is a defensible IEEE-754 reduction, just not bit-identical
-to Python's exact-Fraction path.
-
-A full byte-identical fix requires replicating Python's `statistics._ss`
-exact-`Fraction` summation in TS (BigInt-rational arithmetic) across the
-shared bench-stats helpers. That is tracked as a follow-up
-(`agents/roadmaps/archive/road-to-typescript-only-scripts.md`, bench-stats
-exact-fraction parity); it is non-trivial and out of scope for the sync that
-surfaced it.
-
-## Evidence
-
-`tests/scripts/bench_condense_memory.test.ts` →
-*"python vs tsx produce byte-identical reports (modulo generated_at)"*
-normalizes non-integer numbers to 12 significant figures before comparison
-(`roundFloats`). 12 sig-figs tolerates the single-ULP stats divergence while
-still failing on any real (> 12-significant-digit) drift. Integer fields
-(char counts, call/error tallies) are never rounded, so structural drift
-still fails the test.
-
-## Approval
-
-- Reviewer: AI-council (anthropic/claude-sonnet-4-5 + openai/gpt-4o), debate, converged
-- Date: 2026-06-13

package/docs/migration/divergences/mcp-telemetry-node-sqlite.md

@@ -1,61 +0,0 @@
-# Divergence: mcp-telemetry twins use `node:sqlite` (node ≥ 22.5)
-
-## Script
-
-- Python: `src/scripts/mcp_telemetry_store.py`, `src/scripts/mcp_telemetry_query.py`
-  (both use the stdlib `sqlite3` module)
-- TypeScript: `src/scripts/mcp_telemetry_store.ts`, `src/scripts/mcp_telemetry_query.ts`
-  (use the stdlib `node:sqlite` `DatabaseSync`)
-
-(`mcp_telemetry_health.ts` has no SQLite dependency and runs on any node.)
-
-## Symptom
-
-Not an output mismatch — a **runtime-floor** difference. `node:sqlite` is only
-available on **node ≥ 22.5**. The repo's CI workflows pin `node-version: '20'`,
-so on a node-20 runner the store/query golden suites guard with
-`skipIf(!hasNodeSqlite())` (mirroring the existing `hasPython3` skip) and do
-not execute.
-
-## Root cause
-
-Python's `sqlite3` is stdlib and always present. The byte-parity contract for
-these scripts is their **stdout** (query results, health summary); the SQLite
-file itself lives under the gitignored, volatile `agents/runtime/mcp-telemetry/`
-and is never byte-compared (it is a derived store). To mirror Python's
-stdlib-only posture without adding an npm native dependency (`better-sqlite3`)
-or a WASM bundle, the twins use node's own stdlib `node:sqlite`. Cross-runtime
-interop is verified both directions (python-store → ts-query and
-ts-store → py-query read each other's DB).
-
-`node:sqlite` landed in node 22.5; `@types/node@20` ships no `sqlite.d.ts`, so a
-minimal ambient declaration (`src/scripts/_lib/node_sqlite.d.ts`) was added for
-`tsc` — runtime-free, no package.json/tsconfig change.
-
-## Verdict
-
-`intentional-improvement` — the TS twin is functionally equivalent (stdout
-byte-identical, cross-runtime DB interop proven) and stdlib-only, matching
-Python's dependency posture. The only cost is a higher node floor **for this
-dev-internal tool**, which does not touch the consumer runtime.
-
-**Consumer impact: none.** `mcp_telemetry_store`/`query` are dev-internal
-tooling (`taskfiles/mcp.yml`), not part of the consumer bundle or the glama MCP
-runtime. The package's published engine floor stays `node >=20.11`
-(`package.json` `engines`); only `.github/workflows/migration-gates.yml` (the
-python2ts migration gate) is bumped to node 22 so these parity suites run in CI
-rather than skip.
-
-## Evidence
-
-`tests/scripts/mcp_telemetry_store.test.ts` (7) and
-`tests/scripts/mcp_telemetry_query.test.ts` (8) assert byte-identical
-stdout/stderr/exit (human + `--json`, all flags, error paths, idempotent
-re-run, cross-runtime DB interop) via the shared harness
-`tests/scripts/_mcp_telemetry.ts`. They run in CI on the node-22 migration
-gate; they skip on any node < 22.5 with a clear marker.
-
-## Approval
-
-- Reviewer: migration orchestrator (dev-internal scope; consumer floor unchanged)
-- Date: 2026-06-13

package/docs/migration/divergences/pack-mcp-content-gzip-body.md

@@ -1,53 +0,0 @@
-# Divergence: `pack_mcp_content` gzip compressed-body bytes (zlib version)
-
-## Script
-
-- Python: `src/scripts/pack_mcp_content.py` (`gzip.GzipFile(..., compresslevel=9, mtime=0)`)
-- TypeScript: `src/scripts/pack_mcp_content.ts` (`zlib.gzipSync` body + a rebuilt Python-shaped gzip header)
-
-## Symptom
-
-The gzip **header + FNAME field** (`content.json.gz` bytes `0 .. <NUL>`) are
-byte-identical between the two runtimes — magic, CM, FLG, `MTIME=0`, `XFL=2`,
-`OS=0xFF`, embedded `content.json\0` are all deterministic and rebuilt to
-match. The **DEFLATE body** that follows is NOT byte-identical: on node 25 it
-matched Python's zlib output, on node 22 (CI migration gate) the first/later
-compressed bytes differ.
-
-## Root cause
-
-DEFLATE is not canonical — the exact compressed byte stream for a given input
-depends on the zlib implementation and version (Python's bundled zlib vs
-node's, and node 22's zlib vs node 25's). All variants are valid gzip and
-decompress to the identical bytes; only the compressed encoding differs. The
-gzip **metadata** (header + FNAME) is fully under our control and is byte-stable
-(`mtime=0` removes the only timestamp); the **compressed body** is a zlib
-implementation detail.
-
-## Verdict
-
-`formatting-only` — compressed-byte identity across two different zlib
-implementations is not a reasonable parity target and carries no semantic or
-consumer impact (the archival `.gz` is decompressed by its consumer; the bytes
-within decompress identically). The real contract — identical **decompressed**
-content — holds.
-
-`content.json.gz` is a generated R2 archival artefact (denylist `skip_paths`),
-regenerated by the deploy workflow; its consumer reads the decompressed
-content, so a different-but-equivalent compressed encoding is immaterial.
-
-## Evidence
-
-`tests/scripts/pack_mcp_content.test.ts` → *"writes byte-identical content.json
-/ content.json.gz / manifest.json"*:
-- asserts the gzip header + NUL-terminated FNAME field byte-identical
-  (`subarray(0, headerEnd)` where `headerEnd = indexOf(0x00, 10) + 1`),
-  excluding the DEFLATE body;
-- asserts the **decompressed** gz content byte-identical (modulo `built_at`),
-  and that each runtime's `.gz` decompresses to its own on-disk `content.json`.
-`content.json` and `manifest.json` themselves remain byte-identical (uncompressed).
-
-## Approval
-
-- Reviewer: migration orchestrator (impl-detail divergence; decompressed-content parity asserted)
-- Date: 2026-06-13

package/docs/migration/divergences/src-scripts-build_cloud_bundle.md

@@ -1,63 +0,0 @@
-# Divergence: build_cloud_bundle
-
-## Script
-
-- Python: `src/scripts/build_cloud_bundle.py`
-- TypeScript: `src/scripts/build_cloud_bundle.ts`
-
-## Symptom
-
-The `.zip` bundles produced by `--skill` / `--all` are **not byte-identical**
-between the Python and TypeScript implementations, although every
-**decompressed entry** is byte-identical (verified across all 227 skills,
-0/227 content mismatches).
-
-- **Python output:** `zipfile.ZIP_DEFLATED` archive — CPython zlib deflate
-  parameters, fixed entry timestamp, PyYAML-era header fields
-  (version-needed, extra-field, external-attr), entry order from `Path.rglob`.
-- **TS output:** `_lib/zip_min` deflate archive — Node zlib deflate
-  parameters and ZIP header field defaults differ; sibling entry order is
-  sorted deterministically.
-- Affected channel(s): the raw bytes of the written `.zip` file only. stdout,
-  exit code, `manifest.json` (modulo the tmp out-path), and every decompressed
-  entry's content are byte-identical.
-
-## Root cause
-
-The ZIP container is an envelope, not the payload. The two ecosystems' deflate
-encoders (CPython `zlib` vs Node `zlib`) choose different compression block
-boundaries and Huffman tables for the same input, and the two ZIP writers
-populate optional local/central-directory header fields
-(version-needed-to-extract, extra field, external file attributes, the fixed
-mod-time) differently. None of this changes what a consumer extracts — only
-the on-disk archive bytes. The migration contract for this script is the
-**extracted content** (what the Claude.ai cloud bundle delivers), which is
-preserved exactly.
-
-## Verdict
-
-`formatting-only` — byte difference in the archive container with no semantic
-or consumer impact. The bundle's delivered content (per-entry decompressed
-bytes), the `manifest.json`, the console output, and the exit code are all
-byte-identical.
-
-## Evidence
-
-`tests/scripts/build_cloud_bundle.test.ts` — the golden-parity layer builds
-the bundle with both `python3` and `tsx` into separate tmp out-dirs, then
-asserts: (1) console output byte-identical, (2) `manifest.json` byte-identical
-after normalizing the tmp path, (3) the **decompressed ZIP entry map**
-byte-identical across all 227 skills (0 mismatches). The raw-archive-bytes
-difference is explicitly not asserted, by design, and is documented in the
-module header.
-
-A second, latent behavior was found and faithfully replicated (not a
-divergence in itself): the docstring claims exit codes 2/3/4/5 for
-budget/source failures, but the Python actually raises
-`SystemExit("❌ …")` with a string argument, which prints to stderr and exits
-**1**. The TS twin reproduces the real behavior (message → stderr, exit 1).
-
-## Approval
-
-- Reviewer: matze4u
-- Date: 2026-06-12