arkaos 2.22.1 → 2.28.0

package/core/specs/SPEC-installer-cross-os.md

@@ -0,0 +1,227 @@
+---
+type: spec
+status: approved
+feature: installer-cross-os
+project: ArkaOS
+version: 2.24.0
+pr: PR2 of 6 (Conclave roadmap 2026-05-13)
+branch: feature/v2.24.0-installer-cross-os
+date_created: 2026-05-13
+tags: [spec, arkaos, installer, cross-os, v2.24.0, conclave-pr2]
+---
+
+# SPEC: Installer Cross-OS Completo (v2.24.0)
+
+## Overview
+
+**Problem.** ArkaOS installer is ~65 % cross-OS complete. Obsidian is never auto-installed (only path-detected). Node.js is never validated. `install.sh` hardcodes the GitHub repo URL on line 25 and only scans macOS paths for Obsidian vaults on lines 625–640.
+
+**Goal.** Deliver a full cross-OS install flow (macOS / Linux / Windows) that auto-installs what it can without sudo, reports what needs sudo with copy-paste-ready commands, and falls back gracefully when no package manager is available.
+
+**Actors.** End users running `npx arkaos install` on fresh macOS / Linux / Windows machines; CI pipelines running headless.
+
+## Scope
+
+**In scope (PR2 / v2.24.0):**
+
+| Item | Purpose |
+|---|---|
+| new `installer/package-manager.js` | brew / winget / snap / apt / choco detection + install helpers |
+| new `installer/system-tools.js` | `ensureSystemTools()` phase: Obsidian, Node.js ≥ 20, Python ≥ 3.12 |
+| modify `installer/index.js` | call `ensureSystemTools()` before venv creation |
+| modify `installer/update.js` | re-run `ensureSystemTools()` on `npx arkaos update` |
+| modify `installer/cli.js` | new `npx arkaos doctor` subcommand + `--no-system` flag |
+| new `installer/doctor.js` | diagnose-only report (table format, exit codes 0/1/2) |
+| modify `install.sh` line 25 | `ARKAOS_REPO_URL` env override (default canonical URL) |
+| modify `install.sh` lines 625-640 | add Linux + Windows vault detection |
+| modify `installer/index.js` dashboard step | `pnpm install` / `npm ci` in `dashboard/` if Node ≥ 20 |
+| new `tests/installer/test_package_manager.mjs` | ≥ 10 Node tests |
+| new `tests/installer/test_system_tools.mjs` | ≥ 5 Node tests |
+
+**Out of scope:**
+
+- Auto-update of system tools when newer versions exist (just detect + report).
+- Flatpak / AppImage Obsidian variants on Linux (defer to PR6 cleanup if user demand).
+- Interactive sudo prompt (André chose "print command for manual run" — headless-safe).
+- Aggressive auto-install (André chose hybrid: install what can be installed without sudo; report rest).
+
+## Acceptance Criteria
+
+1. **Fresh macOS install.** Given a Mac without Obsidian, when `npx arkaos install` runs, then `brew install --cask obsidian` is invoked (or printed if brew missing) and Obsidian binary is detected on completion.
+
+2. **Fresh Ubuntu install.** Given Ubuntu without Obsidian / Node, when `npx arkaos install` runs, then the installer prints copy-paste commands like:
+   ```
+   To finish install, run:
+     sudo apt update && sudo apt install -y nodejs
+     sudo snap install obsidian --classic
+   Then re-run: npx arkaos install
+   ```
+   and exits with code 0 (informational, not a failure).
+
+3. **Fresh Windows 11.** Given Windows without Obsidian / Node, when `npx arkaos install` runs, then it invokes `winget install --id Obsidian.Obsidian --silent` (and similar for Node), or prints the command if elevation is denied.
+
+4. **`npx arkaos doctor`.** Given any state, when `npx arkaos doctor` runs, then it prints a table with Obsidian / Node / Python rows showing installed/version/location/action, with exit code 0 (all OK), 1 (missing), or 2 (version mismatch).
+
+5. **`install.sh` GitHub URL configurable.** Given `ARKAOS_REPO_URL=https://gitlab.example.com/x/y.git` is set, when `install.sh` runs in curl|bash mode, then it clones from the custom URL.
+
+6. **`install.sh` Linux vault detection.** Given Ubuntu user with vault at `~/.local/share/obsidian/vault` OR `~/Documents/Obsidian`, when `install.sh` runs vault auto-detection, then both candidate paths are scanned.
+
+7. **`install.sh` Windows vault detection.** Given Git Bash on Windows with vault at `$USERPROFILE/Documents/Obsidian`, when `install.sh` runs vault auto-detection, then the path is scanned.
+
+8. **`--no-system` flag.** Given `npx arkaos install --no-system`, when installer runs, then `ensureSystemTools()` is bypassed (legacy install-only flow preserved for CI).
+
+9. **Idempotent.** Given `ensureSystemTools()` has already installed everything, when it runs again, then no install commands fire, no side effects, exit success.
+
+10. **Regression-free.** Given PR2 merges, when full pytest suite runs, then all 3049 tests still pass. New Node tests add ≥ 15 cases for package-manager + system-tools.
+
+11. **shellcheck clean.** Given the updated `install.sh`, when `shellcheck install.sh` runs, then zero new warnings vs baseline.
+
+## Data Model
+
+N/A — pure installer logic, no persisted schema changes.
+
+## API Contracts
+
+### `installer/package-manager.js`
+
+```javascript
+/**
+ * Detect the highest-priority package manager available on this host.
+ *
+ * Priority order:
+ *   macOS:   brew
+ *   Linux:   apt > snap (apt for Node, snap for Obsidian classic-confined)
+ *   Windows: winget > choco
+ *
+ * Returns the canonical name string or null when nothing is available.
+ */
+export function detectPackageManager(): string | null
+
+/**
+ * Install a single package via the detected (or specified) manager.
+ * Never invokes sudo automatically. When sudo is required, returns
+ * the command for the caller to print and the user to run.
+ */
+export function installViaPackageManager(
+  pkg: string,
+  options?: { manager?: string, fallbackUrl?: string }
+): {
+  success: boolean,
+  command: string,           // command that ran or should run
+  needsSudo: boolean,
+  installed: boolean,        // did we actually install in this call?
+  fallbackOpened?: boolean,  // did we open the download URL?
+  error?: string,
+}
+
+/** Format an array of missing-package commands into copy-paste text. */
+export function formatSudoInstructions(missing: SudoCommand[]): string
+```
+
+### `installer/system-tools.js`
+
+```javascript
+export type ToolStatus = {
+  name: "obsidian" | "node" | "python",
+  installed: boolean,
+  version?: string,
+  location?: string,
+  needsAction: "none" | "install" | "upgrade",
+  suggestedCommand?: string,
+  needsSudo?: boolean,
+}
+
+/**
+ * Check each required system tool. Install what can be installed without
+ * sudo. Collect commands for tools that need sudo into `sudoCommands`
+ * so the caller can print them to the user.
+ *
+ * Idempotent: tools already installed at sufficient version are no-ops.
+ */
+export function ensureSystemTools(options?: {
+  skipSystem?: boolean,
+  dryRun?: boolean,
+}): {
+  obsidian: ToolStatus,
+  node: ToolStatus,
+  python: ToolStatus,
+  sudoCommands: string[],
+}
+
+export function checkObsidian(): ToolStatus
+export function checkNode(): ToolStatus
+export function checkPython(): ToolStatus
+```
+
+### `installer/doctor.js`
+
+```javascript
+/**
+ * `npx arkaos doctor` — diagnose-only report. Never installs.
+ * Returns exit code 0 (all OK), 1 (missing tool), 2 (version mismatch).
+ */
+export function runDoctor(): number
+```
+
+### CLI integration
+
+`installer/cli.js` gains:
+- `npx arkaos doctor` subcommand → calls `runDoctor()`
+- `--no-system` global flag → sets `options.skipSystem = true` for `ensureSystemTools()`
+
+## Edge Cases
+
+1. **brew not installed on macOS** → print Homebrew install one-liner, exit 0 with informational message.
+2. **snap available but `obsidian` not in store** (older Ubuntu) → fall back to `https://obsidian.md/download` opened in browser, or printed for headless.
+3. **Windows < 1809 without winget** → choco fallback, or printed download URL.
+4. **Node installed but version < 20** → `needsAction: "upgrade"`, suggested command per OS.
+5. **Multiple Python versions present** → prefer 3.12+, recommend `pyenv` if mixed.
+6. **User installed Obsidian via Flatpak** → detect via `flatpak list md.obsidian` (best-effort), accept as installed.
+7. **Concurrent installer runs** → checks read filesystem only; install commands themselves are idempotent (apt/brew/winget handle already-installed packages gracefully).
+8. **curl|bash mode** → `install.sh` clones repo first; `ARKAOS_REPO_URL` env wins over hardcoded default; supports private fork redirection.
+9. **Sudo denied** on Windows winget → print the command and ask user to re-run from an elevated prompt; do not loop or retry.
+10. **Headless CI** → `--no-system` flag skips entirely; `arka doctor` exit codes drive CI decisions.
+11. **Network failure during install** → catch, report, exit with copy-paste recovery command.
+
+## Test Scenarios
+
+| # | Scenario | Type | Expected |
+|---|---|---|---|
+| 1 | `detectPackageManager` on macOS w/ brew | Unit | `"brew"` |
+| 2 | `detectPackageManager` on Ubuntu w/ apt+snap | Unit | `"apt"` (then `"snap"` for Obsidian-specific calls) |
+| 3 | `detectPackageManager` on Windows w/ winget | Unit | `"winget"` |
+| 4 | `detectPackageManager` on Linux w/ none | Unit | `null` |
+| 5 | `checkObsidian` when binary in PATH | Unit | `installed: true, location: <path>` |
+| 6 | `checkObsidian` when binary missing | Unit | `installed: false, needsAction: "install"` |
+| 7 | `checkNode` when version < 20 | Unit | `needsAction: "upgrade"` |
+| 8 | `checkNode` when version ≥ 20 | Unit | `needsAction: "none"` |
+| 9 | `checkPython` when 3.11 only | Unit | `needsAction: "upgrade"` |
+| 10 | `ensureSystemTools` w/ all 3 missing | Integration | `sudoCommands` array populated |
+| 11 | `ensureSystemTools` idempotent | Integration | second call: no commands |
+| 12 | `runDoctor` exit codes | Integration | 0 / 1 / 2 verified |
+| 13 | `install.sh` with `ARKAOS_REPO_URL` override | Manual / shell | clones from custom URL |
+| 14 | `install.sh` Linux vault detection | Manual / shell | finds `~/.local/share/obsidian/...` |
+| 15 | `install.sh` Windows vault detection | Manual / shell | finds `$USERPROFILE/Documents/Obsidian` |
+| 16 | `--no-system` flag bypass | Integration | `ensureSystemTools` not called |
+| 17 | full pytest regression | Integration | 3049 still pass |
+
+## Dependencies
+
+- `installer/platform.js` (existing) — `IS_WINDOWS`, `CMD_FINDER`, `PYTHON_CMD`.
+- `installer/path-resolver.js` (PR1) — for any path template substitution.
+- `installer/python-resolver.js` (existing) — Python detection logic.
+- Node.js `node:child_process` for `execSync` (already used).
+- No new npm deps.
+
+## Quality Gate Criteria
+
+- **Eduardo:** all error / status messages read naturally in EN; copy-paste sudo commands are accurate and OS-specific; no AI clichés.
+- **Francisca:** package-manager detection covers macOS/Ubuntu/Debian/Fedora/Arch/Windows 10+/11; `ensureSystemTools()` is fully idempotent; no shell injection vectors in execSync calls; shellcheck clean on install.sh.
+- **Marta:** verified on 3 synthetic environments — macOS with brew, Ubuntu without snap, Windows with winget — each producing the right printed commands and side effects.
+
+## References
+
+- Plan: `~/.arkaos/plans/2026-05-13-arkaos-next-level-conclave.md` (PR2 section)
+- Memory: [[project_next_level_conclave]]
+- Existing: [[SPEC-paths-portability]] (PR1, dependency), [[platform.js]] (platform abstraction)
+- HIGH items inherited from PR1 audit: `install.sh:25`, `install.sh:625-640`

package/core/specs/SPEC-paths-portability.md

@@ -0,0 +1,209 @@
+---
+type: spec
+status: approved
+feature: paths-portability
+project: ArkaOS
+version: 2.23.0
+pr: PR1 of 6 (Conclave roadmap 2026-05-13)
+branch: feature/v2.23.0-paths-portability
+date_created: 2026-05-13
+date_updated: 2026-05-13
+tags: [spec, arkaos, paths, portability, refactor, v2.23.0, conclave-pr1]
+---
+
+# SPEC: Paths Portability (v2.23.0)
+
+## Overview
+
+**Problem.** ArkaOS source contains hardcoded user-specific paths (`/Users/andreagroferreira/...`) across SKILL.md files, JSON configs, Python regexes, and cognitive prompts. These break for the **~20K users** currently running ArkaOS with different home directories and OS layouts.
+
+**Goal.** Replace 7 CRITICAL hardcoded paths with profile-driven templates resolved at runtime, with **non-breaking auto-migration** for the existing user base.
+
+**Actors.** ArkaOS core (skill loader, cognition collector, installer migration), end users (via `~/.arkaos/profile.json`).
+
+## Scope
+
+**In scope (PR1 / v2.23.0):**
+
+| # | File | Fix |
+|---|---|---|
+| 1 | `knowledge/obsidian-config.json:6` | `vault_path` value resolved at load via `path_resolver.resolve_dict` (profile.vaultPath) |
+| 2 | `core/cognition/capture/collector.py:15-17` | Regex generated from `profile.projectRoots`; fallback `os.getcwd()` |
+| 3 | `departments/kb/skills/knowledge/SKILL.md:25` | `${VAULT_PATH}` template |
+| 4 | `departments/ops/skills/operations/SKILL.md:59` | `${VAULT_PATH}` template |
+| 5 | `arka/skills/comfyui/SKILL.md:22-23` + `references/workflows.md` | `${ARKA_OS_REPOS}/{purz-comfyui-workflows,lora_tester}` |
+| 6 | `config/cognition/prompts/dreaming.md` | `${VAULT_PATH}` template |
+| 7 | `config/cognition/prompts/research.md` | `${VAULT_PATH}` template |
+| 8 | `departments/dev/skills/scaffold/SKILL.md:19` | `${GIT_HOST}` template, default `github.com` HTTPS |
+| — | new `core/runtime/path_resolver.py` | `resolve()`, `resolve_dict()`, `load_profile()` |
+| — | new `installer/migrations/v3_path_schema.js` | Auto-migrate `projectsDir` text → `projectRoots` list + `reposRoot` |
+| — | skill loader extension | Substitute `${VAR}` tokens at SKILL.md load |
+| — | new `tests/python/test_path_resolver.py` | ≥ 15 tests |
+
+**Out of scope (deferred):**
+
+- `install.sh:25, 631-634` (GitHub URL hardcode + Mac-only Obsidian detection) → **PR2 v2.24.0** (cross-OS installer is the natural home for OS-aware logic)
+- 50+ docs/superpowers/plans hardcoded paths (LOW priority, examples only) → **PR6 v2.28.0** cleanup pass
+- Vision bridge migration (test_vision_bridge.py + scripts/tools/vision/*) → file was discarded; not relevant to PR1
+- Migration of installed user skills under `~/.claude/skills/arka/` — installer rewrites these from source on every update; fixing source covers it
+
+## Acceptance Criteria
+
+1. **Zero CRITICAL grep hits.** Given a fresh checkout of `feature/v2.23.0-paths-portability`, when `grep -rn "/Users/andreagroferreira" core/ arka/ installer/ config/ departments/ knowledge/ --exclude-dir=node_modules --exclude-dir=__pycache__ --exclude-dir=.git --exclude-dir=docs` runs, then it returns **0 CRITICAL hits**. Hits inside `docs/superpowers/plans/` are tracked but acceptable (PR6 cleanup).
+
+2. **Synthetic install works end-to-end.** Given `$HOME=/tmp/testuser` and `~/.arkaos/profile.json` containing `{"version":"3","vaultPath":"/tmp/testuser/vault","reposRoot":"/tmp/testuser/repos","projectRoots":["/tmp/testuser/code"]}`, when every SKILL.md is loaded, then `${VAULT_PATH}`, `${ARKA_OS_REPOS}` and `${GIT_HOST}` resolve to the configured values with zero `${` leakage.
+
+3. **20K-user safe migration.** Given a legacy profile.json missing `projectRoots` and `reposRoot`, when `npx arkaos@latest update` runs, then:
+   - `projectRoots` is derived from parsing `projectsDir` text (regex extracts absolute paths).
+   - If parsing finds 0 paths, sensible defaults are applied (`["~/Herd","~/Work","~/AIProjects"]`).
+   - `reposRoot` defaults to `~/AIProjects` (or first match containing `AIProjects` if any).
+   - `version` bumps to `"3"`, `migrated_at` timestamp added.
+   - A `.bak-<timestamp>` backup is written first.
+   - `[arka:migrated] profile.json schema v2 → v3` logged.
+
+4. **Hard error on truly missing profile.** Given `~/.arkaos/profile.json` is absent or unparseable JSON, when any `path_resolver` call runs, then `ProfileMissingError("Run /arka setup to configure ArkaOS paths")` is raised. No silent fallback.
+
+5. **Env-var override.** Given `ARKAOS_VAULT_PATH=/tmp/override` is set, when `${VAULT_PATH}` is resolved, then the env var wins over profile. Same for `ARKAOS_REPOS_ROOT`, `ARKAOS_PROJECT_ROOTS`, `ARKAOS_GIT_HOST`. Empty string is treated as unset.
+
+6. **Regression-free.** Given PR1 is merged, when full pytest suite runs, then all existing 542+ tests pass and ≥ 15 new path_resolver tests pass. Coverage ≥ 80%.
+
+7. **Migration idempotent.** Given migration ran once, when it runs again, then profile.json is unchanged (no version re-bump, no second backup).
+
+## Data Model
+
+| Field (new in profile.json v3) | Type | Default | Source |
+|---|---|---|---|
+| `version` | `"3"` (str) | — | bumped by migration |
+| `projectRoots` | `list[str]` | `["~/Herd","~/Work","~/AIProjects"]` | parsed from `projectsDir` text on migration |
+| `reposRoot` | `str` | `"~/AIProjects"` | matches first path containing `AIProjects`, else default |
+| `migrated_at` | ISO8601 `str` | — | written at migration time |
+
+**Backwards-compat fields kept verbatim:** `language`, `market`, `role`, `company`, `projectsDir` (kept for human reference), `vaultPath`, `created`, `updated`.
+
+## API Contracts
+
+### `core/runtime/path_resolver.py`
+
+```python
+class ProfileMissingError(RuntimeError):
+    """Raised when ~/.arkaos/profile.json is absent or unparseable."""
+
+@dataclass
+class ProfileV3:
+    version: str
+    vault_path: str          # ${VAULT_PATH}
+    repos_root: str          # ${ARKA_OS_REPOS}
+    project_roots: list[str] # ${PROJECT_ROOTS}
+    raw: dict                # full profile.json for forward-compat
+
+def load_profile() -> ProfileV3:
+    """Load and cache ~/.arkaos/profile.json. Raises ProfileMissingError."""
+
+def resolve(template: str) -> str:
+    """Substitute known tokens. Unknown tokens pass through unchanged.
+
+    Tokens:
+      ${VAULT_PATH}      -> ARKAOS_VAULT_PATH env or profile.vaultPath
+      ${ARKA_OS_REPOS}   -> ARKAOS_REPOS_ROOT env or profile.reposRoot
+      ${PROJECT_ROOTS}   -> os.pathsep-joined profile.projectRoots
+      ${GIT_HOST}        -> ARKAOS_GIT_HOST env or "github.com"
+      ${HOME}            -> os.path.expanduser("~")
+    """
+
+def resolve_dict(d: dict) -> dict:
+    """Recursively resolve string values in a JSON-shaped dict."""
+
+def project_root_regex() -> re.Pattern:
+    """Compile regex from profile.projectRoots for collector.py."""
+```
+
+### Skill loader extension
+
+Find existing skill loader (likely `core/agents/loader.py` or `arka/skills/.../loader`); extend:
+
+```python
+def load_skill_markdown(path: Path) -> str:
+    return path_resolver.resolve(path.read_text())
+```
+
+### Migration script `installer/migrations/v3_path_schema.js`
+
+```javascript
+function migrateV3(profile) {
+  if (profile.version === "3" || profile.projectRoots) return profile;
+  const roots = parseProjectsDirText(profile.projectsDir);
+  const reposRoot = roots.find(r => r.includes("AIProjects")) || "~/AIProjects";
+  return { ...profile, version: "3", projectRoots: roots,
+           reposRoot, migrated_at: new Date().toISOString() };
+}
+```
+
+Wired into `installer/migrate-user-data.js` (existing framework).
+
+## Edge Cases
+
+1. **`projectsDir` text is empty / null** → defaults applied (no error).
+2. **`vaultPath` empty string** → treated as missing → `ProfileMissingError`.
+3. **SKILL.md contains literal `${SOME_BASH_VAR}` for agent instructions** → resolver only touches the 5 known tokens; unknown tokens pass through.
+4. **Windows path separators in `${PROJECT_ROOTS}`** → uses `os.pathsep` (`;` on Windows, `:` on Unix). Internal storage is POSIX `/`.
+5. **Digest path from foreign OS** (cross-machine Obsidian sync) → `_detect_project` falls back to `os.getcwd()` if no `projectRoots` match (existing behaviour).
+6. **Concurrent calls during migration** → migration uses temp-file + atomic rename; safe.
+7. **User edits profile.json manually mid-session** → load_profile is cached per-process; re-import to refresh. Documented.
+8. **Migration corrupts profile** → `.bak-<timestamp>` rollback file always exists.
+
+## Test Scenarios
+
+| # | Scenario | Type | Expected |
+|---|---|---|---|
+| 1 | `resolve("${VAULT_PATH}/foo")` with `vaultPath="/v"` | Unit | `"/v/foo"` |
+| 2 | `resolve("${HOME}/bar")` | Unit | `"$HOME/bar"` expanded |
+| 3 | `resolve("${UNKNOWN}/baz")` | Unit | `"${UNKNOWN}/baz"` unchanged |
+| 4 | `resolve` with absent profile.json | Unit | `ProfileMissingError` |
+| 5 | `resolve` with `ARKAOS_VAULT_PATH=/x` | Unit | env wins over profile |
+| 6 | `resolve_dict` on obsidian-config.json fixture | Unit | All string values resolved |
+| 7 | `_detect_project` with `projectRoots=["~/Herd"]` | Unit | matches path under `~/Herd` |
+| 8 | `_detect_project` on Windows-style path | Unit | matches with `\` separator |
+| 9 | `load_skill_markdown` on kb SKILL.md | Integration | `${VAULT_PATH}` substituted |
+| 10 | full pytest suite | Regression | all 542+ tests pass |
+| 11 | `migrateV3` on legacy profile (v2 schema) | Integration | new fields added, old kept, .bak written |
+| 12 | `migrateV3` idempotent (second run no-op) | Integration | profile unchanged, no second .bak |
+| 13 | Grep audit (CRITICAL paths) | Audit | 0 hits in core/ arka/ installer/ config/ departments/ knowledge/ |
+| 14 | `scaffold SKILL.md ${GIT_HOST}` | Integration | `github.com` default |
+| 15 | `comfyui SKILL.md ${ARKA_OS_REPOS}` | Integration | substituted correctly |
+| 16 | `migrateV3` with empty `projectsDir` | Unit | defaults applied, no crash |
+| 17 | env vars with empty string values | Unit | treated as unset, profile wins |
+
+## Dependencies
+
+- No external deps. Reuses existing `installer/migrate-user-data.js` framework + `core/specs/` Living Specs engine.
+- New Python module only depends on stdlib (`json`, `os`, `pathlib`, `re`, `dataclasses`).
+
+## Migration Plan for 20K Users
+
+`npx arkaos@latest update` runs `migrate-user-data.js` which includes the new `migrateV3` step. Flow:
+
+1. Read `~/.arkaos/profile.json`. If absent → skip migration (user must run `/arka setup`).
+2. If `version === "3"` or `projectRoots` exists → no-op (idempotent).
+3. Otherwise:
+   - Write backup: `~/.arkaos/profile.json.bak-<unix-timestamp>`.
+   - Parse `projectsDir` text with `/((?:\/Users|\/home|[A-Z]:\\Users)\/\S+?\/(?:Herd|Work|AIProjects|code|repos))/g`.
+   - Apply defaults if parsing yields 0 results.
+   - Atomic write: temp file + `fs.rename`.
+   - Log `[arka:migrated] profile.json schema v2 → v3 ({N} roots, repos=...)` to `~/.arkaos/logs/migrate.log`.
+
+**Rollback procedure (documented in installer):** restore `.bak-<timestamp>` over profile.json.
+
+## Quality Gate Criteria
+
+Marta (CQO) requires APPROVED from all three reviewers:
+
+- **Eduardo (Copy):** All SKILL.md files read naturally after substitution — no `${` leakage in human-facing prose. Error messages clear and actionable.
+- **Francisca (Tech):** path_resolver handles all 8 edge cases. Migration is atomic + idempotent + reversible. 17 test scenarios all green. No crash on corrupt profile.
+- **Marta (CQO):** Migration verified non-breaking by simulating 5 different legacy profile shapes (André's current one + 4 synthetic variants representing common 20K-user variations).
+
+## References
+
+- Plan: `~/.arkaos/plans/2026-05-13-arkaos-next-level-conclave.md` (PR1 section)
+- Memory: [[project_next_level_conclave]]
+- KB: [[2026-04-29-claude-code-2-1-122-and-2-1-123]] (Claude Code features unblocked by 2.1.122)
+- Existing Specs in this project: [[SPEC-cognitive-layer-feedback-loop]], [[SPEC-wave1-single-source-of-truth]]

package/departments/brand/agents/design-ops/design-ops-lead.yaml

@@ -0,0 +1,78 @@
+id: design-ops-lead-iris
+name: Iris
+role: Design Ops Lead
+department: brand
+tier: 1
+model: sonnet
+
+parent_squad: brand
+sub_squad_role: lead
+
+behavioral_dna:
+  disc:
+    primary: D
+    secondary: C
+    communication_style: "Direct, blueprint-driven, defends production quality without smothering creative intent"
+    under_pressure: "Pushes back on shortcuts; protects the design system from drift"
+    motivator: "A design system that ships consistently across every surface"
+  enneagram:
+    type: 8
+    wing: 9
+    core_motivation: "Make the right thing also be the easy thing for designers and engineers"
+    core_fear: "Inconsistent UI shipped because nobody owned the production rails"
+    subtype: self-preservation
+  big_five:
+    openness: 60
+    conscientiousness: 88
+    extraversion: 52
+    agreeableness: 55
+    neuroticism: 28
+  mbti:
+    type: ESTJ
+
+mental_models:
+  primary:
+    - "Atomic Design (Frost)"
+    - "Design Tokens W3C Spec"
+    - "Single Source of Truth (Wheeler)"
+  secondary:
+    - "Theory of Constraints (Goldratt)"
+    - "Cynefin (Snowden)"
+    - "WCAG 2.2 AA"
+
+authority:
+  orchestrate: true
+  approve_quality: true
+  delegates_to:
+    - extraction-script-writer
+    - wcag-auditor
+    - shadcn-padronizer
+  escalates_to: brand-director-valentina
+
+expertise:
+  domains:
+    - design tokens (JSON + CSS variables)
+    - component libraries (shadcn/ui, Radix, Headless UI)
+    - design system governance
+    - figma → code pipelines
+    - accessibility compliance (WCAG 2.2 AA/AAA)
+    - cross-platform tokenisation (Style Dictionary, Tailwind)
+  frameworks:
+    - Atomic Design (Frost)
+    - Design Tokens Community Group
+    - WCAG 2.2
+    - Style Dictionary
+    - shadcn/ui conventions
+    - Tailwind CSS configuration
+  depth: master
+  years_equivalent: 12
+
+communication:
+  language: en
+  tone: "precise, blueprint-driven, low-drama"
+  vocabulary_level: advanced
+  preferred_format: "tables, JSON specs, before/after diffs"
+  avoid:
+    - "design by feel without a token spec"
+    - "ad-hoc one-off components"
+    - "shipping without accessibility audit"

package/departments/brand/agents/design-ops/extraction-script-writer.yaml

@@ -0,0 +1,74 @@
+id: extraction-script-writer-nia
+name: Nia
+role: Design Extraction Engineer
+department: brand
+tier: 2
+model: sonnet
+
+parent_squad: brand
+sub_squad_role: extraction-script-writer
+
+behavioral_dna:
+  disc:
+    primary: C
+    secondary: D
+    communication_style: "Investigative, evidence-first, writes the script before opining"
+    under_pressure: "Goes deeper into the source; refuses to guess"
+    motivator: "Reproducible extraction pipelines that turn a live site into structured tokens"
+  enneagram:
+    type: 5
+    wing: 6
+    core_motivation: "Understand a design system well enough to rebuild it from primitives"
+    core_fear: "Shipping a tokenisation that looks right but is silently wrong"
+    subtype: self-preservation
+  big_five:
+    openness: 78
+    conscientiousness: 82
+    extraversion: 35
+    agreeableness: 50
+    neuroticism: 30
+  mbti:
+    type: INTP
+
+mental_models:
+  primary:
+    - "Design Tokens W3C Spec"
+    - "Unix Philosophy (Pike & Kernighan)"
+    - "Reverse-Engineering Discipline"
+  secondary:
+    - "AST-based code analysis"
+    - "CSS Specificity Model"
+    - "Color Theory (Albers)"
+
+authority:
+  orchestrate: false
+  approve_quality: false
+  delegates_to: []
+  escalates_to: design-ops-lead-iris
+
+expertise:
+  domains:
+    - CSS extraction (computed styles, custom properties)
+    - color palette reverse-engineering from screenshots / live DOM
+    - typography token harvesting (font-family, size, weight, line-height scales)
+    - spacing and grid token inference
+    - figma file parsing
+    - chromium-headless capture pipelines
+  frameworks:
+    - W3C Design Tokens spec
+    - Style Dictionary
+    - Tailwind CSS token format
+    - shadcn/ui CSS variable convention
+    - DTCG JSON schema
+  depth: expert
+  years_equivalent: 9
+
+communication:
+  language: en
+  tone: "concise, citation-heavy, almost terse"
+  vocabulary_level: advanced
+  preferred_format: "JSON specs, before/after color swatches, script snippets"
+  avoid:
+    - "guessing token values without inspecting the source"
+    - "exposing hardcoded RGB instead of named tokens"
+    - "premature opinions on visual quality (that's brand-director territory)"

package/departments/brand/agents/design-ops/shadcn-padronizer.yaml

@@ -0,0 +1,76 @@
+id: shadcn-padronizer-leo
+name: Leo
+role: Component Library Padronizer
+department: brand
+tier: 2
+model: sonnet
+
+parent_squad: brand
+sub_squad_role: shadcn-padronizer
+
+behavioral_dna:
+  disc:
+    primary: C
+    secondary: I
+    communication_style: "Pattern-oriented, shows the canonical component before refactoring"
+    under_pressure: "Stays in the design system; refuses to fork components for one-offs"
+    motivator: "A shadcn/ui-shaped library that every project in the org can adopt verbatim"
+  enneagram:
+    type: 1
+    wing: 9
+    core_motivation: "One canonical component, used everywhere, evolving cleanly"
+    core_fear: "Five teams shipping five Button components that diverge over a quarter"
+    subtype: social
+  big_five:
+    openness: 65
+    conscientiousness: 84
+    extraversion: 50
+    agreeableness: 58
+    neuroticism: 30
+  mbti:
+    type: ISTP
+
+mental_models:
+  primary:
+    - "shadcn/ui composition philosophy"
+    - "Headless UI patterns (Radix, React Aria)"
+    - "Atomic Design (Frost)"
+  secondary:
+    - "Tailwind CSS configuration"
+    - "CVA (class-variance-authority) variants"
+    - "Theming via CSS variables"
+
+authority:
+  orchestrate: false
+  approve_quality: false
+  delegates_to: []
+  escalates_to: design-ops-lead-iris
+
+expertise:
+  domains:
+    - shadcn/ui component generation and customisation
+    - Radix UI primitives integration
+    - Tailwind configuration and theme tokens
+    - CVA variants and slot patterns
+    - dark mode and theme switching
+    - component API surface design (props, slots, polymorphic components)
+    - migration from MUI / Chakra / Ant Design to shadcn
+  frameworks:
+    - shadcn/ui
+    - Radix UI
+    - React Aria (Adobe)
+    - Tailwind CSS
+    - class-variance-authority
+    - tailwind-merge
+  depth: expert
+  years_equivalent: 8
+
+communication:
+  language: en
+  tone: "code-first, pragmatic, mild humour"
+  vocabulary_level: advanced
+  preferred_format: "tsx snippets, before/after component diffs, migration guides"
+  avoid:
+    - "rebuilding a primitive that Radix already ships"
+    - "inline styles that bypass the theme tokens"
+    - "magic numbers in className strings"