@event4u/agent-config 6.1.0 → 7.0.1

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/personas.md

@@ -24,7 +24,7 @@ Removed personas are deleted in-commit (no soak window) — see
 
 Note: `product-owner` was reclassified to **specialist** at v2.0 — see below.
 
-## Catalog — Specialists (opt-in, 18 active)
+## Catalog — Specialists (opt-in, 20 active)
 
 | ID | Role | Wing | Owner | Lens summary |
 |---|---|---|---|---|
@@ -39,6 +39,8 @@ Note: `product-owner` was reclassified to **specialist** at v2.0 — see below.
 | `discovery-lead` | Discovery Lead | — | package | Switch events, falsifiable hypotheses, theme ranking. |
 | `hollywood-director` | Hollywood Director (`ai-video`) | — | package | Live-action lens, lighting, blocking, negative constraints. |
 | `ai-video-technical-director` | AI Video Technical Director (`ai-video`) | — | package | Provider tuning — Veo / Kling / Sora / Higgsfield / OpenAI grammar. |
+| `brand-strategist` | Brand Strategist (`design`) | — | package | Positioning, archetype, voice, messaging; challenges weak briefs. |
+| `design-director` | Design Director (`design`) | — | package | Art-direction and brand-aligned visual judgment; composition, hierarchy, vector-vs-raster. |
 | `cmo` | CMO | 3 | package | Positioning anchored, messaging stacked, launches sequenced. |
 | `growth-pm` | Growth PM | 3 | package | Leaky-bucket vs growth-loop classified, activation correlated. |
 | `customer-success-lead` | Customer Success Lead | 3 | package | TTFV falsifiable, churn cause split, expansion pulled, NRR. |
@@ -53,6 +55,7 @@ Note: `product-owner` was reclassified to **specialist** at v2.0 — see below.
 | Domain | Active specialists | Within cap |
 |---|---|---|
 | `ai-video` | `hollywood-director`, `ai-video-technical-director` | ✅ 2/2 |
+| `design` | `brand-strategist`, `design-director` | ✅ 2/2 |
 | GTM (Wing 3) | `cmo`, `growth-pm`, `customer-success-lead`, `revops` | ✅ (wing, not domain) |
 | Ops / Money (Wing 4) | `engineering-manager`, `people-strategist`, `finance-partner`, `strategist` | ✅ (wing, not domain) |
 | Backend | `backend-architect`, `eloquent-tamer` | ✅ 2/2 |
@@ -131,6 +134,8 @@ slot. Current cite map:
 | `eloquent-tamer` | `eloquent`, `database` |
 | `security-engineer` | `judge-security-auditor`, `threat-modeling`, `authz-review` |
 | `frontend-engineer` | `existing-ui-audit`, `fe-design` |
+| `brand-strategist` | `brand`, `brand-strategy` |
+| `design-director` | `brand-identity`, `logo-generation`, `brand-asset-generation` |
 
 Add a citation by appending `personas: [<id>]` to the skill's
 frontmatter — never overwrite an existing list, append.

package/docs/role-experiences.md

@@ -0,0 +1,19 @@
+# Role experiences — taglines at a glance
+
+> **Generated** by `scripts/generate_role_experiences_catalog.py` from
+> `agents/roles/<role>/index.md` — do NOT hand-edit. Taglines are the
+> existing role-level strings (validated by `lint_role_experiences.py`,
+> rendered in the GUI workspace); this page surfaces them in a catalog.
+
+Each row links to the full role experience (persona · three first tasks ·
+packs). The catalog never duplicates the body — see
+[`docs/contracts/role-experience.md`](contracts/role-experience.md).
+
+| Role | Tagline | Status |
+|---|---|---|
+| [Consultant / advisor](../agents/roles/consultant/index.md) | Client briefs, investor memos, and deck outlines — refined before the meeting, not rewritten after. | `beta-internal` |
+| [Content creator](../agents/roles/content-creator/index.md) | From a one-line idea to a stitched short — voice-locked, character-locked, provider-agnostic. | `beta-internal` |
+| [Galabau owner](../agents/roles/galabau/index.md) | Drafting customer offers and project briefs without a project manager between you and the document. | `beta-internal` |
+| [Team leader](../agents/roles/leadership/index.md) | Summarise weekly status, write the risk memo, structure the decision before the meeting. | `beta-internal` |
+| [Sales rep](../agents/roles/sales/index.md) | Answer customer questions, draft offers, and prep discovery calls — voice-locked, structured, fast. | `beta-internal` |
+| [Support agent](../agents/roles/support/index.md) | Summarise the ticket, draft the reply, flag the escalation — without rewriting the customer's words. | `beta-internal` |

package/docs/setup/per-ide/windsurf.md

@@ -99,7 +99,7 @@ should match `ls .windsurf/workflows/`.
 | Rules not picked up | Windsurf < 1.0 — upgrade or rely on `.windsurfrules`. |
 | Workflow not in Cascade panel | Reload window after `task generate-tools`. |
 | Global workflows missing | Check `~/.codeium/windsurf/global_workflows/` exists. |
-| Frontmatter parse error | Re-run `python3 scripts/condense.py --generate-tools`. |
+| Frontmatter parse error | Re-run `./scripts-run src/scripts/condense --generate-tools`. |
 
 ## Cross-references