[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M76RWTFWZ1AVMQBGK4QDMJ1N":3,"skill-same:01M76RWTFWZ1AVMQBGK4QDMJ1N":44},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":26,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M76RWTFWZ1AVMQBGK4QDMJ1N","running-tests",null,"Safe test execution patterns for opencode-swarm. Covers when to use the test_runner tool vs shell bun commands, scope safety rules, per-file isolation loops (bash and PowerShell), pre-existing failure verification, CI log reading, and failure classification. Load this skill when you need to run tests — not when you need to write them (see writing-tests for authoring guidance).","AlexanderNarbaev\u002Fagi","AlexanderNarbaev","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F33544956?v=4","01M755ZKB1JJ26ZBNZSDJ4C0TV","01M755ZKBX072HZMHVQBWK7MK7",1,"AGPL-3.0","https:\u002F\u002Fgithub.com\u002FAlexanderNarbaev\u002Fagi\u002Fblob\u002Fmain\u002F.opencode\u002Fskills\u002Frunning-tests\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: running-tests\ndescription: >\n  Safe test execution patterns for opencode-swarm. Covers when to use the test_runner\n  tool vs shell bun commands, scope safety rules, per-file isolation loops (bash and\n  PowerShell), pre-existing failure verification, CI log reading, and failure\n  classification. Load this skill when you need to run tests — not when you need to\n  write them (see writing-tests for authoring guidance).\n---\n\n# Running Tests for opencode-swarm\n\nThis skill is about **executing** tests safely. For **writing** tests, see `writing-tests`.\n\n---\n\n## ⛔ The One Rule That Prevents Session Kills\n\n**Never use `test_runner` with more than one source file for any discovery scope.**\n\n`graph` and `impact` each fan out per file through the import tree; `convention` maps\neach source file to a test file by name convention. The union quickly exceeds\n`MAX_SAFE_TEST_FILES = 50`, triggering `scope_exceeded`, which causes LLMs to\ncascade to `scope: 'all'` and kill the session. All three scopes now reject with\n`scope_exceeded` before fan-out when `sourceFiles.length > MAX_SAFE_SOURCE_FILES = 1`.\n\n---\n\n## Three-Layer Defense Against Session Blocking\n\ntest_runner has three pre-resolution guards that prevent unbounded fan-out from blocking the session:\n\n### Layer 1 — Source-file count guard (synchronous, fires before any I\u002FO)\n`sourceFiles.length > MAX_SAFE_SOURCE_FILES (1)` → returns `scope_exceeded` immediately. Catches the common case of multi-file calls before any filesystem access.\n\n### Layer 2 — Pre-resolution fan-out estimate (fast, ~100ms)\n`estimateFanOut(sourceFiles, workingDir)` reads the cached impact map and counts unique test files without spawning subprocesses. If the estimate exceeds `MAX_SAFE_TEST_FILES = 50`, the call returns `scope_exceeded` immediately — before any graph traversal begins. Only fires when `sourceFiles.length === 1` (Layer 1 has already passed).\n\n### Layer 3 — Budget-limited traversal + post-resolution length check\n`analyzeImpact` accepts a `budget` parameter (`MAX_SAFE_TEST_FILES = 50`). The traversal stops as soon as it has visited 50 test files and sets `budgetExceeded: true`. The call site checks this flag and returns `scope_exceeded` before processing results.\nAfter graph resolution, the final `testFiles.length` is additionally compared to `MAX_SAFE_TEST_FILES`. If exceeded, `scope_exceeded` is returned.\n\n**Result:** When fan-out exceeds the safe threshold, the session gets `outcome: 'scope_exceeded'` instead of hanging.\n\n---\n\n## Decision Tree: test_runner tool vs bun shell command\n\n```\nDo you need to run tests?\n│\n├─ Single test file, targeted validation\n│   └─ Either works. Prefer shell: bun --smol test \u003Cfile> --timeout 30000\n│\n├─ Multiple files in the same directory (e.g. all agents tests)\n│   └─ Shell only — per-file loop. Never test_runner with multiple files.\n│\n├─ Find tests related to ONE changed source file\n│   └─ test_runner is fine: { scope: 'graph', files: ['src\u002Fagents\u002Fcoder.ts'] }\n│      (single file → bounded fan-out)\n│\n├─ Find tests related to MULTIPLE changed source files\n│   └─ Shell only — per-file loop over the changed files, or run the whole directory.\n│      test_runner with any discovery scope + multiple source files = scope_exceeded\n│      (guard fires before fan-out for convention, graph, and impact scopes).\n│\n└─ Validate the entire repo (pre-push)\n    └─ Shell only — 5-tier suite from commit-pr skill. Never test_runner scope:'all'.\n```\n\n---\n\n## Scope Safety Reference\n\n| Scope | With `files: [one]` | With `files: [many]` | Notes |\n|-------|--------------------|--------------------|-------|\n| `'convention'` | ✅ Safe | ❌ Rejected (`scope_exceeded`) | Guard fires before fan-out; direct test file paths exempt |\n| `'graph'` | ✅ Safe (capped at 50 via budget) | ❌ Rejected (`scope_exceeded`) | Two-layer guard: source-file count + fan-out estimate |\n| `'impact'` | ✅ Safe (capped at 50 via budget) | ❌ Rejected (`scope_exceeded`) | Two-layer guard: source-file count + fan-out estimate |\n| `'all'` | ❌ Never | ❌ Never | Requires `allow_full_suite: true`; CI mirror only |\n| `'all'` | ❌ Never | ❌ Never | Requires `allow_full_suite: true`; CI mirror only |\n\n**Rule of thumb:** Pass exactly one source file to `test_runner`. For multiple files, use a shell loop.\n\n---\n\n## Per-File Isolation Loops\n\nCI runs agents\u002Ftools\u002Fservices in per-file isolation (one `bun --smol` process per file).\nReproduce this locally with the following loops.\n\n### bash (Linux \u002F macOS)\n\n```bash\n# Single directory — per-file isolation\nfor f in tests\u002Funit\u002Fagents\u002F*.test.ts; do\n  bun --smol test \"$f\" --timeout 30000\ndone\n\n# Multiple directories\nfor dir in tests\u002Funit\u002Ftools tests\u002Funit\u002Fservices tests\u002Funit\u002Fagents; do\n  for f in \"$dir\"\u002F*.test.ts; do\n    bun --smol test \"$f\" --timeout 30000\n  done\ndone\n\n# Stop on first failure (useful for debugging)\nfor f in tests\u002Funit\u002Fagents\u002F*.test.ts; do\n  bun --smol test \"$f\" --timeout 30000 || { echo \"FAILED: $f\"; break; }\ndone\n```\n\n### PowerShell (Windows)\n\n```powershell\n# Single directory — per-file isolation\nGet-ChildItem tests\u002Funit\u002Fagents\u002F*.test.ts | ForEach-Object {\n  bun --smol test $_.FullName --timeout 30000\n}\n\n# Multiple directories\n@('tests\u002Funit\u002Ftools', 'tests\u002Funit\u002Fservices', 'tests\u002Funit\u002Fagents') | ForEach-Object {\n  Get-ChildItem \"$_\u002F*.test.ts\" | ForEach-Object {\n    bun --smol test $_.FullName --timeout 30000\n  }\n}\n\n# Capture output (avoids truncation on large output)\nGet-ChildItem tests\u002Funit\u002Fagents\u002F*.test.ts | ForEach-Object {\n  bun --smol test $_.FullName --timeout 30000\n} | Out-File \"$env:TEMP\\test_out.txt\"\nGet-Content \"$env:TEMP\\test_out.txt\" | Select-Object -Last 50\n```\n\n**Common PowerShell pitfalls:**\n- `for f in ...; do` — invalid, use `Get-ChildItem | ForEach-Object`\n- `Select-String -Last N` — invalid parameter, use `Select-Object -Last N`\n- `2>&1 2>&1` — duplicate redirection, causes parse error; use `2>&1` once\n- `&&` — not supported in PowerShell 5.1; use `; if ($?) { cmd2 }` instead\n- After `bun install --frozen-lockfile --force`, non-elevated Windows shells can hit `EPERM` while reading refreshed `node_modules` entries. Treat that as a host permission\u002Faccess issue: rerun the same focused Bun command with approved\u002Felevated access before diagnosing it as a code or test failure.\n\n---\n\n## Batch vs Per-File: Which Directories Need Isolation?\n\n| Directory | Mode | Reason |\n|-----------|------|--------|\n| `tests\u002Funit\u002Ftools\u002F` | Per-file loop | Heavy `mock.module` usage; cache poisoning risk |\n| `tests\u002Funit\u002Fservices\u002F` | Per-file loop | Same |\n| `tests\u002Funit\u002Fagents\u002F` | Per-file loop | Same |\n| `tests\u002Funit\u002Fhooks\u002F` | Per-file loop | Same |\n| `tests\u002Funit\u002Fcli\u002F` | Batch OK | Fewer mock conflicts |\n| `tests\u002Funit\u002Fcommands\u002F` | Batch OK | Fewer mock conflicts |\n| `tests\u002Funit\u002Fconfig\u002F` | Batch OK | Fewer mock conflicts |\n| `tests\u002Fintegration\u002F` | Batch OK | Integration fixtures, not mock-heavy |\n| `tests\u002Fsecurity\u002F` | Batch OK | Adversarial inputs, no module mocks |\n| `tests\u002Fsmoke\u002F` | Batch OK | Built-package tests |\n\n---\n\n## Truncated Output Recovery\n\nWhen `bun test` output exceeds the bash tool's buffer, it is saved to a file with an ID\nlike `tool_dff778...`. This ID format is **not** accepted by `retrieve_summary` (which only\nreads `S1`, `S2` etc. format IDs). The output is effectively lost.\n\n**Prevention — pipe to a file explicitly:**\n\n```powershell\n# PowerShell\nbun --smol test tests\u002Funit\u002Fagents --timeout 60000 |\n  Out-File \"$env:TEMP\\test_out.txt\"\nGet-Content \"$env:TEMP\\test_out.txt\" | Select-Object -Last 50\n```\n\n```bash\n# bash\nbun --smol test tests\u002Funit\u002Fagents --timeout 60000 2>&1 | tee \u002Ftmp\u002Ftest_out.txt\ntail -50 \u002Ftmp\u002Ftest_out.txt\n```\n\n**To get a clean pass\u002Ffail summary only**, filter immediately:\n\n```powershell\n# PowerShell — show only summary lines\nbun --smol test tests\u002Funit\u002Fagents --timeout 60000 |\n  Select-String \"pass|fail|error\" |\n  Select-Object -Last 10\n```\n\n```bash\n# bash\nbun --smol test tests\u002Funit\u002Fagents --timeout 60000 2>&1 | grep -E \"pass|fail|error\" | tail -10\n```\n\n---\n\n## Verifying Pre-Existing Failures\n\nBefore documenting a failure as \"pre-existing,\" prove it exists on `main` without affecting\nyour working tree. Use a Git worktree — safer than `git stash` (stash can drop untracked\nfiles, fail on locked files on Windows, and leave you in an inconsistent state).\n\n```bash\n# bash — create a throwaway checkout of main\ngit worktree add \u002Ftmp\u002Frepro-check origin\u002Fmain\nbun --smol test \u002Ftmp\u002Frepro-check\u002Ftests\u002Funit\u002Fagents\u002Farchitect-workflow-security.test.ts --timeout 30000\ngit worktree remove \u002Ftmp\u002Frepro-check\n```\n\n```powershell\n# PowerShell — same pattern (use Join-Path for robust separator handling)\ngit worktree add \"$env:TEMP\\repro-check\" origin\u002Fmain\n$testPath = Join-Path \"$env:TEMP\\repro-check\" \"tests\\unit\\agents\\architect-workflow-security.test.ts\"\nbun --smol test $testPath --timeout 30000\ngit worktree remove \"$env:TEMP\\repro-check\"\n```\n\n**Decision after checking:**\n- Fails on `main` too → pre-existing. Document under `## Pre-existing failures` in PR body. Continue.\n- Fails only on your branch → you introduced it. Fix before pushing.\n\n**⚠️ Check your own session history first.** Before documenting anything as pre-existing, confirm you did not fix or update this test earlier in the current session. A test you fixed 20 messages ago is not pre-existing — listing it as such in the table or PR body is incorrect and will be caught in review.\n\n---\n\n## Failure Classification\n\nNot all failures are equal. Before deciding what to do, classify the failure:\n\n| Class | Definition | Example | What to do |\n|-------|-----------|---------|------------|\n| **Stale assertion** | Test checks for text\u002Fvalue that was deliberately removed | `expect(prompt).toContain('CONSTRAINT: [what NOT to do]')` — template removed in refactor | Update the assertion to match current state |\n| **Soft regression indicator** | Test checks a threshold the codebase has since exceeded | `expect(tokenCount).toBeLessThan(35000)` — prompt grew past limit | Fix the threshold or reduce the prompt; do not just document and ignore |\n| **Genuine pre-existing** | Failure exists on `main` unrelated to any recent change | `full-auto-intercept.test.ts` logger gating issue | Document in PR body; do not fix unless scoped |\n| **New regression** | Failure introduced by your changes | Tests for prompt text you removed without updating tests | Fix before pushing |\n\n**Stale assertions and soft regression indicators are actionable** — they signal drift between\ntests and code. Genuine pre-existing failures are not your responsibility to fix in this PR,\nbut they must be documented.\n\n---\n\n## Reading CI Failure Logs\n\nWhen a CI job fails, the GitHub Actions log shows the exact `file:line` of the failure.\nDo not guess — read the log.\n\n```bash\n# Get the failing job URL from the PR\ngh pr view \u003Cnumber> --json statusCheckRollup --jq '.statusCheckRollup[] | select(.conclusion==\"FAILURE\") | .detailsUrl'\n\n# Fetch and search the log (if gh CLI available)\ngh run view --log \u003Crun-id> | grep -E \"FAIL|error\" | head -20\n```\n\nOr open the `detailsUrl` directly in a browser \u002F via WebFetch and search for:\n- `(fail)` — Bun test failure marker\n- `error:` — parse or runtime error\n- `at \u003Canonymous>` — stack frame pointing to the test file and line\n\nOnce you have `tests\u002Funit\u002Fagents\u002Fsome-file.test.ts:354`, reproduce locally:\n```bash\nbun --smol test tests\u002Funit\u002Fagents\u002Fsome-file.test.ts --timeout 30000\n```\n\n---\n\n## Quick Reference: Common Failures and Causes\n\n| Symptom | Likely cause | Fix |\n|---------|-------------|-----|\n| `scope_exceeded` returned from test_runner | Fan-out exceeded 50 test files during graph\u002Fimpact resolution | Switch to per-file shell loop; reduce changed-files scope |\n| Session killed during test_runner | Pre-fix: unbounded fan-out on multiple files | Now returns `scope_exceeded` instead — no more session kills |\n| `mock.module` breaks unrelated tests | Missing spread of real module exports | Add `...realModule` spread |\n| Windows tests fail with EBUSY | `mock.restore()` called while child process holds lock | Add `test.skipIf(process.platform === 'win32')` |\n| Test output truncated, ID unreadable | Bash tool buffer exceeded | Pipe to `Out-File`\u002F`tee` explicitly |\n| `for f in ...; do` parse error | Bash syntax in PowerShell | Use `Get-ChildItem | ForEach-Object` |\n| `Select-String -Last N` error | Invalid PowerShell parameter | Use `Select-Object -Last N` |\n| Token budget test failure | Prompt grew past hardcoded threshold | Treat as soft regression; update threshold |\n| CONSTRAINT assertion fails after refactor | Test checks for removed format template | Update assertion to match current prompt |\n| `package-check` CI failure | `package-check` validates the npm tarball (`npm pack` + tarball contents) — a source\u002Fbuild\u002Fpackage-manifest problem, not generated-file drift. `dist\u002F` is generated and NOT committed — do not stage it; run `bun run build` locally only when you need the bundle. There is no longer a committed-dist drift check. |\n\n## Tree-sitter \u002F WASM test timeouts\n\nTests that exercise tree-sitter (any test calling `extractFileSymbols` or loading a `web-tree-sitter` grammar) may take several seconds on **first WASM module load**. Depending on the code path, tree-sitter is reached via the dynamic symbol-graph import or the externalized runtime import; either way, the first `Parser.init` \u002F grammar load in a process is slow.\n\n- Use `--timeout 60000` (not 30000) for test files that load tree-sitter grammars.\n- If the `test_engineer` agent gets stuck (no output for extended time), run the test file directly via bash with a longer timeout (`--timeout 120000`) to determine whether it's a WASM first-load delay or a genuine code failure.\n- **Classify the timeout** before returning the test_engineer to the coder — a WASM-load timeout is infrastructure, not a code bug.\n- Each test process loads WASM independently (no cross-process cache), so every file's first grammar load is slow.\n","# Running Tests for opencode-swarm\n\nThis skill is about **executing** tests safely. For **writing** tests, see `writing-tests`.\n\n---\n\n## ⛔ The One Rule That Prevents Session Kills\n\n**Never use `test_runner` with more than one source file for any discovery scope.**\n\n`graph` and `impact` each fan out per file through the import tree; `convention` maps\neach source file to a test file by name convention. The union quickly exceeds\n`MAX_SAFE_TEST_FILES = 50`, triggering `scope_exceeded`, which causes LLMs to\ncascade to `scope: 'all'` and kill the session. All three scopes now reject with\n`scope_exceeded` before fan-out when `sourceFiles.length > MAX_SAFE_SOURCE_FILES = 1`.\n\n---\n\n## Three-Layer Defense Against Session Blocking\n\ntest_runner has three pre-resolution guards that prevent unbounded fan-out from blocking the session:\n\n### Layer 1 — Source-file count guard (synchronous, fires before any I\u002FO)\n`sourceFiles.length > MAX_SAFE_SOURCE_FILES (1)` → returns `scope_exceeded` immediately. Catches the common case of multi-file calls before any filesystem access.\n\n### Layer 2 — Pre-resolution fan-out estimate (fast, ~100ms)\n`estimateFanOut(sourceFiles, workingDir)` reads the cached impact map and counts unique test files without spawning subprocesses. If the estimate exceeds `MAX_SAFE_TEST_FILES = 50`, the call returns `scope_exceeded` immediately — before any graph traversal begins. Only fires when `sourceFiles.length === 1` (Layer 1 has already passed).\n\n### Layer 3 — Budget-limited traversal + post-resolution length check\n`analyzeImpact` accepts a `budget` parameter (`MAX_SAFE_TEST_FILES = 50`). The traversal stops as soon as it has visited 50 test files and sets `budgetExceeded: true`. The call site checks this flag and returns `scope_exceeded` before processing results.\nAfter graph resolution, the final `testFiles.length` is additionally compared to `MAX_SAFE_TEST_FILES`. If exceeded, `scope_exceeded` is returned.\n\n**Result:** When fan-out exceeds the safe threshold, the session gets `outcome: 'scope_exceeded'` instead of hanging.\n\n---\n\n## Decision Tree: test_runner tool vs bun shell command\n\n```\nDo you need to run tests?\n│\n├─ Single test file, targeted validation\n│   └─ Either works. Prefer shell: bun --smol test \u003Cfile> --timeout 30000\n│\n├─ Multiple files in the same directory (e.g. all agents tests)\n│   └─ Shell only — per-file loop. Never test_runner with multiple files.\n│\n├─ Find tests related to ONE changed source file\n│   └─ test_runner is fine: { scope: 'graph', files: ['src\u002Fagents\u002Fcoder.ts'] }\n│      (single file → bounded fan-out)\n│\n├─ Find tests related to MULTIPLE changed source files\n│   └─ Shell only — per-file loop over the changed files, or run the whole directory.\n│      test_runner with any discovery scope + multiple source files = scope_exceeded\n│      (guard fires before fan-out for convention, graph, and impact scopes).\n│\n└─ Validate the entire repo (pre-push)\n    └─ Shell only — 5-tier suite from commit-pr skill. Never test_runner scope:'all'.\n```\n\n---\n\n## Scope Safety Reference\n\n| Scope | With `files: [one]` | With `files: [many]` | Notes |\n|-------|--------------------|--------------------|-------|\n| `'convention'` | ✅ Safe | ❌ Rejected (`scope_exceeded`) | Guard fires before fan-out; direct test file paths exempt |\n| `'graph'` | ✅ Safe (capped at 50 via budget) | ❌ Rejected (`scope_exceeded`) | Two-layer guard: source-file count + fan-out estimate |\n| `'impact'` | ✅ Safe (capped at 50 via budget) | ❌ Rejected (`scope_exceeded`) | Two-layer guard: source-file count + fan-out estimate |\n| `'all'` | ❌ Never | ❌ Never | Requires `allow_full_suite: true`; CI mirror only |\n| `'all'` | ❌ Never | ❌ Never | Requires `allow_full_suite: true`; CI mirror only |\n\n**Rule of thumb:** Pass exactly one source file to `test_runner`. For multiple files, use a shell loop.\n\n---\n\n## Per-File Isolation Loops\n\nCI runs agents\u002Ftools\u002Fservices in per-file isolation (one `bun --smol` process per file).\nReproduce this locally with the following loops.\n\n### bash (Linux \u002F macOS)\n\n```bash\n# Single directory — per-file isolation\nfor f in tests\u002Funit\u002Fagents\u002F*.test.ts; do\n  bun --smol test \"$f\" --timeout 30000\ndone\n\n# Multiple directories\nfor dir in tests\u002Funit\u002Ftools tests\u002Funit\u002Fservices tests\u002Funit\u002Fagents; do\n  for f in \"$dir\"\u002F*.test.ts; do\n    bun --smol test \"$f\" --timeout 30000\n  done\ndone\n\n# Stop on first failure (useful for debugging)\nfor f in tests\u002Funit\u002Fagents\u002F*.test.ts; do\n  bun --smol test \"$f\" --timeout 30000 || { echo \"FAILED: $f\"; break; }\ndone\n```\n\n### PowerShell (Windows)\n\n```powershell\n# Single directory — per-file isolation\nGet-ChildItem tests\u002Funit\u002Fagents\u002F*.test.ts | ForEach-Object {\n  bun --smol test $_.FullName --timeout 30000\n}\n\n# Multiple directories\n@('tests\u002Funit\u002Ftools', 'tests\u002Funit\u002Fservices', 'tests\u002Funit\u002Fagents') | ForEach-Object {\n  Get-ChildItem \"$_\u002F*.test.ts\" | ForEach-Object {\n    bun --smol test $_.FullName --timeout 30000\n  }\n}\n\n# Capture output (avoids truncation on large output)\nGet-ChildItem tests\u002Funit\u002Fagents\u002F*.test.ts | ForEach-Object {\n  bun --smol test $_.FullName --timeout 30000\n} | Out-File \"$env:TEMP\\test_out.txt\"\nGet-Content \"$env:TEMP\\test_out.txt\" | Select-Object -Last 50\n```\n\n**Common PowerShell pitfalls:**\n- `for f in ...; do` — invalid, use `Get-ChildItem | ForEach-Object`\n- `Select-String -Last N` — invalid parameter, use `Select-Object -Last N`\n- `2>&1 2>&1` — duplicate redirection, causes parse error; use `2>&1` once\n- `&&` — not supported in PowerShell 5.1; use `; if ($?) { cmd2 }` instead\n- After `bun install --frozen-lockfile --force`, non-elevated Windows shells can hit `EPERM` while reading refreshed `node_modules` entries. Treat that as a host permission\u002Faccess issue: rerun the same focused Bun command with approved\u002Felevated access before diagnosing it as a code or test failure.\n\n---\n\n## Batch vs Per-File: Which Directories Need Isolation?\n\n| Directory | Mode | Reason |\n|-----------|------|--------|\n| `tests\u002Funit\u002Ftools\u002F` | Per-file loop | Heavy `mock.module` usage; cache poisoning risk |\n| `tests\u002Funit\u002Fservices\u002F` | Per-file loop | Same |\n| `tests\u002Funit\u002Fagents\u002F` | Per-file loop | Same |\n| `tests\u002Funit\u002Fhooks\u002F` | Per-file loop | Same |\n| `tests\u002Funit\u002Fcli\u002F` | Batch OK | Fewer mock conflicts |\n| `tests\u002Funit\u002Fcommands\u002F` | Batch OK | Fewer mock conflicts |\n| `tests\u002Funit\u002Fconfig\u002F` | Batch OK | Fewer mock conflicts |\n| `tests\u002Fintegration\u002F` | Batch OK | Integration fixtures, not mock-heavy |\n| `tests\u002Fsecurity\u002F` | Batch OK | Adversarial inputs, no module mocks |\n| `tests\u002Fsmoke\u002F` | Batch OK | Built-package tests |\n\n---\n\n## Truncated Output Recovery\n\nWhen `bun test` output exceeds the bash tool's buffer, it is saved to a file with an ID\nlike `tool_dff778...`. This ID format is **not** accepted by `retrieve_summary` (which only\nreads `S1`, `S2` etc. format IDs). The output is effectively lost.\n\n**Prevention — pipe to a file explicitly:**\n\n```powershell\n# PowerShell\nbun --smol test tests\u002Funit\u002Fagents --timeout 60000 |\n  Out-File \"$env:TEMP\\test_out.txt\"\nGet-Content \"$env:TEMP\\test_out.txt\" | Select-Object -Last 50\n```\n\n```bash\n# bash\nbun --smol test tests\u002Funit\u002Fagents --timeout 60000 2>&1 | tee \u002Ftmp\u002Ftest_out.txt\ntail -50 \u002Ftmp\u002Ftest_out.txt\n```\n\n**To get a clean pass\u002Ffail summary only**, filter immediately:\n\n```powershell\n# PowerShell — show only summary lines\nbun --smol test tests\u002Funit\u002Fagents --timeout 60000 |\n  Select-String \"pass|fail|error\" |\n  Select-Object -Last 10\n```\n\n```bash\n# bash\nbun --smol test tests\u002Funit\u002Fagents --timeout 60000 2>&1 | grep -E \"pass|fail|error\" | tail -10\n```\n\n---\n\n## Verifying Pre-Existing Failures\n\nBefore documenting a failure as \"pre-existing,\" prove it exists on `main` without affecting\nyour working tree. Use a Git worktree — safer than `git stash` (stash can drop untracked\nfiles, fail on locked files on Windows, and leave you in an inconsistent state).\n\n```bash\n# bash — create a throwaway checkout of main\ngit worktree add \u002Ftmp\u002Frepro-check origin\u002Fmain\nbun --smol test \u002Ftmp\u002Frepro-check\u002Ftests\u002Funit\u002Fagents\u002Farchitect-workflow-security.test.ts --timeout 30000\ngit worktree remove \u002Ftmp\u002Frepro-check\n```\n\n```powershell\n# PowerShell — same pattern (use Join-Path for robust separator handling)\ngit worktree add \"$env:TEMP\\repro-check\" origin\u002Fmain\n$testPath = Join-Path \"$env:TEMP\\repro-check\" \"tests\\unit\\agents\\architect-workflow-security.test.ts\"\nbun --smol test $testPath --timeout 30000\ngit worktree remove \"$env:TEMP\\repro-check\"\n```\n\n**Decision after checking:**\n- Fails on `main` too → pre-existing. Document under `## Pre-existing failures` in PR body. Continue.\n- Fails only on your branch → you introduced it. Fix before pushing.\n\n**⚠️ Check your own session history first.** Before documenting anything as pre-existing, confirm you did not fix or update this test earlier in the current session. A test you fixed 20 messages ago is not pre-existing — listing it as such in the table or PR body is incorrect and will be caught in review.\n\n---\n\n## Failure Classification\n\nNot all failures are equal. Before deciding what to do, classify the failure:\n\n| Class | Definition | Example | What to do |\n|-------|-----------|---------|------------|\n| **Stale assertion** | Test checks for text\u002Fvalue that was deliberately removed | `expect(prompt).toContain('CONSTRAINT: [what NOT to do]')` — template removed in refactor | Update the assertion to match current state |\n| **Soft regression indicator** | Test checks a threshold the codebase has since exceeded | `expect(tokenCount).toBeLessThan(35000)` — prompt grew past limit | Fix the threshold or reduce the prompt; do not just document and ignore |\n| **Genuine pre-existing** | Failure exists on `main` unrelated to any recent change | `full-auto-intercept.test.ts` logger gating issue | Document in PR body; do not fix unless scoped |\n| **New regression** | Failure introduced by your changes | Tests for prompt text you removed without updating tests | Fix before pushing |\n\n**Stale assertions and soft regression indicators are actionable** — they signal drift between\ntests and code. Genuine pre-existing failures are not your responsibility to fix in this PR,\nbut they must be documented.\n\n---\n\n## Reading CI Failure Logs\n\nWhen a CI job fails, the GitHub Actions log shows the exact `file:line` of the failure.\nDo not guess — read the log.\n\n```bash\n# Get the failing job URL from the PR\ngh pr view \u003Cnumber> --json statusCheckRollup --jq '.statusCheckRollup[] | select(.conclusion==\"FAILURE\") | .detailsUrl'\n\n# Fetch and search the log (if gh CLI available)\ngh run view --log \u003Crun-id> | grep -E \"FAIL|error\" | head -20\n```\n\nOr open the `detailsUrl` directly in a browser \u002F via WebFetch and search for:\n- `(fail)` — Bun test failure marker\n- `error:` — parse or runtime error\n- `at \u003Canonymous>` — stack frame pointing to the test file and line\n\nOnce you have `tests\u002Funit\u002Fagents\u002Fsome-file.test.ts:354`, reproduce locally:\n```bash\nbun --smol test tests\u002Funit\u002Fagents\u002Fsome-file.test.ts --timeout 30000\n```\n\n---\n\n## Quick Reference: Common Failures and Causes\n\n| Symptom | Likely cause | Fix |\n|---------|-------------|-----|\n| `scope_exceeded` returned from test_runner | Fan-out exceeded 50 test files during graph\u002Fimpact resolution | Switch to per-file shell loop; reduce changed-files scope |\n| Session killed during test_runner | Pre-fix: unbounded fan-out on multiple files | Now returns `scope_exceeded` instead — no more session kills |\n| `mock.module` breaks unrelated tests | Missing spread of real module exports | Add `...realModule` spread |\n| Windows tests fail with EBUSY | `mock.restore()` called while child process holds lock | Add `test.skipIf(process.platform === 'win32')` |\n| Test output truncated, ID unreadable | Bash tool buffer exceeded | Pipe to `Out-File`\u002F`tee` explicitly |\n| `for f in ...; do` parse error | Bash syntax in PowerShell | Use `Get-ChildItem | ForEach-Object` |\n| `Select-String -Last N` error | Invalid PowerShell parameter | Use `Select-Object -Last N` |\n| Token budget test failure | Prompt grew past hardcoded threshold | Treat as soft regression; update threshold |\n| CONSTRAINT assertion fails after refactor | Test checks for removed format template | Update assertion to match current prompt |\n| `package-check` CI failure | `package-check` validates the npm tarball (`npm pack` + tarball contents) — a source\u002Fbuild\u002Fpackage-manifest problem, not generated-file drift. `dist\u002F` is generated and NOT committed — do not stage it; run `bun run build` locally only when you need the bundle. There is no longer a committed-dist drift check. |\n\n## Tree-sitter \u002F WASM test timeouts\n\nTests that exercise tree-sitter (any test calling `extractFileSymbols` or loading a `web-tree-sitter` grammar) may take several seconds on **first WASM module load**. Depending on the code path, tree-sitter is reached via the dynamic symbol-graph import or the externalized runtime import; either way, the first `Parser.init` \u002F grammar load in a process is slow.\n\n- Use `--timeout 60000` (not 30000) for test files that load tree-sitter grammars.\n- If the `test_engineer` agent gets stuck (no output for extended time), run the test file directly via bash with a longer timeout (`--timeout 120000`) to determine whether it's a WASM first-load delay or a genuine code failure.\n- **Classify the timeout** before returning the test_engineer to the coder — a WASM-load timeout is infrastructure, not a code bug.\n- Each test process loads WASM independently (no cross-process cache), so every file's first grammar load is slow.\n",{"name":5,"description":7},"main","7709dc9e5ebd3bd641124ad2a3f6bb053ac2dab6",".opencode\u002Fskills\u002Frunning-tests",0,"https:\u002F\u002Fgithub.com\u002FAlexanderNarbaev\u002Fagi","https:\u002F\u002Fgithub.com\u002FAlexanderNarbaev","2026-11-15 04:35:36",{"source":8,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add AlexanderNarbaev\u002Fagi --skill running-tests",{"tool":36,"command":37},"bunx","bunx skills add AlexanderNarbaev\u002Fagi --skill running-tests",{"tool":39,"command":40},"pnpm","pnpm dlx skills add AlexanderNarbaev\u002Fagi --skill running-tests","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FAlexanderNarbaev\u002Fagi\u002Fblob\u002Fmain\u002F.opencode\u002Fskills\u002Frunning-tests\u002FSKILL.md",true,[],[45,52,59,66,73,80],{"skillNo":46,"name":47,"nameZh":6,"description":48,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":49,"categories":50,"keywords":51,"publishedAt":18},"01M76RZHYHMGE1WP9JBCMNA801","springboot-patterns","Spring Boot architecture patterns, REST API design, layered services, data access, caching, async processing, and logging. Use for Java Spring Boot backend work.","https:\u002F\u002Fgithub.com\u002FAlexanderNarbaev\u002Fagi\u002Fblob\u002Fmain\u002F.veai\u002Fskills\u002Fspringboot-patterns\u002FSKILL.md",[],[],{"skillNo":53,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":56,"categories":57,"keywords":58,"publishedAt":18},"01M76RZE6JNZH5HV7Q8JM7R0PN","search-first","Research-before-coding workflow. Search for existing tools, libraries, and patterns before writing custom code. Invokes the researcher agent.","https:\u002F\u002Fgithub.com\u002FAlexanderNarbaev\u002Fagi\u002Fblob\u002Fmain\u002F.veai\u002Fskills\u002Fsearch-first\u002FSKILL.md",[],[],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":18},"01M76RZBV42EMQV77H7GMFY4AJ","scholar-evaluation","Structured scholarly-work evaluation for papers, proposals, literature reviews, methods sections, evidence quality, citation support, and research-writing feedback.","https:\u002F\u002Fgithub.com\u002FAlexanderNarbaev\u002Fagi\u002Fblob\u002Fmain\u002F.veai\u002Fskills\u002Fscholar-evaluation\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":18},"01M76RZ97GC3XAY48H126C30PM","redis-patterns","Redis data structure patterns, caching strategies, distributed locks, rate limiting, pub\u002Fsub, and connection management for production applications.","https:\u002F\u002Fgithub.com\u002FAlexanderNarbaev\u002Fagi\u002Fblob\u002Fmain\u002F.veai\u002Fskills\u002Fredis-patterns\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":18},"01M76RZ528FANTKX7Q9XR0CXM7","react-patterns","React 18\u002F19 patterns including hooks discipline, server\u002Fclient component boundaries, Suspense + error boundaries, form actions, data fetching, state management decision trees, and accessibility-first composition. Use when writing or reviewing React components.","https:\u002F\u002Fgithub.com\u002FAlexanderNarbaev\u002Fagi\u002Fblob\u002Fmain\u002F.veai\u002Fskills\u002Freact-patterns\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":18},"01M76RZ1244PZQRQV5HBQ4PVYQ","query-patterns","SQL patterns, relational database design, query optimization, transactions, analytics, and dialect-aware best practices.","https:\u002F\u002Fgithub.com\u002FAlexanderNarbaev\u002Fagi\u002Fblob\u002Fmain\u002F.veai\u002Fskills\u002Fquery-patterns\u002FSKILL.md",[],[]]