Scripts Guide

Own local tooling, script wrappers, generated-artifact helper rules.

Ownership Map

• Tests: run-vitest.mjs; follow testing skill + test-authoring skill.
• Lint/typecheck: run-oxlint.mjs + run-tsgo.mjs own repo-local runtime behavior; use them in package scripts and CI steps.
• Changed-file checks: check-changed.mjs owns execution; changed-lanes.mjs owns classification. Never copy path-scope rules into hooks/CI snippets.
• Knip ownership for standalone commands and dynamically loaded children: follow Before You PR.
• PR preparation: pr / pr-lib own source acquisition, correction reviews, gate bindings. Changing them: read PR preparation.
• PR wrapper lifecycle: pr / pr-lib own supervision, locks, materialized dependencies. Changing/repairing them: read PR wrapper tooling.
• GitHub transport: pr-lib owns observations + protected dispatch. Changing API/Octopool behavior: read PR GitHub transport.
• Merge admission/recovery: pr-lib owns policy, retained outcomes, completion. Read merge admission, merge recovery, or prior-CI admin admission for that operation.
• Remote proof: crabbox-wrapper.mjs owns source capsules; .github/actions/prepare-testbox-shell owns shell/cwd. Changing them: read remote gate contracts. Operating boxes: use Crabbox skill.
• Generated artifacts: align source generator, package script, verification command. Prefer *:gen / *:check pairs over undocumented one-offs.

Wrapper Rules

• macOS-only Bash scripts: #!/bin/bash, Bash 3.2-compatible syntax. Invoke directly or with /bin/bash, including fixtures. Add new entrypoints to nativeScripts in test/scripts/build-and-run-mac.test.ts.
• Portable Bash entrypoints using heredocs/here-strings (including sourced helpers): copy the Darwin Bash 5.3+ re-exec guard from test/scripts/build-and-run-mac.test.ts before those operations (prevents heredoc pipe deadlocks) and add the file to portableScripts. stdin/sourced installers: request /bin/bash when replay impossible.
• Tests: run through scripts/run-vitest.mjs or root pnpm test ...; bare vitest ... starts local watch mode unless run or --run explicit.
• Changes to scripts/lib/ planners need the affected planner tests and the tooling test typecheck leaf: node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.test.root.tooling.json --incremental. pnpm tsgo:scripts does not typecheck their test callers.
• macOS CI workflow changes: run all test/scripts/ci-workflow*.test.ts, including failure-collection cases in ci-workflow-complete.test.ts, plus ci-swift-cache-lifetime.test.ts and macos-native-test-launch.test.ts; the workflow guards also exercise native runtime artifact packing and restoration. Validate workflows with scripts/check-workflows.mts.
• Lint (one/few files): direct node scripts/run-oxlint.mjs --tsconfig <matching config> <files...>, not sharded pnpm lint.

TypeScript Syntax

• scripts/** TypeScript implementation files: erasable by Node without transformation; pnpm check:script-erasability enforces it.
• Native Node execution: opt-in per entrypoint + import closure, only when runtime imports stay Node-resolvable. Keep tsx for closures depending on source runtime trees, frozen checkouts, package aliases, or tsconfig/path resolution.

PR Safety

• PR operations: follow maintainer workflow. Gate modes: landing. Default handoff: merge-run --auto-merge. Pending admission ≠ successful proof/merge completion.
• Landing subcommands require canonical/origin-main wrapper code. Never bypass wrapper trust, operation locks, exact-head review/gate bindings, live authority checks, or Octopool string rewrite protection; never select raw gh to get landing through.
• Before returning: join all PR-state-mutating children. Drained self-exited failures auto-release their operation lock; interrupted/uncertain locks stay held — verify no child tools remain before reported exact-OID scripts/pr lock-recover command. Never delete lock refs manually.
• Preserve transition journals, preparation evidence, outcome refs, captures. Never clear/push refs/openclaw/pr-merge-outcomes/<PR>, hand-edit receipts, or infer non-execution from failed command, elapsed time, absent process, or open PR.
• Accepted/pending/uncertain writes: investigate through native recovery. Never blindly resubmit/switch transports. Existing land authority covers investigated same-scope recovery, not gate bypasses/new scope/method.
• Before comments/ownership-checked cleanup: confirm merge receipt. Completion comments: one attempt; reconcile uncertain comments by marker. Preserve worktrees/captures with unresolved outcome; never delete recreated branch by name.

Execution Gotchas

• Fs-safe dependency trouble: follow on-demand vendoring instructions; vendor contents local, registry dependencies default.
• Trusted normal checkout missing dependencies: pnpm install --frozen-lockfile, retry once before diagnosing code defect.
• Formatting: pnpm format defaults locally to the pinned Bun fork, with an oxfmt fallback; OPENCLAW_FORMAT_TOOL=oxfmt forces oxfmt. CI checks oxfmt/Bun parity. Generated-artifact gates retain oxfmt; see caller inventory. Typechecking: repository tsgo lanes. Scope: pnpm changed:lanes --json; targeted tests/checks. Avoiding worktree reconciliation: node scripts/run-vitest.mjs with ready dependencies.