@simpleapps-com/augur-skills 2026.4.16 → 2026.4.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simpleapps-com/augur-skills",
-  "version": "2026.04.16",
+  "version": "2026.04.17",
   "description": "Install curated Claude Code skills",
   "license": "MIT",
   "type": "module",

package/skills/simpleapps/bash-simplicity/SKILL.md

@@ -18,8 +18,8 @@ The entire plugin system exists to remove the user as the bottleneck. Every perm
 
 | Tier | Method | Speed | Example |
 |------|--------|-------|---------|
-| 1 | Dedicated tools (Read, Grep, Glob, Edit) | **WILL** run immediately, zero permission chance | `Grep(pattern: "...", path: "repo")` |
-| 2 | Simple Bash (one command, no operators) | **MAY** run immediately if pre-approved | `pnpm typecheck` |
+| 1 | Dedicated tools (Read, Edit, Write) | **WILL** run immediately, zero permission chance | `Read(file_path: "repo/src/foo.ts")` |
+| 2 | Simple Bash (one command, no operators) | **MAY** run immediately if pre-approved | `pnpm typecheck`, `grep -rn pattern repo` |
 | 3 | Complex Bash (operators, plumbing) | **WILL** trigger a permission prompt | `pnpm typecheck 2>&1; echo $?` |
 
 Prefer tier 1 over tier 2. Use tier 2 only when no dedicated tool exists. NEVER use tier 3.
@@ -37,26 +37,32 @@ The Bash tool is a managed environment, not a raw shell. It already captures std
 | Limit output | Returned in full | `\| head`, `\| tail`, `\| grep` |
 | Run the next step | Make a separate tool call | `&&`, `;`, `\|\|` |
 | Pass output to another command | Write to a tmp file | `$(...)`, backticks |
-| Run inline code | Use Read/Grep/Edit tools | `node -e`, `python -c` |
+| Run inline code | Use Read/Edit tools | `node -e`, `python -c` |
 
 **One command per Bash call. No operators. No plumbing. If the command has a `;`, `&&`, `|`, `$()`, `2>&1`, or `2>/dev/null` in it, it is wrong.**
 
 ## Use Dedicated Tools
 
-Dedicated tools are faster, require no permission, and produce better output. MUST use them instead of Bash equivalents:
+Dedicated tools are faster, require no permission, and produce better output. MUST use them instead of Bash equivalents when one exists:
 
 | Instead of | Use |
 |------------|-----|
-| `grep`, `rg` | Grep tool |
-| `find`, `ls` (for search) | Glob tool |
 | `cat`, `head`, `tail` | Read tool |
 | `sed`, `awk` | Edit tool |
 | `echo >`, `cat <<EOF` | Write tool |
 
-Reserve Bash for commands that have no dedicated tool equivalent: build tools, test runners, git, package managers, and system commands.
+**Search is now Bash-only.** Claude Code 2.1.117 removed the dedicated Grep and Glob tools. Search files with one of:
+
+| Use case | Bash command |
+|----------|--------------|
+| Search file contents | `grep -rn <pattern> <path>` or `rg <pattern> <path>` |
+| Find files by name | `find <path> -name <pattern>` |
+| List directory entries | `ls <path>` |
+
+Reserve Bash for these and for commands that never had a dedicated tool: build tools, test runners, git, package managers, system commands.
 
 These commands are **denied** in project settings and will always be rejected. Do not attempt them:
-`cd`, `cat`, `grep`, `rg`, `find`, `sed`, `awk`, `head`, `tail`, `sleep`, `kill`, `pkill`
+`cd`, `cat`, `sed`, `awk`, `head`, `tail`, `sleep`, `kill`, `pkill`
 
 MUST NOT use `node -e` or `python -c` to run inline scripts. These trigger permission prompts. If you need to read a file, use the Read tool. If you need to process data, do it in your response, not in a shell script.
 
@@ -64,13 +70,11 @@ MUST NOT use `node -e` or `python -c` to run inline scripts. These trigger permi
 
 If a Bash call is denied, do NOT retry the same command and do NOT ask the user to approve it. Before anything else, check for a tool equivalent or shell plumbing that can be decomposed:
 
-- `grep`/`rg` → Grep tool (for files on disk); for command output, the Bash tool already returned it — read what you have
-- `find`/`ls` → Glob tool
 - `cat`/`head`/`tail` → Read tool
 - `sed`/`awk` → Edit tool
 - `|`, `2>&1`, `&&`, `;`, `$()` → split into separate calls; the Bash tool already captures stdout, stderr, and exit code
 
-Worked example: `pnpm --filter <package> typecheck 2>&1 | grep -c "error TS"` is denied because of the pipe to `grep`. The fix is to run `pnpm --filter <package> typecheck` alone — the Bash tool returns the full output and exit code — then count "error TS" occurrences in the returned output yourself. No grep, no redirection, no retry.
+Worked example: `pnpm --filter <package> typecheck 2>&1 | grep -c "error TS"` is denied because of the pipe and redirection. The fix is to run `pnpm --filter <package> typecheck` alone — the Bash tool returns the full output and exit code — then count "error TS" occurrences in the returned output yourself. No pipe, no redirection, no retry. (`grep` itself is allowed; the deny is on the shell plumbing around it.)
 
 ## Background Tasks
 
@@ -96,21 +100,21 @@ Do not retry the server start until the user confirms the port is free.
 
 ## Cross-Project Searching
 
-When looking at another project's code, use dedicated tools with the project path. MUST NOT use shell commands.
+When looking at another project's code, search with Bash directly using the project path. MUST keep it to one simple command per call — no pipes, no `-exec`, no `2>&1 | head`.
 
 Wrong: `find {path}/repo -name "*.ts" -exec grep -l "pattern" {} \; 2>/dev/null | head -10`
-Right: `Grep(pattern: "pattern", path: "{path}/repo", glob: "*.ts")`
+Right: `grep -rln --include="*.ts" "pattern" {path}/repo`
 
-Wrong: `ls {path}/repo/src/components/`
-Right: `Glob(pattern: "{path}/repo/src/components/**/*")`
+Wrong: `ls {path}/repo/src/components/ | head`
+Right: `ls {path}/repo/src/components/`
 
-All project paths are known and predictable (see `simpleapps:wiki` Cross-Project Wiki Access). MUST NOT search the filesystem with `find` or download from the internet. Just use the dedicated tool with the known path.
+All project paths are known and predictable (see `simpleapps:wiki` Cross-Project Wiki Access). Use the known path; do not search the entire filesystem.
 
 ## Subagent Responsibility
 
 Subagents do NOT inherit this skill. They see only the prompt you give them. The primary agent MUST brief every subagent on bash-simplicity before delegating shell work, and owns the output that comes back.
 
-Every subagent prompt that touches Bash MUST include a one-liner: "One command per Bash call. No operators. Use dedicated tools (Read, Grep, Glob, Edit, Write) over shell equivalents."
+Every subagent prompt that touches Bash MUST include a one-liner: "One command per Bash call. No operators. Use dedicated tools (Read, Edit, Write) over their shell equivalents (`cat`, `sed`, `awk`, `echo >`). Search with Bash directly: `grep -rn`, `find`, `ls` — Claude Code 2.1.117 removed the Grep/Glob tools."
 
 If a subagent returns a command containing any forbidden operator (see the table above), that is the primary agent's failure. Reject and ask for a re-plan, or translate into separate simple calls. Do not execute it. A subagent violating this is running on a stale prompt; fix the prompt.
 

package/skills/simpleapps/code-contracts/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: code-contracts
+description: When working in load-bearing code (the 5-10% where correctness matters most — money math, auth, concurrency, state machines, security boundaries), tighten the type system first, then add formal contracts (@requires/@ensures/@invariant/@trusted) in the host language's native comment syntax. Use Unicode glyphs (∀, ∈, ≥, ℕ) for AI priming, paired with ASCII gloss for human readers. The contracts pay off through three independent mechanisms: priming agent reasoning, surfacing tests, and adding context-window value that agents themselves report. Drift between contract and code is a defect.
+---
+
+# Code Contracts
+
+> **Status: EXPERIMENTAL** for the priming hypothesis (mechanism #1). The test-surfacing (#2) and agent-reported-value (#3) mechanisms are observed in practice. Apply selectively to load-bearing code; treat as a defensible bet across three channels — pays off if any one of them lands.
+
+Persistent prompt engineering encoded in source code. Formal contracts on load-bearing functions pay off through three independent mechanisms.
+
+## Three mechanisms — why this is worth the context cost
+
+| # | Mechanism | What it does | Status |
+|---|-----------|--------------|--------|
+| 1 | Latent-space priming | Unicode glyph rarity pulls hidden state toward the formal-methods neighborhood — sharper reasoning on the *next edit* | Hypothesis (defensible bet) |
+| 2 | Test surfacing | Explicit clauses make intent legible — agents generate *new and better tests* using each clause as an oracle | **Observed in practice** |
+| 3 | Agent-reported value | Agents themselves report that contracts add useful context for complex / load-bearing methods | **Observed in practice** |
+
+The contracts are the artifact. The three mechanisms are *consequences*. Even if mechanism #1 is weaker than hoped, mechanisms #2 and #3 are already paying off.
+
+## What this is — and is not
+
+This is **not** documentation. It is **not** a parallel comment style for human readers alone. It is a cognitive switch that targets future agents reading the file, paired with an ASCII gloss that bridges human readers.
+
+Models trained on F\*/Lean/Dafny/Coq corpora develop a "spec-then-implement" reasoning policy — slower, more rigorous, explicit about pre/postconditions and effects. Plain TS/PHP/Python does not activate that policy because the surface form does not match. Unicode-heavy contract prose in the same file *does* match — the model upshifts into the more rigorous mode for the function it precedes.
+
+The annotations do not add information the model could not infer. They change the *mode* the model reasons in. Same idea as "let's reason step by step" or "you are an expert at X" — moved out of the system prompt and into the artifact, where it primes every future agent that touches the code, not just the current session.
+
+## When to use it
+
+MUST apply ONLY in **load-bearing code** — the 5-10% of functions where a subtle bug compounds:
+
+- Money math (pricing, tax, fees, totals, currency conversion, rounding)
+- Auth and permission decisions
+- Concurrency and ordering (locks, queues, retries, idempotency keys)
+- State machines and protocols (multi-step flows that must not be entered out of order)
+- Security boundaries (input validation at trust boundaries, sanitization, sinks like SQL/HTML/shell)
+- Algorithms with non-trivial invariants (custom sort/search variants, bespoke data structures)
+
+MUST NOT apply by default to:
+
+- Getters, setters, simple field accessors
+- Glue code, plumbing, framework adapters
+- UI components, presentational code
+- One-off scripts, throwaway code
+- Test bodies (the test name is the spec)
+
+Annotation density has a real context-window cost on every read. MUST concentrate it where the rigorous-reasoning upgrade matters most.
+
+## Two surfaces per clause
+
+Every clause has two surfaces riding the same line:
+
+| Surface | Purpose |
+|---------|---------|
+| **Formal** (Unicode) | Activates the rigorous-reasoning latent circuits in readers with the bandwidth to parse it. Rarity is the activation. |
+| **Prose** (gloss + assumptions) | Renders the same content as natural language **with assumptions named**, so readers with less parsing bandwidth derive the same conclusions without paying a notation tax. |
+
+These are not redundant translations. **The prose surface carries assumptions, not just symbols.**
+
+### The gloss MUST name assumptions
+
+When a clause depends on something the formal notation does not make explicit — a precondition the caller is presumed to satisfy, a sentinel value the contract treats as out-of-scope, a side condition the body relies on — the gloss MUST name it. Naming what is *not* part of the contract is as important as naming what is.
+
+The formal notation cannot say "and X is assumed to hold." The gloss can. Examples:
+
+- `@requires q ≥ 0  // q is non-negative; assumes caller validated input, no NaN check here`
+- `@ensures result ∈ ℕ  // result is a non-negative integer; overflow is caller's responsibility`
+- `@invariant balance ≥ 0  // balance never negative; assumes no concurrent mutators outside this lock`
+
+Without explicit assumption-naming, a reader must derive the assumptions from negative space — by inspecting callers, the implementation, related tests. That derivation is the parsing tax that costs careful reasoning capacity. The gloss eliminates the tax by naming it directly.
+
+### Why both surfaces
+
+Dense formal notation can crowd out attention to factual claims when parsing it costs the reader most of their bandwidth — the cognitive cost of parsing symbols leaves less capacity for engaging with what the contract actually says. Pairing the formal surface with prose-and-assumptions means:
+
+- Readers with high parsing bandwidth get the formal surface activating careful reasoning **plus** the gloss catching what the formal notation leaves implicit
+- Readers with less parsing bandwidth derive the same conclusions from the prose alone, no tax paid
+- Either reader gets a working contract; neither is left to derive the assumptions from negative space
+
+This is also why the gloss helps human readers: a junior dev seeing `∀ x ∈ xs. x ≥ 0` cold has nowhere to grab. The same dev seeing `∀ x ∈ xs. x ≥ 0  // every x in xs is non-negative; assumes upstream validation` reads it once and starts building intuition for the symbol set with the assumptions made explicit.
+
+### Two pairing patterns
+
+Pick one and apply consistently within a file.
+
+```ts
+// Pattern A — inline assumption-naming gloss after the formal clause
+@requires q ≥ 0           // q is non-negative; assumes caller validated input
+@ensures  result ∈ ℕ       // result is a natural number; overflow is caller's responsibility
+```
+
+```ts
+// Pattern B — bracketed gloss on the same line
+@requires q ≥ 0  (q is non-negative; assumes caller validated input)
+@ensures  ∀ x ∈ items. x.qty ≥ 0  (every item has non-negative qty; empty array is allowed)
+```
+
+Pattern A is denser; Pattern B reads more like prose. Either works.
+
+See `vocabulary.md` for the full glyph palette, the clause-first derivation table, and per-language examples.
+
+## Order of preference
+
+When a function deserves a contract, work down this list. MUST use the first form that expresses the property; SHOULD fall back to looser forms only when the tighter one cannot.
+
+### 1. Tighten the type system first
+
+A type the compiler enforces beats a comment the compiler ignores. The model reads types the same way it reads contracts.
+
+```ts
+// Loose type with comment contract
+// @requires y !== 0
+function divide(x: number, y: number): number { return x / y; }
+
+// Branded type that makes the precondition unrepresentable
+type NonZero = number & { readonly __brand: 'NonZero' };
+function divide(x: number, y: NonZero): number { return x / y; }
+```
+
+Tools by language:
+
+- **TypeScript** — branded types, narrow union types, `readonly`, template literal types, exhaustive `switch` over discriminated unions
+- **PHP** — typed properties, `readonly`, enums (8.1+), Psalm template types
+- **Python** — `Literal`, `Final`, `NewType`, `Annotated`, `Protocol`, `assert_never`
+
+### 2. Use the language's checker-enforced annotation
+
+When the type system cannot express the property, reach for an annotation a real static analyzer enforces. Drift produces a tool error, not just an agent surprise.
+
+| Language | Tool | Real annotations |
+|----------|------|------------------|
+| PHP | Psalm | `@psalm-assert`, `@psalm-pure`, `@psalm-immutable`, `@psalm-mutation-free` |
+| PHP | PHPStan | `@phpstan-assert`, `@phpstan-pure`, generic types |
+| TypeScript | tsc + ESLint | branded types, `eslint-plugin-functional` for purity, `assert_never` |
+| Python | mypy / pyright | `assert_type`, `TypeGuard`, `TypeIs`, `Never`, `@final` |
+
+### 3. Formal contract for the residual
+
+For properties no checker can express — algebraic laws, multi-step protocol invariants, invariants over external state — leave a contract in the host language's native comment syntax with Unicode + ASCII gloss.
+
+Annotation forms:
+
+- `@requires <precondition>` — must hold of inputs at call time
+- `@ensures <postcondition>` — guaranteed of result / observable state
+- `@invariant <property>` — holds at loop head, between method calls, across state transitions
+- `@trusted <param>` — value inlined into a security-sensitive sink; origin must be trusted code, never user input
+- `@pure` / `@mutates X` / `@throws Y` / `@io` — effect declaration
+- `@property <law>` — algebraic law (idempotence, associativity, commutativity, monotonicity)
+- `@time <bound>` / `@space <bound>` — asymptotic complexity. Use `Θ(...)` for tight bound, `O(...)` for upper bound only, `Ω(...)` for lower bound. Most contracts write `O(...)`; SHOULD prefer `Θ(...)` when the bound is actually tight, because `O(n²)` is technically true of an `O(n)` function and that looseness primes the wrong reasoning.
+
+See `vocabulary.md` for the clause-first derivation table (clause shape → encoding tier), the full glyph palette, and the complexity-notation glossary.
+
+## Style rule — form is the activation
+
+The form MUST match formal-language conventions. Informal prose does not switch the reasoning mode. Four tiers, with the strongest pairing Unicode formal + assumption-naming gloss:
+
+- ✗ informal English: `// always positive` — neither activation nor assumptions
+- ✗ ASCII formal alone: `@ensures result >= 0` — weak priming, no assumption-naming
+- ◐ Unicode formal + translation gloss: `@ensures result ≥ 0  // result >= 0` — primes the formal surface, gloss is redundant translation
+- ✓ Unicode formal + assumption-naming gloss: `@ensures result ≥ 0  // result is non-negative; overflow is caller's responsibility` — primes high-bandwidth readers AND gives low-bandwidth readers the same content as prose with assumptions explicit
+
+The shape signals "this is a function to reason about formally," not "this is a function to skim and pattern-match." The gloss makes the contract robust across reader capacities.
+
+## Semantic-ambiguity second pass
+
+After writing range and type constraints, ask: **does any constant or sentinel in this function carry more than one meaning?**
+
+Formal annotations bias toward easy formal targets — range, type, sign. They miss *semantic overloading*: a single value standing for two distinct domain states. The blind spot is structural — `@requires x ≥ 0` cannot express "and `0` is distinct from `null`."
+
+Common patterns to flag:
+
+- `value ?? 0` (or `?? ""`, `?? -1`) where the coalesced-from value and the coalesced-to value carry different meanings downstream
+- Sentinel integers (`-1` for "not found", `999` for "all", `0` for "default")
+- Empty string vs missing string
+- `0` returned from a counter that also legitimately returns `0`
+
+When you find one, lift the sentinel into the type — `null | { kind: 'loaded'; price: PositiveAmount } | { kind: 'call-for-price' }` — so the two states are unrepresentable as the same value. Then the formal annotation regains coverage.
+
+### Real example
+
+`@simpleapps-com/augur-utils` `derive-price.ts` was written with the contract treatment, including a self-aware note about IEEE-754 vs ℝ. It still missed this exact blind spot:
+
+```ts
+const unitPrice = priceData.unitPrice ?? 0;  // null collapses to 0
+isCallForPrice: unitPrice === 0,             // 0 means "call for price"
+```
+
+The contract correctly enforces `unitPrice ≥ 0 ∧ Number.isFinite(unitPrice)` — but cannot say "and `null` is distinct from `0`," because `null` was already coalesced away. The fix is to handle `priceData.unitPrice === null` *before* the coalesce, lifting the two states into the type.
+
+## Drift is a defect — not a sync target
+
+If the code contradicts an annotation, that is a bug. MUST decide which is wrong and fix it. MUST NOT silently rewrite the annotation to match incorrect code.
+
+Unenforced annotations that drift do active harm — they prime future agents toward the wrong invariant. A wrong contract is worse than no contract.
+
+When you find drift while editing:
+
+1. Read the contract carefully
+2. Read the code carefully
+3. Decide which one captures the intended behavior — look at call sites, tests, related code
+4. Fix whichever is wrong
+5. If you cannot tell which is intended, MUST stop and ask the user. MUST NOT guess.
+
+### Tautological postconditions
+
+A related anti-pattern: postconditions that mirror the constructor. `@ensures result.kind === 'loaded'` on `function loaded(item) { return { kind: 'loaded', item } }` adds nothing — the constructor already guarantees it. Useful postconditions assert properties the *reader of the call* would not derive from the constructor alone (algebraic laws, conservation invariants, observable state changes). Restating the constructor adds bookkeeping without adding reasoning, and is a sign the contract was back-fitted rather than written clause-first.
+
+## Why mechanism #1 works (priming hypothesis)
+
+LLM behavior is conditional on context shape. Models trained on verified-language corpora develop latent circuits for spec-then-implementation reasoning. Native-syntax contracts in the F\*/Lean/Dafny shape *plausibly* activate those circuits during code generation, review, and refactoring — even though the host language has no formal semantics.
+
+**Rarity is the activation.** The Unicode glyphs (∀, ∃, ⟨⟩, ↦, ⊑, ≥, ≤, ≠, ⇒, ∧, ∨, ¬, ℕ, ℝ, ∈, ∉) co-occur in training data with theorem-prover output, type-theory papers, and formal-methods source. Sampling tokens with those glyphs pulls hidden state toward that neighborhood. ASCII transliterations (`forall`, `>=`, `=>`) live in commoner code-review text — for AI priming, that familiarity dampens the shift.
+
+The asymmetry: if the priming hypothesis works, as proof-trained model capability improves over time, annotations added today retroactively become more valuable. Zero extra work from the developer; the priming benefit grows with each model upgrade.
+
+## Why mechanism #2 works (test surfacing)
+
+Distinct from priming. **Observed in practice:** when a function carries explicit clauses, the agent generates *new and better tests* on subsequent edits — tests it would not have surfaced reading the implementation alone.
+
+Contracts make intent legible. Each clause is an oracle for at least one test class:
+
+- Each `@requires` → input-boundary tests (`q < 0`, `q = 0`, `q = NaN`)
+- Each `@ensures` → property to assert on the output
+- Each `@invariant` → multi-step test (call sequence, then check invariant)
+- Each `@trusted` → fuzz-test target on untrusted inputs
+- Each `@time O(...)` → scaling benchmark (assert the bound holds at n=10, n=100, n=1000)
+- Each `@space O(...)` → memory-stability test (assert the bound holds across input sizes)
+- Clauses also expose edge cases by negation: `@requires q ≥ 0` makes the agent ask "what about q < 0? what about NaN?"
+
+Without the contract, the agent has only the function body to inspect — and the body rarely announces its boundaries explicitly. With the contract, every clause is a test-case oracle. This effect is observable session-by-session — test count, edge-case coverage, mutation-test kill rate.
+
+### Close cousin: improvement-opportunity surfacing
+
+The same legibility that surfaces tests also surfaces *improvement opportunities*. A function annotated `@time O(n²)` invites the agent reading it to ask "can this be improved to `O(n log n)`?" The complexity contract makes the target visible. Without it, the agent maintains the function as written; with it, the agent has an explicit invariant to question. Same mechanism (legible intent → visible gap), different output (refactor candidates instead of test cases).
+
+This is why complexity contracts are not just documentation. A function honestly labeled `@time O(n²)` and called from a hot loop is a refactor target the agent will surface on the next read.
+
+## Why mechanism #3 works (agent-reported value)
+
+Agents themselves report, in active session use, that the contract content adds useful context for complex / load-bearing methods. The cost of carrying contracts in the context window is paid back in usefulness, not just consumed. Qualitative confirmation, but real-world signal that the practice pays off in routine session work.
+
+## Evidence and falsifiability
+
+Mechanism #1 is **plausible but not directly measured for in-source contracts**. Cite-able adjacent evidence:
+
+- **ContractEval** (arXiv 2510.12047) — LLM contract-satisfaction rises from 0% (vanilla) to ~50% when contracts are stated in the prompt. Demonstrates the mechanism works for *prompt-supplied* contracts.
+- **Specification-Guided Repair of Dafny Programs with LLMs** (arXiv 2507.03659) — LLMs reason measurably better when Dafny pre/postconditions are present.
+- **Type-Constrained Code Generation** (arXiv 2504.09246) — type annotations cut hallucinated APIs and compilation errors >50%. Supports "tighten the type system first."
+- **CoT mech-interp** (arXiv 2402.18312, arXiv 2507.22928) — surface cues like "let's think step by step" route through identifiable internal circuits in larger models. Supports "surface form conditions reasoning mode."
+
+**Falsifiable prediction:** annotating a load-bearing function with these contracts produces, on the next agent edit, fewer correctness regressions and/or more rigorous reasoning traces than the same function un-annotated.
+
+**Practical signals before the formal experiment runs:**
+
+- Test-count / edge-case-coverage / mutation-kill-rate delta between Unicode-bearing and ASCII-bearing contracts on equivalent functions (mechanism #2; observable session-by-session)
+- Fewer correctness regressions in functions carrying contract annotations (mechanism #1; quarter-scale)
+- Fewer "oops, missed the case where X" follow-up commits to annotated functions
+- Agent feedback on whether the contracts are pulling weight in their reasoning (mechanism #3; per-session)
+
+If signals trend the wrong way over a quarter of usage, the bet has not paid off and the skill SHOULD be downgraded or removed.
+
+Until then, treat this skill as a defensible bet across three independent mechanisms.
+
+## See also
+
+- **`vocabulary.md`** — full Unicode glyph palette, ASCII gloss patterns, clause-first derivation table, per-language examples
+- **`audit.md`** — the audit modes (per-file + session-aware), invoked by `/contract-audit`
+- **`apply.md`** — six-phase loop (Orient → Read → Draft → Trim → Discover → Verify) for adding contracts to existing code

package/skills/simpleapps/code-contracts/apply.md

@@ -0,0 +1,154 @@
+# Code Contracts — Apply
+
+The six-phase loop for adding contracts to existing code. Use when starting from a function that does not yet carry contracts and you have decided (manually or via `audit.md`) it is load-bearing enough to warrant them.
+
+## When to invoke this
+
+Three triggers:
+
+1. **Audit recommended it.** A `/contract-audit` report named this file as a contract candidate.
+2. **You're already editing the file** for unrelated reasons and noticed it deserves contracts. Add them as part of the edit pass; do not split into a separate task.
+3. **A bug fix landed here recently.** The fix is the highest-quality signal that the function carries non-trivial invariants worth documenting. Walk the loop after the fix.
+
+MUST NOT invoke broadly. Applying contracts to non-load-bearing code is itself a failure of the practice — it produces JSDoc bloat without the priming or test-surfacing payoff.
+
+## The six phases
+
+Run them in order. Each phase has a discrete output that feeds the next.
+
+### Phase 1: Orient
+
+Read the file's recent history. Bug fixes are bug-locus candidates — they reveal where the invariants matter.
+
+```
+git -C repo log --oneline -10 -- <path>
+```
+
+Flag any `fix:` commits as locus candidates. For each, read the commit message and the diff — what invariant was being violated? Capture it; phase 3 will turn it into a clause.
+
+Re-verify any wiki rule that may apply (e.g., the project's PHP conventions for contract docblocks, naming conventions, helper patterns) before invoking it. Wiki content drifts; do not rely on stale recall.
+
+**Output:** a short list of candidate invariants pulled from recent fix commits.
+
+### Phase 2: Read
+
+Read three things, in order:
+
+1. **The target file** — full content, not skimmed.
+2. **The sibling methods it dispatches to** — if `processOrder` calls `validateLineItems` and `applyTax`, read both.
+3. **The heaviest callers** — find the top three call sites and read enough of each to understand what they assume about this function's behavior.
+
+Reasoning from method names alone produces false recommendations. The contract clauses MUST come from observed behavior (the body) AND observed assumptions (the call sites). Skip this phase and the contracts will be plausible-but-wrong — the worst kind of contract.
+
+**Output:** a working understanding of what the function actually does, what its callers assume, and any drift between intent and implementation.
+
+### Phase 3: Draft
+
+Write the contract clauses, clause-first.
+
+For load-bearing files, write a **file-level docblock** that frames the file's role in the system. For each load-bearing method, write a per-method contract:
+
+```php
+/**
+ * @requires <precondition>          (ASCII gloss)
+ * @ensures  <postcondition>          (ASCII gloss)
+ * @invariant <property>              (ASCII gloss, where applicable)
+ *
+ * Footgun: <named footgun from phase 1 or 2 — bug that hit, sentinel ambiguity, etc.>
+ *          (ASCII gloss of the footgun)
+ */
+```
+
+Use Unicode glyphs paired with ASCII gloss per the dual-audience pattern in `SKILL.md`. See `vocabulary.md` for the glyph palette and per-language examples.
+
+Cite specifics:
+
+- The bug-fix commit (e.g., "Footgun: see fix in <sha> — empty array vs single-zero array were silently the same precondition")
+- Sibling files where applicable (e.g., "see `OrderTotal.php` for how the result is consumed")
+- Wiki rules where they apply (file:line citations)
+
+**Output:** a draft docblock per load-bearing method, plus a file-level overview if the file's role warrants one.
+
+### Phase 4: Trim
+
+Cut anything an agent could recover from reading the code itself. The contract MUST add information, not restate the implementation.
+
+Concrete cuts:
+
+- Postconditions that mirror the constructor (e.g., `@ensures result.kind === 'loaded'` on `function loaded(item) { return { kind: 'loaded', item } }`) — drop them.
+- Range assertions that the type system already enforces (`@requires q ≥ 0` when the parameter type is `Natural`) — drop them.
+- Prose that narrates the body (`// loop builds the running sum`) — drop them.
+- Comments that explain syntax (`// using ?? for default`) — drop them.
+
+What stays:
+
+- Footguns that aren't visible in the body (sentinel ambiguities, cross-file trust boundaries, ordering invariants, conservation properties)
+- Algebraic laws (idempotence, commutativity, monotonicity)
+- Cross-method invariants
+- Anything a future reader would not derive from the body alone
+
+**Output:** a tight contract that earns every line.
+
+### Phase 5: Discover
+
+Ask: **what invariant did you surface that does not belong in this docblock but should be captured as a wiki rule?**
+
+The discover phase is the highest-leverage step and the easiest to skip. While writing contracts, you often surface unstated conventions — a parameter ordering rule, a naming convention, a trust assumption that applies across many files. These do not belong in any one docblock but are the kind of knowledge that evaporates on `/clear`.
+
+For each discovered convention:
+
+- Decide where it belongs (project wiki page, shared skill, a `README.md` next to the code)
+- Write it down (or offer to write it down — the user MAY want to phrase it themselves)
+- Cite the file/line that surfaced it
+
+**Output:** zero or more wiki-bound captures, written or queued.
+
+Examples of the kind of invariants this phase catches:
+
+- A `$siteId`-first-parameter rule across helper functions that was implicit in the code but not documented
+- A trust assumption that strings labeled "internal" never reach SQL without going through a quoter — true in practice, undocumented
+- A "delete flag is `'Y'`, never `null`" convention that the code relies on but no test or comment names
+
+### Phase 6: Verify
+
+For each clause written in phase 3 (and not cut in phase 4), ask: **what tests does this clause demand that the test suite does not yet have?**
+
+Walk the clauses:
+
+- Each `@requires` → name the missing input-boundary tests (negative inputs, NaN, empty, max, etc.)
+- Each `@ensures` → name the missing output-property assertions
+- Each `@invariant` → name the missing multi-step tests that exercise the invariant across call sequences
+- Each `@trusted` → name the missing fuzz cases on untrusted-input simulation
+- Each `@time O(...)` / `Θ(...)` → name the missing scaling benchmark (assert the bound holds at n=10, n=100, n=1000)
+- Each `@space O(...)` / `Θ(...)` → name the missing memory-stability test across input sizes
+
+This phase is the test-gap report for the contract. It is parallel to phase 5: phase 5 captures wiki-bound knowledge gaps, phase 6 captures test-bound knowledge gaps. Complexity-claim gaps are especially load-bearing — an unverified `@time Θ(n)` claim drifts to `O(n²)` silently across refactors.
+
+The output of phase 6 is a list of tests to write. **Do not write them in this loop** — that's a separate task. The list is the artifact; whether the user writes the tests now or later is their call.
+
+**Output:** a list of missing tests, one per clause, ordered by which would catch the most likely class of regression first.
+
+## Convention authority
+
+The PHP-side convention for contract docblocks lives in `wiki/PHP-Conventions.md § Contract Docblocks for Load-Bearing Methods` (in the originating repo's wiki). MUST cite that page rather than duplicating its content here. This skill's role is the *workflow*; the *convention* is a per-repo artifact.
+
+For TS and Python, the conventions are folded directly into `SKILL.md` and `vocabulary.md` because those languages do not yet have a per-repo conventions page that lives elsewhere.
+
+## Canonical examples
+
+Reference the existing contracted methods so an agent can model new work on a verified example:
+
+- `packages/roark/src/MathUtils.php::normalizeL2`
+- `packages/roark/src/StringUtils.php::makeKey`
+- `packages/roark/src/Helpers/CacheHelper.php` (file-level overview plus `tryLock`, `lock`, `isLocked`, `get`, `getLockKeyByName`)
+- `packages/roark/src/Enums/CacheTtl.php` (file-level overview plus `toSeconds`)
+- `packages/roark/src/Enums/StatusChar.php` (file-level overview plus `description`)
+- `packages/open_search/src/Helpers/ItemsHelper.php` (file-level overview plus `applyIndexAction`, `getIndexAction`, `modifyIndex`)
+
+(All paths are in the `simpleapps-com/augur` repo. Cross-repo read may be needed; the WIP-side `code-contracts-cluster.md` notes this as an open item.)
+
+## Reference
+
+- `SKILL.md` — the writing skill (auto-triggered on load-bearing edits) and the three-mechanism framing
+- `vocabulary.md` — full glyph palette + clause-first derivation table + per-language examples
+- `audit.md` — the audit modes (per-file + session-aware)

package/skills/simpleapps/code-contracts/audit.md

@@ -0,0 +1,173 @@
+# Code Contracts — Audit
+
+The audit modes invoked by `/contract-audit`. Two modes; pick by argument:
+
+| Mode | Trigger | What it does |
+|------|---------|--------------|
+| **Per-file** | `/contract-audit <file>` | Walks the file for security seams and contract gaps; produces contracts and a test-gap report |
+| **Session-aware** | `/contract-audit` (no args) | Scans files **read or written in this session**; for each, evaluates load-bearing-ness, existing contracts, and recommendation |
+
+The session-aware mode is the high-leverage one: it surfaces contract candidates *while context is fresh*, instead of relying on the user to remember to run the audit later.
+
+## Frame the audit as bug discovery, not documentation
+
+The exercise's value is the discipline of writing contracts forcing real bugs to surface. The annotations themselves are a secondary artifact. Every audit MUST produce a *report*, not auto-applied annotations — the human stays in the loop on what to annotate vs. fix.
+
+## Per-file audit
+
+For a given file, walk these four questions in order:
+
+### 1. Where do types not capture a runtime constraint?
+
+Look for:
+
+- `string` parameters inlined into SQL, HTML, shell, or other security-sensitive sinks — trusted vs. untrusted origin is invisible
+- Coupled optional fields (e.g. `afterKey` requires `afterKeyColumn`)
+- Non-null assertions (`!`) load-bearing on a runtime guard
+- Sentinel values (`-1`, `0`, `999`, empty string) carrying domain meaning the type cannot express
+- Number that should be ℕ, ℤ⁺, or a refinement (e.g. percentage in `[0, 100]`)
+- Loops over inputs of unknown size — implicit `O(n)` or `O(n²)` claims with no contract to make the cost visible
+
+For each finding, propose a contract clause AND the type-level fix that would make the clause unnecessary (the order-of-preference rule from `SKILL.md`). For complexity findings, propose `@time` / `@space` clauses *and* flag the function as a refactor candidate if the asymptotic class is plausibly improvable (e.g., nested-loop O(n²) where a hash-keyed O(n) is reachable).
+
+### 2. Does the function's name and docstring match its actual behavior?
+
+Read the function name, its docstring (if any), and its body. Look for:
+
+- Plural names returning singular results (e.g. `guardrailPlugins` returning one plugin)
+- Verbs that misstate the operation (`getX` that mutates, `isX` that returns a string)
+- Docstrings describing intent that the body doesn't enforce
+- Function that does N+1 things when the name promises 1
+
+For each finding, decide: rename the function OR rewrite the body. Drift between name and behavior is a defect by the same rule that applies to contracts.
+
+### 3. Does this file produce values consumed elsewhere with implicit contracts?
+
+This is the **highest-value finding** and the hardest to surface. Walk every value the file emits — return values, exported constants, structures pushed into shared state, strings written to global queries, fields assigned on shared objects.
+
+For each emitted value, ask:
+
+- Where is it consumed? (Other files in the repo)
+- What does the consumer assume about its shape, format, sanitization, or origin?
+- Is that assumption written down anywhere?
+
+The producer/consumer pair has an *implicit contract* in the gap. Surface it. Either annotate the producer with a `@trusted`/`@ensures` clause, or harden the consumer to defend against violation. Cross-file trust boundaries are where the worst bugs live.
+
+### 4. For each contract this audit produces, what tests does the contract demand that the test suite does not yet have?
+
+This is the test-gap report. For each clause from questions 1–3:
+
+- `@requires` → list missing input-boundary tests (negative inputs, NaN, empty, max, etc.)
+- `@ensures` → list missing output-property assertions
+- `@invariant` → list missing multi-step tests that exercise the invariant across calls
+- `@trusted` → list missing fuzz cases on untrusted-input simulation
+- `@time O(...)` / `@time Θ(...)` → list missing scaling benchmarks (assert the bound holds at n=10, n=100, n=1000)
+- `@space O(...)` / `@space Θ(...)` → list missing memory-stability tests across input sizes
+
+The test-gap pass turns the audit from "find bugs" into "find bugs *and* find the test that would have caught them next time." Complexity-claim gaps are especially load-bearing — without scaling tests, the claim is unfalsifiable and an `O(n²)` regression slips into an `O(n)`-claimed function unchecked.
+
+## When NOT to annotate
+
+This section MUST appear in every audit report, before the per-section findings. Without it, the audit produces JSDoc bloat instead of signal.
+
+Skip annotations on:
+
+- **Pure transforms whose contract is fully expressed in the type signature.** A function `(n: NonZero) => number` already says `@requires n !== 0` in the type — no comment needed.
+- **Test files.** The test name is the spec. Annotating tests adds noise.
+- **Generated code.** Don't annotate; the generator is the spec.
+- **One-off scripts and throwaway code.** Not load-bearing; not worth the context cost.
+- **Glue code, plumbing, framework adapters, UI components, getters/setters.** Same scope rule as `SKILL.md`.
+
+If the comment would just restate the type, it MUST NOT be added. The audit's signal is bugs surfaced and gaps in tests, not annotation count.
+
+## Output format
+
+Every audit produces a markdown report with this structure:
+
+```markdown
+# Audit: <file or session>
+
+## Scope
+<file paths audited; load-bearing assessment per file>
+
+## When NOT to annotate (carryover)
+<note any patterns in this audit that fall in the skip list — pure transforms whose type already says it, tests, generated, etc.>
+
+## Findings
+
+### 1. Types that don't capture runtime constraints
+<list per-file findings; for each, propose contract + type-level fix>
+
+### 2. Name / docstring drift
+<list per-file findings; for each, propose rename OR body fix>
+
+### 3. Cross-file trust boundaries (highest-value)
+<list producer/consumer pairs with implicit contracts; propose @trusted/@ensures on the producer or hardening on the consumer>
+
+### 4. Test gaps
+<list per-finding tests that the proposed contracts demand and the suite does not have>
+
+## Suggested next steps
+<ordered list — usually: fix bugs found in section 1, address drift in 2, harden boundaries in 3, write missing tests in 4>
+```
+
+The audit is **read-only**. MUST NOT auto-apply contracts or modify code or tests. The human reviews the report and decides what to act on.
+
+## Session-aware mode
+
+When `/contract-audit` is invoked with no arguments, run a session-aware scan instead of per-file.
+
+### Discover the candidate set
+
+Look at the files **read or written in this session** (using session context, recent tool-call history, or open editor state). Filter to:
+
+- Source files in `repo/` (not test files, not config, not generated)
+- Files with at least one substantive read or edit this session
+- Files large enough to plausibly contain load-bearing functions (skip files < ~50 lines unless the agent has reason to believe they're security-critical)
+
+### Score each file
+
+For each candidate, evaluate:
+
+| Dimension | Question |
+|-----------|----------|
+| Load-bearing-ness | Does this file contain money math, auth, concurrency, state machines, security boundaries, or non-trivial algorithms? |
+| Existing contracts | Are there already `@requires` / `@ensures` / `@invariant` / `@trusted` clauses? |
+| Worth adding | If no contracts present, would adding them surface a bug or fill a test gap? |
+
+The agent has been in the file's context this session — use that. Don't re-derive load-bearing-ness from cold.
+
+### Output: ranked recommendations
+
+Produce a ranked list:
+
+```markdown
+# Session-aware contract audit — N candidates
+
+## Recommended (highest leverage)
+
+1. **`<path>`** — <one-line rationale: load-bearing reason + observed gap>
+   Suggested action: <add contracts to function X; harden the boundary at line Y; etc.>
+
+2. **`<path>`** — ...
+
+## Already covered
+
+<files with contracts already in place — note any drift the agent observed during the session>
+
+## Skip (not load-bearing)
+
+<files in the candidate set that don't meet the scope rule; brief reason>
+```
+
+Keep the rationale short. The user picks the top item and runs `/contract-audit <path>` to do a per-file deep dive.
+
+### Why this mode pays off
+
+The user does not have to remember to run an audit. The agent surfaces candidates while the context is fresh. Mechanism #3 (agent-reported value) operationalizes here — the agent saw the file in this session and can score it; a cold audit cannot.
+
+## Reference
+
+- `SKILL.md` — the writing skill (auto-triggered on load-bearing edits)
+- `vocabulary.md` — full glyph palette + clause-first derivation table + per-language examples
+- `apply.md` — six-phase loop for adding contracts to existing code (when this audit recommends "add contracts to function X")

package/skills/simpleapps/code-contracts/vocabulary.md

@@ -0,0 +1,196 @@
+# Code Contracts — Vocabulary Reference
+
+The full glyph palette, ASCII gloss patterns, clause-first derivation table, and per-language examples. Loaded by `SKILL.md` on demand.
+
+## Glyph palette
+
+A small, opinionated set. MUST stay narrow — each glyph the agent emits should be one a reader has seen elsewhere in this codebase, not a novelty.
+
+| Family | Glyphs | ASCII gloss |
+|--------|--------|-------------|
+| Logic | `∀`, `∃`, `∧`, `∨`, `¬`, `⇒`, `⇔` | forall, exists, and, or, not, implies, iff |
+| Comparison | `≤`, `≥`, `≠`, `≡`, `≜` | <=, >=, !=, ==, := (definition) |
+| Sets | `∈`, `∉`, `⊆`, `⊂`, `∪`, `∩`, `∅` | in, not in, subset of, proper subset, union, intersection, empty |
+| Numbers | `ℕ`, `ℤ`, `ℚ`, `ℝ` | natural, integer, rational, real |
+| Functions | `→`, `↦`, `∘` | function-of, mapsto, compose |
+| Brackets | `⟨ ⟩`, `⟦ ⟧` | tuple, denotation |
+| Complexity | `Θ`, `O`, `Ω`, `ω`, `~`, superscripts (`²`, `³`, `ⁿ`) | tight bound, upper bound, lower bound, strictly lower, asymptotic equivalence, exponentiation |
+| Limits | `→ ∞`, `lim` | "as n grows without bound" |
+
+### What stays ASCII
+
+- Tag prefixes (`@requires`, `@ensures`, `@invariant`, `@trusted`, `@pure`) — for tooling compatibility (Psalm, PHPStan, JSDoc tooling, mypy, pyright)
+- Operators inside type signatures (TS/PHP/Python syntax — `&`, `|`, `:`, `?`, etc.)
+- Inline gloss text on every clause (the dual-audience pattern)
+
+Unicode lives inside the *clause body*. ASCII gloss lives on the same or next line.
+
+### Common glyph confusions to avoid
+
+- `⇒` (implication) vs `→` (function arrow) vs `↦` (mapsto). Use `⇒` for logical implication, `→` for "function from A to B," `↦` for "x mapsto f(x)."
+- `≡` (logical equivalence / equal-by-definition in some traditions) vs `≜` (definition). Prefer `≜` for definitions, `≡` for "same up to" relations.
+- `⊆` (subset-or-equal) vs `⊂` (proper subset). Most contract uses want `⊆`.
+- `Θ(f)` (tight bound) vs `O(f)` (upper bound only) vs `Ω(f)` (lower bound). Most code calling itself "O(n log n)" is actually `Θ(n log n)` — the bound is tight, not just an upper limit. SHOULD use `Θ` when the bound is tight; `O` is correct only when the function may run *faster* than f. Loose `O` claims prime the wrong reasoning ("this is at most O(n²)" when the agent should think "this is exactly Θ(n log n)").
+
+## Pairing patterns
+
+Pick one and apply consistently within a file. **The gloss MUST carry assumption-naming, not just translation** (see `SKILL.md` § "Two surfaces per clause"). The Unicode formal surface activates careful reasoning in readers with bandwidth to parse it; the prose gloss carries the same content for readers without that bandwidth, plus the assumptions the formal notation cannot express.
+
+### Pattern A — inline assumption-naming gloss after the formal clause
+
+```ts
+@requires q ≥ 0           // q is non-negative; assumes caller validated input
+@ensures  result ∈ ℕ       // result is a natural number; overflow is caller's responsibility
+```
+
+Denser. Reads as a column of formal clauses with the prose-and-assumptions as a sidebar.
+
+### Pattern B — bracketed gloss on the same line
+
+```ts
+@requires q ≥ 0  (q is non-negative; assumes caller validated input)
+@ensures  ∀ x ∈ items. x.qty ≥ 0  (every item has non-negative qty; empty array is allowed)
+```
+
+Less dense. Reads more like prose. Better when the clauses are short and the assumption-naming is short.
+
+### What the gloss is NOT
+
+A redundant translation. `@requires q ≥ 0  // q >= 0` is the wrong gloss — both lines say the same thing, neither names what is assumed. The gloss MUST add at least one of:
+
+- An assumption the formal notation does not express (no NaN, integer not float, validated upstream)
+- A side condition (locking, transactional context, ordering)
+- A boundary the contract treats as out-of-scope (overflow, empty input, sentinels)
+
+If the gloss is exactly `@requires q ≥ 0  // q >= 0`, drop it — it's bookkeeping, not load-bearing prose.
+
+## Clause-first derivation table
+
+Write the clause first. The encoding falls out of the clause shape.
+
+| Clause shape | Tier | Encoding |
+|--------------|------|----------|
+| Refinement: `q : ℕ ∧ q > 0`  *(q is a positive natural)* | 1 | Branded type + smart constructor: `type PositiveInt = number & { readonly __brand: 'PositiveInt' }; function mkPositive(n: number): PositiveInt` |
+| Sum: `Status ≜ Loaded(Item) ∨ NotFound ∨ CallForPrice`  *(tagged union of three states)* | 1 | Discriminated union: `{ kind: 'loaded'; item: Item } \| { kind: 'not-found' } \| { kind: 'call-for-price' }` |
+| Predicate: `∀ x ∈ xs. p(x)`  *(every x in xs satisfies p)* | 2 | `xs.every(p)` |
+| Predicate: `∃ x ∈ xs. p(x)`  *(some x in xs satisfies p)* | 2 | `xs.some(p)` |
+| Effect: `pure`, `mutates X`, `throws Y` | 2 | `@psalm-pure`, `@psalm-mutation-free`, `eslint-plugin-functional` |
+| Otherwise (algebraic law, multi-step protocol invariant, external state) | 3 | Formal-prose annotation in JSDoc / docstring |
+
+The discipline: write the clause **before** the function. Reversing the order — writing the function and back-fitting a contract — bypasses the cognitive work and produces tautological annotations.
+
+## Per-language examples
+
+### TypeScript
+
+```ts
+/**
+ * Compute order total in cents.
+ *
+ * @requires items.length > 0          // at least one line item; empty cart is caller's responsibility
+ * @requires ∀ i ∈ items. i.qty > 0     // every item has positive qty; assumes upstream validation
+ * @ensures  result === Σ(items, i ↦ i.qty × i.unitPrice)
+ *           // result is the sum of qty × unitPrice; assumes integer cents, no rounding here
+ * @ensures  result ∈ ℕ                 // result is non-negative; overflow is caller's responsibility
+ * @time     Θ(n)                       // linear in n = items.length
+ * @space    O(1)                       // auxiliary space — accumulator only
+ * @pure
+ */
+function totalCents(items: LineItem[]): number { ... }
+```
+
+### PHP
+
+```php
+/**
+ * Rebuild the latest snapshot from the event log.
+ *
+ * @requires $events is sorted ascending by occurredAt
+ *           (events are chronological; ordering is caller's responsibility, not validated here)
+ *
+ * @ensures  result ≜ fold($events, replay)
+ *           (result is the snapshot replayable from the event log; assumes replay is deterministic)
+ *
+ * @invariant during fold, accumulator state ≡ replay($events[0..i])
+ *            (at each step i, accumulator equals replay of events 0 through i; holds only if events are immutable during fold)
+ *
+ * @time     Θ(n)                              // linear fold over events; n = count($events)
+ * @space    O(1)                              // running accumulator, no buffering of events
+ * @pure
+ *
+ * Footgun: $events === ∅ vs $events === [genesis] are not the same precondition.
+ *          (empty array means "no genesis"; caller must distinguish from "not yet bootstrapped")
+ */
+function rebuild(array $events): Snapshot { ... }
+```
+
+### Python
+
+```python
+def transfer(src: Account, dst: Account, cents: int) -> None:
+    """
+    Transfer cents from src to dst, atomically.
+
+    @requires cents > 0                        # cents must be positive; zero-amount is caller's responsibility
+    @requires src.balance ≥ cents              # sufficient funds; assumes balance was read inside the same lock
+    @requires src ≠ dst                        # src and dst differ; self-transfer is caller's bug, not ours
+    @ensures  src.balance ≡ old(src.balance) − cents
+              # src.balance decreases by cents; assumes no concurrent mutators outside this lock
+    @ensures  dst.balance ≡ old(dst.balance) + cents
+              # dst.balance increases by cents; same locking assumption
+    @invariant src.balance + dst.balance ≡ old(src.balance) + old(dst.balance)
+               # total balance is conserved; holds across the atomic boundary, not mid-flight
+    @time     Θ(1)                                # constant — three field updates
+    @space    Θ(1)
+    @mutates  src, dst
+    """
+```
+
+## Annotation forms reference
+
+- `@requires <precondition>` — must hold of inputs at call time
+- `@ensures <postcondition>` — guaranteed of result / observable state
+- `@invariant <property>` — holds at loop head, between method calls, across state transitions
+- `@trusted <param>` — value inlined into a security-sensitive sink (SQL, HTML, shell); origin must be trusted code, never user input
+- `@pure` — no observable effects (no mutation, no IO, no throws under normal inputs)
+- `@mutates <state>` — names the state mutated (a parameter, a field, a global)
+- `@throws <type>` — names the exceptions that may be raised
+- `@io` — performs IO (filesystem, network, console)
+- `@property <law>` — algebraic law the function satisfies (idempotence, commutativity, associativity, monotonicity)
+- `@time <bound>` — runtime complexity. Use `Θ(...)` for tight bound, `O(...)` for upper bound only, `Ω(...)` for lower bound. Amortized: `@time Θ(1) amortized`. Worst/avg split: `@time worst Θ(n²)  avg Θ(n log n)`.
+- `@space <bound>` — auxiliary space complexity (excluding input). Same `Θ`/`O`/`Ω` conventions.
+
+## Glossary
+
+A reader unfamiliar with the symbols can use this section. Over repeated exposure these become routine.
+
+| Symbol | Reads as | Means |
+|--------|----------|-------|
+| `∀ x ∈ S. P(x)` | "for all x in S, P of x" | every element of S satisfies the predicate P |
+| `∃ x ∈ S. P(x)` | "there exists x in S such that P of x" | at least one element of S satisfies P |
+| `A ⇒ B` | "A implies B" | if A then B |
+| `A ⇔ B` | "A iff B" | A holds exactly when B holds |
+| `A ∧ B` | "A and B" | both A and B hold |
+| `A ∨ B` | "A or B" | at least one of A, B holds |
+| `¬A` | "not A" | A does not hold |
+| `x ∈ S` | "x is in S" | x is an element of S |
+| `S ⊆ T` | "S is a subset of T" | every element of S is in T |
+| `S ∪ T` | "S union T" | elements in S or T (or both) |
+| `S ∩ T` | "S intersect T" | elements in both S and T |
+| `∅` | "empty" | the empty set or empty collection |
+| `ℕ` | "naturals" | non-negative integers (0, 1, 2, …) |
+| `ℤ` | "integers" | …, -1, 0, 1, … |
+| `ℝ` | "reals" | the real numbers (note IEEE-754 ≠ ℝ) |
+| `f : A → B` | "f from A to B" | f is a function from set A to set B |
+| `x ↦ f(x)` | "x mapsto f of x" | the function that maps x to f(x) |
+| `≜` | "is defined as" | left side is defined to mean the right |
+| `≡` | "equivalent to" | the two are interchangeable in this context |
+| `Σ(xs, f)` | "sum of f over xs" | sum of f(x) for each x in xs |
+| `Θ(f(n))` | "Theta of f of n" | tight asymptotic bound — function grows exactly at the rate f(n) |
+| `O(f(n))` | "Big-O of f of n" | upper bound only — function grows at most as fast as f(n) |
+| `Ω(f(n))` | "Big-Omega of f of n" | lower bound — function grows at least as fast as f(n) |
+| `ω(f(n))` | "little-omega of f of n" | strictly faster than f(n) |
+| `f ~ g` | "f is asymptotic to g" | f(n)/g(n) → 1 as n → ∞ |
+| `n → ∞` | "as n grows without bound" | the limiting case for asymptotic claims |
+
+The glossary is intentionally short. Other symbols MAY be added when load-bearing across multiple files; bare additions for a single use SHOULD be avoided.

package/skills/simpleapps/project-defaults/SKILL.md

@@ -148,30 +148,30 @@ Every project SHOULD configure `.claude/settings.local.json` with these deny rul
   },
   "permissions": {
     "allow": [
-      "Bash(pnpm:*)",
+      "Bash(basename:*)",
+      "Bash(dirname:*)",
+      "Bash(find:*)",
+      "Bash(grep:*)",
       "Bash(ls:*)",
-      "Bash(wc:*)",
+      "Bash(lsof:*)",
       "Bash(md5:*)",
       "Bash(md5sum:*)",
+      "Bash(pnpm:*)",
+      "Bash(pwd:*)",
       "Bash(readlink:*)",
+      "Bash(rg:*)",
+      "Bash(wc:*)",
       "Bash(which:*)",
-      "Bash(basename:*)",
-      "Bash(dirname:*)",
-      "Bash(pwd:*)",
-      "Bash(lsof:*)",
       "mcp__plugin_simpleapps_augur-api__*"
     ],
     "deny": [
       "Bash(awk:*)",
       "Bash(cat:*)",
       "Bash(cd:*)",
-      "Bash(find:*)",
       "Bash(for:*)",
-      "Bash(grep:*)",
       "Bash(head:*)",
       "Bash(kill:*)",
       "Bash(pkill:*)",
-      "Bash(rg:*)",
       "Bash(sed:*)",
       "Bash(sleep:*)",
       "Bash(tail:*)",
@@ -187,16 +187,17 @@ Why each is denied:
 - **`awk`**: Use the Edit tool instead.
 - **`cat`**: Use the Read tool instead.
 - **`cd`**: MUST NOT use in any Bash command, including compound commands (`cd /path && git`). Use `git -C repo` for git, path arguments for everything else. Compound cd+git commands trigger an unblockable Claude Code security prompt that interrupts the user even when `cd` is denied.
-- **`find`**: Use the Glob tool instead.
-- **`for`**: Shell loops are unnecessary; use dedicated tools or make multiple tool calls instead.
-- **`grep`**: Use the Grep tool instead.
+- **`for`**: Shell loops are unnecessary; make multiple tool calls instead.
 - **`head`/`tail`**: Use the Read tool with `offset` and `limit` parameters instead.
 - **`kill`/`pkill`**: Use `TaskStop` to manage background processes. `TaskStop` cleanly shuts down the task and updates Claude Code's internal tracking.
-- **`rg`**: Use the Grep tool instead (it uses ripgrep internally).
 - **`sed`**: Use the Edit tool instead.
 - **`sleep`**: Unnecessary; use proper sequencing or background tasks.
 - **`Edit(~/.claude/plugins/**)` / `Write(~/.claude/plugins/**)`**: The installed plugin tree is a cache. Marketplace updates clobber it. To change plugin behavior, edit the plugin's source repo (e.g., `~/projects/simpleapps/augur-skills/`) instead.
 
+Why `find`, `grep`, and `rg` are now ALLOWED (previously denied):
+
+Claude Code 2.1.117 removed the dedicated Grep and Glob tools. Search is now done via Bash. Denying `grep`/`find`/`rg` while no dedicated alternative exists makes the agent unable to search anything. These commands are allowed by default; the bash-simplicity skill still applies (one command per call, no shell plumbing).
+
 ## Bin Scripts (PATH)
 
 The augur-skills plugin includes shell scripts (`cld`, `cldo`, `tmcld`, etc.) in `plugins/simpleapps/bin/`. When installed via the Claude Code marketplace, these live at:

package/skills/simpleapps/wiki/SKILL.md

@@ -188,12 +188,12 @@ Every wiki on the machine is a local knowledge base. When looking for how someth
 2. Pull the latest for all wikis before searching:
    - `git -C {projectRoot}/clients/*/wiki pull` (one call per wiki, not a glob)
    - `git -C {projectRoot}/simpleapps/*/wiki pull`
-3. Search across all wikis with Grep:
-   - `Grep(pattern: "...", path: "{projectRoot}/clients", glob: "*/wiki/*.md")`
-   - `Grep(pattern: "...", path: "{projectRoot}/simpleapps", glob: "*/wiki/*.md")`
+3. Search across all wikis with Bash `grep`:
+   - `grep -rn --include="*.md" "<pattern>" {projectRoot}/clients/*/wiki/`
+   - `grep -rn --include="*.md" "<pattern>" {projectRoot}/simpleapps/*/wiki/`
 4. Read the matching pages to get the full context
 
-Use Glob to discover which projects have wikis: `Glob(pattern: "{projectRoot}/clients/*/wiki")` and `Glob(pattern: "{projectRoot}/simpleapps/*/wiki")`.
+Discover which projects have wikis with Bash `ls`: `ls -d {projectRoot}/clients/*/wiki` and `ls -d {projectRoot}/simpleapps/*/wiki`.
 
 The wikis are kept fresh by `/curate-wiki` runs across projects. Searching locally is instant and requires no internet access; the knowledge is already on the machine.
 

package/skills/simpleapps/work-habits/SKILL.md

@@ -11,13 +11,14 @@ Do not add features, refactor surrounding code, or "improve" beyond the request.
 
 ## Use the right tool
 
-Prefer dedicated tools over Bash equivalents. They are faster, need no permissions, and produce cleaner output:
+Prefer dedicated tools over Bash equivalents when one exists. They are faster, need no permissions, and produce cleaner output:
 - Read not `cat`/`head`/`tail`
-- Grep not `grep`/`rg`
-- Glob not `find`/`ls`
 - Edit not `sed`/`awk`
+- Write not `echo >`/`cat <<EOF`
 
-Reserve Bash for commands that have no dedicated tool equivalent.
+Search is Bash-only — Claude Code 2.1.117 removed the dedicated Grep and Glob tools. Use `grep -rn`, `rg`, `find`, and `ls` directly via Bash, one command per call (no `-exec`, no piping to `head`).
+
+Reserve Bash for searches above and for commands that never had a dedicated tool.
 
 MUST NOT use `cd` in any Bash command, not even in compound commands like `cd /path && git log`. Use `git -C repo` for git, and path arguments for everything else. The `cd` deny rule does not suppress Claude Code's built-in security prompt for compound cd+git commands, so any `cd` usage will interrupt the user.
 
@@ -29,12 +30,19 @@ Before asking the user for credentials, tokens, siteId, domain, or any site-spec
 
 When debugging in the browser, MUST check for error overlays (red error pill/badge at the bottom of the page) before guessing at the problem. Click it, read the full error, stack trace, and source location. The answer is almost always right there.
 
-## Protect the context window
+## Context discipline
+
+Every file read, command output, and subagent response sits in context for the rest of the session. The agent behaviors that matter:
+
+- Broad exploration ("where is X wired up", "how does Y work") → delegate to an Explore subagent with a word cap. The entire exploration happens outside your context; only the returned summary costs you tokens. This is the single biggest lever for keeping the main thread slim. The trick is asking for everything you will need up front — file paths, line numbers, surrounding context, edge cases — in one specific request. A complete request yields a complete answer; a vague one forces a second round-trip that erases the saving. See `subagent-briefing.md` for the required briefing elements.
+- Do not re-read files already loaded in this session. Trust the earlier Read.
+- After Grep gives you a line number, Read with offset/limit — not the whole file.
+- Commands with large output (test runs, build logs, long grep results): redirect to a `tmp/` file, then Grep or targeted-Read the parts you need.
+- Do not duplicate subagent work. If you delegated the search, use the answer — do not re-run the greps inline to verify.
 
-- Prefer targeted searches over broad exploration
-- Use subagents for verbose operations (test runs, log analysis, large file reads)
-- `/clear` between unrelated tasks
-- Two sentences that answer the question beat two pages that fill the context window
+## Response length
+
+Be complete and concise. Accuracy and completeness come first — do not truncate a real answer to look terse. But verbosity is not thoroughness. Every token sent to the user is a token they are expected to read; too many tokens raise cognitive load and annoy them. Output tokens also cost ~5x input on Opus, so the waste compounds. Multi-option writeups, draft code blocks, and "here are my thoughts" bullets are the default failure mode when a paragraph would cover it. Say what's needed, then stop.
 
 ## Verify your own work
 
@@ -96,24 +104,23 @@ These actions hide problems; they do not fix them. If a rule or test seems wrong
 
 ## Branch hygiene before starting work
 
-The lifecycle commands `/wip`, `/investigate`, and `/implement` MUST verify branch state before doing anything else. This is a HARD STOP, not a warning. A warning the agent emits and then ignores is identical to no check — three concerns end up on one branch and the mess is only discovered at `/submit`.
+Branch management is the agent's job, not the user's. The lifecycle commands `/wip`, `/investigate`, and `/implement` MUST verify branch state before starting, but the agent SHOULD handle the safe transitions itself rather than blocking the user with "go run `git switch` first."
 
 When invoked for issue `#N`:
 
 1. Run `git -C repo branch --show-current` → branch `B`
 2. Run `git -C repo status --porcelain` → working tree state `T`
 
-Proceed ONLY if one of these holds:
-
-- `B` is `main` or `master` AND `T` is clean
-- `B` contains `N` (e.g., `feat/N-...`, `fix/N-…`) — you are continuing in-flight work for the same issue; dirty tree is allowed
-
-Otherwise STOP. Report exactly what you saw and the recovery path:
+| `B` | `T` | Action |
+|-----|-----|--------|
+| Contains `N` | any | Proceed — continuing in-flight work for this issue |
+| `main` / `master` | clean | For `/wip` and `/investigate` (read/scaffold only): proceed on `main`. For `/implement` (code changes): create the branch yourself with `git -C repo switch -c <type>/<N>-<slug>`, then proceed. Derive `<type>` from the issue title prefix (`feat:`, `fix:`, `chore:`, `docs:`). Derive `<slug>` from the issue title (lowercase-hyphenated, ≤40 chars). |
+| `main` / `master` | dirty | HARD STOP — uncommitted changes need to land somewhere first. Report exactly which files are modified. Let the user decide (commit on a branch, discard, stash). MUST NOT touch their changes. |
+| Belongs to a different issue (`feat/M-…`, `M ≠ N`) | any | HARD STOP — tell the user to `/submit` the in-flight work first, then re-run. MUST NOT switch branches with uncommitted work present. |
 
-- If `B` is for a different issue: tell the user to `/submit` the in-flight work first, then `git -C repo switch main` and re-run the command. Do NOT offer to commit or stash on their behalf.
-- If `B` is `main`/`master` but `T` is dirty: tell the user the uncommitted changes need to land somewhere (their own branch + `/submit`, or explicit discard) before starting new work.
+The HARD STOPs only fire when the user's working state would be lost or mixed by proceeding. Clean main + known issue is not a stop condition — `/implement` creates the branch itself; `/wip` and `/investigate` proceed in place because they don't write code.
 
-Do NOT proceed with a "warning." Do NOT scaffold, investigate, or implement on a stale or wrong branch. Branching mistakes compound silently and the cost of recovery scales with how many commands later they are caught.
+Branching mistakes compound silently and the cost of recovery scales with how many commands later they are caught — but the answer is the agent doing the safe transition autonomously, not screaming the sky is falling at the user every time the workflow requires a routine `git switch`.
 
 ## Track progress