diff --git a/docs/KIMI-ONBOARDING.md b/docs/KIMI-ONBOARDING.md new file mode 100644 index 00000000..e0c49cf8 --- /dev/null +++ b/docs/KIMI-ONBOARDING.md @@ -0,0 +1,115 @@ +# KIMI-ONBOARDING — Kimi's routing doc into WorldOS + +> Written 2026-07-20 by the Kimi orchestrator after a full 8-agent recon sweep. +> **Status: tracked — landed via PR #1624 (closes issue #1623).** It is the Kimi-side entry point; Claude-side agents +> can read it as-is. +> **Decision (owner-asked):** we *use and link to* the existing Claude-side documentation — it is live-edited +> within days, so duplicating it would stale immediately. This file is routing + interop glue only. + +--- + +## 1. Where everything lives + +| Thing | Path / identity | Notes | +|---|---|---| +| Canonical checkout | `/Users/lume/WorldOS` | GitHub `electricsheephq/WorldOS`; local branch **`base` tracks `origin/main`**; tip `fd23e972` (dress_focal v2 / #1621, 2026-07-16) | +| Live worktrees | `/Users/lume/WorldOS-worktrees/` (same dir as lowercase spelling, case-insensitive APFS) | `wt-owner-play` — owner's play copy, branch `main` @ `c8a0b155`, **`.worldos-keep` = never touch**; behind main → `git pull --ff-only origin main` BEFORE any owner reseed (schema-skew class, OPERATIONS.md). `walk-gate-hardening` — clean, @ `92edf8d7`, looks merged; only its owning lane may prune it | +| Stale clone (trap) | `/Volumes/LEXAR/repos/WorldOS` | Jul-1 clone @ `76439e2`, ~19 days behind. Do not mistake for canonical | +| Session scratch/evidence | `~/worldos-session-notes` → symlink to `/Volumes/LEXAR/Codex/offloaded-local/2026-07-09/worldos-session-notes` (9.8 GB) | Newest: `walkability-fix-2026-07-16/`, `ship-2026-07-15/` | +| Unity player install | `/Users/lume/Applications/WorldOSPlayer.app` | Jul 16 12:16 build | +| Built app | `dist/` — **EMPTY right now** (no `dist/WorldOS.app` exists) | AGENTS.md defines the built app as the product; last app evidence early July | +| GEX44 backups | `/Volumes/LEXAR/Codex/worldos-unity-backups/` | `worktree-20260716.tgz` confirmed | + +## 2. Reading order (doc routing) + +1. `docs/OPERATIONS.md` — the bootstrap (fresh, Jul 16). Universal Run Contract: every run closes HEALTH → EVIDENCE → SCORE → VERDICT → POINTER. +2. `VISION.md` — pillars + load-bearing invariants + decision-by-eval. +3. `docs/ACTIVE-GOAL.md` — the standing driver + blocker law (policy is ageless, blocker table stale by construction). +4. `docs/roadmap/PRODUCT-ROADMAP.md` — the plan (durable); its §4b execution-state block is stale (Jul 8). +5. **`docs/roadmap/PROCEDURAL-SCORECARD.md` (Jul 16) — the freshest narrative truth** for the generator chain; narrates the tip events (dress_focal v2/#1618, the wing hardening, the dwing-wing 0-adopted close-out). +6. `docs/ROOM-PIPELINE-RUNBOOK.md` (Jul 16) — the 11-step room pipeline; §10b sandbox hot-load gate loop; §11 walkability ship gate (BOTH beauty panel AND `qa/walk_test.py` GREEN to ship). +7. `qa/PANEL-PROTOCOL.md` (Jul 16) — the versioned blind-panel ruler; nobody freehands the ruler; author never renders own verdict. +8. Active sprint charter: GitHub issue **#1386** (Act II close-out, Rendered Felt) — box claim queue lives in its comments. +9. `docs/roadmap/NOW.md` — **refreshed to the 2026-07-20 truth in PR #1624** (the Jul-9 staleness is resolved); it is again the you-are-here surface. Keep it current per its session-close contract (update at every session close / charter transition). +10. Live plan (Claude-side but plain markdown): `~/.claude/plans/bubbly-cooking-stallman.md` — read **lines 596–668 first** (final log + queue); the CURRENT STATE block at 669+ is an older anchor. + +## 3. Live state snapshot (verified 2026-07-20) + +- **Generator chain merged & staged on main**: 13 PRs — spine (#1604–#1609, incl. sha-pinned certifications #1607 + ledger walk surface #1608), generator (#1610/#1611/#1621), instruments (#1613–#1616). dress_focal v2 gives every generated room 3 non-collinear fire beacons; paint has an `err_cells ≤ 0.35` hard gate with similarity re-registration; walk gates are fire-masked tri-state (GREEN/RED/ERROR). +- **Task #76 (next-cycle packet) is IN FLIGHT** — stage 1 (beacon regen) opened as PR #1625; the render → paint → gate half remains — see §4. +- **QA truth**: `qa/RRI.json` = RRI 2.7, release_ready=false, 3/11 gates, 1-of-5 personas — partial/harness-contaminated and unsuperseded (no valid release verdict exists). Scores ledger: 117 runs, visual-only since Jul 10. Walk-GREEN: crypt, tavern, throne_hall (live) + shop, tavern_snug (pinned certs in `qa/certifications/`). dwing wing: 0-adopted / 3 honest negatives (owner-falsified adoptions → "instruments adjudicate eyeballs"). +- **Live campaign**: `play-state/app-gate-v105-b/campaigns/camp_280cfd4d22a0` — DM budget-stopped after 2 turns (Jul 8). +- **Open PRs that matter**: #1617 (Unity persistence runbook — its OPERATIONS.md sections are NOT in base yet), #1498 (outdoor LoRA, blocked on Scenario train-model quota — owner decision), #1298 (day-plate selection, intentionally unmerged pending owner), #1012 draft (slab tiering, A/B-gated), #1622 (dependabot). +- **GEX44**: reachable, up 19 days, near-idle (probed 2026-07-20). Unity project saved via LFS + autosave cron; **GitHub LFS push blocked on paid data pack (~$5/mo owner billing decision)** — local commits + LEXAR tarball are the save story meanwhile. + +## 4. The next-cycle packet (Task #76 — the staged opener) + +Source: `~/.claude/tasks/237280f0-e8fe-4529-bb6e-72957d537c61/76.json` (status: pending) + GitHub issues #1618/#1619/#1620 + plan STATE block. All paths verified to exist. + +1. **Regen** the wing with dress_focal v2 via `tools/generate_town.py` (staged on main @ `fd23e972`). +2. **Box render ×3** per ROOM-PIPELINE-RUNBOOK §3 (greybox render — the shaded base + optional depth/normal sidecars) + `~/.claude/skills/gex44-unity-host/SKILL.md`; batch the #1616 T-pose registry-sync + player rebuild into the same box build; end the box session with `/home/unity/worldos-unity-save.sh`. +3. **Paint** via `qa/paint_room.py --boxes` (err_cells hard gate auto-warps via the similarity fit). +4. **Hot-load sandbox gates** per runbook §10b (fire-masked, tri-state; cycle `current_room` per room). +5. **Blind-adjudicated verdicts** per `qa/PANEL-PROTOCOL.md` — panels via `qa/panel_workflow.mjs` with `CAL_shipped_shop` calibration reference. +6. Adopt or park per verdict; certifications + `record_room_walk` on adoption. + +- Companions: **#1619 render_recipe** (zero-CU code; consider landing BEFORE the repaint — it kills recipe-authoring bugs) and **#1620** experience gates. +- **Budget gate**: the cycle costs ~140 Scenario CU; ~160 CU remained as of 2026-07-16 19:00 local with a measured 2/6 bug-fix-repaint base rate → the previous orchestrator deliberately handed off rather than strand it mid-budget. **Update 2026-07-20: Scenario CU refilled (5k+) — the "needs fresh budget" blocker is cleared; still confirm the balance before starting step 3.** + +## 5. GEX44 access (probed working 2026-07-20) + +- Secrets (never print values): `~/.openclaw/secrets/evaos-gpu-gex44-1-key`, `~/.openclaw/secrets/gex44.env` (defines `GEX44_SSH_HOST/USER/PORT/KEY`, `GEX44_UNITY_*` etc.). Endpoint (from tracked docs): `root@46.4.26.123`. Moonlight/WireGuard configs also in that dir for display. +- **All box access multiplexes over ONE ControlMaster** at `/tmp/gex44-cm.sock` (rapid separate ssh trips trip fail2ban and kill the master for ~10–17 min — batch box checks into one ssh): + `ssh -i ~/.openclaw/secrets/evaos-gpu-gex44-1-key -o BatchMode=yes -o StrictHostKeyChecking=yes -o UserKnownHostsFile=~/.openclaw/support/known_hosts -o ConnectTimeout=15 -o ServerAliveInterval=30 -M -S /tmp/gex44-cm.sock -f -N root@46.4.26.123` +- Tunnels: Unity-MCP `ssh -N -L 8080:127.0.0.1:8080 …`; reverse combat-surface `-R 8765:127.0.0.1:8770` via the master; NoMachine desktop `-L 4000`. +- On box: Unity `6000.5.1f1` project `/home/unity/worldos-unity` (drive as user `unity`, **Built-in Render Pipeline — not URP**); Unity-MCP on localhost `:8080` (~42 tools, `execute_code` needs `action:"execute"` + `safety_checks:false`); ComfyUI finisher `:8188`; render scripts versioned in repo at `extensions/renderers/unity/scripts/` (deploy to box, never author box-only). +- **Discipline**: single-tenant — claim by commenting on charter #1386 BEFORE any box op; repo-side work first; `chown -R unity:unity` touched files → ctrl+r → restore the scene you found → **save** (`sudo -u unity /home/unity/worldos-unity-save.sh --push` if anything scene/asset/build changed) → comment release. One bounded MCP op at a time; never `pkill -9`; never touch Mac:8765 (Eva's bridge; WorldOS uses 8770). +- Box-drive recipe pattern: `qa/evidence/dungen-spike/BOX-DRIVE-RECIPE.md`. +- Fallback: 32 GB `support-vm-1` (`root@178.104.123.213`, key `~/.openclaw/secrets/cloud-deploy-key`), preflight via `python3 qa/support_vm_preflight.py`; cannot prove Mac-only surfaces. + +## 6. Skills & agent profiles — porting decision (read-on-demand, NO symlinks/copies) + +The skill surface is live-edited (worldos-dev touched Jul 15, blind-adjudicator born Jul 16); copies stale within days and symlinks would mis-register foreign files as Kimi-managed skills. Kimi reads absolute paths natively — so: + +| Surface | Path | How Kimi uses it | +|---|---|---| +| Dev loop (canonical) | `/Users/lume/WorldOS/.claude/skills/worldos-dev/SKILL.md` | Read before any dev loop | +| Decision apparatus | `/Users/lume/WorldOS/.claude/skills/worldos-decide/SKILL.md` | Read when a decision lacks an eval | +| GEX44/Unity lane | `~/.claude/skills/gex44-unity-host/SKILL.md`, `~/.claude/skills/unity-asset-stack/SKILL.md` | Read before any box op | +| Visual critic / asset gen | `/Users/lume/WorldOS/.claude/skills/visual-critic/SKILL.md`, `.../asset-gen/SKILL.md` | Read on those lanes | +| Blind adjudicator | `~/.claude/agents/blind-adjudicator.md` | **Port the prompt verbatim** into a Kimi read-only subagent (`plan`/`explore` type) for gate verdicts — self-contained, model-agnostic | +| Other agent profiles | `~/.claude/agents/{coder,deep-reasoner,fast-worker,codex-worker}.md` | Map frontmatter to Kimi subagent types (`coder`/`plan`/`explore`) | +| WorldOS memory index | `~/.claude/projects/-Users-lume/memory/worldos-index.md` | Read on any WorldOS resume | +| Ops runbook | `~/.claude/runbooks/worldos-evaos-ops.md` | GLM lane, GitNexus reindex, Unity persistence | +| Routing ledger | `~/.claude/routing-ledger.jsonl` | **Shared append-only JSONL** — Kimi appends rows (`{"ts","lane","task","outcome","repo","note"}`) so Claude-side sessions see Kimi dispatches | +| Fable lane table | `~/.claude/CLAUDE.md` | "Fable = orchestrator only, the brain never types" → the Kimi orchestrator inherits that role; cheaper work delegates to subagents | + +Do NOT port: Claude hooks, stop-guards, keepalive ticks (Claude-app mechanics; Kimi has its own turn lifecycle). `.mcp.json` (engine/rules/voice stdio servers) is portable in substance — substitute `${CLAUDE_PLUGIN_ROOT}` → `/Users/lume/WorldOS` if ever wired. + +**Known gap — GitNexus**: this repo's AGENTS.md mandates GitNexus `impact` before edits and `detect_changes` before committing, but Kimi has no `mcp__gitnexus__*` tools. Fallback: the CLI (`node .gitnexus/run.cjs analyze`, index fresh at Jul 16 17:12) + grep — or the owner grants an explicit waiver / wires the MCP. + +## 7. Kimi ↔ Claude interop contract (both sides co-drive) + +Shared surfaces that make either side's work visible to the other: +1. **git + GitHub** — the trunk truth; PR loop per OPERATIONS.md (worktree off main → additive change → focused pytest + `qa/fast_gate.sh` → PR → review-gated merge; shepherd every PR to merged/parked; `gh pr merge --squash --auto`). +2. **Routing ledger** — both sides append (`~/.claude/routing-ledger.jsonl`). +3. **Scores ledger** — every scored run to `qa/scores_db.py` with provider/methodology stamps. +4. **POINTER step** — update the lane's charter/issue + `docs/roadmap/NOW.md` at session close (NOW.md refreshed in #1624; the POINTER step keeps it current). +5. **Universal Run Contract** — HEALTH → EVIDENCE → SCORE → VERDICT → POINTER, every run type. +6. **Box claim queue** — charter #1386 comments, regardless of which agent drives. + +## 8. Where Kimi can add value now (ordered, cheapest-first) + +1. **Doc-hygiene PR — DONE (this file + NOW.md + RUNBOOK-INDEX land via #1624)** (zero CU, zero box): refreshed `docs/roadmap/NOW.md` to the 2026-07-20 truth + added RUNBOOK-INDEX rows for the `qa/walk_test.py` / `tools/generate_town.py` chain. Pure repo loop. +2. **#1619 render_recipe** (zero CU): the code half that kills recipe-authoring bugs — the previous session recommended landing it BEFORE the repaint. **Update: render_recipe PR #1626 opened, in review.** +3. **Task #76 next cycle** (CU refilled; box claim via #1386): the full regen → render → paint → gate → adjudicate loop, §4 above. **Update: stage 1 regen opened as PR #1625.** +4. **#1620 experience gates** and the open companions of #1618. +5. Later/larger: a valid 5-persona RRI sweep to replace the contaminated f5500ac row; dist/WorldOS.app rebuild; towns beyond the 4-room proof (exteriors/streetscape generator is the known gap; TILED-SPACE-SPIKE ruling says towns = layout problem). + +## 9. Open questions for the owner + +1. Scenario CU balance — **refilled 2026-07-20 (5k+)**; the "needs fresh budget" framing is stale. Open remainder: land #1619 (PR #1626, in review) first and defer paint? +2. GitHub LFS data pack for the box repo (~$5/mo) — buy, or keep tarball-only saves? +3. GitNexus — **RESOLVED 2026-07-20: the MCP is wired for Kimi** (impact/detect_changes live from the canonical checkout; index rebuild to the tip runs detached). +4. PR this onboarding doc (+ NOW.md refresh) through the normal loop? — **RESOLVED: landed via #1624.** +5. Green-light to claim the box on #1386 and start Task #76 — **GRANTED 2026-07-21** (CU refilled; reviews + merge first). diff --git a/docs/RUNBOOK-INDEX.md b/docs/RUNBOOK-INDEX.md index bbe7f1d7..594cc3ce 100644 --- a/docs/RUNBOOK-INDEX.md +++ b/docs/RUNBOOK-INDEX.md @@ -49,6 +49,8 @@ | room/backdrop gen | `qa/export_scene_grid.py` → `qa/gen_room_from_scene_grid.sh` → `qa/deploy_room.sh` (live Unity lane; ⚠ `--layered` naming lives on the quarantined Godot tool) | Scenario CUs | plate PNG + pin-check + control-anchored panel (MUST include a disclosed WorldOS house-style anchor — e.g. crypt_dense_v1 — alongside the disguised PoE2/BG2 control; a PoE2-only or absolute-score reading is NOT sufficient for adoption, see plate-style-regression #2026-07-08) + room_recipes entry + library/rooms promotion | visual (panel) | asset-gen skill | | character/asset gen | asset-gen skill (Meshy/Tripo/Scenario/PixelLab) | ~5-25 CU/asset | registry entry (gen_recipe) + grounded upright render per actor + evidence commit | ⚠ NONE today — gate via pre-gate + panel on first composed use | asset-gen skill | | plate-sprint generate→gate→panel→gallery loop | `qa/plate_loop.py` (two-phase: phase 1 generates + runs the deterministic registration/pre-gates + stages the 5-scorer blind panel packet; phase 2 ingests the orchestrator-run panel verdict) | Scenario CUs + panel cost | registration-gate result + staged panel packet (phase 1) then the scores_db row + gallery row (phase 2); an HTML gallery contact sheet (`--gallery `) is UPSERTED with one row per scored candidate (every iteration, not just the adopted one) — owner-facing morning posts embed the best-scoring frame from that gallery | visual (surface="visual", auto via phase 2) | worldos-dev skill + `docs/roadmap/PLATE-RECIPE-DECISION.md` (adopted recipe: flux ControlNet base + Gemini style pass, registration/panel thresholds) | +| town/room generation chain | `tools/generate_town.py` → `qa/seed_gfx_town.py` | free, zero-CU local | fail-loud static gates incl. the beacon-geometry bar (generator self-gate; seeded world walks every cross_door hop) | — (static gates; output feeds the walk gate) | `docs/roadmap/PROCEDURAL-SCORECARD.md` §THE TOWN COMMAND CHAIN · last-verified 2026-07-20 | +| room walkability gate (binding Tier-0 ship gate) | `qa/walk_test.py --room ` | free ($0), live player sandbox | `qa/evidence/walk-*/` reports (walk_report.json + contact sheet) | `walk_gate` in scores_db (class=room rows via `record_room_walk`) | `docs/ROOM-PIPELINE-RUNBOOK.md` §11 · last-verified 2026-07-20 | ## Known wiring gaps (tracked) 1. ~~**Manual-append bucket** (duo, sprint, sweep, app gate, RRI)~~ — CLOSED #1414: each runner now diff --git a/docs/roadmap/NOW.md b/docs/roadmap/NOW.md index dc090ef0..1568d1aa 100644 --- a/docs/roadmap/NOW.md +++ b/docs/roadmap/NOW.md @@ -4,26 +4,35 @@ > a bootstrapping agent reads after OPERATIONS.md. Keep it under a screen. History belongs in > git, not here. -_Last updated: 2026-07-09 (UTC) — Goal Mode active; W5 night._ +_Last updated: 2026-07-21 (UTC) — Jul-16 generator chain merged; Task #76 in flight (wave-1 PRs up)._ + +> Depth: `docs/roadmap/PROCEDURAL-SCORECARD.md` (generator-chain narrative) · +> `docs/ROOM-PIPELINE-RUNBOOK.md` (11-step room pipeline; §11 walk ship gate) · +> `docs/KIMI-ONBOARDING.md` (Kimi-side routing + the full Task #76 packet). ## Active sprint - **ACTIVE charter: #1386** (label `active-sprint`) — Act II close-out, "Rendered Felt". - Items 1 (#1284 grounding), 2 (#1397 pose), 5 (#1378 + extractor pass 2) CLOSED. - Item 3 (#1398 rest-scene demo): composed scene at panel 5.88 (frames in qa/evidence/1423/) — - owner-taste gate pending; polish trackers #1403 (framing) + Meshy-atlas quality remain. - Item 4 (W5): **the macOS player RUNS on the Mac** — build+handoff+shaders+live client merged - (PRs #1430/#1432/#1435; evidence felt-frames/w5a-smoke/). Remaining: **#1436 W5c** runtime - spawning (IN FLIGHT) + T3 harness extension, then the T3 gate run closes Act II. -- **Next charters queued:** S2 (#1309, entry gate satisfied) → S3 (#1310). +- **Jul-16 generator chain MERGED at tip `fd23e972`** — 5-room spine (#1604–#1609, + incl. sha-pinned certifications #1607 + ledger walk surface #1608); generate_town / + dress_focal v2 generator (#1610/#1611/#1621 — 3 non-collinear fire beacons per room); + instruments #1613–#1616 (walk-gate tri-state, T-pose roster fix, wing hardening). + Paint runs under an `err_cells ≤ 0.35` hard gate with similarity re-registration. +- **Task #76 next cycle IN FLIGHT** — regen → box render ×3 → paint under the err_cells + gate → hot-load walk gates → blind-adjudicated panels (~140 Scenario CU; refilled + 2026-07-20). Stage 1 (beacon regen) = PR #1625; #1619 render_recipe = PR #1626; + doc hygiene = PR #1624. Box claim via #1386 comments; packet in docs/KIMI-ONBOARDING.md §4. +- **Companions:** #1620 experience gates (open). ## Live lanes -- **#1436 W5c runtime spawning** — coder on the box (claim via #1386). -- **Flywheel:** quest-authoring cues LIVE (#1409); visual promotion gate LIVE (two-tier, - calibrated — docs/roadmap/VISUAL-PROMOTION-GATE-DECISION.md); backdrop cadence restarted - (camp_clearing_night adopted tier=stable; market_square honestly REJECTED at delta −5.0, - needs iteration); demo cast at ~10 (wave-2 monsters merged #1428). +- **Walk-GREEN rooms:** crypt / tavern / throne_hall live + shop / tavern_snug certified + (sha-pinned certs in `qa/certifications/`). +- **dwing wing CLOSED:** 0 adopted / 3 honest negatives — instruments adjudicate eyeballs. +- **Release truth:** `qa/RRI.json` = 2.7 partial/harness-contaminated — **NO valid release + verdict exists.** `dist/` is EMPTY (no built app). +- **Open PRs (notable):** #1624/#1625/#1626 (this wave's drafts) · #1617 (Unity persistence docs) · #1498 (outdoor LoRA — CU now refilled) · #1298 (owner-held) · #1012/#1102/#573 (drafts) · #1622 (dependabot). +- **Next charters queued:** S2 (#1309) → S3 (#1310), both open. ## Blockers @@ -31,8 +40,9 @@ None. (Blocker Law: fresh-probe row in docs/ACTIVE-GOAL.md or it isn't a blocker ## Known frictions (not blockers) -- Auto-merge hangs repo-wide → `gh pr merge --admin --squash` after green+resolved (#1389). +- Auto-merge fires normally (the #1389 "hang" was a stale ruler pin — resolved by #1431/#1434); + `--admin` is emergency-only (declare why in a PR comment + file a follow-up). - qa-release-gate-tests was RED repo-wide (stale ruler pin) — FIXED by #1431; if it re-reds, check SCORING_CONFIG_FILES drift first. -- Ruler duos: SOLO-TENANT only; scorer keychain token may need re-derivation per - reference_claude_p_automation_auth. +- GitHub LFS push for the box Unity repo blocked on a paid data pack (~$5/mo owner decision); + local commits + LEXAR tarball are the save story meanwhile.