@event4u/agent-config 6.0.0 → 7.0.0

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

@@ -0,0 +1,65 @@
+# Divergence: inventory_abstraction_budget
+
+## Script
+
+- Python: `src/scripts/inventory_abstraction_budget.py`
+- TypeScript: `src/scripts/inventory_abstraction_budget.ts`
+
+## Symptom
+
+In the generated `frontmatter.csv` / Markdown audit table, the
+`dominant_value` column can differ between the Python and TypeScript runs
+**on rows where the top frequency is shared by two or more values** (a
+top-frequency tie). All other columns — `class`, `field`, `total`,
+`distinct`, `dominant_share`, `bloat_candidate` — are byte-identical.
+
+- Observed (CI, ext4): `fm row 5 col 4` — Python `4`, TS `3`.
+- Not observed locally (macOS APFS) — the two filesystems happened to
+  iterate the source files in the same order, so the tie resolved to the
+  same value.
+- Affected channel(s): the `dominant_value` cell only, and only on
+  rows whose `dominant_share` ≤ 50% (no strict majority → a tie is
+  possible).
+
+## Root cause
+
+`dominant_value` is `Counter.most_common(1)[0]` in Python — among the
+max-count group it returns the **first-inserted** value, and insertion
+order is the file-iteration order. Python `Path.glob("**/*.md")` returns
+files in **unsorted OS `readdir` order**; the TS twin's `_globPattern`
+sorts (`out.sort()`). When a field has two values tied at the top count,
+the "first-inserted" winner depends on that file order, so the sorted-TS
+order and the unsorted-Python order can pick different tied values.
+
+This is **unreconcilable**, not a port bug: Python's own glob order is
+OS-nondeterministic, so two Python runs on different filesystems can
+already disagree on the same tie. Forcing the TS twin to sort does not
+help (Python is unsorted); forcing it to read unsorted would still not
+reliably reproduce CPython's recursive-glob traversal order across
+runtimes. Every other derived value (the counts, the share, the bloat
+flag) is order-independent and stays byte-identical.
+
+## Verdict
+
+`formatting-only` — the byte difference is confined to a single
+display-label column that is inherently OS-iteration-order-dependent in
+the Python original itself. No count, share, or bloat-candidate decision
+changes. The column that the script exists to drive (`bloat_candidate`,
+gated on `dominant_share > 0.95`) is unaffected, because a >95% share is a
+strict majority and therefore never tied.
+
+## Evidence
+
+`tests/scripts/inventory_abstraction_budget.test.ts` — the golden-parity
+suite asserts `inventory.csv` byte-identical, and for `frontmatter.csv`
+compares every column byte-identical **except** `dominant_value` on rows
+without a strict majority (`dominant_share` ≤ 50%, where a top tie is
+possible). On rows with `dominant_share > 50%` the dominant value is
+provably unique and IS compared. The Markdown table comparison
+independently permits a per-line divergence only in the `dominant_value`
+cell (pipe-cell index 5) and asserts every other cell identical.
+
+## Approval
+
+- Reviewer: matze4u
+- Date: 2026-06-12

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

@@ -0,0 +1,57 @@
+# Divergence: lint_marketplace
+
+## Script
+
+- Python: `src/scripts/lint_marketplace.py`
+- TypeScript: `src/scripts/lint_marketplace.ts`
+
+## Symptom
+
+One byte-level mismatch, confined to the malformed-`marketplace.json` path
+where the message embeds the language's native JSON-parser error text:
+
+- **Python output:** `❌  .claude-plugin/marketplace.json is not valid JSON: Expecting property name enclosed in double quotes: line 1 column 3 (char 2)`
+- **TS output:** `❌  .claude-plugin/marketplace.json is not valid JSON: Expected property name or '}' in JSON at position 2 (line 1 column 3)`
+- Affected channel(s): stdout
+
+Every other case (valid repo, missing file, missing field, version mismatch,
+nonexistent / SKILL.md-less / duplicate skill paths, empty plugins, missing
+owner email, reverse-drift, completeness exemptions) is byte-identical.
+
+## Root cause
+
+The Python original catches `json.JSONDecodeError` and renders `str(exc)`,
+which is CPython's hand-written decoder message
+(`Expecting property name enclosed in double quotes: line L column C (char N)`).
+The TypeScript port catches the `JSON.parse` `SyntaxError` and renders
+`e.message`, which is V8's decoder message
+(`Expected property name or '}' in JSON at position N (line L column C)`).
+The two decoders disagree on wording, position vs. char offset, and clause
+order for the same malformed input. Reproducing CPython's exact decoder
+message in TS would require porting CPython's `json.scanner` state machine
+verbatim — out of scope and of no consumer value: the message is a debugging
+hint appended to the stable `… is not valid JSON: ` prefix, which is the
+actual contract (alongside exit code 1). Mirrors the same cross-language
+parser-error-text divergence already accepted for `check_memory`
+(YAML parse-error class name).
+
+## Verdict
+
+`formatting-only` — the byte difference is a debugging-hint suffix with no
+semantic or consumer impact. The stable `… is not valid JSON: ` prefix and the
+exit code (1) are preserved; both are what callers and tests assert on.
+
+## Evidence
+
+- The TS twin `tests/scripts/lint_marketplace.test.ts` runs python3 and tsx in
+  the same tmp cwd and asserts **byte-identical** stdout/stderr/exit for every
+  fixture **except** the malformed-JSON one, where it asserts the stable
+  contract (exit 1 + the `is not valid JSON` prefix on both) per this doc.
+- The real-repo golden-parity case (the live CI invocation, which has a valid
+  `marketplace.json`) is byte-identical.
+
+## Approval
+
+Approved as a Phase-4 documented divergence. Permanent — it stems from the
+cross-language JSON-decoder error taxonomy, the same class as the accepted
+`check_memory` YAML divergence.

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

@@ -0,0 +1,70 @@
+# Divergence: lint_mcp_registry_manifest
+
+## Script
+
+- Python: `src/scripts/lint_mcp_registry_manifest.py`
+- TypeScript: `src/scripts/lint_mcp_registry_manifest.ts`
+
+## Symptom
+
+**Conditional, latent divergence — not reached on the real repo.** Golden
+parity (python3 vs tsx, no-arg and `--quiet`) is byte-identical today, because
+`dist/mcp/` is absent in this worktree, so both versions short-circuit on the
+first artefact check and emit:
+
+- stderr: `❌  missing: dist/mcp/registry-manifest.json`
+- exit: 1
+
+The only branch where the two versions *would* differ is the schema-validation
+failure message, which fires solely on a **structurally invalid** manifest
+(after all four `dist/mcp/*` artefacts exist):
+
+- **Python output:** `❌  schema validation: <jsonschema e.message> at <list(e.absolute_path)>`
+  — wording produced by `jsonschema.Draft202012Validator`.
+- **TS output:** `❌  schema validation: <subset-validator message> at [<path…>]`
+  — wording produced by the hand-rolled Draft-2020-12 subset validator in the
+  TS port.
+- Affected channel(s): stderr (only on an invalid manifest)
+
+The stable prefix `schema validation: ` and the surrounding control flow
+(which artefact is checked, in what order, the exit code 1, the `❌  `
+glyph + two-space prefix) are identical. Only the embedded
+validator-specific error string and the `at [...]` path rendering can differ.
+
+## Root cause
+
+Python uses `jsonschema.Draft202012Validator(schema).validate(manifest)` and
+formats `f"schema validation: {e.message} at {list(e.absolute_path)}"`. The TS
+runtime has only `ajv` v6 (Draft-07) available — it cannot evaluate a
+Draft-2020-12 schema with `jsonschema`-identical diagnostics. Following the
+established Wave-4b pattern (`src/scripts/lint_discovery_manifest.ts`), the TS
+port ships a faithful Draft-2020-12 **subset** validator that ACCEPTS every
+valid manifest (the golden path) but renders rejection messages in its own
+wording. Matching `jsonschema`'s per-keyword English message text + Python
+`repr` of the instance + `list(absolute_path)` rendering byte-for-byte is out
+of scope and provides no consumer value (the manifest is generated, so an
+invalid manifest is a build bug surfaced equally by either version).
+
+## Verdict
+
+`intentional-improvement` — both behaviors reject an invalid manifest with a
+non-zero exit and a `schema validation: …` stderr line; the TS wording is a
+deliberate, documented substitute for the unavailable Draft-2020-12
+`jsonschema` diagnostics. The accept/reject decision (the consumer-relevant
+behavior) is preserved.
+
+## Evidence
+
+- `tests/scripts/lint_mcp_registry_manifest.test.ts`:
+  - the behavioural-spec block asserts the subset validator ACCEPTS a fully
+    valid manifest and REJECTS each malformed shape (wrong `version` const,
+    missing required key, unknown additional property, bad `status` enum,
+    `< minItems` registries) — i.e. the accept/reject contract holds.
+  - the golden-parity block asserts byte-identical stdout + stderr + exit on
+    the real repo for both the no-arg and `--quiet` invocations (the
+    `missing:` branch), proving no actual mismatch ships today.
+
+## Approval
+
+- Reviewer: <pending>
+- Date: <pending>

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

@@ -0,0 +1,60 @@
+# Divergence: spotcheck_thin_root
+
+## Script
+
+- Python: `src/scripts/spotcheck_thin_root.py`
+- TypeScript: `src/scripts/spotcheck_thin_root.ts`
+
+## Symptom
+
+The entire `main()` is a **live AI-council call** (Anthropic `claude-sonnet-4-5`
++ OpenAI `gpt-4o`) that requires API keys + network access and produces a
+**non-deterministic** report — per-call `latency_ms` and `tokens_in/out` vary
+every run, and the model prose is not reproducible. There is therefore no
+golden-parity path: python3 vs tsx output cannot be byte-compared, and the
+script cannot run inside CI.
+
+- Affected channel(s): written files (`thin-root-platform-spotcheck.md` /
+  `.json`) + stderr (`Running …`, `✅  Wrote …`).
+
+## Root cause
+
+The Python original imports three still-Python `ai_council` modules with no TS
+twin in this wave:
+
+- `ai_council.clients` — `AnthropicClient`, `OpenAIClient`,
+  `load_anthropic_key`, `load_openai_key` (~1,385 lines, network clients).
+- `ai_council.orchestrator` — `CostBudget`, `CouncilQuestion`, `consult`
+  (~1,206 lines).
+- `ai_council.pricing` — `load_prices` (ported as `ai_council/pricing.ts`).
+
+A `.ts` cannot import a `.py`, and the "PORT + import, never inline the
+un-ported logic" rule forbids re-implementing those ~2,800 lines of
+network-calling code inside this twin. Per the established precedent for
+un-ported Python deps (`check_discovery_determinism.ts` runs its un-ported
+scanner via `python3`; `smoke_quickstart.ts` Step 3 imports `decision_engine`
+via a `python3` shim), the TS twin delegates the live `consult(...)` call to a
+`python3` shim that imports the real Python modules. The deterministic parts —
+artefact assembly, the `json.dumps(indent=2)` writer, the Markdown report
+layout, the stderr lines — are ported faithfully in TS.
+
+## Verdict
+
+`intentional-improvement` — both behaviors are defensible; the TS twin
+preserves the byte-shape of the written report and the stderr surface while
+running the unportable, non-deterministic, network-bound council step through
+the still-Python modules. Porting the two large network clients is out of this
+wave's scope and tracked separately.
+
+## Evidence
+
+`tests/scripts/spotcheck_thin_root.test.ts` asserts the module imports without
+a top-level throw and exposes the `main` entry point (the deterministic CLI
+surface). The live council path (network + keys) is excluded from CI by
+construction — there is no fixture that could pin a non-deterministic
+LLM-latency report.
+
+## Approval
+
+- Reviewer: <pending — porting subagent, Wave 8h>
+- Date: 2026-06-13

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

@@ -0,0 +1,58 @@
+# Divergence: validate_agent_settings
+
+## Script
+
+- Python: `src/scripts/validate_agent_settings.py`
+- TypeScript: `src/scripts/validate_agent_settings.ts`
+
+## Symptom
+
+Only the **error-message prose** of a schema violation can differ. The exit
+code, the GitHub `::error file=…::<loc>:` location prefix, the violation
+count, the summary line, and the clean-pass line are byte-identical.
+
+- **Python output (violation):** `::error file=…::rule_loading_tier: 'lean' is not one of ['minimal', 'balanced', 'full', 'custom']`
+  — the trailing clause is produced verbatim by the `jsonschema` library and
+  is Python-version-dependent.
+- **TS output (violation):** same `::error file=…::rule_loading_tier:` prefix
+  and field path; the enum/type clause is reproduced by a minimal Draft-07
+  validator (`_iter_errors`) and may differ in exact wording from a given
+  `jsonschema` release.
+- Affected channel(s): stdout (only the prose tail of a violation line).
+
+## Root cause
+
+The Python script delegates message text to `jsonschema.Draft7Validator`,
+whose `ValidationError.message` wording is not a stable contract (it has
+changed across `jsonschema` releases). The package ships no `ajv`/jsonschema
+dependency for the TS side and `package.json` is frozen for this wave, so the
+twin implements the exact constraint subset the shared schema uses (`type`
+object/string, string `enum`, `properties`, permissive `additionalProperties:
+true`) and approximates the message text. Per ADR-200 §4 the parity contract
+for schema-validation findings is **exit code + flagged field-paths**, not
+byte-exact jsonschema prose.
+
+## Verdict
+
+`formatting-only` — the constraint set, the violating field path, the error
+location prefix, the violation count, and both summary lines match exactly;
+only the human-readable enum/type clause may differ, with no semantic or
+consumer impact (CI greps the `::error file=…::<loc>:` location, not the tail).
+
+## Evidence
+
+- `tests/scripts/validate_agent_settings.test.ts` asserts: every valid
+  `rule_loading_tier` accepted; an out-of-enum value rejected **at the
+  `['rule_loading_tier']` path** with a message naming the allowed values;
+  the legacy `cost_profile` key tolerated (shipped reality); nested enums
+  (`memory.cadence`, `model.auto_switch`, `worktrees.mode`) enforced at the
+  correct paths.
+- Golden parity: the same test runs `python3 validate_agent_settings.py` vs
+  `tsx validate_agent_settings.ts` on the real repo and asserts stdout, stderr,
+  and exit code are byte-identical (the clean repo never triggers a violation
+  line, so the only golden-parity surface is the OK summary — byte-identical).
+
+## Approval
+
+- Reviewer: <pending — porting subagent, ADR-200 Phase 4 / Wave 4c>
+- Date: 2026-06-11

package/docs/migration/node-floor.md

@@ -0,0 +1,86 @@
+# Node Floor Audit
+
+> Phase 1 Step 12 of `agents/roadmaps/road-to-typescript-only-scripts.md`.
+> Decision: which Node.js floor the TS-only script suite supports, where it is
+> enforced, and what CI tests.
+
+## Facts (as audited 2026-06-11, branch feat/py2ts-phase1-infra)
+
+| Surface | Value | Source |
+|---|---|---|
+| `engines.node` | `>=20.11.0` | `package.json:53-55` |
+| tsconfig target | `ES2022` (`module: ESNext`, `moduleResolution: Bundler`) | `tsconfig.json:3-5` |
+| tsconfig lib | `ES2022` (+ `DOM` in `tsconfig.ui.json:4`, `tsconfig.test.json:6`) | tsconfig files |
+| CI — tests.yml | Node `20` | `.github/workflows/tests.yml:241` |
+| CI — release-drift.yml | Node `20` | `.github/workflows/release-drift.yml:44` |
+| CI — publish-npm.yml | Node `20` | `.github/workflows/publish-npm.yml:48` |
+| CI — smoke-public-install.yml | matrix `node: ['20', '22']` × 3 OS | `smoke-public-install.yml:78-80` |
+| CI — deploy-mcp-worker.yml | Node `22` | `deploy-mcp-worker.yml:68` |
+| `engine-strict` | not set (no `.npmrc`) — `engines` is advisory only | repo root |
+| Installer Node check | none today (Python installer never inspects `process.version`) | grep of `src/scripts/install*`, `setup.sh` |
+
+Feature scan of `src/` TypeScript (sampled, not exhaustive):
+
+- `node:` protocol imports — 34 files (Node ≥ 16; trivially within floor).
+- Global `fetch` in Node-side code — `src/server/token.ts` (stable without flag
+  since Node 18, marked stable in 21; fine on ≥ 20.11).
+- No hits for `structuredClone`, top-of-module top-level `await`,
+  `Array.prototype.at(-…)`, `Object.hasOwn`, `findLast` in `src/` TS.
+- Browser-only `fetch` usage (`src/ui/api.ts`) is covered by the `DOM` lib, not
+  the Node floor.
+
+Conclusion of the scan: nothing in the current TS code requires more than
+Node 18; the ES2022 compile target is the binding constraint and is fully
+served by every Node ≥ 18.12. The floor question is therefore a **support
+lifecycle** decision, not a syntax one.
+
+## Recommendation
+
+**Raise the floor to Node `>=22.0.0` as part of the TS-only migration; test
+22 (minimum) and 24 (current LTS) in CI.** Keep `>=20.11.0` only until the
+first major/breaking release of the migration lands, then flip — the bump is a
+semver-major signal per the package's versioning policy.
+
+## Rationale
+
+- **Node 20 is end-of-life.** Its maintenance window ended April 2026. A
+  migration that will ship through 2026/27 should not anchor its floor on a
+  line that no longer receives security fixes; keeping it implies supporting
+  consumers on an unpatched runtime.
+- **Node 22 (maintenance LTS) and 24 (active LTS) are the 2026 reality.** CI
+  already runs 22 in two workflows; the smoke matrix already proves installs
+  on 22. Raising the floor to 22 costs no code changes (the feature scan shows
+  no >ES2022 usage to add or remove) and removes a dead line from the matrix.
+- **Consumer compatibility risk is low and visible.** The package is a dev-time
+  tool invoked via `npx`/global install, not a production runtime dependency.
+  Consumers still on Node 20 get a clear, immediate failure at install time
+  (see Enforcement) rather than a latent one.
+- **Why not 24 as the floor:** 24 only entered LTS in late 2025; many CI images
+  and corporate baselines still pin 22. Floor = oldest non-EOL LTS (22),
+  matrix-test up to current LTS (24).
+
+## Enforcement points
+
+1. **`package.json` `engines`** — flip to `">=22.0.0"` at the breaking release.
+   Advisory only without `engine-strict`; npm prints a warning, pnpm/yarn fail
+   harder. Do **not** set `engine-strict` repo-wide (it would also bind
+   maintainers); rely on point 2 for the hard gate.
+2. **TS installer runtime check (the hard gate).** Phase 3 Step 2 already
+   requires "Node-version check with a clear error": the TS installer must
+   compare `process.versions.node` against the floor on startup and fail with
+   an actionable message before writing anything. This is the enforcement the
+   Python installer never had — it must land with the TS installer.
+3. **CI matrix** — pin the floor and the current LTS:
+   - `smoke-public-install.yml`: `node: ['22', '24']` (replacing `['20', '22']`).
+   - `tests.yml` / `release-drift.yml` / `publish-npm.yml`: bump single-version
+     jobs `20` → `22`; add a `24` leg to `tests.yml` if budget allows.
+4. **Docs** — README Quickstart and `docs/getting-started.md` state the floor
+   explicitly ("requires Node 22+"); CHANGELOG `### Breaking` entry +
+   `BREAKING_CHANGES.md` index the bump per the versioning policy.
+
+## Decision status
+
+Recommended here; the `engines` flip itself is release-gated (semver-major)
+and should ride the first breaking release of the TS migration, not this
+infra PR. Until then `>=20.11.0` stays in `package.json`, and CI keeps one
+Node 20 leg solely to honor the published floor.

package/docs/migration/yaml-roundtrip-spike.md

@@ -0,0 +1,163 @@
+# YAML Round-Trip Spike — Verdict
+
+> Phase 1 Step 7 of `agents/roadmaps/road-to-typescript-only-scripts.md`.
+> Originally framed as a "ruamel.yaml → npm `yaml`" risk. The survey below
+> shows that framing was wrong: there is **no ruamel usage anywhere** — the
+> comment-preserving round-trip layer is `src/scripts/sync_yaml_rt.py`, a
+> **self-contained, stdlib-only, hand-written narrow-subset parser**, and it
+> ports 1:1 to TypeScript with no external library.
+
+## 1. Usage survey
+
+Grep surface: `src/scripts/` + `src/agent-src/templates/scripts/` for
+`import yaml`, `from yaml`, `ruamel`, `safe_load`, `safe_dump`,
+`yaml.load`, `yaml.dump` (2026-06-11, branch `feat/py2ts-phase1-infra`).
+
+| Category | Files | What it is |
+|---|---:|---|
+| (a) `sync_yaml_rt` own parser | 1 (+2 consumers) | `src/scripts/sync_yaml_rt.py` — stdlib-only round-trip parser/emitter/merger for `.agent-settings.yml`. Consumed by `src/scripts/sync_agent_settings.py` and `src/scripts/_cli/cmd_settings_check.py`. |
+| (b) PyYAML read-only consumers | 90 | 81 under `src/scripts/` + 9 under `src/agent-src/templates/scripts/`. All `safe_load` only — frontmatter readers, settings readers, linters, manifest loaders. |
+| (c) PyYAML writers (`safe_dump`) | 6 | Listed below — these risk formatting drift on port. |
+| (d) ruamel users | **0** | Verified: `grep -rn ruamel` over both trees → no hits. The council's "ruamel showstopper" has no code behind it. |
+
+Mention-only matches (not consumers): `audit_cloud_compatibility.py`
+(regex pattern for a linter), `render_value_md.py` / `render_benchmark_md.py`
+(local helper functions named `safe_load` that read JSON, not YAML).
+
+### Category (c) — the six writer scripts, explicitly
+
+| Script | What it dumps | Drift risk |
+|---|---|---|
+| `src/scripts/new_skill.py` | New-skill frontmatter block (`sort_keys=False, allow_unicode=True`) | New files only — no existing bytes to preserve. Low. |
+| `src/scripts/move_artefact.py` | Rewritten artefact frontmatter after a move (`sort_keys=False, allow_unicode=True`) | Touches existing frontmatter — PyYAML's quote/wrap style differs from `yaml.stringify`. **Flag for its port phase.** |
+| `src/scripts/generate_pack_manifests.py` | Generated pack-manifest YAML (`sort_keys=True`, deterministic header) | Generated output with goldens — port must match or goldens regenerate once. **Flag.** |
+| `src/scripts/measure_projection_bytes.py` | Temporary rewrite of `agents/.agent-tools.yml`, restored on exit | Transient file, restored from the original string. Low. |
+| `src/scripts/config/session_profiles.py` | Whole `.agent-settings.local.yml` overlay (atomic write) | Gitignored per-machine file, machine-managed (no user comments preserved today either). Low-medium. |
+| `src/scripts/ai_council/compile_corpus.py` | Deterministic corpus lock YAML (`dump_lock_yaml`, `width=10_000`) | Determinism is asserted by tests — port must reproduce or the lock format is re-baselined once. **Flag.** |
+
+## 2. Spike results
+
+### 2.1 `sync_yaml_rt` 1:1 port (`tests/spikes/yaml_rt_spike.ts`)
+
+The core round-trip property (parse → emit reproduces every user line
+character-for-character) was ported to TypeScript — ~430 lines, **zero
+dependencies**, mirroring the Python module function-for-function
+(tokeniser, inline-comment splitter honouring quote boundaries, mapping/
+list line parsers, indent-stack tree builder, verbatim emitter).
+
+Fixture corpus: `tests/spikes/fixtures/yaml-rt/` — 12 fixtures derived
+from the documented subset and from the `src/config/agent-settings.template.yml`
+shape (synthetic/generic values):
+
+| Fixture | Nasty case covered |
+|---|---|
+| `01-basic-mapping.yml` | 2-space block mapping, header comment |
+| `02-inline-comments.yml` | inline comments after values, comment-only values, `#` inside quotes |
+| `03-blank-line-runs.yml` | multi-blank-line runs, trailing comment + blank |
+| `04-block-list.yml` | block lists, item inline comments, bare `-` item |
+| `05-inline-flat-list.yml` | inline flat lists `[a, b, c]`, empty `[]` |
+| `06-four-space-indent.yml` | 4-space indent |
+| `07-crlf.yml` | CRLF-terminated file |
+| `08-duplicate-keys.yml` | duplicate keys, last-wins |
+| `09-quoted-scalars.yml` | quoted scalars, `~`/`null`/`None`, bools, quoted key with `:` |
+| `10-agent-settings-shape.yml` | real template shape (comment banners, nested sections, list) |
+| `11-no-trailing-newline.yml` | final line without terminator |
+| `12-deep-nesting-mixed.yml` | deep nesting, comments between siblings |
+
+Differential test (`tests/spikes/yaml_rt_spike.test.ts`, 31 tests, green):
+
+- **Round-trip property:** for every fixture except the duplicate-keys one,
+  TS `emit(parse(x)) === x` byte-for-byte (CRLF and missing-final-newline
+  included).
+- **Differential parity:** for **all 12** fixtures, TS output is
+  byte-identical to the Python reference output
+  (`tests/spikes/yaml_rt_py_driver.py` → `sync_yaml_rt.parse`/`emit`).
+- **Duplicate keys** are round-trip *lossy by design* in **both**
+  implementations identically: last wins, the earlier line and its leading
+  comment block are dropped; the result is idempotent. (Verified against
+  Python: `'a: 1\na: 2\nb: 3\n'` → `'a: 2\nb: 3\n'` on both sides.)
+- **Error parity** spot-checked: tabs in indent and inconsistent dedent
+  ("over-indent") raise on both sides; mixed per-line EOLs are preserved.
+
+### 2.2 PyYAML readers → npm `yaml` (`tests/spikes/pyyaml_vs_npm.test.ts`)
+
+Representative real files — `Taskfile.yml`, `taskfiles/engine.yml`,
+`src/config/agent-settings.template.yml`, `.github/workflows/consistency.yml`
+— parsed with PyYAML `safe_load` and with npm `yaml` (`YAML.parse`),
+canonicalised to sorted compact JSON on both sides: **semantically equal**
+(5 tests, green).
+
+Two load-bearing findings for the production port:
+
+1. **YAML version pin.** PyYAML implements YAML 1.1: `on:` (workflow files)
+   resolves to boolean `true`, `yes`/`off` are booleans. npm `yaml`
+   defaults to YAML 1.2 (those stay strings). Every PyYAML replacement
+   must pass `{ version: '1.1' }` to keep semantics identical. Without
+   the pin, the workflow fixture fails.
+2. Non-string keys (boolean `true` from `on:`) must be canonicalised the
+   same way on both sides when comparing (Python dict key `True` ↔ JS
+   object key `"true"`); with that, equality holds.
+
+## 3. Verdict
+
+- **Comment-preserving round-trip = self-contained 1:1 port of
+  `sync_yaml_rt.py`. NO external library needed.** The council's
+  "ruamel.yaml has no npm equivalent" showstopper is **moot** — ruamel is
+  used nowhere, and the actual round-trip layer is a hand-written
+  stdlib-only parser whose core property has now been reproduced
+  byte-for-byte in TypeScript against a 12-fixture differential corpus.
+- **PyYAML read-only consumers (90 files) → npm `yaml` with
+  `{ version: '1.1' }`.** Semantic equality verified on real repo files.
+- **PyYAML writers (6 files) → npm `yaml` `stringify`,** with a
+  formatting-drift review in each script's own port phase. `new_skill.py`
+  and `measure_projection_bytes.py` are low-risk (new/transient output);
+  `move_artefact.py`, `generate_pack_manifests.py`,
+  `compile_corpus.py` (and to a lesser degree `session_profiles.py`)
+  emit bytes that other tooling or goldens see — handle any
+  PyYAML-vs-`yaml.stringify` style differences as documented divergences
+  (`docs/migration/divergences/`) or one-time golden re-baselines.
+
+## 4. What the production port (Phase 5) must cover beyond the spike
+
+The spike ports **`parse` + `emit` only**. The production
+`sync_yaml_rt.ts` additionally needs:
+
+1. **`merge(user, template)`** — additive merge: insert-position logic
+   honouring user reordering, blank-line separator insertion for
+   top-level sections, EOL normalisation of cloned template subtrees
+   (`_detect_eol`, `_normalize_line_endings`, `_ensure_blank_separator`,
+   `_find_insert_pos`).
+2. **`heal_user_block(user, template)`** — legacy `_user._user.foo`
+   corruption healer: leaf collection with `_user`-segment stripping,
+   re-homing into template paths, orphan rebuild, idempotency.
+3. **`sync(user_text, template_text)`** — the pipeline entry point
+   (parse → heal → merge → emit).
+4. **Synthetic-node rendering** under merge (the spike includes
+   `renderSyntheticHeader` but no caller exercises it — production tests
+   must).
+5. **Full error-message parity or documented divergence** — the Python
+   `ValueError` strings (line numbers included) are user-visible via
+   `sync_agent_settings.py` / `cmd_settings_check.py`; decide verbatim
+   parity vs. documented divergence.
+6. **The existing Python test suite as the conformance oracle** —
+   `tests/test_sync_agent_settings.py`, `tests/test_sync_round_trip.py`
+   and friends should be mirrored (or run differentially, as in this
+   spike) until the Python side is deleted.
+7. **Lone-`\r` line endings** — Python `splitlines` recognises more
+   terminators (`\v`, `\f`, `\x1c`…) than the spike's `\n`/`\r\n`/`\r`
+   splitter. The spike handles `\r`; the exotic terminators are outside
+   the documented subset — confirm and document as a divergence.
+
+## 5. Verification evidence
+
+```
+npx vitest run tests/spikes/
+
+ ✓ tests/spikes/pyyaml_vs_npm.test.ts (5 tests)
+ ✓ tests/spikes/yaml_rt_spike.test.ts (31 tests)
+
+ Test Files  2 passed (2)
+      Tests  36 passed (36)
+```
+
+Environment: node v25.9.0, npm `yaml` 2.9.0, python3 3.9.6, PyYAML 6.0.3.

package/docs/parity/bench-external.json

@@ -0,0 +1,58 @@
+{
+  "schema": "parity-bench-external-v1",
+  "status": "infrastructure_ready_awaiting_corpus_run",
+  "owner_roadmap": "agents/roadmaps/step-11-external-parity.md",
+  "parity_doc": "docs/parity/external.md",
+  "parent_bench": "docs/parity/bench.json",
+  "claim_under_test": {
+    "source": "agents/evidence/audits/2026-05-14-north-star/external-findings.md § 2",
+    "headline": "Average dollar cost per 25-prompt corpus run, separated by model tier (Haiku / Sonnet / Opus) and by token class (input / output / cache-read / cache-write).",
+    "comparison_target": "external cost-tracker README (claimed upstream, not yet pulled into this repo)",
+    "type": "claimed_upstream_not_verified_in_repo"
+  },
+  "measurement_protocol": {
+    "corpus": "internal/bench/corpus/* (25-prompt corpus owned by step-4-measurement-and-benchmark.md)",
+    "tracker": "scripts/cost/track.mjs",
+    "pricing": "internal/bench/pricing.yaml",
+    "session_source": "~/.claude/projects/*/sessions/*.jsonl (Claude Code-native, no manual tracking)",
+    "tokens_to_dollars": "track.mjs multiplies input/output/cache-read/cache-write tokens by per-1M pricing from internal/bench/pricing.yaml, separated by model id",
+    "headline_output": "average dollar cost per 25-prompt run, with min / max / p50 / p90 across N reports"
+  },
+  "current_window": {
+    "report_count": 0,
+    "verdict": "awaiting_first_corpus_run",
+    "notes": "Phase 1-5 of step-11 delivered the cost-tracking and bench infrastructure. Phase 6 Step 2 awaits the first end-to-end 25-prompt corpus run against the live tracker. Until then this file exists as a methodology contract, not a verdict surface."
+  },
+  "soak_inheritance": {
+    "follows": "docs/parity/bench.json",
+    "min_days": 60,
+    "min_reports": 30,
+    "earliest_flip": "2026-07-15",
+    "arbiter_command": "task bench:baseline-ready",
+    "notes": "bench-external.json flips status to 'baseline_ready' only after the parent bench.json flips. No independent soak window — same corpus, same arbiter."
+  },
+  "redundancy_verdict": {
+    "status": "pending",
+    "criterion": "Once bench.json soak completes, this verdict is set by comparing the dollar cost in current_window vs the external runtime's published table.",
+    "outcome_branches": {
+      "redundant": "Our cost-per-25-prompt-run sits within the external runtime's published range (or beats it). G5 redundancy gate row for cost surface flips green.",
+      "behind": "Our cost-per-run > the external runtime's. Follow-up issue filed; G5 stays open."
+    }
+  },
+  "fields_pending_first_run": [
+    "current_window.avg_cost_per_run_usd",
+    "current_window.cost_by_model.haiku_usd",
+    "current_window.cost_by_model.sonnet_usd",
+    "current_window.cost_by_model.opus_usd",
+    "current_window.cost_by_class.input_usd",
+    "current_window.cost_by_class.output_usd",
+    "current_window.cost_by_class.cache_read_usd",
+    "current_window.cost_by_class.cache_write_usd"
+  ],
+  "decisions_pending": {},
+  "_meta": {
+    "created": "2026-05-16",
+    "created_by": "step-11-external-parity.md Phase 6 Step 2",
+    "spec": "scripts/cost/track.mjs --bench-external (planned wiring); for now the file is a methodology contract"
+  }
+}