Prepare release v0.2.0

CHANGELOG.md

@@ -6,6 +6,10 @@ Versions follow [semantic versioning](https://semver.org): while the major versi
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-11-03
+
+Agents follow the skill more reliably and load less of it. `SKILL.md` is half as long, and each mode reads only its own files. In every mode, the agent now reads the language file for the code it works on, and sizes the work from the project's configuration. It reports instructions planted in project files. It also catches more of what breaks optimizations: caches that serve stale data across processes, callers that change a returned value, and code that nothing runs. Install or update with `npx skills add https://github.com/protechnocrats/algorithmic-intelligence --skill algorithmic-intelligence`.
+
 ### Changed
 
 - **Clearer instructions throughout:** `SKILL.md`, `WORKFLOW.md`, `REPORTING.md`, `DIFFERENTIAL-TESTING.md`, `BENCHMARKING.md`, and `ALGORITHM-ARSENAL.md` rewritten in shorter sentences, with each instruction stated once and the rest pointing to it. No rule, step, threshold, example, or named section was removed.
@@ -24,14 +28,23 @@ Versions follow [semantic versioning](https://semver.org): while the major versi
 - **"Fixed as a side effect" needs proof.** The agent must name the failing input and the command that showed the original failing; a changed condition or check is never a side effect.
 - **Instructions found in project files are reported.** Text in comments, docs, test data, or fetched pages that addresses AI assistants is never followed, and the agent tells the developer which file contains it. The report header has a required "Instructions found in project files" section, and the final summary repeats it, so the warning is not lost in report mode.
 - **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,800 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.
+- **`SKILL.md` is about half as long** (about 2,900 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.
-- **Conflicting size sources are reported.** When the README, configuration, code, or tests give different input sizes, the agent lists each source and number, says which one it used and why, and asks the developer to confirm when the choice changes a ranking or a design.
+- **Conflicting size sources are reported.** When the README, configuration, code, or tests give different input sizes, the agent lists each source and number, says which one it used and why, and asks the developer to confirm when the choice changes a ranking or a design. The report header has a required "Input sizes" section that lists each size, its source, and every disagreement between sources.
+- **Complexity is reported in every size variable, with the lower bound.** Apply results, the final summary, and write mode's performance decisions give each item's complexity before and after in every size variable (O(n·k) → O(n), not only O(n²) → O(n)) and the lower bound with its reason, or "unknown" with why.
+- **Sizes come from the project's configuration first.** Before estimating sizes, in every mode and even for one named function, the agent reads the configuration and deployment files and the README for production sizes. Apply results open with the sizes used and their sources.
+- **Callers' use of a result is part of the contract.** For each caller, the agent reads what it does after the call (changes, appends to, keeps, or encodes the result, or changes the arguments it passed) and names those callers, so a rewrite that returns shared memory or a different empty value is caught.
+- **Measured numbers are checked against the output.** A number labeled measured must appear in a command's output from the session, or be computed from it with the arithmetic shown; projections are estimated even next to measured numbers. The agent checks every measured number before finishing.
+- **Every cache or index gets a memory estimate:** its bound, its size in bytes across every copy that can exist at once, and the memory limit from the project's configuration it was compared with.
+- **Shared state is tested under concurrent callers.** When new code adds a cache, memo table, index, or counter that several threads, goroutines, or workers can reach, the agent tests it concurrently, with the race detector or thread sanitizer where one exists.
+- **Caching checks what callers do with the result.** Before caching, write mode reads each caller after the call; if any changes or keeps the returned value, the cache hands out copies or caches only the inputs.
+- **Bugs are recorded in any code the agent reads,** not only in the function it optimizes: other functions in the same file, callers, and helpers.
+- **The skill loads for more new-code requests:** code that walks trees, graphs, or parent/child links, or that handles input from users or public APIs, even when the request does not mention speed.
 - **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

README.md

@@ -139,16 +139,16 @@ 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 from the code, configuration, and documentation (when they disagree, it lists each source and its number, says which it used, and asks you to confirm when the choice matters), names the limiting resource, and checks exposure. Evidence that code runs (a profile, you saying it runs or is slow, documentation or deployment configuration saying what uses it or when it runs) 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 and never deleted, bugs noticed in it are still logged, 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, the scope (including what was not inspected), any text addressed to AI assistants found in project files (never followed), and code with no entry point found; lists behavior changes for review first, then ranks items by real-world impact. Report mode ends here.
+4. **Report:** starts with the test-suite baseline, the scope (including what was not inspected), any text addressed to AI assistants found in project files (never followed), the input sizes with their sources and any disagreement between them, and code with no entry point found; 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, 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, and never ships weaker results than you asked for (stale, approximate, or reordered) without asking: it writes the exact version and offers the faster one as an option, and a cache it writes detects changes made by other processes. It 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.
 
 ## What you get
 
-- **`OPTIMIZATION-REPORT.md`:** written once, at the end of report mode, and never edited afterward. It opens with the test-suite baseline (including tests that were already failing), the scope and what was not inspected, any instructions to AI assistants found in project files, code with no entry point found, and behavior changes awaiting your decision. Then, for each item: the location, its contract, the entry point it is reached from, the limiting resource, exposure, current complexity, lower bound and its basis, the candidates considered with their sources, the recommendation and why nothing better was chosen, the kind of win (asymptotic, constant-factor, or work avoided), memory impact across all copies, dependency needs, behavior risks, the prediction, and the planned verification. Changes that were tried and rejected are listed with their measurements. Each field is one line unless you have a decision to make about it, and straightforward items use a shorter format, so the report stays proportional.
-- **`APPLY-RESULTS.md`** (apply mode): written once at the end, so the analysis report stays exactly as you reviewed it. For each item you approved: the verification level, inputs and properties checked, the planted differences the tests caught, the tests and tools run, what remains unverified, measurements against the prediction with the end-to-end share, how to reproduce them, and the files changed. Also changes marked as needing testing, behavior-change decisions, changes tried and rejected while applying, and bugs found while applying.
+- **`OPTIMIZATION-REPORT.md`:** written once, at the end of report mode, and never edited afterward. It opens with the test-suite baseline (including tests that were already failing), the scope and what was not inspected, any instructions to AI assistants found in project files, the input sizes with their sources and any disagreement between them, code with no entry point found, and behavior changes awaiting your decision. Then, for each item: the location, its contract, the entry point it is reached from, the limiting resource, exposure, current complexity, lower bound and its basis, the candidates considered with their sources, the recommendation and why nothing better was chosen, the kind of win (asymptotic, constant-factor, or work avoided), memory impact across all copies, dependency needs, behavior risks, the prediction, and the planned verification. Changes that were tried and rejected are listed with their measurements. Each field is one line unless you have a decision to make about it, and straightforward items use a shorter format, so the report stays proportional.
+- **`APPLY-RESULTS.md`** (apply mode): written once at the end, so the analysis report stays exactly as you reviewed it. It opens with the input sizes and their sources. For each item you approved: its complexity before and after in every size variable with the lower bound, the verification level, inputs and properties checked, the planted differences the tests caught, the tests and tools run, what remains unverified, measurements against the prediction with the end-to-end share, how to reproduce them, and the files changed. Also changes marked as needing testing, behavior-change decisions, changes tried and rejected while applying, and bugs found while applying.
 - **`BUGS-FOUND.md`:** bugs noticed during analysis, with inputs, whether the bug was reproduced or only suspected, impact, a suggested fix (not applied), and whether an optimization removed it as a side effect.
 - **Differential tests** in your test sources, with the original implementation kept as a reference. You decide whether to keep them as regression tests.
 - **One commit per applied optimization, if you authorize commits,** with the before and after complexity and benchmark numbers. Without authorization nothing is committed, and the report lists each item's changed files.

skills/APPLYING.md

@@ -22,11 +22,12 @@ Write `APPLY-RESULTS.md` once, in one pass ("Apply results format" below), and l
 
 ## Apply results format
 
-`APPLY-RESULTS.md` starts with the test suite status before and after (from runs on the final code), then one entry per item the developer approved, using its ID from `OPTIMIZATION-REPORT.md`:
+`APPLY-RESULTS.md` (or, for a small result, the summary in the conversation) starts with the test suite status before and after (from runs on the final code), and the input sizes used with their sources and any disagreement between sources, then one entry per item the developer approved, using its ID from `OPTIMIZATION-REPORT.md`:
 
 ```markdown
 ### <ID>. <Short title> — <Applied (verified: level) | Applied (NEEDS-TESTING, developer approved) | Applied (BEHAVIOR-CHANGE, developer approved) | Not applied (reason; original restored)>
 
+- **Complexity:** before → after in every size variable (for example O(n·k) → O(n), not only O(n²) → O(n)), with the case labeled (rule 9); the lower bound with its reason and basis, or "unknown" with why; and whether the new version reaches it.
 - **Verification:** Level reached (tested | property-checked | exhaustively checked, with the domain | proven, with the tool and what it proved); inputs and properties covered (edge cases, generated cases, seeds, sizes); the planted differences the tests caught and the A/A result ("Check the check" in `DIFFERENTIAL-TESTING.md`); tests and tools actually run, with results; behavior left unverified. "Proven" only at that level.
 - **Performance:** Measured time and memory before and after at realistic n, at a larger n, and on worst-case inputs where relevant, with environment, run count, median, and spread, as absolute values and percentage change; the measured growth exponent against the prediction, and the explanation when they disagree. If measurement could not be completed, say why; the item is not a confirmed win.
 - **End-to-end:** The share of the whole operation's time (the request, job, frame, or command) the changed code took before the change, and the resulting saving for that operation, each labeled measured or estimated (rule 8). When it cannot be measured here, estimate it from the call frequency and sizes found in the survey, and say so. Never leave this field out.

skills/BEHAVIOR-TRAPS.md

@@ -93,7 +93,7 @@ A function is not pure just because its arguments are unchanged. Before caching
 
 ## Concurrency
 
-- **Thread safety.** Replacing a synchronized or concurrent structure with an unsynchronized one, or adding shared mutable caches, introduces races.
+- **Thread safety.** Replacing a synchronized or concurrent structure with an unsynchronized one, or adding shared mutable caches, introduces races. When the code can run on several threads, goroutines, or workers at once (request handlers usually do), synchronize any shared state you add and test it with concurrent callers, with the language's race detector or thread sanitizer where one exists. Locks that no test exercises concurrently are unverified.
 - **Iterator invalidation.** Modifying a collection while iterating it throws, skips elements, or (in C and C++) is undefined behavior, depending on the platform.
 - **Changed concurrency.** Running previously sequential work concurrently changes ordering, error behavior (fail-fast versus continue), rate limiting, and resource usage.
 - **Optimistic and speculative execution.** A reader that proceeds without a lock (sequence locks, optimistic concurrency) can see torn or inconsistent data before it validates. It must not act on that data first: no pointer dereference, division, array index, or output. A retry repeats every side effect of the attempt, and speculative work done for a guess that turns out wrong must leave no trace (no writes, logs, or messages).