lazycodex-ai 5.0.0-beta.85 → 5.0.0-beta.87

package/packages/omo-codex/plugin/skills/browser/scripts/browser-doctor.mjs

@@ -1,41 +1,46 @@
 #!/usr/bin/env node
-import { platform } from "node:os"
-import { connectedBrowsers, readStatus, resolveCli, STORE_LISTINGS, SUPPORTED_PLATFORMS } from "./browser-env.mjs"
+import { loadOmowright } from "./omowright.mjs"
+
+const { entry, omowright } = await loadOmowright()
+const report = await omowright.bskDoctor({ waitForBrowserMs: 0 })
+
+const state = report.ready
+  ? "ready"
+  : !report.cli.installed
+    ? "no-cli"
+    : !report.daemon.running
+      ? "no-daemon"
+      : report.browsers.length === 0
+        ? "no-browser-support"
+        : "no-extension"
 
 const REMEDIES = {
-  ready: "Start a session: bsk session start --json --no-focus --name \"<task>\"",
-  "no-extension": `Ask the user to install and enable the extension, then re-run this doctor.\n  Chrome: ${STORE_LISTINGS.chrome}\n  Edge:   ${STORE_LISTINGS.edge}`,
-  "no-cli": "Install the CLI: node \"<skill-root>/scripts/browser-install.mjs\", then re-run this doctor.",
-  "no-browser-support": "This platform has no supported browser. Say so and stop; do not substitute another engine.",
+  ready: "Attached engine is live: const { connectBrowserSkill } = await import(omowrightEntry); const session = await connectBrowserSkill({ name: \"<task>\", focused: false })",
+  "no-cli": "Run node \"<skill-root>/scripts/browser-install.mjs\" — it installs the CLI, starts the daemon and registers the extension; then tell the user the single step it prints.",
+  "no-daemon": "Run node \"<skill-root>/scripts/browser-install.mjs\" (it starts the daemon through `bsk status`), then re-run this doctor.",
+  "no-extension": report.nextStep ?? "Register the extension with browser-install.mjs, then relay its human step to the user and re-run this doctor.",
+  "no-browser-support": "No Chromium-family browser profile was found on this machine. Say so and stop; do not substitute another engine.",
 }
 
-async function diagnose() {
-  if (!SUPPORTED_PLATFORMS.has(platform())) {
-    return { state: "no-browser-support", platform: platform() }
-  }
-  const cli = await resolveCli()
-  if (cli === undefined) return { state: "no-cli", platform: platform() }
-
-  let status
-  try {
-    status = await readStatus(cli)
-  } catch (error) {
-    return { state: "no-extension", platform: platform(), cli, detail: `status failed: ${error.message}` }
-  }
-  const browsers = connectedBrowsers(status)
-  if (browsers.length === 0) return { state: "no-extension", platform: platform(), cli }
-  return { state: "ready", platform: platform(), cli, browsers: browsers.length }
+const summary = {
+  state,
+  omowright: entry,
+  cli: report.cli,
+  daemon: { running: report.daemon.running, version: report.daemon.version ?? null, protocolVersion: report.daemon.protocolVersion ?? null, error: report.daemon.error ?? null },
+  browsersDetected: report.browsers.map((browser) => ({ id: browser.id, userDataDir: browser.userDataDir, extensionRegistered: browser.extensionRegistered })),
+  browsersConnected: report.browsersConnected.map((browser) => ({ instanceId: browser.instance_id, name: browser.browser_name, version: browser.browser_version })),
+  nextStep: report.nextStep,
+  remedy: REMEDIES[state],
 }
 
-const report = await diagnose()
-const json = process.argv.includes("--json")
-if (json) {
-  console.log(JSON.stringify({ ...report, remedy: REMEDIES[report.state] }, null, 2))
+if (process.argv.includes("--json")) {
+  console.log(JSON.stringify(summary, null, 2))
 } else {
-  console.log(`state: ${report.state}`)
-  if (report.cli) console.log(`cli:   ${report.cli}`)
-  if (report.browsers) console.log(`browsers connected: ${report.browsers}`)
-  if (report.detail) console.log(`detail: ${report.detail}`)
-  console.log(`\n${REMEDIES[report.state]}`)
+  console.log(`state: ${state}`)
+  console.log(`omowright: ${entry}`)
+  console.log(`cli: ${report.cli.installed ? `${report.cli.bskBin} (${report.cli.version})` : "not installed"}`)
+  console.log(`daemon: ${report.daemon.running ? `running (${report.daemon.version}, protocol ${report.daemon.protocolVersion})` : `not running${report.daemon.error ? ` — ${report.daemon.error}` : ""}`}`)
+  console.log(`browsers detected: ${summary.browsersDetected.map((b) => `${b.id}${b.extensionRegistered ? " (extension registered)" : ""}`).join(", ") || "none"}`)
+  console.log(`browsers connected: ${summary.browsersConnected.map((b) => `${b.name} ${b.version} [${b.instanceId}]`).join(", ") || "none"}`)
+  console.log(`\n${REMEDIES[state]}`)
 }
-process.exit(report.state === "ready" ? 0 : 1)

package/packages/omo-codex/plugin/skills/browser/scripts/browser-install.mjs

@@ -1,51 +1,38 @@
 #!/usr/bin/env node
-import { spawn } from "node:child_process"
-import { platform } from "node:os"
-import { resolveCli, STORE_LISTINGS, SUPPORTED_PLATFORMS } from "./browser-env.mjs"
+import { loadOmowright } from "./omowright.mjs"
 
-const UNIX_INSTALL = "curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh"
-const WINDOWS_INSTALL = "irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | iex"
+const json = process.argv.includes("--json")
+const waitArg = process.argv.find((arg) => arg.startsWith("--wait-ms="))
+const waitTotalMs = waitArg ? Number(waitArg.slice("--wait-ms=".length)) : 0
 
-function installCommand() {
-  return platform() === "win32"
-    ? { file: "powershell", args: ["-NoProfile", "-Command", WINDOWS_INSTALL], display: WINDOWS_INSTALL }
-    : { file: "sh", args: ["-c", UNIX_INSTALL], display: UNIX_INSTALL }
-}
-
-function spawnInstaller({ file, args }) {
-  return new Promise((resolve) => {
-    const child = spawn(file, args, { stdio: "inherit", windowsHide: true })
-    child.on("error", () => resolve(1))
-    child.on("close", (code) => resolve(code ?? 1))
-  })
-}
+const { omowright } = await loadOmowright()
+const steps = []
+const result = await omowright.bskOnboard({
+  onHumanStep: (step) => steps.push(step),
+  waitForBrowserMs: waitTotalMs > 0 ? Math.min(15_000, waitTotalMs) : 0,
+  waitTotalMs,
+})
 
-if (!SUPPORTED_PLATFORMS.has(platform())) {
-  console.error(`unsupported platform: ${platform()}. macOS, Linux and Windows x64 only.`)
-  process.exit(1)
+const summary = {
+  ready: result.ready,
+  cli: result.cli,
+  installerRan: result.install !== null,
+  daemon: { running: result.daemon.running, version: result.daemon.version ?? null, error: result.daemon.error ?? null },
+  registrations: result.registrations.map((r) => ({ browser: r.browser, registered: r.registered, alreadyPresent: r.alreadyPresent ?? false, reason: r.reason ?? null, needsRestart: r.needsRestart ?? null, humanStep: r.humanStep ?? null })),
+  browsersConnected: result.browsersConnected.map((b) => ({ instanceId: b.instance_id, name: b.browser_name, version: b.browser_version })),
+  humanStep: result.humanStep,
 }
 
-if (await resolveCli()) {
-  console.log("bsk is already installed; run browser-doctor.mjs to check the extension.")
-  process.exit(0)
+if (json) {
+  console.log(JSON.stringify(summary, null, 2))
+} else if (result.ready) {
+  console.log(`attached engine ready: ${summary.browsersConnected.map((b) => `${b.name} ${b.version}`).join(", ")}`)
+} else {
+  console.log(`cli: ${result.cli.installed ? `${result.cli.bskBin} (${result.cli.version})` : "install failed"}`)
+  console.log(`daemon: ${result.daemon.running ? "running" : `not running${result.daemon.error ? ` — ${result.daemon.error}` : ""}`}`)
+  for (const r of summary.registrations) {
+    console.log(`extension for ${r.browser}: ${r.registered ? (r.alreadyPresent ? "already registered" : "registered") : `not registered (${r.reason})`}`)
+  }
+  console.log(`\nTell the user exactly this, then re-run browser-doctor.mjs:\n  ${result.humanStep}`)
 }
-
-const command = installCommand()
-console.log(`installing the bsk CLI with the upstream installer:\n  ${command.display}\n`)
-const code = await spawnInstaller(command)
-if (code !== 0) {
-  console.error(`\ninstaller exited ${code}. Report this instead of retrying blindly.`)
-  process.exit(code)
-}
-
-console.log([
-  "",
-  "CLI installed. Two things remain, and only the user can do the first:",
-  "",
-  "1. Install the browser extension from the store, then enable it:",
-  `     Chrome: ${STORE_LISTINGS.chrome}`,
-  `     Edge:   ${STORE_LISTINGS.edge}`,
-  "2. Re-run: node \"<skill-root>/scripts/browser-doctor.mjs\"",
-  "",
-  "If PATH does not pick up the CLI in this shell, use its absolute path under ~/.local/bin.",
-].join("\n"))
+process.exitCode = result.ready ? 0 : 2

package/packages/omo-codex/plugin/skills/browser/scripts/omowright.mjs

@@ -0,0 +1,25 @@
+import { existsSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath, pathToFileURL } from "node:url"
+
+const scriptDir = dirname(fileURLToPath(import.meta.url))
+const skillRoot = dirname(scriptDir)
+
+export function resolveOmowrightEntry(env = process.env) {
+  const candidates = [
+    env.OMOWRIGHT_ROOT ? join(env.OMOWRIGHT_ROOT, "index.js") : undefined,
+    join(skillRoot, "runtime", "omowright", "index.js"),
+    join(skillRoot, "..", "..", "..", "..", "node_modules", "omowright", "src", "index.js"),
+  ].filter((candidate) => candidate !== undefined)
+  return candidates.find((candidate) => existsSync(candidate))
+}
+
+export async function loadOmowright(env = process.env) {
+  const entry = resolveOmowrightEntry(env)
+  if (entry === undefined) {
+    throw new Error(
+      "omowright is not staged in this skill; run `node packages/shared-skills/stage-omowright-runtime.mjs` in a checkout, or set OMOWRIGHT_ROOT to a directory holding its bundled index.js",
+    )
+  }
+  return { entry, omowright: await import(pathToFileURL(entry).href) }
+}

package/packages/omo-codex/plugin/skills/debugging/SKILL.md

@@ -49,7 +49,7 @@ These are not "optional extras". They are the correct tool in their domain, and
 
 | Tool | Use when | Reference |
 |---|---|---|
-| **Playwright CLI** | Any browser-served web UI bug. Any flow that requires clicking/typing/navigating. Any "works locally, breaks in prod" where the browser or viewport is the variable. **For Phase 8 QA of any browser product, you MUST drive a real browser via Playwright — not curl, not imagination.** | 📖 **[references/tools/playwright-cli.md](references/tools/playwright-cli.md)** |
+| **omowright** | Any browser-served web UI bug. Any flow that requires clicking/typing/navigating. Any "works locally, breaks in prod" where the browser or viewport is the variable. **For Phase 8 QA of any browser product, you MUST drive a real browser through omowright — not curl, not imagination.** | 📖 **[references/tools/browser-qa.md](references/tools/browser-qa.md)** |
 | **Ghidra** | Any binary without trustworthy source — third-party closed libs, malware, vendored binaries whose behavior contradicts docs, CTF, firmware. **Use Ghidra's decompiler before `strings`/`objdump` guessing. It turns machine code into readable C.** | 📖 **[references/tools/ghidra.md](references/tools/ghidra.md)** |
 | **pwndbg** | Any native binary debugging session. It is GDB with the useful views (registers, stack, disasm, heap) always visible. **If you'd reach for plain `gdb`, reach for `pwndbg` instead — it is strictly a superset.** | 📖 **[references/tools/pwndbg.md](references/tools/pwndbg.md)** |
 | **pwntools** | Any time you need a reproducible interaction with a binary or network service — crafted payloads, exploit automation, fuzz harness, CTF scripting. | 📖 **[references/tools/pwntools.md](references/tools/pwntools.md)** |
@@ -97,7 +97,7 @@ These are not phases — read them when the situation calls for them:
 <safety>
 1. **Runtime state is the only source of truth.** A hypothesis without an observed value is a guess. Do not fix guesses.
 2. **Every debug artifact is journaled before it is created.** Journal-then-modify, not modify-then-remember-maybe.
-3. **Never ship a fix without a failing-first test.** Red→green transition required, or the fix is unverified.
+3. **Never ship a fix without its reproduction.** The failing case captured BEFORE the fix, the same case passing after it, or the fix is unverified. Where the repository keeps tests for this behavior, that case is the regression test.
 4. **Never declare done on type-check/compile alone.** Types catch declaration bugs. Only running the actual user scenario catches the actual user bug.
 5. **Never ask the user a question that runtime evidence can already answer.** Escalation is for genuine ambiguity.
 6. **Never silently swallow errors while debugging.** If the system swallows errors, that is often the bug itself. Make them loud temporarily; restore at cleanup.

package/packages/omo-codex/plugin/skills/debugging/references/methodology/06-fix.md

@@ -1,4 +1,4 @@
-# Phase 6 + 7 — Root Cause Confirmation & TDD Fix
+# Phase 6 + 7 — Root Cause Confirmation & Reproduction-Locked Fix
 
 A cause is not "confirmed" until you can toggle the bug by toggling the cause. Every other level of evidence is correlation, and correlation-driven fixes ship bugs.
 
@@ -51,7 +51,7 @@ The "mechanism" field is the acid test. If you can't write the causal chain from
 
 Red, green, refactor. No shortcuts.
 
-### 1. Red — failing-first test
+### 1. Red — the reproduction as a test
 
 Write a test that fails *specifically because of this bug*. Requirements:
 
@@ -117,6 +117,6 @@ Full suite: <N tests, <M failures — should be 0>
 
 ## The red-green discipline summary
 
-No red test → no proof the fix addresses the reported bug. Only proof it doesn't break tests that already existed.
+No captured failure → no proof the fix addresses the reported bug. Only proof it doesn't break tests that already existed. Keep the reproduction as a test where the repository keeps tests for this behavior; otherwise the captured before/after run is the proof.
 
 A test written *after* the fix might still pass with the fix reverted. If that's the case, the test doesn't lock the bug — it locks something else. Always verify the test fails without the fix and passes with it. The journal should show both outputs.

package/packages/omo-codex/plugin/skills/debugging/references/methodology/08-qa.md

@@ -14,7 +14,7 @@ Pick the row that matches the product. Do what it says. Do not substitute.
 |---|---|
 | **CLI tool** | Open `tmux`, run the actual command end-to-end, capture output. Paste the session transcript into the journal. Include exit code, stdout, stderr, side-effect check (files created/modified). |
 | **HTTP API** | Start the real server, hit endpoints with `curl` or `httpie`, inspect response status + body + headers. Hit the specific endpoint that reproduced the bug. If there's auth, use real auth. |
-| **Browser-served web app** | **Drive a real browser via Playwright CLI.** See [tools/playwright-cli.md](../tools/playwright-cli.md). Navigate the exact page/flow that reproduced the bug. Capture screenshot + DOM + network evidence. **Do not substitute with curl** — browsers have state (cookies, localStorage, service workers, client-side JS, viewport-dependent CSS) that curl does not have. |
+| **Browser-served web app** | **Drive a real browser through omowright.** See [tools/browser-qa.md](../tools/browser-qa.md). Navigate the exact page/flow that reproduced the bug. Capture screenshot + DOM + network evidence. **Do not substitute with curl** — browsers have state (cookies, localStorage, service workers, client-side JS, viewport-dependent CSS) that curl does not have. |
 | **Agent / LLM pipeline** | Run the same user prompt that originally failed. Capture the full turn — tool calls, messages, usage counters. **Confirm non-zero usage** (zero usage = still failing silently, see silent-failure check below). |
 | **Background worker / job queue** | Trigger the job through the normal entry point (API call, cron tick, message publish), tail the worker logs, observe completion state in the queue or DB. Don't just call the worker function directly — the trigger path matters. |
 | **MCP server** | Invoke the tool via its actual client (Claude Desktop, Cursor, etc. if available) or `mcp-cli`, not just the HTTP probe endpoint. The MCP handshake itself is sometimes where bugs live. |

package/packages/omo-codex/plugin/skills/debugging/references/tools/browser-qa.md

@@ -0,0 +1,104 @@
+# Browser QA — omowright from js eval
+
+A browser UI bug needs a rendered browser, not curl. omowright is staged inside the `browser`
+skill; load it from a js-eval cell and pick the engine the bug lives in:
+
+```js
+const { loadOmowright } = await import("<browser-skill-root>/scripts/omowright.mjs")
+const { omowright } = await loadOmowright()
+```
+
+| The bug needs | Engine |
+|---|---|
+| A public page, a fresh profile, a pinned viewport, traces, network capture | **owned** — `connectPipe` (or `connectCloakProfile` when the site scores bots) |
+| The user's login, their cookies, their open tabs | **attached** — `connectBrowserSkill()`; never a clone of their profile |
+
+Chrome must already be installed for the owned engine; report an absent executable rather than
+downloading a managed browser.
+
+## The four things you'll actually use
+
+### 1. Reproduce with a flight trace
+
+```js
+const profile = mkdtempSync(join(tmpdir(), "debug-repro-"))
+const browser = await omowright.connectPipe({ browserPath, browserArgs: ["--headless", `--user-data-dir=${profile}`], storageRoot: profile })
+const page = await browser.newTab("about:blank")
+const trace = omowright.createTrace(page, { dir: traceDir })          // trace.jsonl + trace.har + before/after screenshots
+const consoleErrors = []
+page.on("console", (entry) => { if (entry.type === "error") consoleErrors.push(entry.text) })
+try {
+  await trace.step("open", () => page.goto(url, { waitUntil: "load" }))
+  await trace.step("submit", async () => {
+    const { tree } = await page.snapshot({ interactive: true })       // read, then act on a fresh ref
+    await page.locator("e5").fill(value)
+    await page.locator("e7").click()
+    await page.waitForURL(/\/done/, { timeout: 10_000 })
+  })
+  await Bun.write(pngPath, await page.screenshot())
+} finally {
+  await trace.stop()
+  await browser.close()
+  rmSync(profile, { recursive: true, force: true })
+}
+```
+
+A screenshot alone is not a reproduction assertion. Read the snapshot for the exact observable
+state (a role, a name, a value) and fail the step when it is absent.
+
+### 2. Read the network instead of guessing
+
+```js
+const snoop = omowright.createNetworkSnoop(page)
+const hit = await snoop.waitFor({ url: /\/api\/submit/ }, { timeoutMs: 10_000 })   // subscribe BEFORE the click
+console.log(hit.status, hit.body?.slice(0, 500))
+```
+
+Subscribe before triggering the action, then await that specific response; do not sleep or wait
+for generic idleness. `createRoutes(page)` fails one request on purpose to test an error path.
+
+### 3. Reproduce in the user's browser
+
+When the bug only happens signed in:
+
+```js
+const session = await omowright.connectBrowserSkill({ name: "debug repro", focused: false })
+try {
+  await session.navigate(url)
+  const { tree, css } = await omowright.bskSnapshot(session, { interactive: true })
+  await session.click({ selector: css.e7 })
+  const errors = await session.console({ since: 0 })
+  const shot = await session.screenshot()
+} finally {
+  await session.stop()
+}
+```
+
+The value of this engine is the state that curl and a fresh profile do not have — cookies,
+localStorage, service workers. Never read credentials through `evaluate`, never clear the
+profile's data.
+
+### 4. Viewport and device emulation
+
+`emulate(page, "iphone-14")` applies viewport, device scale factor, user agent and touch
+together; `emulate(page, { width: 375, height: 667, deviceScaleFactor: 2, mobile: true, hasTouch: true })`
+for a custom preset. Match the reference's pixel scale as well as its viewport.
+
+## Headless vs headed during debugging
+
+Drop `--headless` from `browserArgs` with an available display when reproducing headed-only
+behavior. State which mode produced the evidence; do not claim a headless capture proves
+desktop-browser permissions or window behavior.
+
+## Gotchas
+
+- Wait for state, not time: a snapshot ref, `waitForURL`, or a snooped response is the signal.
+- Refs die on every new snapshot; read again after any navigation or large DOM change.
+- Fresh task-owned profiles avoid cached state leaking between runs.
+- Auth belongs to the attached engine, never to a copy of the live browser profile.
+- Give every run its own output directory and a bounded process lifetime.
+
+## Phase 9 cleanup specifics
+
+`browser.close()` / `session.stop()` even on failure, stop the fixture server, and remove only this
+run's profile directory. Preserve requested PNG/trace evidence; keep auth-bearing traces private.

package/packages/omo-codex/plugin/skills/frontend/SKILL.md

@@ -147,7 +147,7 @@ Domains: `product` `style` `typography` `color` `landing` `chart` `ux` `react` `
 | Situation | Load |
 |---|---|
 | Brand/style not among the 70 in `references/design/`, or the user says "Open Design" | `open-design` skill — the local nexu-io/open-design library (137+ design skills, 150+ design systems) |
-| Driving a browser for the Design QA phase | `visual-qa` skill: Bun.WebView / local-Chrome `playwright-core` scripts from js eval; Codex in-app browser |
+| Driving a browser for the Design QA phase | `visual-qa` skill: omowright from js eval (owned engine for renders, attached engine for signed-in pages) |
 | Pure TypeScript/logic work with zero visual surface | `programming` skill alone — this skill adds nothing there |
 
 ## Activation

package/packages/omo-codex/plugin/skills/frontend/references/design/clone-from-url.md

@@ -8,7 +8,7 @@ A `DESIGN.md` whose every token, interaction state, and motion value was read fr
 
 ## Phase 1 — Extract the runtime truth (never guess a value)
 
-Drive a real browser from js eval: `new Bun.WebView()` on Bun >= 1.4 (macOS default; Linux/Windows need installed Chrome/Chromium/Edge), otherwise write and run a `playwright-core` script against local Chrome (`channel: "chrome"`). Use that script lane for Chrome semantics, stealth, trace, or auth, with persistent contexts on CLONED profiles only. Codex: `browser:control-in-app-browser`. Do NOT parse CSS files — minification, CORS, CSS-in-JS, and Tailwind utilities make source unreliable. `getComputedStyle` returns what the browser ACTUALLY rendered, so it is the only source of truth.
+Drive a real browser with omowright from js eval (staged in the `browser` skill): `connectPipe` on a task-owned profile for a public page, `connectCloakProfile` when the source is bot-scored, `connectBrowserSkill()` when it needs the user's login — then `page.evaluate` / `session.evaluate` for `getComputedStyle`. Do NOT parse CSS files — minification, CORS, CSS-in-JS, and Tailwind utilities make source unreliable. `getComputedStyle` returns what the browser ACTUALLY rendered, so it is the only source of truth.
 
 Sweep the page and read, for every meaningful element and every repeated pattern:
 

package/packages/omo-codex/plugin/skills/programming/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: programming
-description: "Applies strict, modern language practice (typed errors, exhaustive match, TDD) for Python, Rust, TypeScript, and Go. Use for work on .py, .rs, .ts, or .go files."
+description: "Applies strict, modern language practice (typed errors, exhaustive match, tests that can fail) for Python, Rust, TypeScript, and Go. Use for work on .py, .rs, .ts, or .go files."
 ---
 
 # Programming
@@ -47,23 +47,15 @@ These are not style preferences. They are the seven axioms every recipe in `refe
 
 5. **Trust framework guarantees. Validate only at boundaries.** No null checks for values the type system already proves non-null. No `try/except` around code that cannot raise. No `unwrap`/`!`/`as` to paper over a contract you should have encoded in types. No defensive layer for a scenario you cannot name.
 
-6. **Test-driven, with the right shape of test.** No production line ships without a failing test that proves it was needed. Behavior is locked by tests, not by hope. See the TDD discipline below.
+6. **Tests are the behavior of record, and only tests that can fail count.** READ the tests covering the area BEFORE you change it: do they encode the intent, cover this path, pass? One wrong before your change is a FINDING — never edit it green. Reproduce a bug before fixing it. The run proves the change; add a test ONLY where the repository keeps tests for this behavior AND a regression would otherwise pass unnoticed — sized like its neighbors, never restating the change. See the test discipline below.
 
 ---
 
-## TDD DISCIPLINE — NON-NEGOTIABLE
-
-**Every change follows the red → green → refactor loop.** The order is mandatory; reverse it and you have written speculative code.
-
-### The order
-
-1. **Red.** Write a failing test that names the behavior in `Given / When / Then`. Run it. *Confirm it fails for the right reason* — not a typo, not an import error. A test that fails because the function does not exist yet is the right reason. A test that fails because of a missing import is not.
-2. **Green.** Write the minimum code to make the test pass. Resist adding the second case until the first passes. The second case is the next red.
-3. **Refactor.** With the test green, restructure ruthlessly. The test is your safety net. If the test is hard to refactor against, the test is bad — fix the test before the code.
+## TEST DISCIPLINE
 
 ### The shape of the test pyramid
 
-Every feature ships with all three rungs, sized in this proportion:
+Where the repository keeps these rungs, test at the cheapest rung that observes the behavior:
 
 | Rung | Count | Purpose | Speed budget |
 |---|---|---|---|
@@ -71,7 +63,7 @@ Every feature ships with all three rungs, sized in this proportion:
 | **Integration** | some | The real adapter against the real downstream (DB, queue, HTTP) — via `testcontainers`, `httptest`, or equivalent. NEVER a unit test pretending to be integration. | < 1 s each |
 | **E2E scenario** | few | One narrative per user-visible outcome. Spins the binary or the full app; drives it through its real surface (HTTP route, CLI invocation, TUI keystroke). Asserts the *observable outcome*, not internal state. | seconds, run on CI |
 
-If a feature has zero E2E coverage, it is undone — even if every unit test passes.
+A user-visible outcome you never drove through its real surface is unverified — a green unit suite does not stand in for that run.
 
 ### Given / When / Then is mandatory
 
@@ -121,7 +113,7 @@ If no machine consumes the text, there is no seam: write NO test and say so in t
 
 | Anti-pattern | Why it fails | Fix |
 |---|---|---|
-| Writing code first, tests "to add later" | Tests-after rationalize the existing design, even when wrong. | Red first. Always. |
+| A test that restates the change (pins a constant, a string, a rename, a call) | Cannot fail for any regression; certifies the diff, not the behavior. | The run is the proof. Delete the test. |
 | One mega-test asserting 12 things | First failure hides the next 11. | Split by `Then` clause — one assertion class per test. |
 | Mocking every collaborator | Test passes regardless of real behavior. | Use a fake or the real thing. Mock only true unmockables. |
 | `time.sleep(0.1)` to "let it finish" | Flake guaranteed. | Subscribe to the completion signal; bounded await. |
@@ -143,7 +135,7 @@ Apply unless the per-language reference overrides with something stricter.
 | Immutable by default | `@dataclass(frozen=True, slots=True)` / Pydantic `frozen=True` | every binding is `let` (not `let mut`) unless mutation is the documented purpose | every field is `readonly`; arrays are `readonly T[]` | value types, unexported fields, no mutation methods unless mutation is the purpose |
 | Branded primitives | `UserId = NewType("UserId", int)` | `struct UserId(u64);` (newtype tuple) | `type UserId = Brand<string, "UserId">` | `type UserID string` + smart constructor with unexported field |
 | Exhaustive variant matching | `match` + `assert_never` | `match` (compiler-enforced) | `switch` + `assertNever` | sealed interface + type switch + **`exhaustive` linter** (the compiler will not help) |
-| No untyped escape hatches | no `Any` in public sigs, no `cast`, no `# type: ignore` | no `unwrap`/`expect` outside `main`/tests, no `as` for narrowing, no `#[allow]` to silence real warnings | no `any`, no `as` (except `as const`, `satisfies`), no `!`, no `@ts-ignore`, no `@ts-expect-error` | no `interface{}` / bare `any` in domain sigs; no `_ = err`; no `//nolint` without reason |
+| No untyped escape hatches | no `Any` in public sigs, no `cast`, no `# type: ignore` | no `unwrap`/`expect` outside tests (invariant `expect` only behind `#[expect(clippy::expect_used, reason)]`), no numeric `as`, no `#[allow]` (silence with `#[expect(lint, reason)]`) | no `any`, no `as` (except `as const`, `satisfies`), no `!`, no `@ts-ignore`, no `@ts-expect-error` | no `interface{}` / bare `any` in domain sigs; no `_ = err`; no `//nolint` without reason |
 | No bare error strings | typed exception dataclass with `__str__` | `thiserror` enum (lib) or `anyhow` with `.context(...)` (app) | `Error` subclass with typed fields | sentinel `errors.New` + typed `*XError` struct; wrap with `%w`; check via `errors.Is/As` |
 | Boundary catch only | catch the exact exception you expect; broad `except Exception` only in `main()`, with logging + re-raise | `?` everywhere; never `panic!` in library code | `catch` must narrow with `instanceof` and re-throw or convert; no empty catch | every `(T, error)` checked; `panic` only in `main`/tests; one `httperr.Write` funnel in handlers |
 | Resources via RAII | `with` (sync) / `async with` (async) | `Drop` impl or RAII guard | `using`/`await using` (TC39 explicit resource management) | `defer x.Close()` immediately after acquisition; `bodyclose`/`sqlclosecheck` linters enforce |
@@ -189,7 +181,7 @@ A bare default constructor for any of these (no timeouts, no pool tuning, no sch
 | UB / soundness gate | (n/a) | **nightly miri** with strict provenance + Tree Borrows pass | (n/a) | **`nilaway`** + `-race` detector + `goleak` are the equivalent gate |
 | Disposable scripts | **PEP 723** inline metadata + `uv run script.py` | **rust-script** with inline `Cargo.toml` block | `bun run script.ts` | `//go:build ignore` + `go run script.go` |
 | Bootstrap a new project | `scripts/python/new-project.py` | `scripts/rust/new-project.py` | `scripts/typescript/new-project.ts` | `scripts/go/new-project.py` |
-| Pre-commit / CI gate | `ruff check . && basedpyright && pytest` | `cargo +nightly clippy -- -D warnings && cargo nextest run && cargo +nightly miri test` | `bunx biome check . && bunx tsc --noEmit && bun test` | `gofumpt -l . && golangci-lint run ./... && nilaway ./... && go test -race -shuffle=on -count=1 ./...` |
+| Pre-commit / CI gate | `ruff check . && basedpyright && pytest` | `cargo clippy --all-targets -- -D warnings && cargo nextest run && cargo test --doc && cargo +nightly miri nextest run` | `bunx biome check . && bunx tsc --noEmit && bun test` | `gofumpt -l . && golangci-lint run ./... && nilaway ./... && go test -race -shuffle=on -count=1 ./...` |
 
 A `tsconfig.json` with `"strict": true` alone is **not** strict. The reference enumerates the additional flags. Same for `pyproject.toml` and `Cargo.toml` - the references contain the canonical full configuration.
 
@@ -281,7 +273,7 @@ After every code-writing session, answer these out loud (in your reply) before d
 1. **Single responsibility?** Can I name what this file owns in one short noun phrase? If the answer needs the word "and", split.
 2. **Boundary purity?** Did I parse untrusted input into a typed value at the boundary, or did I pass `dict[str, Any]` / `serde_json::Value` / `unknown` past the boundary? If the latter, fix it.
 3. **Variant discrimination?** Did I use `if`/`elif`/`else` (or `switch` without `assertNever`, or `match` without `assert_never`) anywhere to discriminate on a tagged type or enum? If yes, rewrite as exhaustive match.
-4. **Escape hatches?** Any `Any`, `# type: ignore`, `unwrap`, `expect` outside `main`/tests, `as` numeric cast, `!`, `@ts-ignore`, `@ts-expect-error`, `#[allow]` on a real warning? If yes, fix the type or document why with a comment.
+4. **Escape hatches?** Any `Any`, `# type: ignore`, `unwrap`, `expect` outside tests, `as` numeric cast, `!`, `@ts-ignore`, `@ts-expect-error`, a Rust `#[allow]` instead of `#[expect(lint, reason)]`? If yes, fix the type or document why with a comment.
 5. **Defensive layer?** Any null check, try/except, or `isinstance` guarding a value the type system already proves? If yes, delete.
 6. **Helpers for one-off?** Any function, class, or trait introduced for a single caller that will never get a second caller? If yes, inline — axiom 0 should have caught it pre-write; this is the backstop.
 7. **Tests?** Is the behavior I just introduced locked by a test that would fail if I revert this commit?
@@ -349,7 +341,9 @@ These two skills are not optional cosmetics. They are the recovery path for the
 | Concurrency primitives (locks, atomics, channels, loom) | `references/rust/concurrency.md` |
 | axum + sqlx + tracing + tower HTTP stack | `references/rust/axum-stack.md` |
 | clap + color-eyre + tracing + indicatif CLI stack | `references/rust/clap-stack.md` |
-| Property tests (proptest) + snapshot tests (insta) | `references/rust/proptest-insta.md` |
+| Public API design (naming, conversions, traits, rustdoc sections) | `references/rust/api-design.md` |
+| Declarative and procedural macros | `references/rust/macros.md` |
+| Property tests (proptest) + snapshot tests (insta), test placement, doctests | `references/rust/proptest-insta.md` |
 | Disposable `rust-script` scripts | `references/rust/one-liners.md` |
 | Canonical library defaults | `references/rust/libraries.md` |
 | **ANY `unsafe` / FFI / `MaybeUninit` / lock-free work** | **`references/rust-ub/` (full directory)** |

package/packages/omo-codex/plugin/skills/programming/references/rust/README.md

@@ -35,6 +35,10 @@ let val = map.get("key").unwrap();
 let val = map.get("key").context("missing 'key' in config")?;
 ```
 
+The one exception is a failure that can only mean a bug in this crate (a proven invariant): `.expect("<the invariant>")` behind `#[expect(clippy::expect_used, reason = "<why it cannot fail>")]` on that statement. Clippy's `expect_used` deny and `scripts/rust/check-no-excuse-rules.sh` both honor exactly that form.
+
+**Discarding is handling too.** `let _ = fallible();` and `.ok();` that drop an error are forbidden (`let_underscore_must_use`). A best-effort call (cleanup in `Drop`, a rollback on an error path) logs the error it cannot return.
+
 Typed errors for libraries ([thiserror](https://docs.rs/thiserror)), ad-hoc errors for binaries ([anyhow](https://docs.rs/anyhow) / [color-eyre](https://docs.rs/color-eyre)). Full stack → [libraries.md](libraries.md).
 
 ### 2. No `unsafe` Without Miri Proof
@@ -73,30 +77,31 @@ fn process(input: &str) -> Cow<'_, str> { ... }
 fn process(input: &[u8], output: &mut [u8]) -> usize { ... }
 ```
 
-### 4. Compile-Time First — const fn Everything Const-Eligible
+### 4. Compile-Time First — Compute What Is Known at Build Time
 
-If a function CAN be `const fn`, it MUST be `const fn`. Full recipes → [zero-cost-safety.md §2](zero-cost-safety.md).
+Lookup tables, size assertions, and buffer sizes are computed at compile time. A function is `const fn` when a `const` context needs it or it is trivially const-eligible; never contort runtime logic to be const. Full recipes → [zero-cost-safety.md §2](zero-cost-safety.md).
 
 ```rust
 // Lookup tables computed at compile time — zero runtime cost
+#[expect(clippy::indexing_slicing, reason = "const evaluation: an out-of-bounds index is a compile error")]
 const CRC_TABLE: [u32; 256] = {
     let mut table = [0u32; 256];
-    let mut i = 0;
+    let mut i: u32 = 0;
     while i < 256 {
-        let mut crc = i as u32;
+        let mut crc = i;
         let mut j = 0;
         while j < 8 {
-            crc = if crc & 1 != 0 { (crc >> 1) ^ 0xEDB88320 } else { crc >> 1 };
+            crc = if crc & 1 != 0 { (crc >> 1) ^ 0xEDB8_8320 } else { crc >> 1 };
             j += 1;
         }
-        table[i] = crc;
+        table[i as usize] = crc; // u32 -> usize widens: the one cast `const` allows
         i += 1;
     }
     table
 };
 
 // Compile-time assertions — catch violations at build time, not runtime
-const { assert!(std::mem::size_of::<Header>() == 12, "Header must be 12 bytes") };
+const _: () = assert!(std::mem::size_of::<Header>() == 12, "Header must be 12 bytes");
 ```
 
 Use `const generics` for stack-allocated buffers with compile-time size:
@@ -119,7 +124,11 @@ use scopeguard::guard;
 fn deploy(artifact: &Path) -> Result<(), DeployError> {
     let backup = snapshot_current()?;
     // errdefer: restore on failure
-    let rollback = guard(backup, |b| { let _ = restore(&b); });
+    let rollback = guard(backup, |b| {
+        if let Err(error) = restore(&b) {
+            tracing::error!(%error, "rollback failed");
+        }
+    });
 
     upload(artifact)?;
     health_check()?;
@@ -185,6 +194,21 @@ impl Order<Validated> {
 // Order<Draft> has no .pay() method. Compiler enforces the workflow.
 ```
 
+### 9. Numbers State What Overflow and Conversion Mean
+
+`+` panics in debug and wraps in release: it states nothing. Pick the operation that says what the domain wants, and convert through the trait that says whether it can fail.
+
+```rust
+let total = a.checked_add(b).ok_or(Error::Overflow)?; // overflow is an error
+let level = volume.saturating_add(step);              // clamp at the bound
+let slot = seq.wrapping_add(1) % RING;                // modular by design
+let wide = u64::from(small);                          // lossless: From
+let port = u16::try_from(raw).map_err(|_| Error::Port(raw))?; // lossy: TryFrom
+scores.sort_by(f64::total_cmp);                        // NaN-safe total order
+```
+
+Never `as` for numeric conversion (the only exception is a lossless widening inside `const`, where `From` is unavailable; see [zero-cost-safety.md §2](zero-cost-safety.md)). Compare floats with an explicit tolerance chosen by the domain, never `==`. A value that can never be zero is `NonZeroU32` (and `Option<NonZeroU32>` costs no extra space).
+
 ---
 
 ## Standard Library Defaults
@@ -217,7 +241,7 @@ Every new project gets the strict lint config from [cargo-strict.md](cargo-stric
 ```bash
 cargo fmt --all -- --check && \
 cargo clippy --all-targets --all-features -- -D warnings && \
-cargo nextest run && \
+cargo nextest run && cargo test --doc && \
 cargo +nightly miri nextest run  # when unsafe is involved
 ```
 
@@ -231,19 +255,21 @@ Run through this list after writing any Rust code. Every item links to its recip
 |---|---|---|
 | 1 | Every function signature prefers `&[T]`/`&str`/`Cow` over owned types | [zero-cost-safety.md §3](zero-cost-safety.md) |
 | 2 | Hot-path allocations use arena (`bumpalo`) not scattered `Box`/`Vec` | [zero-cost-safety.md §1](zero-cost-safety.md) |
-| 3 | Const-eligible functions are `const fn` | [zero-cost-safety.md §2](zero-cost-safety.md) |
-| 4 | Lookup tables / config constants computed at compile time | [zero-cost-safety.md §2](zero-cost-safety.md) |
+| 3 | Values known at build time (tables, size asserts, buffer sizes) are computed at compile time | [zero-cost-safety.md §2](zero-cost-safety.md) |
+| 4 | Arithmetic states its overflow intent; numeric conversions use `From`/`TryFrom` | This file §9 |
 | 5 | Binary format parsing uses `zerocopy`, not `transmute` | [zero-cost-safety.md §4](zero-cost-safety.md) |
 | 6 | Cleanup logic uses `scopeguard` or `Drop`, never manual `if err` cleanup | [zero-cost-safety.md §5](zero-cost-safety.md) |
 | 7 | Distinct semantic units are newtypes, not primitive aliases | [type-state.md](type-state.md) |
 | 8 | State machines use type-state, not runtime `if state ==` | [type-state.md](type-state.md) |
-| 9 | No `unwrap()`/`expect()` outside `#[cfg(test)]` | [libraries.md](libraries.md) |
+| 9 | No `unwrap()`/`expect()` outside tests (invariant `expect` only behind `#[expect(clippy::expect_used, reason)]`); no discarded `Result` | This file §1 |
 | 10 | Every `unsafe` has SAFETY comment + miri test | [unsafe-discipline.md](unsafe-discipline.md), [../rust-ub/](../rust-ub/) |
 | 11 | Match on owned enums is exhaustive (no `_ =>`) | This file §7 |
 | 12 | Clippy pedantic passes with zero warnings | [cargo-strict.md](cargo-strict.md) |
 | 13 | Property tests exist for any function with a nontrivial domain | [proptest-insta.md](proptest-insta.md) |
 | 14 | Concurrency uses channels first, locks second, atomics last | [concurrency.md](concurrency.md) |
-| 15 | Async code uses `JoinSet` for structured concurrency | [async-tokio.md](async-tokio.md) |
+| 15 | Async code uses `JoinSet` for structured concurrency; no lock guard, `watch` borrow, or entered span held across `.await` | [async-tokio.md](async-tokio.md) |
+| 16 | Public API follows the naming, conversion, and trait rules; `From` never bypasses a newtype invariant | [api-design.md](api-design.md) |
+| 17 | A performance-motivated change carries its before/after measurement | [libraries.md](libraries.md) (criterion) |
 
 ---
 
@@ -274,7 +300,9 @@ zerocopy = { version = "0.8", features = ["derive"] }
 | File | When to Load |
 |---|---|
 | [zero-cost-safety.md](zero-cost-safety.md) | Arena, allocator, const fn, comptime, zero-alloc, bitfield, repr, scopeguard, errdefer, Zig-like patterns |
-| [type-state.md](type-state.md) | Newtype wrappers, type-state machines, branded IDs, phantom types |
+| [type-state.md](type-state.md) | Newtype wrappers, validated construction, type-state machines, branded IDs, phantom types |
+| [api-design.md](api-design.md) | Public API: naming, conversions, trait design, `#[must_use]`, `#[non_exhaustive]`, visibility, rustdoc sections |
+| [macros.md](macros.md) | `macro_rules!` hygiene, proc-macro crates (`syn`/`quote`), spanned compile errors |
 | [unsafe-discipline.md](unsafe-discipline.md) | Any `unsafe` block — SAFETY comments, safe wrappers, miri proof |
 | [libraries.md](libraries.md) | Library selection, crate decision tree, dependency audit |
 | [cargo-strict.md](cargo-strict.md) | Project bootstrap, lint config, CI gate commands |
@@ -297,7 +325,7 @@ zerocopy = { version = "0.8", features = ["derive"] }
 ///
 /// # Errors
 /// Returns `FooError::Bar` when the input is invalid.
-const fn frobnicate<'a>(
+fn frobnicate<'a>(
     arena: &'a Bump,        // explicit allocator when arena is in play
     input: &[u8],           // borrow, not owned
     output: &mut [u8],      // caller-provided buffer