fixing skills

.devcontainer/Dockerfile

@@ -1,6 +1,9 @@
-# The JDK, Ruby, Python, and C toolchains, and the libraries Swift needs, for running agent
-# sessions on projects in those languages, the same way on any machine and sandboxed in the
-# container. Node and Rust come from devcontainer.json; Swift from post-create.sh.
+# A contributor environment for trying the skill with a coding agent on Java, Python, C,
+# JavaScript/TypeScript, Rust, Swift, or Ruby code (Ruby has no language file, so it exercises
+# languages/GENERIC.md), the same way on any machine and sandboxed in the container. Kotlin
+# and C# toolchains are not included. This file installs the JDK, Ruby, Python, and C
+# toolchains and the libraries Swift needs; Node and Rust come from devcontainer.json, and
+# Swift and Claude Code from post-create.sh.
 # Base: the dev container project's Ubuntu image (non-root user "vscode").
 FROM mcr.microsoft.com/devcontainers/base:ubuntu-24.04
 

CHANGELOG.md

@@ -26,6 +26,11 @@ Versions follow [semantic versioning](https://semver.org): while the major versi
 - **The language file is required reading.** In every mode, `SKILL.md` names the language files next to the mode file, to be read before any code: one for each language in the code being read or written, `GENERIC.md` for a language without one, and a language met partway through is loaded before its code is read. The language's hidden costs and security traps (such as unrandomized integer hashing in Python) are no longer skipped.
 - **`SKILL.md` is less than half as long** (about 2,600 words, from 5,600), so every session loads less. Each mandatory rule is stated in a few sentences there, and its full text moved to a new "Rule details" section in `WORKFLOW.md`, which report and apply mode already read. The workflow overview and anti-pattern list, which repeated `WORKFLOW.md` and the rules, were removed; their examples moved into the rules. Rule numbers are unchanged.
 - **Report mode loads less.** Applying and close-out (Phases 5 and 6) moved from `WORKFLOW.md` to a new `APPLYING.md`, which only apply mode reads, in the same step as `WORKFLOW.md`. Text in "Rule details" that repeated those phases or `DIFFERENTIAL-TESTING.md` was removed.
+- **Report mode reads the report format.** `SKILL.md` names `REPORTING.md` for report mode, to be read with `WORKFLOW.md`, so the required report header (including instructions found in project files) is not skipped. The apply results format and the `NEEDS-TESTING` and `BEHAVIOR-CHANGE` markers moved to `APPLYING.md`, so report mode does not load them.
+- **Code that nothing reaches is not optimized.** The agent follows callers, including indirect ones (dependency injection, routing, listeners, plugins, reflection), up to an entry point. Evidence that the code runs (a profile or log, the developer saying it runs or is slow, documentation or deployment configuration saying what uses it or when it runs) also counts. When the chain reaches none, or only tests, the code is not optimized, since speeding it up saves nothing: it is listed in the report under "No entry point found" as likely unused, never deleted, bugs noticed in it are still logged, and the developer is asked where it is used. Before, it stayed a ranked item with unknown reachability.
+- **Every file loads less.** The source lists at the end of each file moved to `references/`, which the agent reads only to verify a claim. The machine-learning, image, geometry, and simulation traps moved from `BEHAVIOR-TRAPS.md` to a "Behavior traps" section in the matching `techniques/` file, which `BEHAVIOR-TRAPS.md` names for code in those domains. All files were reworded to be shorter, with no rule, step, fact, or example removed.
+- **Caches see writes from other processes.** A new trap, "Writers outside this process": when other processes, machines, or jobs share the data, a cache inside one process must detect their writes on every read (a version number or change counter the data source keeps) or cache only data they never change. In write mode the agent decides this before writing: it writes the version that keeps exact results and offers the faster, possibly stale version as an option, instead of shipping it and asking afterwards.
+- **Fewer wasted steps.** The agent runs tests the way the project documents them instead of guessing a runner, and gives commands that can hang a time limit.
 - **New traps and tests:** cyclic structures (an iterative rewrite without a visited set loops forever where recursion failed fast), and round-trip tests when new code reads what existing code writes.
 
 ### Fixed

CONTRIBUTING.md

@@ -31,7 +31,7 @@ Every line of `skills/SKILL.md` is loaded on every run, so a rule there must ear
 
 ## Language companion files
 
-Use [`skills/languages/GENERIC.md`](skills/languages/GENERIC.md) as the checklist, follow the structure of the existing files, and add a row to `skills/languages/INDEX.md`. A profile the skill saved in your project (`.algorithmic-intelligence/languages/<LANGUAGE>.md`) is a good starting point. Cover the language and its standard library only, not frameworks. Cite official documentation for every complexity and ordering claim, and where a claim is implementation behavior rather than documented behavior, say so.
+Use [`skills/languages/GENERIC.md`](skills/languages/GENERIC.md) as the checklist, follow the structure of the existing files, and add a row to `skills/languages/INDEX.md`. A profile the skill saved in your project (`.algorithmic-intelligence/languages/<LANGUAGE>.md`) is a good starting point. Cover the language and its standard library only, not frameworks. Cite official documentation for every complexity and ordering claim, and where a claim is implementation behavior rather than documented behavior, say so. Sources go in `skills/references/languages/<LANGUAGE>.md`, not in the language file, which ends with a pointer to them.
 
 ## Evaluation
 

README.md

@@ -137,11 +137,11 @@ The Skills CLI documents folder URLs like this, not tags as such; it installed `
 Report and apply mode:
 
 1. **Setup:** detects languages and versions, finds your test, benchmark, profiling, and verification tooling, and runs your existing test suite. If tests already fail, report mode lists them and continues; apply mode stops before changing any code until you decide. In apply mode it asks once whether to commit each optimization, unless your project's instructions already say.
-2. **Survey:** confirms the scope you asked for, profiles the code when it can run, and finds candidate hotspots. For each one it writes the contract, traces the callers up to a real entry point (a route, job, listener, command, UI handler, or public API, including code reached through dependency injection, plugins, or reflection), multiplies the cost along that call chain, estimates input sizes, names the limiting resource, and checks exposure. Code with no caller found is never assumed dead: its reachability is reported as unknown and you are asked.
+2. **Survey:** confirms the scope you asked for, profiles the code when it can run, and finds candidate hotspots. For each one it writes the contract, traces the callers up to a real entry point (a route, job, listener, command, UI handler, or public API, including code reached through dependency injection, plugins, or reflection), multiplies the cost along that call chain, estimates input sizes, names the limiting resource, and checks exposure. Evidence that code runs (a profile, you saying it runs or is slow, documentation or deployment configuration) also counts. Code whose callers never lead to an entry point or such evidence, or lead only to tests, is not optimized, since speeding it up saves nothing. It is reported as likely unused, never deleted, and you are asked where it is used.
 3. **Analyze:** first asks whether the work is needed at all, then states the lower bound and compares approaches as described in "How it thinks," writes a prediction of the speedup and of the end-to-end effect, and plans how strongly the change can be verified.
 4. **Report:** starts with the test-suite baseline and the scope (including what was not inspected), lists behavior changes for review first, then ranks items by real-world impact. Report mode ends here.
 5. **Apply** (only on approval): writes differential tests and contract checks against the original first and checks that they can fail, makes the change, verifies it at the highest cheap level, benchmarks it against its written prediction and states its share of the end-to-end operation, and commits each optimization separately only if you authorized commits.
-6. **Close out:** summarizes what was applied and at which verification level, predictions against measurements, what was tried and rejected, what is marked as needing testing, bugs found, pending dependency requests, items whose reachability is unknown, the commits made or the files each item changed, and regression benchmarks you chose to keep.
+6. **Close out:** summarizes what was applied and at which verification level, predictions against measurements, what was tried and rejected, what is marked as needing testing, bugs found, pending dependency requests, code with no entry point found, the commits made or the files each item changed, and regression benchmarks you chose to keep.
 
 Write mode: estimates input sizes and call frequency for each part of the new code, picks or derives algorithms and data structures to match, keeps calls into slow existing code to a minimum, tests the new code against a slow, obviously correct reference version and its contract, and lists its performance decisions with their complexity, size assumptions, and verification level.
 
@@ -252,18 +252,19 @@ The skill's knowledge base is modular and organized around its workflow. The age
 |---|---|
 | `SKILL.md` | The mandatory rules in brief, modes, which files to read first, instructions found in project files, working in few steps |
 | `WORKFLOW.md` | Report and apply mode: setup (including the test baseline and commit authorization), survey (scope, contracts, reachability to entry points, cost along the call chain, exposure), analysis, report; the full text of the mandatory rules ("Rule details") |
-| `APPLYING.md` | Apply mode only: applying each item (differential tests first, change, verify, benchmark, behavior changes held back, commits only if authorized) and close-out |
+| `APPLYING.md` | Apply mode only: applying each item (differential tests first, change, verify, benchmark, behavior changes held back, commits only if authorized), close-out, the apply results format, and the `NEEDS-TESTING` and `BEHAVIOR-CHANGE` markers |
 | `WRITING-NEW-CODE.md` | Write mode: which rules apply to new code, sizing the workload, choosing structures, existing-code bottlenecks, tests, summary |
 | `ALGORITHM-ARSENAL.md` | How to find candidates: six triage questions (starting with whether the work is needed at all), complexity reference, routing by current complexity, lower bounds, reformulation, behavior-changing techniques |
 | `CORE-TECHNIQUES.md` | Lookup tables of core techniques with their assumptions, production patterns, database queries, bit manipulation, combinations; loaded one section at a time |
 | `DISCOVERY.md` | The method for finding better algorithms when no known technique fits (see "The discovery method" above) |
 | `ADVANCED-TECHNIQUES.md` | Index of the advanced techniques: which domain file to load for which problem, and the rules shared by all of them |
-| `techniques/*.md` | Advanced techniques by domain: graphs and trees; sequences, DP, search, and NP-hard problems; strings, automata, parsers, and ranked retrieval; math and numerics; machine learning and AI; image and signal processing; geometry and CAD; games and simulation; spatial data; hardware and concurrency; data at scale; optimization and scheduling (operations research); hostile inputs (including adaptive adversaries that observe outputs), secrets, and hard deadlines; distributed systems; queues and latency; specialized data structures |
+| `techniques/*.md` | Advanced techniques by domain: graphs and trees; sequences, DP, search, and NP-hard problems; strings, automata, parsers, and ranked retrieval; math and numerics; machine learning and AI; image and signal processing; geometry and CAD; games and simulation; spatial data; hardware and concurrency; data at scale; optimization and scheduling (operations research); hostile inputs (including adaptive adversaries that observe outputs), secrets, and hard deadlines; distributed systems; queues and latency; specialized data structures. Each domain file with its own traps has a "Behavior traps" section |
 | `DIFFERENTIAL-TESTING.md` | How to verify equivalence: reference copies, what to compare (including aliasing and object identity), inputs, verification levels, the contract as executable checks, checking the check (planted differences and an A/A run), reporting evidence |
 | `BENCHMARKING.md` | How to measure: predictions, doubling experiments, the noise floor from an A/A run, sound statistics, memory, regression guards, component versus end-to-end effect, and whether a proxy metric implies the real target |
-| `BEHAVIOR-TRAPS.md` | Rewrites that look equivalent but are not: ordering, aliasing and identity, removed work, numerical, machine-learning, image, geometry, simulation, hidden-input, concurrency, cancellation, and security traps |
-| `REPORTING.md` | Report header (test baseline, scope, language profile), item format, tried and rejected, behavior changes for review, bug log, `NEEDS-TESTING` and `BEHAVIOR-CHANGE` markers, final summary |
+| `BEHAVIOR-TRAPS.md` | Rewrites that look equivalent but are not: ordering, aliasing and identity, removed work, numerical, hidden-input, concurrency, cancellation, and security traps; domain traps (machine learning, images, geometry, simulation) are in the matching `techniques/` file |
+| `REPORTING.md` | Report mode's formats: report header (test baseline, scope, instructions found in project files, language profile), item format, tried and rejected, behavior changes for review, bug log, final summary |
 | `languages/INDEX.md`, `languages/*.md` | Which companion file to load for which project, the per-language companions, and `GENERIC.md` for building and saving a profile for any other language |
+| `references/` | The sources behind each file's claims, one file per skill file, kept out of the files the agent loads; read only to verify a claim |
 
 ## For contributors
 

skills/ADVANCED-TECHNIQUES.md

@@ -1,6 +1,6 @@
 # Advanced Techniques
 
-Load this file in Phase 3 alongside `ALGORITHM-ARSENAL.md` (or in write mode, step 4) when the core techniques do not reach the lower bound, or when the problem falls in one of the domains below. Then load only the domain files whose topics match. Load several when a problem spans domains (for example, a game's collision detection needs `techniques/spatial-data.md` and `techniques/games-and-simulation.md`). If no row matches but the core techniques fall short, scan the "Load when the problem involves" column again for the abstract problem from Phase 3, not the code's surface.
+Load this file in Phase 3 alongside `ALGORITHM-ARSENAL.md` (or in write mode, step 4) when the core techniques do not reach the lower bound, or when the problem falls in one of the domains below. Then load only the matching domain files, several when a problem spans domains (for example, a game's collision detection needs `techniques/spatial-data.md` and `techniques/games-and-simulation.md`). If no row matches but the core techniques fall short, scan the "Load when the problem involves" column again for the abstract problem from Phase 3, not the code's surface.
 
 ## Domain files
 
@@ -25,14 +25,14 @@ Load this file in Phase 3 alongside `ALGORITHM-ARSENAL.md` (or in write mode, st
 
 ## How to read the tables
 
-Every domain file uses the same columns. Read them the same way as in `CORE-TECHNIQUES.md`: build or preprocessing cost is stated separately from per-query cost, output cost counts, bounds are worst case unless labeled expected, average, or amortized, and "in practice" marks workload-dependent speedups.
+Every domain file uses the columns of `CORE-TECHNIQUES.md`, read the same way: build or preprocessing cost is stated separately from per-query cost, output cost counts, bounds are worst case unless labeled expected, average, or amortized, and "in practice" marks workload-dependent speedups.
 
 ## Shared rules
 
 These techniques apply to any codebase: operating system kernels, storage and database engines, file systems, compilers, search engines, machine learning and AI systems, image, video, and audio processing, CAD and geometry kernels, scientific and financial code, games and simulations, infrastructure tooling, backends, and apps. Every rule still applies. In particular:
 
 - **Assumptions decide validity.** Each technique below has strict preconditions. Confirm each one from the code and record the evidence.
 - **Most need an implementation inside the project.** Standard libraries rarely include them. Write a focused implementation with its own tests (see "Testing a new data structure" in `DIFFERENTIAL-TESTING.md`) and a comment naming the technique and its complexity (rule 13). If a well-tested library is the better route, ask first (rule 7).
-- **Approximate results are always behavior changes.** Any technique whose answer can differ from the exact answer callers receive today (sketches, sampling, approximate nearest neighbor, probabilistic primality tests without a deterministic base set) needs developer review (rule 5). Randomized or probabilistic techniques whose final answer stays exact are not behavior changes on that account: a Bloom or cuckoo filter followed by the exact check, a hash match confirmed by direct comparison, randomized quickselect. Their randomness affects only running time; label those bounds as expected.
+- **Approximate results are always behavior changes.** Any technique whose answer can differ from the exact answer callers receive today (sketches, sampling, approximate nearest neighbor, probabilistic primality tests without a deterministic base set) needs developer review (rule 5). Randomized or probabilistic techniques whose final answer stays exact are not behavior changes for that reason: a Bloom or cuckoo filter followed by the exact check, a hash match confirmed by direct comparison, randomized quickselect. Their randomness affects only running time; label those bounds as expected.
 - **Constant factors matter.** Several techniques win only at large sizes. Benchmark at realistic sizes (rule 8).
 - **A behavior change is a decision, not a disqualification.** When the best technique changes results (more accurate floating-point sums, a different eviction order, approximate answers), still report it with the exact behavior before and after, and let the developer decide (rule 5). Offer the best equivalent alternative next to it.