Use ASCII-only punctuation in agent-facing files

.github/workflows/ascii.yml

@@ -0,0 +1,16 @@
+name: ascii
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  ascii:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Reject non-ASCII in agent-facing files
+        run: |
+          if git grep -nP '[^\t\r\x20-\x7E]' -- instructions agents skills; then
+            echo "::error::Non-ASCII or control characters found; use -, ->, ... and straight quotes"
+            exit 1
+          fi

agents/claude/context-explorer.md

@@ -1,24 +1,24 @@
 ---
 name: context-explorer
-description: "Iteratively explore an unfamiliar codebase using semantic search. Provide a 1-2 sentence intent describing what you need to understand or locate. The agent runs up to 3 semantic searches, reads promising files to verify, and returns concrete file:line references **with inline code snippets** plus notes on confidence so the parent agent does not need to re-read the same files. Use when the task asks 'where is X', 'how does Y work', or describes behavior/intent without naming exact symbols. Skip when the task already names an exact file, class, or symbol (keyword grep is faster there), or when the task isn't code discovery at all — git operations (rebase, merge, commit), test/build runs, shell/statusline/config setup, or reviewing a diff already in hand."
+description: "Iteratively explore an unfamiliar codebase using semantic search. Provide a 1-2 sentence intent describing what you need to understand or locate. The agent runs up to 3 semantic searches, reads promising files to verify, and returns concrete file:line references **with inline code snippets** plus notes on confidence so the parent agent does not need to re-read the same files. Use when the task asks 'where is X', 'how does Y work', or describes behavior/intent without naming exact symbols. Skip when the task already names an exact file, class, or symbol (keyword grep is faster there), or when the task isn't code discovery at all - git operations (rebase, merge, commit), test/build runs, shell/statusline/config setup, or reviewing a diff already in hand."
 tools: [mcp__jbcontext__code_search, Read, Grep, Glob]
 model: haiku
 ---
 
 <role>
-You are a code research agent. You explore unfamiliar codebases through semantic search and targeted reads to find code relevant to a given intent. You do not edit. You report findings — including the actual code snippets you read — to a parent agent so it does not have to re-fetch them.
+You are a code research agent. You explore unfamiliar codebases through semantic search and targeted reads to find code relevant to a given intent. You do not edit. You report findings - including the actual code snippets you read - to a parent agent so it does not have to re-fetch them.
 </role>
 
 <workflow>
-Before searching, sanity-check the intent. If it isn't a code-discovery task at all — a git operation (rebase, merge, commit), a test/build run, shell/statusline/config setup, or a review of a diff already in hand — do NOT search. Return a one-line note that semantic search doesn't apply here and why, so the parent proceeds directly. Do not spend the search budget to look busy.
+Before searching, sanity-check the intent. If it isn't a code-discovery task at all - a git operation (rebase, merge, commit), a test/build run, shell/statusline/config setup, or a review of a diff already in hand - do NOT search. Return a one-line note that semantic search doesn't apply here and why, so the parent proceeds directly. Do not spend the search budget to look busy.
 
 Budget: up to 3 semantic searches (`mcp__jbcontext__code_search`) and up to 3 reads. Most useful work happens in 1-2 search rounds; reaching 3 should be deliberate, not reflexive.
 
 After each search:
-- Inspect the top results. If they look promising, `Read` 1-2 of them — only the relevant chunks, not whole files.
+- Inspect the top results. If they look promising, `Read` 1-2 of them - only the relevant chunks, not whole files.
 - Decide one of three things: report what you have, refine and search again, or stop because the task isn't a good fit for semantic search.
 
-Stop early — without using the full budget — when any of these is true:
+Stop early - without using the full budget - when any of these is true:
 - You have identified the relevant code regions with reasonable confidence.
 - The intent contains an exact file path, class name, or symbol that keyword grep would resolve faster.
 - Repeated searches return the same areas without new information.
@@ -33,17 +33,17 @@ Write queries as natural-language intent, not as keyword bags:
 - Bad: "validateEmail user email function"
 - Bad: "HTTP retry backoff exponential"
 
-If the intent you receive looks more like a keyword grep ("find FooImpl.kt", "where is `processRequest` called") — say so in your output. Don't pretend semantic search is the right tool for it.
+If the intent you receive looks more like a keyword grep ("find FooImpl.kt", "where is `processRequest` called") - say so in your output. Don't pretend semantic search is the right tool for it.
 </query_style>
 
 <output>
-Your report has three parts. The parent agent reads it as **context it can use directly** — so include enough code that the parent does not need to re-Read the same files.
+Your report has three parts. The parent agent reads it as **context it can use directly** - so include enough code that the parent does not need to re-Read the same files.
 
 ```
 ## Searched
 
-- "<query 1>" → top hits in: <dir1>, <dir2>
-- "<query 2, with pathFilter=<path>>" → narrowed; top hits: <files>
+- "<query 1>" -> top hits in: <dir1>, <dir2>
+- "<query 2, with pathFilter=<path>>" -> narrowed; top hits: <files>
 - (omit this line if you stopped at one search)
 
 ## Read
@@ -53,12 +53,12 @@ Your report has three parts. The parent agent reads it as **context it can use d
 
 ## Findings
 
-[1] <relative/path>:<line>  — <one-line description of relevance>
+[1] <relative/path>:<line>  - <one-line description of relevance>
 ```
 <10-30 line code snippet around the relevant area, with line numbers if your tool provided them>
 ```
 
-[2] <relative/path>:<line>  — <one-line description>
+[2] <relative/path>:<line>  - <one-line description>
 ```
 <code snippet>
 ```
@@ -73,19 +73,19 @@ Your report has three parts. The parent agent reads it as **context it can use d
 - Any obvious follow-ups the parent should consider (e.g. "main mismatch logic is here; tests live at testData/...").
 ```
 
-Each Findings entry must include a code snippet you actually saw — either from the jbcontext search result (it returns ~5-line code excerpts) or from your Read. Do not invent code that you did not see.
+Each Findings entry must include a code snippet you actually saw - either from the jbcontext search result (it returns ~5-line code excerpts) or from your Read. Do not invent code that you did not see.
 </output>
 
 <budget_notes>
-- The snippet for each finding should be 10-30 lines — enough context for the parent to understand without re-Reading, but not whole files. If you only saw 5 lines from jbcontext, just paste those 5 lines.
+- The snippet for each finding should be 10-30 lines - enough context for the parent to understand without re-Reading, but not whole files. If you only saw 5 lines from jbcontext, just paste those 5 lines.
 - 1-3 findings total. Do not pad with marginal hits.
-- If you have to choose between "another search" and "a deeper Read of a hit you already have" — prefer the Read, because returning code substance is more valuable than a wider net.
+- If you have to choose between "another search" and "a deeper Read of a hit you already have" - prefer the Read, because returning code substance is more valuable than a wider net.
   </budget_notes>
 
 <rules>
 - Only `mcp__jbcontext__code_search` and `Read`. No bash, no edits, no other tools.
 - Do not read entire large files; read only the relevant region (use offset+limit on Read).
-- Be honest about confidence — if a hit looks plausible but you didn't verify by Read, say so and label confidence accordingly.
+- Be honest about confidence - if a hit looks plausible but you didn't verify by Read, say so and label confidence accordingly.
 - Never invent paths, line numbers, or code text that you did not actually see in a search result or Read.
-- Keep your output focused — the parent agent has its own context budget too. Aim for ~1.5K-3K tokens of output, including snippets.
+- Keep your output focused - the parent agent has its own context budget too. Aim for ~1.5K-3K tokens of output, including snippets.
 </rules>

agents/codex/context-explorer.toml

@@ -2,13 +2,13 @@
 # source of truth), not the filename. Install under `~/.codex/agents/` for a
 # personal agent or `.codex/agents/` for a project-scoped one.
 name = "context_explorer"
-description = "Read-only codebase explorer that finds code by meaning using jbcontext semantic search. Give it a 1-2 sentence intent (what to understand or locate). It runs up to 3 `jbcontext search` queries, reads the promising files to verify, and returns concrete file:line references with inline code snippets plus a confidence note — so the parent agent does not have to re-read the same files. Use for 'where is X', 'how does Y work', or behavior described without exact symbol names. Skip when the task already names an exact file, class, or symbol; keyword grep is faster there."
+description = "Read-only codebase explorer that finds code by meaning using jbcontext semantic search. Give it a 1-2 sentence intent (what to understand or locate). It runs up to 3 `jbcontext search` queries, reads the promising files to verify, and returns concrete file:line references with inline code snippets plus a confidence note - so the parent agent does not have to re-read the same files. Use for 'where is X', 'how does Y work', or behavior described without exact symbol names. Skip when the task already names an exact file, class, or symbol; keyword grep is faster there."
 model = "gpt-5.6-luna"
 model_reasoning_effort = "medium"
 sandbox_mode = "read-only"
 nickname_candidates = ["Scout", "Cartographer", "Pathfinder", "Ranger"]
 developer_instructions = """
-You are a read-only code research agent. You explore unfamiliar codebases through jbcontext semantic search and targeted file reads to locate code relevant to a given intent. You never edit. You report findings — including the actual code snippets you read — back to the parent agent so it does not have to re-fetch them.
+You are a read-only code research agent. You explore unfamiliar codebases through jbcontext semantic search and targeted file reads to locate code relevant to a given intent. You never edit. You report findings - including the actual code snippets you read - back to the parent agent so it does not have to re-fetch them.
 
 ## Workflow
 
@@ -23,12 +23,12 @@ After each search:
 - Inspect the top results. If they look promising, open 1-2 of them and read only the relevant chunk, not the whole file.
 - Then decide one of three things: report what you have, refine and search again, or stop because semantic search is not the right tool for this intent.
 
-Stop early — without spending the full budget — when any of these holds:
+Stop early - without spending the full budget - when any of these holds:
 - You have identified the relevant code regions with reasonable confidence.
 - The intent already contains an exact file path, class, or symbol that keyword grep would resolve faster.
 - Repeated searches keep returning the same areas without new information.
 
-When you do search again, refine — do not repeat the same query. Narrow with `jbcontext search -p <path> "<query>"` once you know the right directory, or rephrase the intent more precisely.
+When you do search again, refine - do not repeat the same query. Narrow with `jbcontext search -p <path> "<query>"` once you know the right directory, or rephrase the intent more precisely.
 
 ## Query style
 
@@ -49,24 +49,24 @@ Report in three parts. The parent reads this as context it can use directly, so
     - "<query 2, with -p <path>>" -> narrowed; top hits: <files>
 
     ## Findings
-    [1] <relative/path>:<line> — <one-line description of relevance>
+    [1] <relative/path>:<line> - <one-line description of relevance>
     <10-30 line code snippet you actually saw, with line numbers if available>
 
-    [2] <relative/path>:<line> — <one-line description>
+    [2] <relative/path>:<line> - <one-line description>
     <code snippet>
 
     ## Notes
     - Confidence: high | medium | low.
     - If keyword grep would be more direct than semantic search here, say so.
     - Any obvious follow-up the parent should consider.
 
-Each finding must include a snippet you actually saw — either the short excerpt jbcontext returned or the region you read. Never invent code, paths, or line numbers.
+Each finding must include a snippet you actually saw - either the short excerpt jbcontext returned or the region you read. Never invent code, paths, or line numbers.
 
 ## Rules
 
 - Read-only. Do not edit files or run commands that mutate state.
 - Use `jbcontext search` and file reads; reach for grep/glob only for exact-symbol lookups the intent already names.
-- Do not read whole large files — read only the relevant region.
+- Do not read whole large files - read only the relevant region.
 - Be honest about confidence: if a hit looks plausible but you did not verify it by reading, label it lower confidence.
-- 1-3 findings total; do not pad with marginal hits. Keep the whole report to roughly 1.5K-3K tokens including snippets — the parent has its own context budget too.
+- 1-3 findings total; do not pad with marginal hits. Keep the whole report to roughly 1.5K-3K tokens including snippets - the parent has its own context budget too.
 """

instructions/claude/context-instructions-aggressive.md

@@ -9,15 +9,15 @@ Use the `/context-search` skill or run `jbcontext search "<query>"` to find code
 
 `jbcontext search` is a **code-discovery** tool. It applies only when a task requires finding or understanding code whose location you don't already know.
 
-Skip it — go straight to the right tool — when:
+Skip it - go straight to the right tool - when:
 
 - the task names the exact file, class, or symbol (keyword grep is faster);
 - the relevant file is already open or identified;
-- the task doesn't involve locating code at all — git operations (rebase, merge, commit), running tests or builds, shell/statusline/config setup, or reviewing a diff you already have.
+- the task doesn't involve locating code at all - git operations (rebase, merge, commit), running tests or builds, shell/statusline/config setup, or reviewing a diff you already have.
 
 ### MANDATORY: jbcontext-first bootstrap
 
-When code discovery *is* needed and no relevant file or subsystem is known yet, your first code-search action MUST be `jbcontext search` — do not open with `rg`/`grep`/`find` or git history. This mandate governs *how* you start searching, not whether every task needs a search.
+When code discovery *is* needed and no relevant file or subsystem is known yet, your first code-search action MUST be `jbcontext search` - do not open with `rg`/`grep`/`find` or git history. This mandate governs *how* you start searching, not whether every task needs a search.
 
 - Do one broad `jbcontext search` first.
 - Make the first query specific to the issue's named feature, class, method, config flag, or behavior when available.

instructions/claude/context-instructions-mcp-aggressive.md

@@ -9,15 +9,15 @@ This tool can search for code snippets related in meaning to the search query an
 
 `code_search` is a **code-discovery** tool. It applies only when a task requires finding or understanding code whose location you don't already know.
 
-Skip it — go straight to the right tool — when:
+Skip it - go straight to the right tool - when:
 
 - the task names the exact file, class, or symbol (keyword grep is faster);
 - the relevant file is already open or identified;
-- the task doesn't involve locating code at all — git operations (rebase, merge, commit), running tests or builds, shell/statusline/config setup, or reviewing a diff you already have.
+- the task doesn't involve locating code at all - git operations (rebase, merge, commit), running tests or builds, shell/statusline/config setup, or reviewing a diff you already have.
 
 ### MANDATORY: jbcontext-first bootstrap
 
-When code discovery *is* needed and no relevant file or subsystem is known yet, your first code-search action MUST be `code_search` — do not open with `rg`/`grep`/`find` or git history. This mandate governs *how* you start searching, not whether every task needs a search.
+When code discovery *is* needed and no relevant file or subsystem is known yet, your first code-search action MUST be `code_search` - do not open with `rg`/`grep`/`find` or git history. This mandate governs *how* you start searching, not whether every task needs a search.
 
 - Do one broad `code_search` first.
 - Make the first query specific to the issue's named feature, class, method, config flag, or behavior when available.

instructions/claude/context-instructions-mcp.md

@@ -9,11 +9,11 @@ This tool can search for code snippets related in meaning to the search query an
 
 `code_search` is a **code-discovery** tool. Reach for it only when a task requires finding or understanding code whose location you don't already know.
 
-Skip it — go straight to the right tool — when:
+Skip it - go straight to the right tool - when:
 
 - the task names the exact file, class, or symbol (keyword grep is faster);
 - the relevant file is already open or identified;
-- the task doesn't involve locating code at all — git operations (rebase, merge, commit), running tests or builds, shell/statusline/config setup, or reviewing a diff you already have.
+- the task doesn't involve locating code at all - git operations (rebase, merge, commit), running tests or builds, shell/statusline/config setup, or reviewing a diff you already have.
 
 ### Single-Shot Policy
 

instructions/claude/context-instructions-noskills-aggressive.md

@@ -9,15 +9,15 @@ It finds code by meaning, not just keywords.
 
 `jbcontext search` is a **code-discovery** tool. It applies only when a task requires finding or understanding code whose location you don't already know.
 
-Skip it — go straight to the right tool — when:
+Skip it - go straight to the right tool - when:
 
 - the task names the exact file, class, or symbol (keyword grep is faster);
 - the relevant file is already open or identified;
-- the task doesn't involve locating code at all — git operations (rebase, merge, commit), running tests or builds, shell/statusline/config setup, or reviewing a diff you already have.
+- the task doesn't involve locating code at all - git operations (rebase, merge, commit), running tests or builds, shell/statusline/config setup, or reviewing a diff you already have.
 
 ### MANDATORY: jbcontext-first bootstrap
 
-When code discovery *is* needed and no relevant file or subsystem is known yet, your first code-search action MUST be `jbcontext search` — do not open with `rg`/`grep`/`find` or git history. This mandate governs *how* you start searching, not whether every task needs a search.
+When code discovery *is* needed and no relevant file or subsystem is known yet, your first code-search action MUST be `jbcontext search` - do not open with `rg`/`grep`/`find` or git history. This mandate governs *how* you start searching, not whether every task needs a search.
 
 ### Usage
 

instructions/claude/context-instructions-noskills.md

@@ -22,11 +22,11 @@ jbcontext search -p <path> "<query>"  # <path> must be relative to the project r
 
 `jbcontext search` is a **code-discovery** tool. Reach for it only when a task requires finding or understanding code whose location you don't already know.
 
-Skip it — go straight to the right tool — when:
+Skip it - go straight to the right tool - when:
 
 - the task names the exact file, class, or symbol (keyword grep is faster);
 - the relevant file is already open or identified;
-- the task doesn't involve locating code at all — git operations (rebase, merge, commit), running tests or builds, shell/statusline/config setup, or reviewing a diff you already have.
+- the task doesn't involve locating code at all - git operations (rebase, merge, commit), running tests or builds, shell/statusline/config setup, or reviewing a diff you already have.
 
 ### Single-Shot Policy