lemmaly 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may accept liability
+      and/or offer to charge a fee for, or to provide support, warranty,
+      indemnity, or other liability obligations and/or rights consistent
+      with this License. However, in accepting such obligations, You may
+      act only on Your own behalf and on Your sole responsibility, not on
+      behalf of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Morse Chimwai
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,238 @@
+# lemmaly
+
+[![skills.sh](https://skills.sh/b/morsechimwai/lemmaly)](https://skills.sh/morsechimwai/lemmaly)
+
+**A deterministic CI scanner for algorithmically lazy code, plus a codified four-skill methodology that teams can adopt as their reviewing standard.**
+
+Every AI coding assistant writes code that works. Few write code that scales, terminates correctly on every edge case, or reaches for the right algorithm. The same handful of failures ship in nearly every AI-generated codebase: **O(n²) loops where a hash would do, N+1 queries, missed base cases, off-by-one bugs, brute force when a known algorithm exists, and "should be O(log n)" claims that were never derived.**
+
+lemmaly ships two things:
+
+1. **A CLI scanner** with 59 deterministic rules across 11 languages that catches these patterns in CI without an LLM, without an API key, and without a network call. This is the validated, measurable value.
+2. **A four-skill methodology** (gateway + correctness + math + corrective) with hand-authored Incorrect/Correct examples per rule. Use it as a team standard, a reviewer checklist, or as Claude Code / Cursor skills for projects where you want explicit complexity statements in code comments.
+
+---
+
+## The suite — four skills
+
+lemmaly is not one skill; it is a small family that covers the whole CS surface AI assistants typically skip.
+
+| Skill | Triggers on | What it forces |
+| --- | --- | --- |
+| **`lemmaly`** (gateway) | any loop, collection, lookup, recursion, query | state Big-O, name the data structure, pick the algorithm family, justify repeated work |
+| **`mathguard`** | large-n problems, similarity, dedupe, top-K, streaming, embeddings, signal/poly, geometry | reach for probabilistic structures (Bloom, HLL, Count-Min, MinHash/LSH), FFT/NTT, JL projection, sweep line, kd-tree — and declare ε/δ when approximate |
+| **`invariant-guard`** | loops, recursion, mutating state | state loop invariants, base cases, termination measure, edge case table — before code |
+| **`complexity-cuts`** | "this is slow", "times out", "OOM", existing code with bad Big-O | corrective playbook: nested loop → hash, repeated scan → index, materialize → stream, naive → memoized, brute-force → sort+sweep |
+
+The skills compose. `lemmaly` picks the algorithm; `invariant-guard` proves it works; `mathguard` reaches further when classical hits its floor; `complexity-cuts` fixes what already shipped.
+
+## What it ships
+
+- **Four Claude Code / Cursor skills** in `skills/` — drop into `~/.claude/skills/` or commit per-project under `.claude/skills/`. Each skill has frontmatter `metadata` (pathPatterns, importPatterns, chainTo) so the agent loads the right one automatically.
+- **Per-rule documentation** in `skills/lemmaly/rules/<rule-id>.md` — one file per CLI rule with hand-authored Incorrect/Correct examples and an escalation path. CLI and skills share the same rule IDs.
+- **Compiled rule catalog** in `skills/lemmaly/AGENTS.md` — single-document batch-load view of all 59 rules.
+- **Slash commands** as the vocabulary: `/complexity`, `/hotpath`, `/n-plus-one`, `/invariant`, `/cut`, `/benchmark`, `/ship-check`, `/scale-check`.
+- **Reference modules** loaded on demand — complexity tables, N+1 patterns, hot-path recognition, memory & async pitfalls. Small context cost.
+- **A deterministic CLI** (`lemmaly scan`) — no API key, no LLM, no network. **59 rules across 11 languages**: JavaScript / TypeScript, Python, SQL, Java, C#, Go, Rust, C++, PHP, Ruby, Shell / Bash. Runs in CI in seconds.
+- **Self-consistency tests** (`npm test`) — rule-pattern tests plus a checker that verifies CLI rules, per-rule docs, AGENTS.md, and the gateway catalog stay in sync.
+- **Generators** (`npm run gen`) — regenerate per-rule docs and the compiled catalog from `rules/*.json` whenever new rules are added.
+- **A GitHub Actions workflow** ready to drop into any repo — runs both the scan and the self-test, fails CI on doc/rule drift.
+
+## Install
+
+### As a Claude Code / Cursor skill suite
+
+```bash
+# Via the skills CLI (works with Claude Code, Codex, Cursor, OpenCode, and 50+ agents)
+npx skills add morsechimwai/lemmaly                # project-local
+npx skills add morsechimwai/lemmaly -g             # global (~/.claude/skills/)
+npx skills add morsechimwai/lemmaly --list         # see all 4 skills first
+```
+
+Or copy directly:
+
+```bash
+# Personal (every project picks them up)
+cp -r skills/lemmaly skills/mathguard skills/invariant-guard skills/complexity-cuts ~/.claude/skills/
+cp commands/*.md ~/.claude/commands/
+
+# Or project-local (commit it with the repo)
+mkdir -p .claude/skills .claude/commands
+cp -r skills/lemmaly skills/mathguard skills/invariant-guard skills/complexity-cuts .claude/skills/
+cp commands/*.md .claude/commands/
+```
+
+### Hermes Agent (Nous Research)
+
+Hermes uses the `SKILL.md` standard from [agentskills.io](https://agentskills.io). The `npx skills` CLI ships an `hermes-agent` target — verified in `skills` v0.x against `~/.hermes/skills/`.
+
+```bash
+# Project-scoped — drops the four skills into ./.hermes/skills/
+npx skills add morsechimwai/lemmaly --agent hermes-agent \
+  --skill lemmaly mathguard invariant-guard complexity-cuts -y --copy
+
+# User-global — drops them into ~/.hermes/skills/
+npx skills add morsechimwai/lemmaly --agent hermes-agent -g \
+  --skill lemmaly mathguard invariant-guard complexity-cuts -y --copy
+```
+
+Manual equivalent (if you don't want the CLI):
+
+```bash
+mkdir -p ~/.hermes/skills
+cp -r skills/lemmaly skills/mathguard skills/invariant-guard skills/complexity-cuts ~/.hermes/skills/
+```
+
+### OpenClaw
+
+OpenClaw also reads `SKILL.md` (see [docs.openclaw.ai/clawhub/skill-format](https://docs.openclaw.ai/clawhub/skill-format)). The `npx skills` CLI ships an `openclaw` target — verified to write to `./skills/` (project) and `~/.openclaw/skills/` (global).
+
+```bash
+# Project-scoped — drops the four skills into ./skills/
+npx skills add morsechimwai/lemmaly --agent openclaw \
+  --skill lemmaly mathguard invariant-guard complexity-cuts -y --copy
+
+# User-global — drops them into ~/.openclaw/skills/
+npx skills add morsechimwai/lemmaly --agent openclaw -g \
+  --skill lemmaly mathguard invariant-guard complexity-cuts -y --copy
+```
+
+Manual equivalent:
+
+```bash
+mkdir -p ~/.openclaw/skills
+cp -r skills/lemmaly skills/mathguard skills/invariant-guard skills/complexity-cuts ~/.openclaw/skills/
+```
+
+The four skills declare no `requires.env` or external `bins`, so OpenClaw's security scan passes them as-is — no extra `metadata.openclaw` block needed. The CLI scanner is optional; install it separately if you want CI gating (see below).
+
+> Targeting both at once: `--agent hermes-agent openclaw` is a single install. List every supported client with `npx skills add <repo> -l`.
+
+### As a CLI scanner
+
+```bash
+# From this repo
+node cli/lemmaly.js scan ./src
+
+# Or globally (once published)
+npm i -g lemmaly
+lemmaly scan ./src
+```
+
+## Try it
+
+```bash
+node cli/lemmaly.js scan examples/before-after/bad.jsx
+```
+
+You should see **2 errors, 5 warnings, 3 info** across 9 distinct rule IDs — every numbered anti-pattern in the demo file flagged with a specific fix. Compare against `examples/before-after/good.jsx`.
+
+## How to use it with an AI agent
+
+Once the skills are installed (see above), invoke them by name from Claude Code, Cursor, or any agent that loads `.claude/skills/`. The skill descriptions, `pathPatterns`, and `importPatterns` also let it auto-trigger when you touch loops, queries, or collections — but explicit prompts are the most reliable.
+
+| When | Paste this prompt |
+| --- | --- |
+| **First look** — no specific concern, just point it at the code | `Use the lemmaly skill to check src/ for algorithmic risks. State the Big-O of any function over a collection, and call out N+1 queries, repeated scans, and brute-force loops with a named fix.` |
+| **Before writing** a new function | `Use the lemmaly skill: run /complexity on findDuplicates(items: T[]). State Big-O, the data structure choice, and the loop invariant in comments before writing the body.` |
+| **After AI writes** an endpoint that feels slow | `Use the lemmaly skill: run /n-plus-one on src/orders/list.ts. If it finds a repeated query inside a loop, follow up with /cut and rewrite using a single batched IN query.` |
+| **Pre-merge gate** on a diff | `Use the lemmaly skill: run /ship-check on the current diff. Block merge if any new function is O(n²) without a comment justifying it, and flag any recursion without a stated base case.` |
+| **Will it hold at 10×?** | `Use the lemmaly skill: run /scale-check on this dedupe at 10× and 100× today's 50k rows. Name the cliff and the next structure (HLL, MinHash, sweep line) when classical breaks.` |
+
+The slash commands (`/complexity`, `/n-plus-one`, `/ship-check`, `/scale-check`, `/hotpath`, `/invariant`, `/cut`, `/benchmark`) are the vocabulary — full list and demos at [lemmaly.dev](https://lemmaly.dev/#prompts).
+
+## What we tested, honestly
+
+We ran a live behavioral test: 8 prompts (2 per skill) sent twice to Claude Haiku 4.5 — once with the lemmaly skills installed in `.claude/skills/`, once without. We then scored each response for skill-aligned markers (Big-O claims, named data structures, invariants, ε-bounds for approximate algorithms). [Reproducer here.](./tests/skill-triggering/live.js)
+
+**Result on Haiku 4.5: 7 ties, 1 cosmetic regression, 0 strong uplift, $0.40 total spend.**
+
+That finding matters. It means:
+
+- **Frontier 2026 models (Haiku 4.5 / Sonnet 4.6 / Opus 4.7) already produce skill-aligned code on these prompts by default.** They reach for Set, write `O(1) lookup` in the explanation, and recommend HyperLogLog for cardinality-at-scale — without lemmaly installed.
+- **The skills are not making competent models smarter.** They are codifying the discipline you would want a junior engineer or a less-capable model to follow.
+
+Where lemmaly's value is empirically validated:
+
+| Layer | Value | Evidence |
+|---|---|---|
+| **CLI scanner** | Catches the named anti-patterns deterministically in CI | 59/59 rule-pattern tests pass; sanity scan flags 21 findings across 8 sample files in 8 languages |
+| **Per-rule docs + AGENTS.md** | Single source of truth for both human reviewers and AI agents | Consistency test verifies CLI ↔ MDs ↔ AGENTS.md ↔ gateway stay in sync |
+| **Skill methodology** | Iron Laws, verification checklists, canonical Good/Bad pairs, escalation paths | Documents a complete reviewing standard a team can adopt |
+| **Behavioral uplift on Haiku 4.5+** | **Not measurably present.** Skills duplicate what the model already knows | Live test: 0/8 strong wins |
+
+Where we expect skills to actually move behavior (untested, but plausible): smaller / older models, code-review settings where the Iron Laws force explicit derivations in comments, and contexts where the CLI scanner output is fed back to the model.
+
+## The honest pitch
+
+> **For competent models you barely need the skills. For CI gates and team standards, you need the rules.**
+
+Install the CLI. Drop the GitHub Actions workflow into your repo. Read the four `SKILL.md` files as a reviewing checklist. Install the skills into Claude Code / Cursor if you want every AI-generated commit to carry an explicit complexity comment — that part is discipline, not knowledge.
+
+## The rules
+
+**59 deterministic rules across 11 languages** — JavaScript / TypeScript, Python, SQL, Java, C#, Go, Rust, C++, PHP, Ruby, Shell / Bash. Run `lemmaly rules` to see the full list, or read `skills/lemmaly/AGENTS.md` for every rule with its Incorrect / Correct example.
+
+| Severity | Rule | Why it matters |
+| --- | --- | --- |
+| error | `js-await-in-for-loop` | N+1 over network |
+| error | `js-async-in-foreach` | dropped promises |
+| error | `py-mutable-default-arg` | shared default state |
+| error | `sql-update-no-where` | touches every row |
+| error | `java-arraylist-remove-in-for-i` | index shifts; CMException risk |
+| error | `cs-async-void` | unobserved exceptions crash the process |
+| error | `go-loop-var-capture` | pre-1.22 race on the last value |
+| error | `php-query-in-loop` | N+1 against the database |
+| warning | `js-helper-call-in-iterator` | N round-trips inside a loop |
+| warning | `js-deep-clone-via-json` | `JSON.parse(JSON.stringify(x))` |
+| warning | `sql-select-star` | blocks index-only scans |
+| warning | `java-string-concat-in-loop` | use `StringBuilder` |
+| warning | `cs-disposable-no-using` | leak on exception |
+| warning | `go-defer-in-loop` | defers accumulate to function exit |
+| warning | `rs-unwrap-in-prod` | panics on `None`/`Err` |
+| warning | `cpp-raw-new` | manual delete; exception-unsafe |
+| warning | `rb-bare-rescue` | catches `StandardError`; hides bugs |
+| warning | `sh-set-e-no-pipefail` | pipe failures masked |
+| warning | `sh-unquoted-var` | word-splitting / glob expansion |
+| info | `js-nested-for-loops` | O(n×m) — hash one side |
+| info | `cpp-range-loop-copy` | use `const auto&` |
+| info | `php-loose-equality` | use `===` |
+| info | `sh-useless-cat-pipe` | pass file directly |
+| … 35 more across 11 languages | (see `lemmaly rules` or `skills/lemmaly/AGENTS.md`) | |
+
+## CI integration
+
+```yaml
+# .github/workflows/lemmaly.yml
+- run: npm i -g lemmaly
+- run: lemmaly scan .
+```
+
+Exit code `1` on any `error`-severity finding. Warnings and info do not fail the build.
+
+## Status
+
+**v0.2 — multi-language CI scanner + codified methodology.**
+
+- ✅ 59 rules across 11 languages, all with positive + negative test cases.
+- ✅ Per-rule documentation aligned with CLI rule IDs.
+- ✅ Self-consistency tests prevent rule / doc / catalog drift.
+- ✅ GitHub Actions workflow: scan + self-test + regenerate-and-diff.
+- ✅ Static skill-triggering test (42 prompts) confirms prompt vocabulary matches skill descriptions.
+- ✅ Live behavioral test scaffolding (`tests/skill-triggering/live.js`) and findings (above).
+
+The case study in `case-studies/` describes a measured 22.8× speedup on a real production app — predating this release's multi-language and live-test work.
+
+## Roadmap
+
+- v0.2 — multi-language CI scanner + codified methodology + honest live-test findings. **You are here.**
+- v0.3 — framework rule packs (Next.js, FastAPI, Rails) and broader sampling of the live behavioral test against weaker / older models where we expect the skills to actually move behavior.
+- v0.4 — VS Code extension that surfaces CLI findings inline; CLI emits invariant-stub comments for `invariant-guard`.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). Especially welcome: new rule proposals with both a positive and a negative test case, and new playbook entries for `complexity-cuts` and `mathguard` with derivations.
+
+## License
+
+[Apache 2.0](./LICENSE). Use it commercially, modify it, fork it. If you are an enterprise looking for custom rule packs or codebase-specific tuning, reach out — that is the support model.

package/cli/gen-agents-md.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// Generates skills/lemmaly/AGENTS.md — full compiled rule catalog for batch loading.
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+const RULES_DIR = path.join(ROOT, 'skills', 'lemmaly', 'rules');
+const OUT = path.join(ROOT, 'skills', 'lemmaly', 'AGENTS.md');
+
+const SEV_ORDER = { error: 0, warning: 1, info: 2 };
+const SEV_HEADER = {
+  error: '## CRITICAL — will break or scale-fail in production',
+  warning: '## HIGH — hot-path or correctness risk at realistic n',
+  info: '## MEDIUM — suboptimal; flag when n is large or hot path',
+};
+
+const files = fs
+  .readdirSync(RULES_DIR)
+  .filter((f) => f.endsWith('.md'))
+  .map((f) => {
+    const raw = fs.readFileSync(path.join(RULES_DIR, f), 'utf8');
+    const m = raw.match(/^---\n([\s\S]+?)\n---\n([\s\S]*)$/);
+    if (!m) throw new Error('No frontmatter: ' + f);
+    const fm = {};
+    for (const line of m[1].split('\n')) {
+      const i = line.indexOf(':');
+      if (i < 0) continue;
+      const k = line.slice(0, i).trim();
+      const v = line.slice(i + 1).trim();
+      if (k) fm[k] = v;
+    }
+    return { fm, body: m[2].trimStart() };
+  });
+
+files.sort((a, b) => {
+  const s = SEV_ORDER[a.fm.severity] - SEV_ORDER[b.fm.severity];
+  if (s !== 0) return s;
+  return a.fm.id.localeCompare(b.fm.id);
+});
+
+const parts = [
+  '# Lemmaly Rule Catalog (compiled)',
+  '',
+  'Full compiled view of every CLI rule with hand-authored Incorrect/Correct examples and escalation path. Generated from `rules/*.json` and `skills/lemmaly/rules/*.md`.',
+  '',
+  'For per-rule documents, load `skills/lemmaly/rules/<rule-id>.md`. For the deterministic CLI, run `node cli/lemmaly.js scan <path>`.',
+  '',
+];
+
+let currentSev = null;
+for (const { fm, body } of files) {
+  if (fm.severity !== currentSev) {
+    currentSev = fm.severity;
+    parts.push('', SEV_HEADER[currentSev], '');
+  }
+  parts.push(`### \`${fm.id}\` — ${fm.language}`, '', body.trim(), '');
+}
+
+fs.writeFileSync(OUT, parts.join('\n'));
+console.log('Wrote', OUT, '(' + files.length + ' rules)');